List all payout links

payout-links

GET

/api/v1/payout-links

Get all the links that you have created, or use the query parameters to filter the results.

The links are sorted by the createdAt date in reverse chronological order.

The returned links are paginated. The maximum number of payout links returned per page is specified by the limit parameter.

Authorizations

bearerAuth

Type

HTTP (bearer)

Parameters

Header Parameters

x-region*

Mandatory routing header to direct the request to the appropriate regional products

Type

string

Required

Valid values

"EU""US""UK"

Query Parameters

state

Possible values: [ACTIVE, PENDING_APPROVAL, QUEUED, PROCESSING, PAID, FAILED, EXPIRED, CANCELLED]

Retrieves links in the specified state(s). Possible states are:

• ACTIVE: The payout link is live and available for the recipient to claim. No funds have been moved yet.
• PENDING_APPROVAL: The recipient has provided details; the transaction is now undergoing internal treasury review or compliance screening.
• FAILED: The payout link couldn't be paid due to a failure during transaction booking.
• QUEUED: The payout link is approved and queued for payout processing.
• EXPIRED: The payout link cannot be redeemed because it wasn't claimed before its expiry date.
• CANCELLED: The payout link cannot be redeemed because it was cancelled.
• PROCESSING: Funds have been debited from the source account and are currently in the clearing cycle of the selected payment rail.
• PAID: Confirmation received from the clearing house that funds have been successfully credited to the recipient's account.

Use for filtering to retrieve only links in specified states. To specify multiple values, follow this pattern: state={VALUE1}&state={VALUE2}.

Type

array

createdBefore

the date-time at which the request is made

Retrieves links with createdAt < createdBefore. The default value is the current date and time at which you are calling the endpoint.

Provided in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Type

string

Example"2024-03-24T03:14:15Z"

Format

"date-time"

Pattern

"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

limit

The page size, indicating the number of entries returned per page.

Type

integer

Format

"int64"

Maximum

1000

Minimum

1

Default

100

page

This is the page number.

Type

integer

Example1

Minimum

1

Default

1

Responses

List of your payout links.

Content-Type

application/json

object

object

Required

This is the page number.

Minimum0

The page size, indicating the number of entries returned per page.

Minimum0

true if there are more pages available beyond this one.

object[]

Required

The date and time the payout link was created in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Format"date-time"

Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

The date and time the payout link was last updated in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Format"date-time"

Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

The URL of the payout link. Returned only for active payout links.

Format"uri"

Unique, client-generated identifier for the payout request. Used to track and reconcile the payout across your internal systems.

Min Length7

Max Length90

Pattern"^[-_a-zA-Z0-9]+$"

The unique cross-system identifier for the counterparty (e.g., ERP vendor ID). Facilitates seamless mapping between the Synthix ledger and your internal CRM/ERP.

Max Length36

Min Length3

Pattern"^[-_a-zA-Z0-9]+$"

The full legal name of the individual or entity as registered with their financial institution. Critical for matching during Anti-Money Laundering (AML) checks.

Min Length3

Max Length90

Pattern"^[-_ a-zA-Z0-9]+$"

object

Required

The debtor account identifier on the payout link. Can be either an IBAN (type: IBAN) or an account ID (type: ID).

Decimal string. 1–999999999.99, max 2 dp.

Pattern"^\\d{1,9}(\\.\\d{1,2})?$"

The 3-letter ISO 4217 currency code. Supported values: EUR, USD, GBP. This determines the settlement currency and applicable regional payment rails.

Valid values"EUR""USD""GBP"

A clear, descriptive narrative that appears on the recipient's bank statement. Essential for automated reconciliation and 'know your payment' (KYP) transparency.

Min Length3

Max Length90

Pattern"^[A-Za-z0-9_.,'-]+( +[A-Za-z0-9_.,'-]+)*$"

The specific payment rail (e.g., SEPA-INSTANT, ACH) used for fund disbursement. Each rail has distinct settlement times and clearing house rules.

Valid values"SEPA-CT""SEPA-INSTANT""US-ACH""UK-BACS""UK-FAST"

The expiry date and time for the payout link, expressed in ISO 8601 format. If the recipient does not claim the funds before the expiry, the link becomes invalid. The default and maximum expiry is 7 days from the time of link creation. Example: 2024-03-24T03:14:15Z.

Format"date-time"

Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

ISO 8601-shaped period after which the payout link expires
(e.g. p7d). Echoed verbatim from the create-request so clients
can reconcile by the chosen window rather than the absolute
expiryDate.

Valid values"pt10m""pt30m""pt1h""pt2h""pt4h""pt8h""pt12h""p1d""p2d""p3d""p4d""p5d""p6d""p7d""p10d""p15d""p20d""p25d""p30d"

Default"p7d"

Regulatory purpose code (e.g., SALARY, TAX) required by central banks for cross-border or high-value reporting (ISO 20022 compliant).

Valid values"SALARY""PENSION_PAYMENT""TAX_PAYMENTS""LOAN_REPAYMENT""DEBT_SETTLEMENT""INVOICE_PAYMENT""RENT_PAYMENT""GIFT_PAYMENT""DONATION""INSURANCE_PREMIUM_PAYMENT""SUBSCRIPTION_PAYMENT""ADVANCE_PAYMENT""REIMBURSEMENT""INTEREST_PAYMENT""DIVIDEND_PAYMENT""UTILITY_BILL_PAYMENT""FEE_PAYMENT""CREDIT_BALANCE_REFUND""CAPITAL_CONTRIBUTION""EXPENSE_REIMBURSEMENT""PAYMENT_FOR_SECURITIES""FUND_TRANSFER""CLAIM_PAYMENT""BONUS_PAYMENT""REPURCHASE""TREASURY_RELATED_PAYMENT""MISCELLANEOUS_PAYMENT""PAYMENT_FOR_SERVICES_RENDERED""DISPOSITION_OF_FUNDS""PARTIAL_PAYMENT_FOR_A_GOOD_OR_SERVICE"

Possible values: [ACTIVE, PENDING_APPROVAL, QUEUED, PROCESSING, PAID, FAILED, EXPIRED, CANCELLED]

• ACTIVE: The payout link is live and available for the recipient to claim. No funds have been moved yet.
• PENDING_APPROVAL: The recipient has provided details; the transaction is now undergoing internal treasury review or compliance screening.
• QUEUED: The payout link has been approved and is queued for payout processing.
• PROCESSING: Funds have been debited from the source account and are currently in the clearing cycle of the selected payment rail.
• PAID: Confirmation received from the clearing house that funds have been successfully credited to the recipient's account.
• FAILED: The payout link couldn't be paid due to a failure during transaction booking.
• EXPIRED: The payout link cannot be redeemed because it wasn't claimed before its expiry date.
• CANCELLED: The payout link cannot be redeemed because it was cancelled.

Valid values"ACTIVE""PENDING_APPROVAL""QUEUED""PROCESSING""PAID""FAILED""EXPIRED""CANCELLED"

The ID of the created transaction. Returned only if the payout has been claimed.

Format"uuid"

Possible values: ['MULTIPLE_ATTEMPTS','CANCELLED_ANCHOR_CLIENT','CANCELLED_COUNTERPARTY']
The reason for which the payout link was cancelled.

Valid values"MULTIPLE_ATTEMPTS""CANCELLED_ANCHOR_CLIENT""CANCELLED_COUNTERPARTY"

The field will store the value if the Counterparty rejects the link for the payout transaction, provided by the sender

Defines the rigor of bank account ownership validation (e.g., Pennies-drop, IBAN-name check) required before the payout is authorized for clearing.

Valid values"NO_VERIFICATION""MANDATORY_VERIFICATION""OPTIONAL_VERIFICATION"

This fields captures the maximum attempts allowed for account verification. This is an optional input applicable only if "accountVerificationOption" is "MANDATORY_VERIFICATION" or "OPTIONAL_VERIFICATION". Possible values are 3 or 5.

Valid values35

Optional reference to a branding template. When supplied, must exist, belong to the calling tenant, and be of payout type. If the referenced template is ACTIVE, the hosted payout-link page renders with the tenant's branding; otherwise Synthix defaults apply.

Format"uuid"

The mode in which the payout link is rendered. hosted: Synthix-hosted full-page checkout. embedded: partner-controlled iframe via the Synthix SDK.

Valid values"hosted""embedded"

Default"hosted"