Payments
View as MarkdownPayments record incoming and outgoing amounts. They can be expected, paid, refunded, or cancelled.
On this page
- The payment object
- List paymentsGET
/api/v1/payments - Retrieve a paymentGET
/api/v1/payments/{id} - Create a paymentPOST
/api/v1/payments - Update a paymentPATCH / PUT / POST
/api/v1/payments/{id} - Delete a paymentDELETE
/api/v1/payments/{id}POST/api/v1/payments/{id}/delete - Export paymentsGET
/api/v1/payments/export - Preview receipt numberingGET
/api/v1/payments/receipt-numbering/preview - Get the next receipt numberGET
/api/v1/payments/{year}/goodone - List receipt email recipientsGET
/api/v1/payments/{id}/emails - Generate a receipt PDFPOST
/api/v1/payments/{id}/print - Email a payment receiptPOST
/api/v1/payments/{id}/send - Record a refundPOST
/api/v1/payments/{id}/refund - List available athlete creditGET
/api/v1/payments/credits - Review credit allocationsGET
/api/v1/payments/{id}/credit-allocations - Remove all credit allocationsDELETE
/api/v1/payments/{id}/credit-allocations - Preview a historical payment importPOST
/api/v1/payments/historical-import/preview - Import historical paymentsPOST
/api/v1/payments/historical-import/commit
Payments record incoming and outgoing amounts. They can be expected, paid, refunded, or cancelled.
Attributes
idinteger- Identifier assigned by the API.
payment_typestring- Use incoming or outgoing.
statusstring- Use expected, paid, refunded, or cancelled.
amountinteger- Amount in minor currency units. Use amount_cents as an alternative.
currencystring- Three-letter currency code. Defaults to EUR.
due_at_tsinteger or null- Due date for an expected or cancelled payment. Returned in Unix seconds.
payment_at_tsinteger or null- Payment date for a paid or refunded payment. Returned in Unix seconds.
receipt_at_tsinteger or null- Receipt date for a settled incoming payment. Returned in Unix seconds.
subject_typestring or null- Use athlete, coach, staff, or manager.
subject_idinteger or null- ID of the associated person.
sport_idinteger or null- ID of the sport for a sport-scoped payment.
payer_parent_idinteger or null- ID of the paying parent. Required for a settled incoming payment for a minor athlete.
supplier_idinteger or null- ID of the supplier.
subscription_idinteger or null- ID of an associated subscription.
accounting_category_idinteger- Accounting category ID matching the payment direction.
tag_idsarray of integers- Tag IDs. An empty array clears tags. On update, omission keeps the current tags.
payment_method_idinteger or null- ID of the payment method.
bank_account_idinteger or null- ID of the bank account.
reasonstring or null- Payment reason.
notesstring or null- Additional notes.
receipt_numberinteger or null- Optional explicit receipt number.
receipt_series_idinteger or null- Optional receipt numbering series.
excludeinteger- Use 1 to mark the payment excluded.
metadatamap or null- Additional payment details.
accounting_categorymap or null- Accounting category summary.
tagsarray of objects- Associated tag summaries.
receipt_display_numberstring or null- Formatted receipt number.
fiscal_yearinteger or null- Fiscal year derived from the receipt date.
document_originstring- Use system for platform receipts and external for historical records documented elsewhere.
/api/v1/paymentsLists payment records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Query parameters
payment_typestring- Use incoming or outgoing.
statusstring or array- Filter by one or more statuses. For incoming payments, a paid filter also includes refunded.
sport_idinteger- Limit results to an active sport.
subject_typestring or null- Use athlete, coach, staff, or manager.
subject_idinteger or null- ID of the associated person.
athlete_idinteger- Filter by athlete ID.
payer_parent_idinteger- Filter by payer parent.
supplier_idinteger- Filter by supplier.
subscription_idinteger- Filter by subscription.
yearinteger- Calendar year when no date range is supplied. Defaults to the current year.
from_datedate string- Inclusive start date in YYYY-MM-DD format.
to_datedate string- Inclusive end date in YYYY-MM-DD format.
contextstring- Use athlete_detail, parent_detail, coach_detail, or staff_detail to include the full history.
coach_idinteger- Filter by coach when context is coach_detail.
accounting_category_idinteger- Filter by accounting category.
tag_idinteger- Filter by tag.
include_readableinteger- Use 1 to include formatted payment information. Alias expand_readable.
expand_subjectinteger- Use 1 to include the related subject record.
expand_athleteinteger- Use 1 to include the related athlete record.
expand_parentinteger- Use 1 to include the related parent record.
expand_subscriptioninteger- Use 1 to include the related subscription record.
qstring- Search payment text and readable names.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, tsc, tsu, due_at_ts, receipt_at_ts, payment_at_ts, receipt_number, status, payment_type, amount, reason, or readable classification and payment method fields. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
API key access to this operation depends on the workspace’s payment sport access. A request can return 403 even when the key has Payments read permission.
Returns
Returns matching payments and their classification in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{id}Returns one payment by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Returns
The payment is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/paymentsCreates a payment.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Body parameters
payment_typestring- Use incoming or outgoing.
statusstring- Use expected, paid, refunded, or cancelled.
amountinteger- Amount in minor currency units. Use amount_cents as an alternative.
currencystring- Three-letter currency code. Defaults to EUR.
due_at_tsinteger or date string or null- Due date for an expected or cancelled payment. Supply Unix seconds or a date.
payment_at_tsinteger or date string or null- Payment date for a paid or refunded payment. Supply Unix seconds or a date.
receipt_at_tsinteger or date string or null- Receipt date for a settled incoming payment. Supply Unix seconds or a date.
subject_typestring or null- Use athlete, coach, staff, or manager.
subject_idinteger or null- ID of the associated person.
sport_idinteger or null- ID of the sport for a sport-scoped payment.
payer_parent_idinteger or null- ID of the paying parent. Required for a settled incoming payment for a minor athlete.
supplier_idinteger or null- ID of the supplier.
subscription_idinteger or null- ID of an associated subscription.
accounting_category_idintegerRequired- Accounting category ID matching the payment direction.
tag_idsarray of integers- Tag IDs. An empty array clears tags. On update, omission keeps the current tags.
payment_method_idinteger or null- ID of the payment method.
bank_account_idinteger or null- ID of the bank account.
reasonstring or null- Payment reason.
notesstring or null- Additional notes.
receipt_numberinteger or null- Optional explicit receipt number.
receipt_series_idinteger or null- Optional receipt numbering series.
numbering_modestring- Use automatic to allocate a receipt number automatically on creation.
receipt_request_keystring- Receipt request identifier. Use 16–64 letters, digits, hyphens, or underscores. Reuse it for an identical retry.
excludeinteger- Use 1 to mark the payment excluded.
is_athlete_creditboolean- Marks a paid incoming payment for an athlete as credit. The payment cannot belong to a subscription.
metadatamap or null- Additional payment details.
This example registers a workspace-wide payment. A sport-scoped write requires access to the selected sport. Confirm that receipt numbering is configured before creating a paid incoming payment.
Returns
The created payment is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{id}Updates a payment by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Body parameters
payment_typestring- Use incoming or outgoing.
statusstring- Use expected, paid, refunded, or cancelled.
amountinteger- Amount in minor currency units. Use amount_cents as an alternative.
currencystring- Three-letter currency code. Defaults to EUR.
due_at_tsinteger or date string or null- Due date for an expected or cancelled payment. Supply Unix seconds or a date.
payment_at_tsinteger or date string or null- Payment date for a paid or refunded payment. Supply Unix seconds or a date.
receipt_at_tsinteger or date string or null- Receipt date for a settled incoming payment. Supply Unix seconds or a date.
subject_typestring or null- Use athlete, coach, staff, or manager.
subject_idinteger or null- ID of the associated person.
sport_idinteger or null- ID of the sport for a sport-scoped payment.
payer_parent_idinteger or null- ID of the paying parent. Required for a settled incoming payment for a minor athlete.
supplier_idinteger or null- ID of the supplier.
subscription_idinteger or null- ID of an associated subscription.
accounting_category_idinteger- Accounting category ID matching the payment direction.
tag_idsarray of integers- Tag IDs. An empty array clears tags. On update, omission keeps the current tags.
payment_method_idinteger or null- ID of the payment method.
bank_account_idinteger or null- ID of the bank account.
reasonstring or null- Payment reason.
notesstring or null- Additional notes.
receipt_numberinteger or null- Optional explicit receipt number.
receipt_series_idinteger or null- Optional receipt numbering series.
numbering_modestring- Use automatic to allocate a receipt number automatically on creation.
receipt_request_keystring- Receipt request identifier. Use 16–64 letters, digits, hyphens, or underscores. Reuse it for an identical retry.
excludeinteger- Use 1 to mark the payment excluded.
is_athlete_creditboolean- Marks a paid incoming payment for an athlete as credit. The payment cannot belong to a subscription.
metadatamap or null- Additional payment details.
This example updates a workspace-wide payment. A sport-scoped write requires access to that sport.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{id}/api/v1/payments/{id}/deleteRemoves a payment record.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/exportDownloads all matching payment records as CSV.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Query parameters
payment_typestring- Use incoming or outgoing.
statusstring or array- Filter by one or more statuses. For incoming payments, a paid filter also includes refunded.
sport_idinteger- Limit results to an active sport.
subject_typestring or null- Use athlete, coach, staff, or manager.
subject_idinteger or null- ID of the associated person.
athlete_idinteger- Filter by athlete ID.
payer_parent_idinteger- Filter by payer parent.
supplier_idinteger- Filter by supplier.
subscription_idinteger- Filter by subscription.
yearinteger- Calendar year when no date range is supplied. Defaults to the current year.
from_datedate string- Inclusive start date in YYYY-MM-DD format.
to_datedate string- Inclusive end date in YYYY-MM-DD format.
contextstring- Use athlete_detail, parent_detail, coach_detail, or staff_detail to include the full history.
coach_idinteger- Filter by coach when context is coach_detail.
expand_subjectinteger- Use 1 to include the subject’s details.
expand_payer_parentinteger- Use 1 to include the paying parent’s details.
expand_supplierinteger- Use 1 to include supplier details.
split_amountsinteger- Use 1 for separate incoming and outgoing amount columns.
API key access to this operation depends on the workspace’s payment sport access. A request can return 403 even when the key has Payments read permission.
Returns
Returns a CSV file with payment dates, amounts, and classifications.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
/api/v1/payments/receipt-numbering/previewPreviews the next receipt number for a document date.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Query parameters
datedate string- Document date in YYYY-MM-DD format. Defaults to today.
series_idinteger- Use a compatible receipt series.
Returns
Returns the proposed number, series, and whether the numbering setup is confirmed. The preview does not reserve the number.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{year}/goodoneReturns the indicative next receipt number for a year.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Path parameters
yearintegerRequired- Fiscal year, 1970–9999.
For series and document dates, use Preview receipt numbering.
Returns
Returns the next number without reserving it.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{id}/emailsLists suggested receipt email recipients for one payment.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Returns
Returns addresses, recipient types, and display names.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/payments/{id}/printGenerates a PDF receipt for a payment with a system document.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Body parameters
template_idinteger or null- ID of the receipt template.
mystring- Optional print action.
Returns
Returns the generated receipt URL.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
/api/v1/payments/{id}/sendEmails a system receipt to one recipient.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Body parameters
emailstringRequired- Recipient email address. Alias email_to.
body_htmlstringRequired- HTML email body. Alias body.
subjectstring- Email subject.
msgstring- Optional extra message.
Returns
Returns a confirmation and, when available, the receipt link.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
503- The receipt link could not be prepared.
/api/v1/payments/{id}/refundRecords a full refund as an outgoing payment and marks the original incoming payment as refunded.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Body parameters
payment_at_tsinteger or date string or null- Refund date. Defaults to today. Supply Unix seconds or a date.
payment_method_idinteger or null- ID of the payment method.
bank_account_idinteger or null- ID of the bank account.
reasonstring or null- Payment reason.
This example refunds a workspace-wide payment. A sport-scoped refund requires access to that sport.
Returns
Returns the refund payment. This records the transaction in the workspace.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
/api/v1/payments/creditsLists athlete credit payments with an available balance.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Query parameters
athlete_idintegerRequired- ID of the athlete.
API key access to this operation depends on the workspace’s payment sport access. A request can return 403 even when the key has Payments read permission.
Returns
Returns credits with their allocated and available amounts in minor units.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
/api/v1/payments/{id}/credit-allocationsReturns the amounts and current allocations for one athlete credit payment.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Read.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Returns
Returns the payment balance and the list of allocations in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
422- The payment is not an eligible credit.
/api/v1/payments/{id}/credit-allocationsRemoves all current credit allocations for one payment.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Headers
X-Sport-Idinteger- Send the sport ID when the payment belongs to a sport.
Path parameters
idintegerRequired- ID of the payment.
Body parameters
allocation_idsarray of integersRequired- The current allocation IDs from the review endpoint.
Returns
Returns confirmation that the credit allocation set was removed.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The supplied fields or payment state do not allow this action.
404- The requested record was not found.
409- The allocation set has changed or cannot be removed.
422- An allocation is invalid.
/api/v1/payments/historical-import/previewValidates a CSV of externally documented payments and reports each row’s import status.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Body parameters
csvstringRequired- UTF-8 CSV text up to 2 MiB and 2,000 rows. Required headers are data, importo, and codice_fiscale_atleta. Optional headers are codice_fiscale_genitore and causale.
optionsmapRequired- Supply bank_account_id, payment_method_id, and an incoming accounting_category_id.
Returns
Returns validation counts and per-row results. Dates use YYYY-MM-DD or DD/MM/YYYY. CSV amounts are in major currency units.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The CSV or import options are invalid.
/api/v1/payments/historical-import/commitImports eligible CSV rows as paid incoming payments documented externally.
Permissions
Send your API key in X-API-Key. Required permissions are Payments → Write.
Body parameters
csvstringRequired- UTF-8 CSV text up to 2 MiB and 2,000 rows. Required headers are data, importo, and codice_fiscale_atleta. Optional headers are codice_fiscale_genitore and causale.
optionsmapRequired- Supply bank_account_id, payment_method_id, and an incoming accounting_category_id.
request_idstringRequired- Batch identifier, 16–64 letters, digits, or hyphens. Reuse it with the same input when retrying.
Returns
Returns counts and per-row results. Inspect failed and already_imported before retrying.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- The CSV, import options, or request ID are invalid.