> ## Documentation Index
> Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 🇨🇳 CNY Payout

This endpoint allows you to process payouts in **Chinese Yuan (CNY)** to recipients with a bank account in China.

***

## Endpoint

**POST:** `https://sandboxapi.me-cash.com/v2/payout`

***

## Supported Payment Channels

CNY payouts support the following payment channel:

| **Channel**     | **Description**                                  | **Use Case**                |
| :-------------- | :----------------------------------------------- | :-------------------------- |
| `BANK_TRANSFER` | Standard bank transfer to a Chinese bank account | Business/Personal transfers |

***

## Request Details

### Headers

Include these headers in your request:

| **Header**     | **Value**          | **Required** |
| :------------- | :----------------- | :----------- |
| `Content-Type` | `application/json` | ✅ Yes        |
| `x-api-key`    | `YOUR_API_KEY`     | ✅ Yes        |

***

## Sample Requests

<Tabs>
  <Tab title="BANK_TRANSFER">
    Use `BANK_TRANSFER` for payouts to Chinese bank accounts.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location --request POST 'https://sandboxapi.me-cash.com/v2/payout' \
      --header 'x-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
          "recipient": {
              "name": "张少杰",
              "nickName": "{{$randomColor}}",
              "occupation": "HEALTHCARE",
            "icNumber": "130132**********10",
              "relationship": "SELF",
              "type": "BUSINESS",
              "account": {
              "accountNumber": "621700*********343",
                  "sortCode": "01026",
                  "bankName": "BAOSHANG BANK (包商银行)",
                  "bankCity": "SHENZHEN"
              },
              "companyName": "龙口市玉杰五金工具有限公司",
              "companyIdNumber": "913706**********6N",
              "gender": "F",
              "nationality": "CN",
              "itemCategory": "PRD0003",
              "itemType": "Pipe Wrench",
              "quantity": 100,
              "paymentChannel": "BANK_TRANSFER",
              "currency": "CNY",
              "country": "CN",
              "stored": false
          },
          "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
          "reason": "Gift",
          "remark": "Testing"
      }'
      ```

      ```javascript JavaScript (Fetch) theme={null}
      const url = 'https://sandboxapi.me-cash.com/v2/payout';

      const options = {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
        },
        body: JSON.stringify({
          recipient: {
            name: "张少杰",
            nickName: "{{$randomColor}}",
            occupation: "HEALTHCARE",
            icNumber: "130132**********10",
            relationship: "SELF",
            type: "BUSINESS",
            account: {
              accountNumber: "621700*********343",
              sortCode: "01026",
              bankName: "BAOSHANG BANK (包商银行)",
              bankCity: "SHENZHEN"
            },
            companyName: "龙口市玉杰五金工具有限公司",
            companyIdNumber: "913706**********6N",
            gender: "F",
            nationality: "CN",
            itemCategory: "PRD0003",
            itemType: "Pipe Wrench",
            quantity: 100,
            paymentChannel: "BANK_TRANSFER",
            currency: "CNY",
            country: "CN",
            stored: false
          },
          quoteId: "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
          reason: "Gift",
          remark: "Testing"
        })
      };

      fetch(url, options)
        .then(res => {
          if (!res.ok) {
            throw new Error(`HTTP error! status: ${res.status}`);
          }
          return res.json();
        })
        .then(data => console.log(data))
        .catch(error => console.error('Error:', error));
      ```

      ```python Python (Requests) theme={null}
      import requests
      import json

      url = "https://sandboxapi.me-cash.com/v2/payout"

      payload = {
          "recipient": {
              "name": "张少杰",
              "nickName": "Lee",
              "occupation": "HEALTHCARE",
            "icNumber": "130132**********10",
              "relationship": "SELF",
              "type": "BUSINESS",
              "account": {
              "accountNumber": "621700*********343",
                  "sortCode": "01026",
                  "bankName": "BAOSHANG BANK (包商银行)",
                  "bankCity": "SHENZHEN"
              },
              "companyName": "龙口市玉杰五金工具有限公司",
              "companyIdNumber": "913706**********6N",
              "gender": "F",
              "nationality": "CN",
              "itemCategory": "PRD0003",
              "itemType": "Pipe Wrench",
              "quantity": 100,
              "paymentChannel": "BANK_TRANSFER",
              "currency": "CNY",
              "country": "CN",
              "stored": False
          },
          "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
          "reason": "Gift",
          "remark": "Testing"
      }

      headers = {
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      }

      try:
          response = requests.post(url, headers=headers, data=json.dumps(payload))
          response.raise_for_status()
          print(response.json())
      except requests.exceptions.HTTPError as err:
          print(f"HTTP Error: {err}")
      ```
    </CodeGroup>
  </Tab>
</Tabs>

***

### Request Body Breakdown

<Tabs>
  <Tab title="BANK_TRANSFER Fields">
    | **Field**                         | **Type** | **Description**                                                        | **Required** |
    | :-------------------------------- | :------- | :--------------------------------------------------------------------- | :----------- |
    | `quoteId`                         | String   | The unique ID of the quote for this payout.                            | ✅ Yes        |
    | `reason`                          | String   | The purpose of the transfer.                                           | ✅ Yes        |
    | `recipient`                       | Object   | An object containing all details about the person receiving the funds. | ✅ Yes        |
    | `recipient.name`                  | String   | The full name of the recipient or business.                            | ✅ Yes        |
    | `recipient.nickName`              | String   | Recipient nickname.                                                    | ❌ No         |
    | `recipient.occupation`            | String   | Recipient occupation.                                                  | ❌ No         |
    | `recipient.icNumber`              | String   | Recipient identity card number.                                        | ❌ No         |
    | `recipient.relationship`          | String   | Relationship with the recipient.                                       | ❌ No         |
    | `recipient.type`                  | String   | The type of recipient. Enum: `INDIVIDUAL`, `BUSINESS`.                 | ✅ Yes        |
    | `recipient.paymentChannel`        | String   | The payment method. Use `BANK_TRANSFER`.                               | ✅ Yes        |
    | `recipient.currency`              | String   | The ISO currency code. Must be `CNY`.                                  | ✅ Yes        |
    | `recipient.country`               | String   | The recipient's two-letter ISO country code. Must be `CN`.             | ✅ Yes        |
    | `recipient.account`               | Object   | An object containing the recipient's bank account details.             | ✅ Yes        |
    | `recipient.account.accountNumber` | String   | The recipient's bank account number.                                   | ✅ Yes        |
    | `recipient.account.sortCode`      | String   | Bank code / Sort code.                                                 | ❌ No         |
    | `recipient.account.bankName`      | String   | The name of the recipient's bank.                                      | ✅ Yes        |
    | `recipient.account.bankCity`      | String   | City of the bank.                                                      | ❌ No         |
    | `recipient.companyName`           | String   | Company name (required if `type` is `BUSINESS`).                       | ❌ No         |
    | `recipient.companyIdNumber`       | String   | Company identification number (required if `type` is `BUSINESS`).      | ❌ No         |
    | `recipient.gender`                | String   | Gender of the recipient (`M` or `F`).                                  | ❌ No         |
    | `recipient.nationality`           | String   | Nationality of the recipient (e.g., `CN`).                             | ❌ No         |
    | `recipient.itemCategory`          | String   | Category of items (e.g., `PRD0003`).                                   | ❌ No         |
    | `recipient.itemType`              | String   | Type of item (e.g., `Pipe Wrench`).                                    | ❌ No         |
    | `recipient.quantity`              | Number   | Quantity of items.                                                     | ❌ No         |
  </Tab>
</Tabs>

***

## Success Response (200 OK)

If the payout is successfully created, the API returns the following response:

```json copy theme={null}
{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-xxxxxxxxxxxxx",
    "invoice": "4b9b6d30-a2ed-421a-bd69-xxxxxxxxxxxx",
    "reason": "Payment for goods",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "859b19e8-8a00-4d59-9970-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 230000
      },
      "target": {
        "currency": "CNY",
        "country": "CN",
        "amount": 1000
      },
      "rate": 230,
      "fee": {
        "amount": 100
      }
    },
    "recipient": {
      "name": "张少杰",
      "nickName": "Green",
      "occupation": "HEALTHCARE",
      "icNumber": "130132**********10",
      "relationship": "SELF",
      "type": "BUSINESS",
      "account": {
          "accountNumber": "621700*********343",
          "sortCode": "01026",
          "bankName": "BAOSHANG BANK (包商银行)",
          "bankCity": "SHENZHEN"
      },
      "companyName": "龙口市玉杰五金工具有限公司",
      "companyIdNumber": "913706**********6N",
      "gender": "F",
      "nationality": "CN",
      "itemCategory": "PRD0003",
      "itemType": "Pipe Wrench",
      "quantity": 100,
      "paymentChannel": "BANK_TRANSFER",
      "currency": "CNY",
      "country": "CN"
    },
    "created": "2025-02-27T14:17:48.038044Z",
    "processed": "2025-02-27T14:20:49.712685Z"
  }
}
```

***

## **Response Breakdown**

| **Field**                    | **Type** | **Description**                                                 |
| :--------------------------- | :------- | :-------------------------------------------------------------- |
| `message`                    | String   | A confirmation message indicating the result of the request.    |
| `status`                     | String   | The overall status of the request.                              |
| `data`                       | Object   | A container for all the transaction data.                       |
| `data.id`                    | String   | The unique identifier for this payout transaction.              |
| `data.state`                 | String   | The current state of the payout (`COMPLETED`, `PENDING`, etc.). |
| `data.quote.source.currency` | String   | The three-letter currency code of the source funds.             |
| `data.quote.target.amount`   | Number   | The converted amount that the recipient received.               |

***

## **Best Practices**

✅ Ensure `quoteId` is valid and linked to an existing quote.\
✅ Confirm that the recipient's **account number** is correct for the destination bank.\
✅ Use `recipient.country: "CN"` and `recipient.currency: "CNY"`.