Processing a payout

Flow, statuses, return codes, retries, credit reversals, webhooks and sandbox testing for payouts.

This page walks through a payout from request to final status: the sequence of calls, the statuses, the return codes, what to do when the result is unknown, and how to test in Sandbox.

Sequence

  1. Tokenize

    Tokenize the beneficiary card with Create a token.

  2. Create the transfer

    Call Create a transfer with the token, the amount, the purpose and your order_merchant_id.

  3. Eligibility and credit

    The platform validates the request, checks the card's eligibility with the partner when the contract requires it, then sends the credit.

  4. Status

    The response carries the final or pending status. A webhook follows every status change.

  5. Pending result

    Wait for the final webhook, or call Retrieve a transfer.

Example

The request below creates a transfer with Create a transfer. All fields are described there.

{
  "transfer_type": "oct",
  "transfer_purpose": "online_gambling_payout",
  "amount": 250.00,
  "currency": "EUR",
  "order_merchant_id": "PAYOUT-2026-11-0041",
  "merchant_contract": "69fb373bacda23a62375d5b0",
  "destination_account_type": "card",
  "destination_account_token": "3554757d2b2039e34d4f43950ba1ac475904492b9d03d2b964f237ad51a0ec16",
  "destination_account_id": "PLAYER-0635656565",
  "destination_account_first_name": "John",
  "destination_account_last_name": "Doe",
  "destination_account_country": "FR"
}
{
  "result": { "code": "980001", "description": "credit successful" },
  "order_id": "69fdb213cf4304374840f155",
  "transaction_id": "69fdb213cf4304374840f157",
  "status": "credit_successful",
  "category": "payout",
  "transfer_type": "oct",
  "transfer_purpose": "online_gambling_payout",
  "order_amount": 250.00,
  "order_currency": "EUR",
  "order_merchant_id": "PAYOUT-2026-11-0041",
  "payment_method_name": "visa",
  "destination_account_type": "card",
  "destination_account_token": "3554757d2b2039e34d4f43950ba1ac475904492b9d03d2b964f237ad51a0ec16",
  "destination_account_id": "PLAYER-0635656565",
  "destination_account_last_4_digits": "5987",
  "destination_account_scheme": "visa",
  "destination_account_funding_type": "debit",
  "destination_account_country": "FR",
  "is_eligible": true,
  "eligibility_status": "eligibility_approved",
  "is_credited": true,
  "credit_date": "2026-11-16T12:30:05Z",
  "credit_status": "credit_successful",
  "payout_partner": "MockPay",
  "merchant_contract_id": "69fb373bacda23a62375d5b0",
  "psp_result_code": "0",
  "psp_result_description": "Success",
  "psp_transaction_id": "psp_txn_8a8294a71c33",
  "network_reference_id": "654321123456",
  "authorization_code": "123456"
}

Status flow

A payout ends in one final state. Only credit_successful moves funds. When the eligibility check is disabled on the contract, the payout goes straight from created to credit_requested.

Payout status flow: created, then eligibility, then credit. Only credit_successful moves funds; credit_reversed can follow it later. Eligibility can be skipped when the check is disabled on the contract.REQUESTELIGIBILITYCREDITcreatedeligibility_requestedeligibility_approvedcredit_requestedeligibility_declinedeligibility_request_failedEligibility checkdisabled onthe contractcredit_successfulcredit_declinedcredit_request_failedcredit_request_expiredReturned by the partner, latercredit_reversedPendingFunds creditedFailed, no funds movedFunds returned after a credit

Statuses

StatusMeaningOrder stateFinal
createdRequest accepted, not yet sent.pendingNot final
eligibility_requestedCard eligibility being checked with the partner.pendingNot final
eligibility_approvedThe card can receive the credit.pendingNot final
eligibility_declinedThe card cannot receive an OCT. No credit attempted.failedFinal
eligibility_request_failedTechnical failure on the eligibility check.failedFinal
credit_requestedCredit sent, partner result pending.pendingNot final
credit_successfulFunds credited to the beneficiary.closedFinal
credit_declinedRefused by the partner or the issuer. No funds moved.failedFinal
credit_request_failedTechnical failure (timeout, 5xx). Result unknown.failedFinal
credit_request_expiredNo final result within the expiry delay.failedFinal
credit_reversedFunds returned by the partner after a successful credit.closedFinal
route_not_foundNo eligible payout contract.failedFinal
blocked_by_routerBlocked by a routing rule.failedFinal

The same statuses are returned in status by Create a transfer and Retrieve a transfer, and listed in Order status.

Return codes

Payout return codes follow the return code structure. The first digit 8 is the credit phase. Error responses use the envelope described in Errors.

CodeStatusMeaningWhat to do
980001credit_successfulCredit successful.Nothing. The funds are on their way.
821001credit_requestedCredit requested, pending at the partner.Wait for the final webhook, or call Retrieve a transfer.
821101credit_declinedCredit declined by the issuer.Do not retry as is. Check the card and the purpose.
821201credit_reversedCredit reversed, funds returned.Reconcile: the beneficiary did not keep the funds.
810001credit_request_failedCredit request failed (technical).Result unknown. Call Retrieve a transfer before any new attempt.
811001credit_request_expiredNo final result within the expiry delay.Same as 810001.
840001eligibility_declinedDestination card not eligible for OCT.Ask the beneficiary for another card.
840101eligibility_declinedIssuer does not support money transfers.Ask the beneficiary for another card.
841001credit_declinedDestination account closed or invalid.Ask the beneficiary for another card.
850001route_not_foundTransfer purpose not supported by the contract.Use another purpose or another contract.
851001route_not_foundNo payout contract for this country or currency, or merchant_contract is not a payout contract.Check merchant_contract.
861001NoneRequest incomplete: purpose code or beneficiary data missing for this corridor.Complete the request. See Specification.
861003NoneDuplicate order_merchant_id for a payout.Use a new order_merchant_id, and check the result of the first transfer.
861005NoneBoth original_transaction_id and psp_original_transaction_id sent.Send only one.
861006NoneThis contract requires an original transaction reference.Add one of the two reference fields.
861007NoneA card number was sent in an account number field.Tokenize the card with Create a token and use destination_account_token.
111012NoneInvalid parameter: a field that is not accepted on a transfer was sent.Remove the field. See Create a transfer.

Retries and duplicates

The platform never retries a credit

A replayed request could pay the beneficiary twice, so a failed credit is never sent again automatically.

On credit_request_failed (810001), the partner may or may not have processed the credit. Before you submit a new transfer:

  1. Check the transfer

    Call Retrieve a transfer and check the status.

  2. Check the partner

    Look the payout up in your partner reporting.

  3. Ask if in doubt

    Contact Support before you send a new transfer.

order_merchant_id is unique per API key for payouts. A duplicate is rejected with 861003.

Credit reversal

The partner can return the funds after a successful credit, for example when the account is closed or the scheme returns the credit. The transaction keeps is_credited: true and gains is_credit_reversed: true with credit_reversal_amount. The status becomes credit_reversed and a webhook is sent. Retrieve a transfer returns the reversal fields on the credit transaction.

Both legs are kept, never netted.

Webhooks

Payout webhooks use the same delivery, signature and retry policy as payment webhooks. See Accept webhooks and Webhooks workflow.

ItemDetails
Events to subscribecredit_requestedcredit_successfulcredit_declinedcredit_request_failedcredit_request_expiredcredit_reversedeligibility_declined

The other eligibility events are available too. See Payout events.

Default payloadrequest_idorder_idtransaction_idmerchant_order_idmerchant_contract_idcategorystatusaction_dateamountcurrencyconverted_amountconverted_currencytransfer_typetransfer_purposetransfer_referencepayment_methodpayout_partneris_eligibleis_creditedcredit_datecredit_statuscredit_resultcredit_reasonis_credit_reversedcredit_reversal_datecredit_reversal_statuscredit_reversal_resultcredit_reversal_amountcredit_reversal_reasoncredit_reversal_reason_codepsp_result_codepsp_result_descriptionmerchant_accountprogram_managerevent_typemerchant_data

Every payout notification carries category: "payout".

Optional fieldsAddable per webhook in the Console: the destination_account_* fields (never the account number), eligibility_status and eligibility_reason.
Always presentorder_idtransaction_idstatusmerchant_account
Never sentcapture_total_amountrefund_total_amountis_capturableauthentication_*card_6_digits

Payment-only fields.

Handle several notifications per payout

A payout can receive several webhooks over several days: pending, final, then a reversal. Delivery is at-least-once and unordered.

  • Handle duplicates idempotently on transaction_id + status.
  • Order events by action_date.

Test in Sandbox

On the sandbox payout contract, the amount sent to Create a transfer drives the result:

AmountResult
20.12eligibility_declined
25.48credit_declined
Any other amountcredit_successful

Related pages