# 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 <a href="#body-request" id="body-request"></a>

| Name            | Type   | Mandatory | Description                                                                                                                           |
| --------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization   | String | M         | <p>Represents Basic Authentication.</p><p>e.g. Basic dW5kZWZpbmVkOnBhc3N3b3Jk</p>                                                     |
| 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 <a href="#body-request" id="body-request"></a>

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

#### Sample Request <a href="#sample-request" id="sample-request"></a>

```
{
  "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 <a href="#body-response" id="body-response"></a>

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

#### Sample Response <a href="#sample-response" id="sample-response"></a>

```
{
"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) <a href="#sample-response" id="sample-response"></a>

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

```

### Create Payout Status <a href="#sample-response" id="sample-response"></a>

<table><thead><tr><th width="79">No</th><th width="145">Status</th><th valign="top">Description</th></tr></thead><tbody><tr><td>1</td><td>ACCEPTED</td><td valign="top">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.</td></tr><tr><td>2</td><td>REQUESTED</td><td valign="top">The payout has been sent to the channel. Funds have been sent to the channel for processing.</td></tr><tr><td>3</td><td>FAILED</td><td valign="top">Payout failed. See possible reasons in Failed Reasons section.</td></tr><tr><td>4</td><td>SUCCEEDED</td><td valign="top">Sender bank/channel has sent out the payout</td></tr><tr><td>5</td><td>CANCELLED</td><td valign="top">Payout has been cancelled per your request</td></tr><tr><td>6</td><td>REVERSED</td><td valign="top">Payout was rejected by the channel after the payout succeeded. Commonly due to invalid or dormant account.</td></tr></tbody></table>

### Create Payout HTTP Status Code <a href="#sample-response" id="sample-response"></a>

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.finpay.id/api-reference/finpay-wallet-as-a-service/core-api/create-payout.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.