Specification
Transfer purpose, fields required by country, and referenced payouts.
This page covers the payout rules that are not obvious from the field list: how to choose the transfer purpose, which fields become required by country, and how to reference an original payment. For every field, see Create a transfer and Retrieve a transfer.
Choose the transfer purpose
Send one transfer_purpose value. The platform maps it to the Visa Business Application Identifier (BAI) and the Mastercard Transaction Type Identifier (TTI). The same values are listed in Available values.
Pick the value that describes the business reason of the payout. Schemes and issuers use it to accept or decline the credit, and a wrong purpose is a common cause of declines.
| transfer_purpose | Typical use | Visa BAI | Mastercard TTI |
|---|---|---|---|
online_gambling_payout | Online gaming or betting winnings | OG | C04 |
gambling_payout | Land-based gambling winnings | GP | C04 |
liquid_assets_transfer | Crypto or investment off-ramp | LA | C07 |
p2p_transfer | Person-to-person transfer | PP | C07 |
merchant_disbursement | Marketplace seller or partner settlement | MD | C57 |
disbursement | General disbursement (insurance, claims) | FD | C55 |
payroll_payout | Salary, gig-worker earnings | PD | Not supported |
business_to_business | B2B payment | BB | C65 |
merchant_initiated_transfer | Merchant-initiated transfer | MI | C60 |
me_to_me | Account to account, same person | AA | C52 |
funds_transfer | Generic funds transfer | FT | C52 |
government_payout | Government disbursement | GD | C56 |
card_bill_payment | Card bill payment | CP | C54 |
cash_deposit | Cash deposit | CD | C59 |
bank_initiated_transfer | Bank-initiated transfer | BI | Not supported |
bill_payment | Bill payment | BP | Not supported |
consumer_bill_payment | Consumer bill payment | CB | Not supported |
payment_to_government | Payment to government | PG | Not supported |
payment_for_goods_services | Payment for goods and services | PS | Not supported |
wallet_load | Wallet load | WT | Not supported |
topup_prepaid_load | Prepaid top-up | TU | Not supported |
Mastercard has no OCT indicator for this purpose. The request is sent without a TTI, and the partner or the issuer decides. For Mastercard cards, prefer a supported purpose when the business case allows it.
Fields required by country
| Beneficiary country | Required fields |
|---|---|
| AR, BD, CL, CO, EG, IN, SA | transfer_purpose_code: ISO purpose code, for example ISPAYR, ISSALA or ISOTHR. |
| CA, AU, NZ | The beneficiary address: destination_account_street_name, destination_account_city, destination_account_state, destination_account_zip_code. |
| Cross-border payouts | May require destination_account_birth_date and the sender_* fields. Requirements are confirmed per corridor. |
A request that misses a field required for its corridor is rejected with 861001. See Return codes.
The beneficiary
destination_account_first_name and destination_account_last_name are required, unless the beneficiary is the customer of the request. In that case, send destination_account_is_customer: true with the customer_* fields.
Never send a card number. Tokenize the card with Create a token and pass the token in destination_account_token. A card number sent in destination_account_number is rejected with 861007.
The sender
Send the sender_* fields only for PayFac, marketplace or on-behalf-of payouts. When they are omitted, the merchant of the payout contract is the sender. The accepted values of sender_account_type and sender_source_of_funds are in Create a transfer.
Referenced payouts
Some partners only credit a card that was charged before. Reference the original payment with one of these fields, never both:
| Field | When to use it |
|---|---|
original_transaction_id | The payment was processed by the platform. Send its transaction_id, as returned by Retrieve an order. It must belong to your merchant account and be captured. |
psp_original_transaction_id | The payment was processed elsewhere. Send the partner-side identifier; it is passed through as is. |
Sending both fields returns 861005. A contract that requires a reference returns 861006 when neither is sent.
Related pages
Updated 5 days ago