> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commercepay.asia/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Payout

> Request a payout and transfer funds via bank account or DuitNow Proxy.

An API endpoint used to request a payout and transfer funds to the specified recipients through a bank account or DuitNow Proxy.

## Request

### Headers

<ParamField header="Abp-TenantId" type="string" required>
  Your unique Merchant ID assigned by CommercePay.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your API credentials used for authentication (typically a Bearer token).
</ParamField>

<ParamField header="cap-signature" type="string" required>
  A unique security hash used to verify the integrity of the request body. See [Generate Signature](/docs/generate-signature) for how to generate this.
</ParamField>

### Body

<ParamField body="channelId" type="integer" required>
  An identifier that represents a CommercePay payments channel. Production Payout ChannelId: 9. Staging Payout ChannelId: 15.
</ParamField>

<ParamField body="providerChannelId" type="string" required>
  An identifier that represents the payment method (Bank or DuitNow Proxy). You can obtain the providerChannelId via the [Get Provider Channels API](/api-reference/get-provider-channels) or refer to it [here](/docs/payout-provider-channel).
</ParamField>

<ParamField body="currencyCode" type="string" required>
  Currency code with a 3-letter ISO 4217 standard code. Maximum length: 3. Example: `MYR`.
</ParamField>

<ParamField body="amount" type="int64" required>
  Payout amount. This field accepts only integer values. For example, 1050 represents 10.50.
</ParamField>

<ParamField body="referenceCode" type="string" required>
  Merchant reference code. Maximum length: 50.
</ParamField>

<ParamField body="description" type="string">
  Transaction description. Maximum length: 100.
</ParamField>

<ParamField body="ipAddress" type="string" required>
  Customer's IP address captured by the merchant system. Maximum length: 50.
</ParamField>

<ParamField body="userAgent" type="string">
  Customer's user agent. Maximum length: 200.
</ParamField>

<ParamField body="returnUrl" type="string" required>
  A return URL provided by the merchant. The user can be redirected to the final destination page from the CommercePay receipt page after the transaction payment has been completed. Maximum length: 500.
</ParamField>

<ParamField body="callbackUrl" type="string">
  A URL provided by the merchant to receive server-to-server notifications from the system regarding transaction status updates. This URL is called automatically once the payment process is completed or when the transaction status changes. Maximum length: 500.
</ParamField>

<ParamField body="customer" type="object" required>
  <Expandable title="properties">
    <ParamField body="customer.email" type="string">
      Customer's email address. Maximum length: 150.
    </ParamField>

    <ParamField body="customer.mobileNo" type="string">
      Customer's mobile number. Required when processing a payout via DuitNow Proxy using a mobile number. Maximum length: 16.
    </ParamField>

    <ParamField body="customer.name" type="string">
      Customer's name. Required when processing a payout via bank transfer. Maximum length: 36.
    </ParamField>

    <ParamField body="customer.username" type="string">
      A field for bank account number, national ID (NRIC) or Business Registration Number. Maximum length: 36.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="localCitizen" type="boolean" required>
  If the customer is Malaysian, set this to true; otherwise, set it to false.
</ParamField>

<ParamField body="timestamp" type="int64" required>
  Current timestamp. Example: `1621851652617`.
</ParamField>

### Request Payload Sample

```json Payout_With_Bank theme={null}
{
  "channelId": 15,
  "providerChannelId": "UOVBMYKL",      // Beneficiary Bank Swift Code 
  "currencyCode": "MYR",
  "amount": 1000,
  "referenceCode": "BankPayout_1",
  "description": "BankPayout_1",
  "ipAddress": "202.184.234.13",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:106.0) Gecko/20100101 Firefox/106.0",
  "returnUrl": "https://staging-web-payments.commerce.asia",
  "callbackUrl": "https://callback.com",
  "customer": {
    "email": "ATD@commerce.asia",
    "mobileNo": "0101234567",
    "name": "ACCOUNT DUITNOW - HYPHEN ACCOUNT DUITNOW - HYPHEN",      // Beneficiary Bank Account Name
    "username": "2093011793"      // Beneficiary Bank Account Number
  },
  "localCitizen": true,
  "timestamp": 1669862494
}
```

```json Payout_With_DuitNow_Proxy theme={null}
{
  "channelId": 15,
  "providerChannelId": "NRIC",      // Proxy Mode 
  "currencyCode": "MYR",
  "amount": 1000,
  "referenceCode": "ProxyPayout_1",
  "description": "ProxyPayout_1",
  "ipAddress": "202.184.234.13",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:106.0) Gecko/20100101 Firefox/106.0",
  "returnUrl": "https://staging-web-payments.commerce.asia",
  "callbackUrl": "https://callback.com",
  "customer": {
    "email": "ATD@commerce.asia",
    "mobileNo": "0101234567",
    "name": "John",
    "username": "660124020789"      // National ID Or Business Registration Number
  },
  "LocalCitizen": true,
  "timestamp": 1669862494
}
```

## Response

### Body

<ResponseField name="currencyCode" type="string">
  Payout currency. Maximum length: 3.
</ResponseField>

<ResponseField name="amount" type="integer">
  Payout amount. For example, 1050 represents 10.50.
</ResponseField>

<ResponseField name="transactionNumber" type="string">
  Unique CommercePay Transaction Number. Maximum length: 24.
</ResponseField>

<ResponseField name="channelId" type="integer">
  An identifier that represents a CommercePay payments channel.
</ResponseField>

<ResponseField name="redirectionType" type="integer">
  Represents the **redirectUrl** type. This field returns 1 (URL redirection).
</ResponseField>

<ResponseField name="redirectUrl" type="string">
  URL used for the customer to redirect to the payment page.
</ResponseField>

### Response Payload Sample

```json Response_2XX theme={null}
{
  "result": {
    "currencyCode": "MYR",
    "amount": 1000,
    "transactionNumber": "20061769514A13A0A02260425",
    "channelId": 15,
    "redirectionType": 1,
    "redirectUrl": "https://dev-payments.commerce.asia/paymentgateway/Return/15?exchangeToken=QVNNMGd5Nmh5NzAxNnp3RkRUOVdRbFIzakcrM0ZHRnJmRmZkUlp5aDNuaz0"
  }
}
```

## Error Responses

| Code | Message                  |
| ---- | ------------------------ |
| 2056 | `Failed Payment Request` |
| 1    | `Invalid Signature.`     |

```json Response_400 theme={null}
{
  "result": null,
  "error": {
    "code": 2056,
    "message": "Failed Payment Request"
  }
}
```

```json Response_400 theme={null}
{
  "result": {
    "code": 1,
    "message": "Invalid Signature."
  },
  "error": null
}
```