# CNY Transfer

See availability and TATs for CNY transfers [here](https://kgegjwnjseu.sg.larksuite.com/file/FKx3bRqg5oWpoQxmkPAlBnMHgrc). 

## Apply for CNY Express Transfer

<mark style="color:green;">`POST`</mark> `/trans/applyForCnyExpress`

<table data-full-width="false"><thead><tr><th width="176.93328857421875">Parameter</th><th width="116.86669921875">Type</th><th width="326.1998291015625">Description</th><th width="395.1334228515625">Required?</th></tr></thead><tbody><tr><td><code>payerAccountId</code></td><td>string</td><td>Payer account number</td><td>TRUE</td></tr><tr><td><code>beneficiaryType</code></td><td>string</td><td>1 = Individual <br>2 = Enterprise</td><td>TRUE</td></tr><tr><td><code>beneficiaryName</code></td><td>int</td><td>Beneficiary full name. Chinese name is preferred.</td><td>TRUE</td></tr><tr><td><code>beneficiaryIdNumber</code></td><td>decimal</td><td>Identification number of beneficiary.  <br>Maximum 18 characters <br><br>• Individual → National ID/Passport <br>• Enterprise → Company registration number</td><td>TRUE</td></tr><tr><td><code>beneficiaryCountryCode</code></td><td>string</td><td><p>Required when <code>beneficiaryType</code> = 1. </p><p>Must be one of supported CNY nationalities. <br>See <a href="https://q4ydyb1s6iw.sg.larksuite.com/sheets/Bv1OsMi0ohrJjQtGDFblNxYOgog">list</a> of supported nationalities</p></td><td>CONDITIONAL</td></tr><tr><td><code>beneficiaryBankCode</code></td><td>string</td><td>Beneficiary bank code. <br>Must be from <a href="https://mib.feishu.cn/sheets/YXMTsK8JuhXDpWtt3bgcrVgFnch">CNY Express_Bank List</a></td><td>TRUE</td></tr><tr><td><code>beneficiaryBankName</code></td><td>string</td><td>Beneficiary bank name. <br>Must be from <a href="https://mib.feishu.cn/sheets/YXMTsK8JuhXDpWtt3bgcrVgFnch">CNY Express_Bank List</a></td><td>TRUE</td></tr><tr><td><code>beneficiaryBankAddress</code></td><td>string</td><td>Bank Address</td><td>TRUE</td></tr><tr><td><code>beneficiaryAccountId</code></td><td>string</td><td>Beneficiary's account number</td><td>TRUE</td></tr><tr><td><code>paymentPurpose</code></td><td>string</td><td>Payment purpose<br>Enumeration value: PURCHASE_GOODS, RELATED_PARTY_PAYMENT</td><td>TRUE</td></tr><tr><td><code>messageToBeneficiary</code></td><td>string</td><td>Optional message displayed to beneficiary. Transfer post script; no more than 100 characters</td><td>OPTIONAL</td></tr><tr><td><code>remark</code></td><td>string</td><td>Remark</td><td>OPTIONAL</td></tr><tr><td><code>supportDocumentFile</code></td><td>string</td><td>Base64</td><td>TRUE</td></tr><tr><td><code>supportDocumentType</code></td><td>string</td><td>image or pdf</td><td>TRUE</td></tr><tr><td><code>companyRegisDocumentFile</code></td><td>string</td><td>Base64</td><td>TRUE</td></tr><tr><td><code>companyRegisDocumentType</code></td><td>string</td><td>image or pdf</td><td>TRUE</td></tr><tr><td><code>invoice</code></td><td>string</td><td>Base64<br>Mandatory if <code>Amount</code> exceeds 70,000 CNY <br>Allow 1 file (do not exceed 30MB)</td><td>CONDITIONAL</td></tr><tr><td><code>invoiceDocumentType</code></td><td></td><td>image or pdf</td><td>TRUE</td></tr><tr><td><code>orderArray</code></td><td>Array</td><td></td><td></td></tr><tr><td><code>productName</code></td><td>string</td><td>Product Name</td><td>TRUE</td></tr><tr><td><code>quantity</code></td><td>integer</td><td>Quantity purchased. <br>Positive integer which is ≤ 99,999,999</td><td>TRUE</td></tr><tr><td><code>amount</code></td><td>string</td><td>Must be ≤ 500,000 CNY</td><td>TRUE</td></tr><tr><td><code>orderTime</code></td><td>long</td><td>Order timestamp<br>Format: 165595208112</td><td>TRUE</td></tr><tr><td><code>platform</code></td><td>string</td><td>Merchant business name or website URL. <br>Platform name or business URL<br>Must be ≤ 128 characters</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
    "code": "00000",
    "msg": "Completed successfully",
    "sender": "apigw.baas.choice",
    "requestId": "MYWAGEPAY28ca10d424eef8789098ab234",
    "locale": "en_KE",
    "data": {
        "applicationId": "CERI1680908092136570888212"
    },
    "timestamp": 1769763090200,
    "salt": "Qw5jJJT5RBeHAiRqmXVKoL_B)GN3p2f!",
    "signature": "08196eb684feeb50a398810be36967904e545116f7903b4e48e15af91722c4a0"
}
```

{% endtab %}
{% endtabs %}

## Get List of CNY Transfers

<mark style="color:green;">`POST`</mark>  `/query/getCnyTransList`

\<Use this endpoint to purchase Airtime>

**Parameters**

<table data-full-width="false"><thead><tr><th width="170.5333251953125">Parameters</th><th width="87">Type</th><th width="393.4000244140625">Description</th><th width="172.2000732421875">Required?</th></tr></thead><tbody><tr><td><code>userId</code></td><td>string</td><td>Unique identifier of the user in your system.</td><td>TRUE</td></tr><tr><td><code>accountId</code></td><td>string</td><td>Payer Account Number</td><td>TRUE</td></tr><tr><td><code>startTime</code></td><td>long</td><td>UTC timestamp in millisecond of the start time of the queried period.</td><td>TRUE</td></tr><tr><td><code>endTime</code></td><td>long</td><td>UTC timestamp in millisecond of the end time of the queried period.</td><td>TRUE</td></tr><tr><td><code>pageNo</code></td><td>string</td><td>Number of pages to be returned</td><td>TRUE</td></tr><tr><td><code>pageSize</code></td><td>string</td><td>Number of records per page to return</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
    "code": "00000",
    "msg": "Completed successfully",
    "sender": "apigw.baas.choice",
    "requestId": "MYWAGEPAYac110c7d24a119443c52b6d90",
    "locale": "en_KE",
    "data": {
        "result": [
            {
                "applicationId": "CERI1680870648924160008212", // application id 
                "payerAccountId": "46013000093962",// payer account id 
                "beneficiaryType": "1",// beneficiary type
                "beneficiaryName": "beneficiaryName", // Name of beneficiary bank.
                "beneficiaryCountryCode": "ZAF", //beneficiary country code
                "beneficiaryBankCode": "AHZYRCB", //bank code
                "beneficiaryBankName": "安徽枞阳农村商业银行", // bank name
                "beneficiaryIdNumber": "1523452345", // regist id number 
                "beneficiaryBankAddress": "安徽枞阳",// bank adress
                "beneficiaryAccountId": "1345634565", // beneficiary account id
                "paymentPurpose": "PURCHASE_GOODS",
                "messageToBeneficiary": "messageToBeneficiary",// Message sent to beneficiary (if provided).
                "remark": "46012000012311",// remark
                "amount": "10.0000", // total amount
                "status": -1, // status
                "createTime": 1769757057000, // create time
                "completedTime": null // conpleted time
            }
            ......
        ]
        "totalRows": 5
    },
    "timestamp": 1769762521608,
    "salt": "b3_&!#f&Xb!h6Tdt$v1FYI4dRr5Yd*wR",
    "signature": "e8bae60d95e2fe3f54775435a67c7fb8d05785125a1fef60efac80c2a8d553b9"
}
```

{% endtab %}
{% endtabs %}

## Get CNY Transfer Details

<mark style="color:green;">`POST`</mark>  `/query/getCnyTransferDetails`

**Parameters**

<table data-full-width="false"><thead><tr><th width="210">Parameters</th><th width="87">Type</th><th width="353.9337158203125">Description</th><th width="354.5999755859375">Required?</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>string</td><td>Application ID as returned by the API in the first subsection</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
    "code": "00000",
    "msg": "Completed successfully",
    "sender": "apigw.baas.choice",
    "requestId": "MYWAGEPAYd6867d5dd4dfb82a746aabb5a",
    "locale": "en_KE",
    "data": {
        "applicationId": "CERI1680870648924160008212",// application id
        "payerAccountId": "46013000093962", // payer account id
        "beneficiaryType": "1", // beneficiary type
        "beneficiaryName": "beneficiaryName", // beneficiary name
        "beneficiaryCountryCode": "ZAF", // beneficiary country code
        "beneficiaryBankCode": "AHZYRCB", // bank code 
        "beneficiaryBankName": "安徽枞阳农村商业银行",// bank name
        "beneficiaryIdNumber": "1523452345",// beneficiary id number
        "orders": [
            {
                "productName": "productName20260130",
                "quantity": 10,
                "amount": "10.00",
                "orderTime": 165595208000,
                "platform": "platform"
            }
        ],
        "beneficiaryBankAddress": "安徽枞阳",
        "beneficiaryAccountId": "1345634565",
        "paymentPurpose": "PURCHASE_GOODS",
        "messageToBeneficiary": "messageToBeneficiary",
        "supportDocumentFile": "https://choice-baas-dev.s3.ap-southeast-1.amazonaws.com/sit/baas/MyWagePay/62855c012572402611511c310cd5314d4e0f0856b802903fb6e35d41b7f341bd?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260130T084258Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=AKIA5SULLDDZAOIQKGWB%2F20260130%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=c7debf455cf21e3b62164e743102b49dc119eef04666a3ab5fd8e672610fa2c5",
        "companyRegisDocumentFile": null,
        "invoice": "https://choice-baas-dev.s3.ap-southeast-1.amazonaws.com/sit/baas/MyWagePay/c35403b7bfe722f02d2fb10b42070aedd2d2fab5c42922e2e41e0b5da12a2d5f?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20260130T084258Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=AKIA5SULLDDZAOIQKGWB%2F20260130%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=e860c3675f23c807be357a6564b820cd36684b8cccf1b506675380da91ff4e36",
        "remark": "46012000012311",
        "amount": "10.0000",
        "status": -1,
        "createTime": 1769757057000,
        "completedTime": null
    },
    "timestamp": 1769762578592,
    "salt": "ksZFfR(*O3_kssL&q6jneI#mcD3JOAY0",
    "signature": "616358921ab95ed2ba8327bcc35c5ae292e697e8235c4a25ffce12607c7fc9d9"
}
```

{% endtab %}
{% endtabs %}

See also CNY Callback [0028](https://choice-bank.gitbook.io/choice-bank/notifications/callback-configuration#id-0028-cny-transfer-notification) and CNY Transfer [Status](https://choice-bank.gitbook.io/choice-bank/notifications/callback-configuration#id-0028-cny-transfer-notification) Definition