# 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="https://257545343-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNw4nU37LIEg41plxXG5u%2Fuploads%2FvBXI8QATrncq17zlRm1P%2Fdashboad-klasha-settings.png?alt=media&#x26;token=1ebaf2b3-7e99-4490-9ede-a660c8d0035c" 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="../../overview/authentication" %}
[authentication](https://developers.klasha.com/overview/authentication)
{% endcontent-ref %}

### [Encryption algorithm here](https://developers.klasha.com/accepting-payments/payments-api#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](https://developers.klasha.com/transfers/payout/..#polling-transfer-statuses) to fetch status of initiated payouts.

###

SENDER/SENDER_BUSINESS ID	Allowed Types	Transfer Types	Services
	ID_CARD PASSPORT	C2C / B2C	BANK_CARD
	ID_CARD PASSPORT HONGKONG_ID_CARD DRIVER_LICENSE HONGKONG_MACAO_TAIWAN_PERMIT ALIEN_RESIDENT_PERMIT EMPLOYEE_CARD OTHER	C2C	BANK_ACCOUNT
	ID_CARD PASSPORT	C2C	WALLET
	BUSINESS_REGISTRATION_CERT OTHER	B2C	BANK_ACCOUNT
	BUSINESS_REGISTRATION_CERT	B2B	BANK_ACCOUNT

RECEIVER/RECEIVER_BUSINESS ID	Allowed Types	Transfer Types	Services
	Receiver ID not compulsory	C2C / B2C	BANK_CARD
	ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT	C2C	BANK_ACCOUNT
	Receiver ID not compulsory	C2C	WALLET
	ID_CARD HONGKONG_MACAO_TAIWAN_PERMIT	B2C	BANK_ACCOUNT
	UNIFIED_SOCIAL_CREDIT_ID ID_CARD	B2B	BANK_ACCOUNT
Allowed Values	Transfer Types	Services
RELATIONSHIP not compulsory	C2C / B2C	BANK_CARD
SELF SPOUSE PARENTS SONS_AND_DAUGHTERS BROTHERS_AND_SISTERS GRANDPARENTS GRANDPARENTS_IN_LAW GRANDCHILDREN MATERNAL_GRANDCHILDREN	C2C	BANK_ACCOUNT
SPOUSE PARENTS SONS_AND_DAUGHTERS	C2C	WALLET
EMPLOYEE	B2C	BANK_ACCOUNT
RELATIONSHIP not compulsory	B2B	BANK_ACCOUNT