Payouts¶
A payout sends an amount to one beneficiary account; you create the beneficiary once, then pay its account by id. All payout routes need an ADVANCED_ACCESS or FULL_ACCESS key.
Object model¶
| Object | What it is |
|---|---|
| Payout destination | The beneficiary: a person (PERSONAL) or a company (CORPORATE). Bound to one of your provider bindings (merchantPaymentProviderId), which sends its payouts. |
| Payout destination account | One set of bank details of that beneficiary, in one currency, on one payment system (e.g. EUR / SEPA). Created and returned with its destination. |
| Payout | One payment of an amount to one account. Currency, payment system and provider come from the account; you do not send them. |
Ask Payard for the merchantPaymentProviderId of the binding you pay out through, or read it with POST /merchant-payment-provider/get-all.
Create a beneficiary¶
POST /payout-destination/create
{
"merchantPaymentProviderId": "7d2e4b1a-5c3f-4e8d-9a6b-2f1c0e7d8a94",
"name": "Mueller Consulting GmbH",
"type": "CORPORATE",
"PayoutDestinationAccounts": [
{
"currencyId": "EUR",
"paymentSystemId": "SEPA",
"status": "ACTIVE",
"bankDetails": {
"accountHolderName": "Mueller Consulting GmbH",
"accountHolderNameType": "ACCOUNT_HOLDER_NAME",
"financialAccountId": "DE89370400440532013000",
"financialAccountIdType": "IBAN",
"financialInstitutionCode": "COBADEFFXXX",
"financialInstitutionCodeType": "BIC",
"accountHolderCountry": "DEU",
"bankCountry": "DEU"
}
}
]
}
The 201 answer is the destination with PayoutDestinationAccounts[], each with its id. Store the account id: a payout names it. This call is not idempotent; sending it twice creates two beneficiaries.
bankDetails field |
Required | Notes |
|---|---|---|
accountHolderName |
yes | ≤ 120 characters |
accountHolderNameType |
yes | ACCOUNT_HOLDER_NAME, ACCOUNT_NAME, USER_IDENTIFIER, NPP_DESCRIPTION, PAY_ID_NAME |
financialAccountId |
yes | IBAN, account number, PayID…; whitespace is removed |
financialAccountIdType |
yes | IBAN, ACCOUNT_NUMBER, PAY_ID, EMAIL, CLABE, VIRTUAL_ACCOUNT_ID, ROLL_NUMBER, … |
financialInstitutionCode / financialInstitutionCodeType |
for non-IBAN accounts | e.g. BIC, SORT_CODE, BSB_NUMBER, ROUTING_NUMBER |
accountHolderCountry, bankCountry |
no | ISO alpha-3 only |
accountHolderCity, accountHolderAddress, bankName, bankAddress |
no | Free text |
If your provider keeps pre-registered beneficiaries, send only { "bankDetails": { "originalDestinationAccountId": "<provider's account id>" } } instead.
Read beneficiaries with GET /payout-destination/get-one/:id and POST /payout-destination/get-all. Beneficiary and account statuses are yours to maintain: keep them current and pay out only to ACTIVE accounts.
Create a payout¶
POST /payout/create
{
"amount": 125000,
"destinationAccountId": "9f1c1b6e-4a2d-4c3b-a8e7-5d6f2b9c1e03",
"idempotencyKey": "b2e3f9aa-88e1-4a76-9df8-7c1b9b8f1a88",
"reference": "INV-2026-0412",
"country": "DEU",
"comment": "November settlement"
}
| Field | Required | Notes |
|---|---|---|
amount |
yes | Integer > 0, minor units of the account currency |
destinationAccountId |
yes | The account id from the beneficiary |
idempotencyKey |
strongly recommended | UUID v4; omit it rather than send null, which is refused |
reference |
no | ≤ 100 characters |
comment |
no | ≤ 500 characters |
country |
no | Alpha-2 or alpha-3. Some providers require it; it must be allowed for the account's payment system. |
payoutSourceId + payoutSourceType |
no, together | Your source of funds; type ACCOUNT, CLIENT, WALLET, PAYMENT_ORDER, OTHER |
purposeCode |
no | ≤ 5 characters, e.g. ACCT; only for payment systems that need one |
The 201 answer is the payout in status INITIATED, with id and a human-readable code (e.g. POUT7K3M9Q2XBD). It means accepted, not paid.
Idempotency. The same key returns the same payout; the rest of the body is not compared. On a timeout, resend with the same key. To check without any chance of paying, search instead: POST /payout/get-all with { "idempotencyKeys": ["<key>"] }; an empty data means the payout was never created. A CONFLICT (409) means another merchant already used that key.
Pre-flight (optional). To confirm that payouts are enabled for a provider before you create one, call POST /core/payment-provider-config with { "paymentMethod": "BANK_TRANSFER", "paymentProviderId": "<provider id>" } and read canPayout. Do not send currencies for this check.
Recording a payout made elsewhere. With "dispatchToProvider": false plus a final status (and optionally statusReason, originalPayoutId, executedAt), Payard records the payout without sending it. Spell the switch exactly: an unknown field is dropped, and the payout would then be sent for real.
Statuses¶
| Status | Meaning |
|---|---|
INITIATED |
Accepted and queued for the provider |
IN_PROGRESS, ON_HOLD, UNKNOWN |
Not final |
COMPLETED |
Final: paid |
FAILED, CANCELED, DECLINED, BLOCKED, EXPIRED |
Final: not paid; see statusReason |
Read one payout with GET /payout/get-one/:id; list them with POST /payout/get-all (e.g. { "statuses": ["INITIATED", "IN_PROGRESS", "ON_HOLD", "UNKNOWN"] }). Poll non-final payouts periodically as a safety net alongside webhooks.