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_purposeTypical useVisa BAIMastercard TTI
online_gambling_payoutOnline gaming or betting winningsOGC04
gambling_payoutLand-based gambling winningsGPC04
liquid_assets_transferCrypto or investment off-rampLAC07
p2p_transferPerson-to-person transferPPC07
merchant_disbursementMarketplace seller or partner settlementMDC57
disbursementGeneral disbursement (insurance, claims)FDC55
payroll_payoutSalary, gig-worker earningsPDNot supported
business_to_businessB2B paymentBBC65
merchant_initiated_transferMerchant-initiated transferMIC60
me_to_meAccount to account, same personAAC52
funds_transferGeneric funds transferFTC52
government_payoutGovernment disbursementGDC56
card_bill_paymentCard bill paymentCPC54
cash_depositCash depositCDC59
bank_initiated_transferBank-initiated transferBINot supported
bill_paymentBill paymentBPNot supported
consumer_bill_paymentConsumer bill paymentCBNot supported
payment_to_governmentPayment to governmentPGNot supported
payment_for_goods_servicesPayment for goods and servicesPSNot supported
wallet_loadWallet loadWTNot supported
topup_prepaid_loadPrepaid top-upTUNot supported
"Not supported" for Mastercard

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 countryRequired fields
AR, BD, CL, CO, EG, IN, SAtransfer_purpose_code: ISO purpose code, for example ISPAYR, ISSALA or ISOTHR.
CA, AU, NZThe beneficiary address: destination_account_street_name, destination_account_city, destination_account_state, destination_account_zip_code.
Cross-border payoutsMay 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:

FieldWhen to use it
original_transaction_idThe 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_idThe 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