Add a new payout link

payout-links

POST

/api/v1/payout-links

Create a payout link to send money even when you don't have the full banking details of the counterparty.

After you have created the link, send it to the recipient so that they can claim the payment.

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"

Request Body

application/json

object

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. Required when creating a new counterparty (i.e., when no existing counterpartyReference is provided). 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).

Type of account identifier.
IBAN — International Bank Account Number (EUR/GBP accounts).
ID — Local account number.

Valid values"ID""IBAN"

Value of the account identifier.
For IBAN: uppercase alphanumeric, e.g. DE89370400440532013000.
For ID: digits only — 9-18 digits for INR, any digits for USD.

Min Length1

Max Length34

Pattern"^[A-Z0-9]+$"

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 operational window (ISO 8601 duration) for the recipient to interact with the link. Expired links release the soft-hold on reserved funds. Values shorter than p1d (pt10m..pt12h) are only valid when uiMode is embedded; supplying them with uiMode: hosted (or the default) returns 400.

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

Format"iso8601"

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"

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"

Where the payout link is rendered. hosted (default): Synthix-hosted full-page checkout. The returned url opens in a top-level browsing context. expiryPeriod must be at least p1d (24 h). embedded: page is loaded inside a partner-controlled iframe via the Synthix SDK. Shorter expiryPeriod values (pt10m..pt12h) are accepted; the partner origin must be on the tenant's allowed-SDK-origins allowlist.

Valid values"hosted""embedded"

Default"hosted"