# CNY Payout (new encryption)

Summary

Unlock seamless cross-border payments with the Payout API for CNY, enabling businesses/customers to send funds to recipients in China efficiently.

## Integration steps

The integration process involves the following key steps:

* **Generate a Bearer Token:** Authenticate to get your access token.
* **Create a Quotation:** Get a quote for the amount you wish to transfer. This quote will provide the exchange rate, fees, and a unique `quotationId`.
* **Get Bank Codes (for BANK\_ACCOUNT and BANK\_CARD):** Retrieve a list of supported banks and their codes.
* **Upload Attachment (B2B only):** For certain B2B transfers, you may need to upload supporting documents.
* **Initiate a Transfer:** Use the `quotationId` to execute the payout.
* **Listen for Status:** Use webhooks to receive real-time updates on the transaction status.

{% hint style="info" %}
Before you begin!

* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))

<img src="/files/LFFicElNA6dWGpxBEdo1" alt="" data-size="original">
{% endhint %}

{% hint style="info" %}

### <mark style="color:orange;">Source wallet</mark>

<mark style="color:yellow;">All transfers would be debited from the respective payout currency wallet balance. Ensure you have sufficient balance before making any transfer request.</mark>
{% endhint %}

### Generate a Bearer Token

{% content-ref url="/pages/p15ikIRu4qZuG2xRX2op" %}
[Authentication](/overview/authentication.md)
{% endcontent-ref %}

### [Encryption algorithm here](/accepting-payments/payments-api.md#encryption-algorithm)

### Create a Quote

To begin a transfer, you first need to create a quote. This will lock in the exchange rate and fees for a specific period.\
Payout quotation is created based on the category. Here is the list of categories

| Transfer Type | Service       | Service Code   |
| ------------- | ------------- | -------------- |
| B2C           | BANK\_ACCOUNT | Not applicable |
| B2B           | BANK\_ACCOUNT | Not applicable |
| C2C           | BANK\_ACCOUNT | Not applicable |
| B2B           | BANK\_CARD    | UNIONPAY       |
| C2C           | BANK\_CARD    | UNIONPAY       |
| C2C           | WALLET        | ALIPAY         |

#### Make a POST call to the create quotation API

<mark style="color:blue;">`POST`</mark> `{{env_url}}/wallet/merchant/quotation/v2`

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |
| x-auth-token  | MERCHANT PUBLIC KEY  |

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

#### Request body (plain)

{% tabs %}
{% tab title="Wallet - Alipay" %}

```json
{
    "serviceCode": "ALIPAY",
    "service": "WALLET",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Union Pay Card - C2C" %}

```json
{
    "serviceCode": "UNIONPAY",
    "service": "BANK_CARD",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Union Pay Card - B2B" %}

```json
{
    "serviceCode": "UNIONPAY",
    "service": "BANK_CARD",
    "transferType": "B2B",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Bank Account - C2C" %}

```json
{
    "service": "BANK_ACCOUNT",
    "transferType": "C2C",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}

{% tab title="Bank Account - B2B" %}

```json
{
    "service": "BANK_ACCOUNT",
    "transferType": "B2B",
    "destinationCurrency": "CNY",
    "sourceCurrency": "USD",
    "fundSource": "CASH",
    "destinationAmount": "10"
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "id": 472,
    "sourceAmount": 9.40,
    "sourceCurrency": "USD",
    "destinationAmount": 70.00,
    "destinationCurrency": "CNY",
    "fxRate": 7.44,
    "fee": 6.00,
    "expiration": 1734490800000,
    "reference": "f7c32b34-ec79-4de2-ae8a-42529",
    "expired": false
}
```

{% endtab %}
{% endtabs %}

### **Get Bank Codes**

#### Get Bank codes by BANK\_ACCOUNT

<mark style="color:blue;">`GET`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/banks/CNY

#### Get Bank codes by BANK\_CARD

<mark style="color:blue;">`GET`</mark> `{{env_url}}/`wallet/merchant/bank/transfer/request/banks/CNY?type=bank\_card

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: OK  - By BANK\_ACCOUNT" %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "403100000004",
            "name": "Postal Savings Bank of China (中国邮政储蓄银行)"
        },
        {
            "code": "102100099996",
            "name": "Industrial and Commercial Bank of China (中国工商银行)"
        },
        {
            "code": "103100000026",
            "name": "Agricultural Bank of China (中国农业银行)"
        }
   ...]
}    
```

{% endtab %}

{% tab title="200: OK - By BANK\_CARD" %}

```json
{
    "message": "success",
    "error": null,
    "data": [
        {
            "code": "03010000",
            "name": "Bank of Communications"
        },
        {
            "code": "01040000",
            "name": "Bank of China"
        },
        {
            "code": "03033320",
            "name": "Guang Da Bank"
        },
        {
            "code": "14505800",
            "name": "GuangDong Rural Credit Bank"
        }
    ...]
}
```

{% endtab %}
{% endtabs %}

### Upload attachment

For B2B transfers, such as `ECOMMERCE` or `GOODS_PURCHASE`, you may need to upload supporting documents like invoices or customs declarations.

Supported Attachment Types

| Values                              |
| ----------------------------------- |
| COMMERCIAL\_DOCUMENTS               |
| LOGISTICS\_DOCUMENTS                |
| LOGISTICS\_COMMUNICATION\_DOCUMENTS |
| CONTRACT\_DOCUMENTS                 |
| ORDER\_DOCUMENTS                    |
| CUSTOMS\_DECLARATION                |
| OTHERS                              |

Make a POST call to upload file&#x20;

<mark style="color:green;">`POST`</mark> `{{env_url}}/`wallet/merchant/file

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                 |
| ------------- | --------------------- |
| Context-Type  | multipart/form-data   |
| Authorization | Bearer \<token here>  |
| x-auth-token  | MERCHANT PUBLIC TOKEN |

**Form Data:**

| Key              | Value                | Description                                                       |
| ---------------- | -------------------- | ----------------------------------------------------------------- |
| `file`           | (file)               | The actual file to be uploaded (e.g., `invoice.pdf`, `image.png`) |
| `purpose`        | Order Delivery       | The type of document being uploaded.                              |
| `attachmentType` | CUSTOMS\_DECLARATION | The type of document being uploaded.                              |

#### Response

```json
{
    "id": 628,
    "purpose": "Order Delivery",
    "attachmentType": "CUSTOMS_DECLARATION"
}
```

### Initiate a transfer

Once you have a `quotationId` (and a `bankCode` if applicable), you can initiate the transfer. The request body will vary depending on the payout method and transfer type.

#### Make a POST call to the initiate transfer request API

<mark style="color:green;">`POST`</mark> `{{env_url}}`/wallet/merchant/{businessId}/bank/transfer/v2/request

You would need to pass, as a header the <mark style="color:red;">x-auth-token</mark>. This can be obtained from your merchant **dashboard → Settings → Generate API keys → Merchant public key**.

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Content-Type  | application/json     |
| x-auth-token  | MERCHANT PUBLIC KEY  |
| Authorization | Bearer \<token here> |

#### ID TYPE

<table data-header-hidden><thead><tr><th></th><th width="326.22265625"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>SENDER/SENDER_BUSINESS ID</strong></td><td><strong>Allowed Types</strong></td><td><strong>Transfer Types</strong></td><td><strong>Services</strong></td></tr><tr><td></td><td>ID_CARD<br>PASSPORT</td><td>C2C / B2C</td><td>BANK_CARD</td></tr><tr><td></td><td><p>ID_CARD</p><p>PASSPORT HONGKONG_ID_CARD</p><p>DRIVER_LICENSE</p><p>HONGKONG_MACAO_TAIWAN_PERMIT</p><p>ALIEN_RESIDENT_PERMIT EMPLOYEE_CARD OTHER</p></td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>ID_CARD<br>PASSPORT</td><td>C2C</td><td>WALLET</td></tr><tr><td></td><td><p>BUSINESS_REGISTRATION_CERT</p><p>OTHER</p></td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>BUSINESS_REGISTRATION_CERT</td><td>B2B</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td></td><td></td><td></td></tr><tr><td><strong>RECEIVER/RECEIVER_BUSINESS ID</strong></td><td><strong>Allowed Types</strong></td><td><strong>Transfer Types</strong></td><td><strong>Services</strong></td></tr><tr><td></td><td>Receiver ID not compulsory</td><td>C2C / B2C</td><td>BANK_CARD</td></tr><tr><td></td><td>ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT</td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td>Receiver ID not compulsory</td><td>C2C</td><td>WALLET</td></tr><tr><td></td><td>ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT</td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td></td><td><p>UNIFIED_SOCIAL_CREDIT_ID</p><p>ID_CARD</p></td><td>B2B</td><td>BANK_ACCOUNT</td></tr></tbody></table>

ACCOUNT ID

| Values | **Description**      |
| ------ | -------------------- |
| MOBILE | ALIPAY and WECHATPAY |
| EMAIL  | ALIPAY only          |

#### Relationship

<table><thead><tr><th width="363.3046875">Allowed Values</th><th>Transfer Types</th><th>Services</th></tr></thead><tbody><tr><td>RELATIONSHIP not compulsory</td><td>C2C / B2C </td><td>BANK_CARD</td></tr><tr><td><p>SELF</p><p>SPOUSE</p><p>PARENTS SONS_AND_DAUGHTERS BROTHERS_AND_SISTERS</p><p>GRANDPARENTS</p><p>GRANDPARENTS_IN_LAW GRANDCHILDREN</p><p>MATERNAL_GRANDCHILDREN</p></td><td>C2C</td><td>BANK_ACCOUNT</td></tr><tr><td><p>SPOUSE</p><p>PARENTS</p><p>SONS_AND_DAUGHTERS</p></td><td>C2C</td><td>WALLET</td></tr><tr><td>EMPLOYEE</td><td>B2C</td><td>BANK_ACCOUNT</td></tr><tr><td>RELATIONSHIP not compulsory</td><td>B2B</td><td>BANK_ACCOUNT</td></tr></tbody></table>

#### Account Type

| Values     |
| ---------- |
| INDIVIDUAL |
| COMPANY    |

#### TradeType

| Values |
| ------ |
| GOODS  |

#### Purpose

| Allowed Values                                                                                          | **Transfer Type** | Services                       |
| ------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------ |
| <p>ECOMMERCE</p><p>GOODS\_PURCHASE</p>                                                                  | B2B               | BANK \_ACCOUNT                 |
| <p>SALARY<br>FAMILY\_SUPPORT<br>TRAVEL<br>INSURANCE<br>SERVICE\_CHARGES<br>PATENT\_ROYALTY<br>OTHER</p> | C2C/B2C           | BANK\_CARD                     |
| FAMILY\_SUPPORT                                                                                         | C2C               | <p>BANK\_ACCOUNT<br>WALLET</p> |
| SALARY                                                                                                  | B2C               | BANK\_ACCOUNT                  |

**Supported Product Categories for `GOODS_PURCHASE`**

When the **purpose** is `GOODS_PURCHASE`, you must provide a `productCategory`.&#x20;

The supported values are:&#x20;

`APPAREL`, `BEAUTY_PERSONAL_CARE`, `ELEC_COMPONENTS`, `TOYS_MODELS`, `GARDEN`, `FOOD`, `BOOKS_MEDIA`, `BABY`, `GIFTS_CRAFTS`, `AUTO_ACCESSORIES`, `HOME_GOODS`, `SPORTS_OUTDOORS`, `JEWELRY`, `ENTERTAINMENT`, `MUSICAL_INSTRUMENTS`, `ELECTRONICS`, `ANTIQUES_ART`, `WATCHES_EYEWEAR`, `MECHANICAL_PARTS`.

**Request body (encrypted):**

```json
{ 
  "message": "encrypted-request-body"
}
```

#### Request body (plain)

{% tabs %}
{% tab title="UNION PAY, C2C Card" %}

```json
{
    "bankCode": "01020000",
    "bankName": "Industrial and Commercial bank of China",
    "cardHolderName": "Cui Xia",
    "cardNumber": "6222040000030009",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 795,
    "receiverFirstName": "Receiver",
    "receiverLastName": "China",
    "requestId": "China_payout-union-10",
    "senderAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderFirstName": "Sender",
    "senderIdNumber": "1000000000",
    "senderIdType": "ID_CARD",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="UNION PAY, B2B Card" %}

```json
{
    "bankCode": "01020000",
    "bankName": "Industrial and Commercial bank of China",
    "cardHolderName": "Zhang Meizhen",
    "cardNumber": "6222040000030016",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 802,
    "receiverFirstName": "Receiver",
    "receiverLastName": "China",
    "requestId": "China_payout-union-b2c-10",
    "senderBusinessAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "senderFirstName": "Sender",
    "senderIdNumber": "1000000000",
    "senderIdType": "ID_CARDs",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, C2C" %}

```json
{
    "accountName": "必须是中文",
    "accountNumber": "6222040000030016",
    "accountType": "INDIVIDUAL",
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "creditAccountCountry": "CN",
    "purpose": "FAMILY_SUPPORT",
    "quotationId": 794,
    "receiverFirstName": "test",
    "receiverIdNumber": "331081199609218031",
    "receiverIdType": "ID_CARD",
    "receiverLastName": "China",
    "receiverMobileNumber": "+8618612345678",
    "receiverRelationship": "SPOUSE",
    "requestId": "必须是中文-01",
    "senderAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderFirstName": "Sender",
    "senderIdNumber": "331081199609218031",
    "senderIdType": "ID_CARD",
    "senderLastName": "China",
    "senderNationality": "CN"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2C" %}

```json
{
    "accountName": "必须是中文",
    "accountNumber": "6222040000030016",
    "accountType": "INDIVIDUAL",
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "creditAccountCountry": "CN",
    "purpose": "SALARY",
    "quotationId": 804,
    "receiverFirstName": "test",
    "receiverIdNumber": "331081199609218031",
    "receiverIdType": "ID_CARD",
    "receiverLastName": "China",
    "receiverMobileNumber": "+8613699262597",
    "receiverRelationship": "EMPLOYEE",
    "requestId": "必须是中文-04",
    "senderBusinessAddress": {
        "city": "Beijing",
        "countryCode": "CN",
        "postcode": "065001",
        "state": "Heilongjiang",
        "streetAddress": "West Street"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "senderBusinessIdNumber": "91510104MA6A3FYD7B",
    "senderBusinessIdType": "BUSINESS_REGISTRATION_CERT"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2B" %}

```json
{
    "accountName": "上海弢汇商务咨询有限公司",
    "accountNumber": "31050161363900000210",
    "accountType": "COMPANY",
    "bankCode": "105100000017",
    "bankName": "Construction Bank of China",
    "creditAccountCountry": "CN",
    "document": {
        "attachments": [
            {
                "fileId": "595"
            }
        ],
        "orderCurrency": "CNY",
        "orderNumber": "001AD#",
        "orderTime": "2025-01-01",
        "products": [
            {
                "name": "FEMALE BAG",
                "quantity": "1",
                "website": "stbc.com"
            }
        ],
        "totalAmount": "100",
        "tradeType": "GOODS"
    },
    "purpose": "ECOMMERCE",
    "quotationId": 4786,
    "receiverBusinessAddress": {
        "city": "Shanghai",
        "countryCode": "CN",
        "postcode": "201599",
        "state": "Shanghai",
        "streetAddress": "Tingwei Highway"
    },
    "receiverBusinessIdNumber": "91310116MA1J9LE95D",
    "receiverBusinessIdType": "UNIFIED_SOCIAL_CREDIT_ID",
    "receiverBusinessMobileNumber": "+8613816932352",
    "receiverBusinessRegisteredName": "上海弢汇商务咨询有限公司",
    "requestId": "6222040000030016-03",
    "senderBusinessAddress": {
        "city": "Lagos",
        "countryCode": "NG",
        "postcode": "50001",
        "state": "Lagos State",
        "streetAddress": "Ligali"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD"
}
```

{% endtab %}

{% tab title="BANK ACCOUNT, B2B" %}

```json
{
    "accountName": "上海弢汇商务咨询有限公司",
    "accountNumber": "31050161363900000210",
    "accountType": "COMPANY",
    "bankCode": "105100000017",
    "bankName": "中国建设银行",
    "creditAccountCountry": "CN",
    "purpose": "GOODS_PURCHASE",
    "quotationId": 4852,
    "receiverBusinessIdNumber": "91310116MA1J9LE95D",
    "receiverBusinessIdType": "UNIFIED_SOCIAL_CREDIT_ID",
    "receiverBusinessMobileNumber": "+8613816932352",
    "receiverBusinessRegisteredName": "上海弢汇商务咨询有限公司",
    "receiverBusinessAddress": {
        "city": "Shanghai",
        "streetAddress": "Tingwei Highway",
        "countryCode": "CN",
        "postcode": "201599",
        "state": "Shanghai"
    },
    "requestId": "6222040000030016-06",
    "senderBusinessAddress": {
        "city": "Lagos",
        "streetAddress": "Ligali",
        "countryCode": "NG",
        "postcode": "50001",
        "state": "Lagos State"
    },
    "senderBusinessRegisteredName": "KLASHA TECHNOLOGIES LTD",
    "document": {
        "totalAmount": "100",
        "attachments": [
            {
                "fileId": "628"
            }
        ],
        "orderNumber": "001AD#",
        "orderTime": "2025-01-01",
        "orderCurrency": "CNY",
        "tradeType": "GENERAL_GOODS",
        "products": [
            {
                "name": "FEMALE BAG",
                "quantity": "1",
                "productCategory": "APPAREL"
            }
        ],
        "paymentType": "COLLECT",
        "customs": {
            "customsDecNo": "00112345666"
        },
        "logistics": {
            "company": "GIG",
            "orderNo": "001AD#",
            "shipDate": "2025-04-27"
        }
    }
}

```

{% endtab %}

{% tab title="ALIPAY" %}

```json
{
    "senderAddress": {
        "city": "Beijing",
        "streetAddress": "Beijing",
        "countryCode": "CN",
        "postcode": "100001",
        "state": "Beijing"
    },
    "senderFirstName": "Chin",
    "senderLastName": "Yung",
    "senderNationality": "CN",
    "senderIdNumber": "B12507200",
    "senderBirthDate": "1991-09-26",
    "senderIdType": "PASSPORT",
    "purpose": "FAMILY_SUPPORT",
    "creditAccountCountry": "CN",
    "receiverLastName": "Fan",
    "receiverIdNumber": "B12507200",
    "receiverFirstName": "Jing",
    "requestId": "d99c0f80-301e-4938-9f79-d9753",
    "quotationId": 728,
    "accountNumber": "8613699262597",
    "accountId": "MOBILE",
    "receiverRelationship": "SELF"
}
```

{% endtab %}
{% endtabs %}

Fields specification: C2C, BANK\_CARD

| **Field**              | **Description**                                                                  |
| ---------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                       |
| `senderFirstName`      | Sender first name                                                                |
| `senderLastName`       | Sender last name                                                                 |
| `senderNationality`    | Sender nationality                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                       |
| `senderIdNumber`       | Sender ID number                                                                 |
| `senderAddress`        | Sender’s address. Refer to the address object                                    |
| `bankName`             | Name of the bank                                                                 |
| `bankCode`             | Bank ID                                                                          |
| `creditAccountCountry` | Bank’s country                                                                   |
| `cardNumber`           | Card number                                                                      |
| `cardHolderName`       | Name on card                                                                     |
| `quotationId`          | Quotation ID obtained after creating a quotation                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer |

Fields specification: C2C, BANK\_ACCOUNT

| **Field**              | **Description**                                                                  |
| ---------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                       |
| `receiverMobileNumber` | Receiver mobile number. Format: +8613699262597                                   |
| `receiverEmail`        | Receiver email                                                                   |
| `receiverRelationship` | Relationship with the receiver                                                   |
| `receiverIdType`       | Receiver ID type. Please refer to the supported ID type list                     |
| `receiverIdNumber`     | Receiver ID number                                                               |
| `senderFirstName`      | Sender first name                                                                |
| `senderLastName`       | Sender last name                                                                 |
| `senderNationality`    | Sender nationality                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                       |
| `senderIdNumber`       | Sender ID number                                                                 |
| `senderAddress`        | Sender address. Refer to the address object                                      |
| `bankName`             | Name of the bank                                                                 |
| `bankCode`             | Bank ID                                                                          |
| `creditAccountCountry` | Credit account bank’s country                                                    |
| `accountNumber`        | Credit account number                                                            |
| `accountName`          | Credit account name (必须是中文)                                                      |
| `accountType`          | Credit account type. Please refer to the supported account type list             |
| `quotationId`          | Quotation ID obtained after creating a quotation                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer |

Fields specification: C2C, WALLET (ALIPAY, WECHATPAY)

| **Field Name**         | **Description**                                                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiverIdNumber`     | Receive ID number                                                                                                                                                |
| `receiverFirstName`    | Receiver first name (必须是中文)                                                                                                                                      |
| `receiverLastName`     | Receiver last name (必须是中文)                                                                                                                                       |
| `receiverRelationship` | Relationship with the receiver                                                                                                                                   |
| `senderFirstName`      | Sender first name                                                                                                                                                |
| `senderLastName`       | Sender last name                                                                                                                                                 |
| `senderBirthDate`      | Sender date of birth                                                                                                                                             |
| `senderNationality`    | Sender nationality                                                                                                                                               |
| `senderIdType`         | Sender ID type. Please refer to the supported ID type list                                                                                                       |
| `senderIdNumber`       | Sender ID number                                                                                                                                                 |
| `senderAddress`        | Sender address. Refer to the address object                                                                                                                      |
| `creditAccountCountry` | Credit account bank’s country                                                                                                                                    |
| `accountNumber`        | Credit account number - this is either an email or mobile number for ALIPAY or a mobile number for WECHAT PAY. The login account ID to WeChat or Alipay account. |
| `accountId`            | The account ID type of either the WeChat or Alipay account. Please refer to the supported account ID type.                                                       |
| `quotationId`          | Quotation ID obtained after creating a quotation                                                                                                                 |
| `purpose`              | Reason for the payout. Please refer to the supported purpose list                                                                                                |
| `requestId`            | It’s a unique transaction reference will be used to uniquely identify a transfer                                                                                 |

Fields specification: B2B, BANK\_ACCOUNT

| **Field**                        | **Description**                                                                  |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `receiverFirstName`              | Receiver first name (必须是中文)                                                      |
| `receiverLastName`               | Receiver last name (必须是中文)                                                       |
| `receiverBusinessMobileNumber`   | Receiver mobile number. Format: +86 18612345678                                  |
| `receiverEmail`                  | Receiver email                                                                   |
| `receiverBusinessIdType`         | Receiver ID type. Please refer to the supported ID type list                     |
| `receiverBusinessIdNumber`       | Receiver ID number                                                               |
| `receiverBusinessRegisteredName` | Receiver business name. Chinese characters are required if it's in China         |
| `receiverBusinessAddress`        | Receiver business address                                                        |
| `senderFirstName`                | Sender first name                                                                |
| `senderLastName`                 | Sender last name                                                                 |
| `senderBusinessAddress`          | Sender business address. Refer to the address object                             |
| `senderBusinessRegisteredName`   | Sender business name                                                             |
| `bankName`                       | Name of the bank                                                                 |
| `bankCode`                       | Bank ID                                                                          |
| `creditAccountCountry`           | Credit account bank’s country                                                    |
| `accountNumber`                  | Credit account number                                                            |
| `accountName`                    | Credit account name (必须是中文)                                                      |
| `accountType`                    | Credit account type. Please refer to the supported account type list             |
| `quotationId`                    | Klasha quotation ID                                                              |
| `purpose`                        | Reason for the payout. Please refer to the supported purpose list                |
| `requestId`                      | It’s a unique transaction reference will be used to uniquely identify a transfer |
| `document`                       | See: Document                                                                    |

Fields specification: Document

| **Field**       | **Description**                         |
| --------------- | --------------------------------------- |
| `totalAmount`   | Total amount                            |
| `orderNumber`   | Order number                            |
| `orderTime`     | Order time                              |
| `orderCurrency` | Order currency                          |
| `logistics`     | See: Logistics                          |
| `tradeType`     | Please refer to the supported TradeType |
| `products`      | `List<Product>` Product                 |
| `attachments`   | `List<Attachment>` See: Attachment      |

Fields specification: Product

| **Field**  | **Description** |
| ---------- | --------------- |
| `name`     | Product name    |
| `quantity` | Quantity        |

Fields specification: Attachment

| **Field** | **Description** |
| --------- | --------------- |
| `fileId`  | Klasha file ID  |

Fields specification: Logistics

| **Field** | **Description**        |
| --------- | ---------------------- |
| `company` | Logistics company      |
| `orderNo` | Logistics order number |

Fields specification: Address

| **Field**       | **Description**   |
| --------------- | ----------------- |
| `city`          | City              |
| `streetAddress` | Street address    |
| `countryCode`   | Country code      |
| `postcode`      | Postcode          |
| `state`         | Province or state |

#### Response

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "id": 1,
    "amount": 70.00,
    "payoutStatus": "PENDING",
    "requestId": "ed5fa-a33ed-fc4dc",
    "narration": "GOODS_PURCHASE",
    "country": "CN",
    "fee": 6.00,
    "bankCode": "03010000",
    "bankName": "Bank of communications",
    "accountNumber": "10000000000",
    "accountName": "Test Flow"
}
```

{% endtab %}
{% endtabs %}

### Listen for a status response

When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.

Once a transfer is processed, we send the final status of the transfer as a POST request to your webhook URL

{% tabs %}
{% tab title="Successful Webhook" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253331236",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "successful"
  },
  "event": "payout"
}
```

{% endtab %}

{% tab title="Failed Webhook" %}

```json
{
  "data": {
    "reference": "kbtr-3857-011-null-166993253334816",
    "createdAt": "2023-03-28T23:01:45.336",
    "amount": 1000,
    "accountName": "Pastor Bright",
    "narration": "certification",
    "name": "Steph and sons",
    "currency": "NGN",
    "bankName": "ACCESS BANK NIGERIA",
    "accountNumber": "0690000032",
    "status": "failed"
  },
  "event": "payout"
}
```

{% endtab %}
{% endtabs %}

The possible statuses are listed and described in the following table:

| Status                                       | Description                                                                   |
| -------------------------------------------- | ----------------------------------------------------------------------------- |
| <mark style="color:green;">successful</mark> | This is sent when the transfer is successful                                  |
| <mark style="color:red;">failed</mark>       | This is sent when the transfer fails                                          |
| <mark style="color:orange;">pending</mark>   | This transfer is still in progress. Please wait for either success or failed. |

### **Query payout status**

Make a [call](/transfers/payout.md#polling-transfer-statuses) to fetch status of initiated payouts.

###


---

# 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://developers.klasha.com/transfers/payout/cny-payout-new-encryption.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.