Create Payout

Create Payout API is used to disburse funds from a sub-account to a destination bank account.

Environment	Method	URL
Development	POST	https://devo.finnet.co.id/payout/create
Production	POST	https://{tba}/payout/create

Header Request

Name	Type	Mandatory	Description
Authorization	String	M	Represents Basic Authentication. e.g. Basic dW5kZWZpbmVkOnBhc3N3b3Jk
Idempotency-key	String	M	A unique key to prevent processing duplicate requests. Can be your reference_id or any GUID.
accept	String	M	Mandatory header to specify the response format. Must be set to application/json so the server returns the response in JSON format.
for-user-id	String	M	Sub-account user ID that this payout is created for

Body Request

No	Name	Type	Mandatory	Min Length	Max Length	Description
1	reference_id	string	Yes		255	Client unique reference for this payout
2	channel_code	string	Yes		5	Destination bank channel code (example: 91014)
3	channel_properties	object	Yes		-	Destination account details
3.1	channel_properties.account_number	string	Yes		50	Destination account number
3.2	channel_properties.account_holder_name	string	Yes		255	Destination account holder name
4	amount	number	Yes		-	Payout amount (in the specified currency)
5	description	string	No		255	Optional payout note/description
6	currency	string	Yes		3	Currency code (ISO 4217), example: IDR

Sample Request

{
  "reference_id": "myref-1482928194",
  "channel_code": "91014",
  "channel_properties": {
    "account_number": "000000000099",
    "account_holder_name": "Michael Chen"
  },
  "amount": 10000,
  "description": "July payout",
  "currency": "IDR"
}

Body Response

No	Name	Type	Mandatory	Min Length	Max Length	Description
1	id	string	Yes		36	Unique payout ID generated by the system
2	amount	number	Yes		-	Payout amount
3	channel_code	string	Yes		5	Payout channel code
4	currency	string	Yes		3	Currency code (ISO 4217)
5	reference_id	string	Yes		255	Client reference for this payout
6	status	string	Yes		20	Payout status: ACCEPTED COMPLETED FAILED SUCCEEDED CANCELLED REVERSED
7	created	string (date-time)	Yes		24	Payout creation timestamp (ISO 8601)
8	updated	string (date-time)	Yes		24	Last payout update timestamp (ISO 8601)
9	estimated_arrival_time	string (date-time)	No		24	Estimated time the funds will arrive
10	failure_code	string	No		50	Payout failure code (only when the payout fails)
11	business_id	string	Yes		36	Business / merchant ID
12	channel_properties	object	Yes		-	Destination account details
12.1	channel_properties.account_holder_name	string	Yes		255	Destination account holder name
12.2	channel_properties.account_number	string	Yes		50	Destination account number
12.3	channel_properties.account_type	string	No		20	Destination account type
13	receipt_notification	object	No		-	Receipt notification settings
13.1	receipt_notification.email_to	array[string]	No		-	Primary recipient email list
13.2	receipt_notification.email_cc	array[string]	No		-	CC email list
13.3	receipt_notification.email_bcc	array[string]	No		-	BCC email list
14	metadata	object	No		-	Custom additional data from the client
14.1	metadata.my_custom_id	string	No		255	Merchant custom ID
14.2	metadata.my_custom_order_id	string	No		255	Merchant custom order ID

Sample Response

{
"id": "disb-571f3644d2b4edf0745e9703",
"amount": 10000,
"channel_code": "91014",
"currency": "string",
"reference_id": "myref-1482928194",
"status": "ACCEPTED",
"created": "string",
"updated": "string",
"estimated_arrival_time": "string",
"failure_code": "INSUFFICIENT_BALANCE",
"business_id": "5785e6334d7b410667d355c4",
"channel_properties": {
  "account_holder_name": "string",
  "account_number": "string",
  "account_type": "string"
},
"receipt_notification": {
  "email_to": [
   "string"
  ],
  "email_cc": [
   "string"
  ],
  "email_bcc": [
   "string"
  ]
},
"metadata": {
  "my_custom_id": "merchant-123",
  "my_custom_order_id": "order-123"
}
}

Sample Response (Negative)

{
    "error_code": "CHANNEL_CODE_NOT_SUPPORTED_ERROR",
    "message": "Channel code is not supported"
}

Create Payout Status

No	Status	Description
1	ACCEPTED	The payout request has been accepted and has not yet been sent on to a channel. A payout may remain in this status if the chosen channel is currently offline.
2	REQUESTED	The payout has been sent to the channel. Funds have been sent to the channel for processing.
3	FAILED	Payout failed. See possible reasons in Failed Reasons section.
4	SUCCEEDED	Sender bank/channel has sent out the payout
5	CANCELLED	Payout has been cancelled per your request
6	REVERSED	Payout was rejected by the channel after the payout succeeded. Commonly due to invalid or dormant account.

Create Payout HTTP Status Code

No	HTTP Status Code	HTTP Status Description	Description
1	400	DUPLICATE_ERROR	A payout with this idempotency key already exists. If you meant to execute a different request, please use another idempotency key
2	400	API_VALIDATION_ERROR	Should have required property xxx amount should have 2 decimal places or less expires_at should be at least 2 days from now and not exceeding 90 days channel_code is not supported. See list of supported channel codes at the URL below
3	400	MINIMUM_TRANSFER_LIMIT_ERROR	"amount” is under the minimum amount supported for the channel. See amount limitations at the URL below
4	400	MAXIMUM_TRANSFER_LIMIT_ERROR	“amount” is more than the maximum amount supported for the channel. See amount limitations at the URL below
5	400	AMOUNT_INCREMENT_NOT_SUPPORTED	“amount” needs to be a multiple of the minimum increment supported by the channel
6	401	INVALID_API_KEY	API key format is invalid
7	403	REQUEST_FORBIDDEN_ERROR	The API key is forbidden to perform this request
8	500	SERVER_ERROR	Error connecting to our server. Retry safely using Idempotency-key header when available