Initiate a Payout request

Initiate a Payout request

Create a payout request to a beneficiary. Parts of the schema will depend on the payment method you wish to use to do the payout.

Note that you may send a payout request in either Local Currency or USD. Please confirm with your account manager.

The end beneficiary will receive payout in Local Currency only.

Endpoint

Environment	Method	URL
Sandbox	POST	https://payout.codapayments-staging.com/payouts
Production	POST	https://payout.codapayments.com/payouts

Request parameters

Parameter	Type	Required	Description	Validation
payout_method	Object	Yes	Details of the payout method to use	See payout_method details below
amount	Object	Yes	Details of the amount	See amount details below
country_code	string	Yes	2-letter country code ISO 3166	2 letters e.g. Egypt: “EG” See “Country_code & currency_code list” below.
purpose	string	Yes	Purpose of the payout	Enum: “revenue_share”, “salaries”, “payment_for_suppliers” Pakistan: Influencer payments should be reported as “revenue_share”. These will be charged withholding tax.
reference	string	No	This is a reference you wish to attach to the payout. It will be displayed to the beneficiary if the payment method used allows it.	This is a free text field. Max 255 char
request_id	string	Yes	A unique request ID that is attached to the payout request, created by Merchant. Please note that this has to be idempotent.	Only allow alphanumeric characters, hyphen “-”, and underscore “_”

amount

Parameter	Type	Required	Description	Validation
value	number	Yes	Request amount – total requested payout amount.	Max decimal place: 2
currency_code	string	Yes	Request currency – currency of the request amount. 3-letter currency code ISO 4217.	3 letters e.g. EGP See “Country_code & currency_code list” below.

payout_method

Parameter	Type	Required	Description	Validation
type	string	Yes	Payout method used	Enum: ”bank_transfer”, “wallet”
payment_method	string	Yes	Payment method used	One of the payment methods supported. See “Country details” below for supported methods in each country.
beneficiary	Object	Yes	Details of the beneficiary	See beneficiary details below

beneficiary

Parameter	Type	Required	Description	Validation
name	string	Yes	Recipient’s full name	Max 255 char
payout_method_details	Object	Yes	Details on the recipient’s account for the specified payment channel.	See “Country details” below for supported methods in each country.

Depending on the payment channel you want to use to send the payout to the beneficiary, the “payout_method_details” object would be named differently and have different mandatory fields. You can find below the list of payment channels supported and the mandatory fields for each.

Response parameters

Parameter	Description
payout_method.type	Country code + the Payout method used, passed in the request
amount.value	Request amount – total requested payout amount. Passed in the API request.
amount.currency_code	Request currency – currency of the request amount. 3-letter currency code ISO 4217, passed in the API request.
country_code	Country of payout. 2-letter country code ISO 3166, passed in the API request
purpose	Purpose of payout, passed in the API request
reference	Free text, passed in the API request
request_id	A unique request ID that is attached to the payout request, created by Merchant. Passed in the API request.
due_date	As passed in the API request
id	Coda payout transaction id: string