ASDinCloudDocs

The payment object

View as Markdown

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.

List payments

View as Markdown
GET/api/v1/payments

Lists 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.

Retrieve a payment

View as Markdown
GET/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.

Create a payment

View as Markdown
POST/api/v1/payments

Creates 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.

Update a payment

View as Markdown
PATCH / PUT / POST/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.

Delete a payment

View as Markdown
DELETE/api/v1/payments/{id}
POST/api/v1/payments/{id}/delete

Removes 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.

Export payments

View as Markdown
GET/api/v1/payments/export

Downloads 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.

Preview receipt numbering

View as Markdown
GET/api/v1/payments/receipt-numbering/preview

Previews 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.

Get the next receipt number

View as Markdown
GET/api/v1/payments/{year}/goodone

Returns 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.

List receipt email recipients

View as Markdown
GET/api/v1/payments/{id}/emails

Lists 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.

Generate a receipt PDF

View as Markdown
POST/api/v1/payments/{id}/print

Generates 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.

Email a payment receipt

View as Markdown
POST/api/v1/payments/{id}/send

Emails 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.

Record a refund

View as Markdown
POST/api/v1/payments/{id}/refund

Records 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.

List available athlete credit

View as Markdown
GET/api/v1/payments/credits

Lists 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.

Review credit allocations

View as Markdown
GET/api/v1/payments/{id}/credit-allocations

Returns 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.

Remove all credit allocations

View as Markdown
DELETE/api/v1/payments/{id}/credit-allocations

Removes 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.

Preview a historical payment import

View as Markdown
POST/api/v1/payments/historical-import/preview

Validates 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.

Import historical payments

View as Markdown
POST/api/v1/payments/historical-import/commit

Imports 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.