Skip to content

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.