CNY Payout API Example

The Payout API allows users to process payouts in Chinese Yuan (CNY) to recipients in China via different payment channels such as AliPay and WeChat.

In this example, we will look at the examples of the 3 Payment channels available for CNY payouts:

Channel	Description
`ALIPAY`	Payouts via Alipay
`WECHAT`	Payouts via WeChat
`BANK_TRANSFER`	Payouts via a Chinese bank account (B2B and personal)

This guide shows you how to create payouts for each channel.

Endpoint

POSThttps://api.me-cash.comv1/payout -- Create a CNY Payout

Authentication

Include these headers in your request:

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

Remember to replace YOUR_API_KEY with your actual secret API key.

Before You Start: Get a Quote ID

Every payout request requires a quoteId. This ID represents a specific currency conversion quote (e.g., from your source currency like USD or NGN to CNY) including the amount and fees. You typically get a quoteId from our Quote API before making the payout request.

Payment Channel Examples

AliPay

You can target an AliPay recipient using their MOBILE number or EMAIL address.

Key fields for AliPay:

recipient.paymentChannel: ALIPAY
recipient.type: MOBILE or EMAIL
recipient.account.accountNumber : The recipient's mobile number (starting with country code, e.g., 86...) or email address.

Sample cURL Request for AliPay (Mobile)

curl --location --request POST 'https://api.me-cash.com/v1/payout' \
--header 'x-api-key: API_KEY_:YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient": {
    "firstName": "Zen",
    "lastName": "Lui",
    "type": "MOBILE",
    "account": {
      "accountNumber": "8612343562723"
    },
    "paymentChannel": "ALI_PAY",
    "currency": "CNY",
    "country": "CN",
    "stored": true
  },
  "quoteId": "859b19e8-8a00-4d59-9970-85395006cc13",
  "reason": "Gift"
}'

Request Details

Headers

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

Request Body

The following fields are required when making a CNY payout request:

Field	Type	Description	Required
`recipient.firstName`	String	First name of the recipient	✅ Yes
`recipient.lastName`	String	Last name of the recipient	✅ Yes
`recipient.type`	String	Recipient type (`MOBILE' or` EMAIL`)	✅ Yes
`recipient.account.accountNumber`	String	Recipient’s mobile wallet number	✅ Yes
`recipient.paymentChannel`	String	Payment method (`ALI_PAY` for AliPay)	✅ Yes
`recipient.currency`	String	`CNY` (Chinese Yuan)	✅ Yes
`recipient.country`	String	`CN` (China)	✅ Yes
`stored`	String	Option to save recipient's details (`true` or `false`)	✅ Yes
`quoteId`	String	Unique Quote ID for the payout	✅ Yes
`reason`	String	Reason for the payout (e.g., `Gift`, `Invoice Payment`)	✅ Yes

Success Response for CNY Alipay Payment Channel (200 OK)

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

{
    "message": "Transaction created successfully",
    "status": "success",
    "data": {
        "id": "8c684c17-ef91-4133-a624-53f31514f059",
        "remark": "Tested",
        "reason": "Gift",
        "referenceNumber": "W1TDB6RWSQMKF",
        "type": "SEND",
        "state": "COMPLETED",
        "quote": {
            "id": "b39b64b9-3ca0-4566-b66b-a5fef8e81e7a",
            "source": {
                "currency": "NGN",
                "country": "NG",
                "amount": 15000
            },
            "target": {
                "currency": "CNY",
                "country": "CN",
                "amount": 59.28
            },
            "rate": 253.05,
            "fee": {
                "amount": 1850
            }
        },
        "recipient": {
            "name": "Zen Lui",
            "firstName": "Zen",
            "lastName": "Lui",
            "relationship": "SELF",
            "type": "MOBILE",
            "account": {
                "accountNumber": "8612343562723"
            },
            "paymentChannel": "WECHAT",
            "currency": "CNY",
            "country": "CN"
        },
        "created": "2025-02-27T14:17:48.038044",
        "processed": "2025-02-27T14:20:49.712685"
    }
}

meCash to WeChat

meCash uses the WeChat and supports the following types:

MOBILE

Key fields for WeChat:

recipient.paymentChannel: WECHAT
recipient.type: MOBILE
recipient.account: May be an empty object or require specific fields based on your integration setup (please verify). The original example showed an empty object.
recipient.email: Optional, but can be helpful for record-keeping as shown in the original example.

Sample cURL Request for WeChat

 
curl -X POST https://api.me-cash/v1/payouts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "recipient": {
      "firstName": "Zen",
      "lastName": "Lui",
      "email": "test@email.com",
      "type": "MOBILE",
      "account": {},
      "paymentChannel": "WECHAT",
      "currency": "CNY",
      "country": "CN",
      "stored": true
    },
    "quoteId": "859b19e8-8a00-4d59-9970-85395006cc13",
    "reason": "Gift"
  }'

Success Response for CNY WeChat Payment Channel (200 OK)

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

{
    "message": "Transaction created successfully",
    "status": "success",
    "data": {
        "id": "8c684c17-ef91-4133-a624-53f31514f059",
        "remark": "Tested",
        "reason": "Gift",
        "referenceNumber": "W1TDB6RWSQMKF",
        "type": "SEND",
        "state": "COMPLETED",
        "quote": {
            "id": "b39b64b9-3ca0-4566-b66b-a5fef8e81e7a",
            "source": {
                "currency": "NGN",
                "country": "NG",
                "amount": 15000
            },
            "target": {
                "currency": "CNY",
                "country": "CN",
                "amount": 59.28
            },
            "rate": 253.05,
            "fee": {
                "amount": 1850
            }
        },
        "recipient": {
            "name": "Zen Lui",
            "firstName": "Zen",
            "lastName": "Lui",
            "relationship": "SELF",
            "type": "MOBILE",
            "account": {
                "accountNumber": "8612343562723"
            },
            "paymentChannel": "WECHAT",
            "currency": "CNY",
            "country": "CN"
        },
        "created": "2025-02-27T14:17:48.038044",
        "processed": "2025-02-27T14:20:49.712685"
    }
}

Bank Transfer for CNY

This channel supports

Business-to-Business (B2B) and
Business-to-Individual (B2I) transfers.

Key fields for Bank Transfer (Example - may vary):

recipient.paymentChannel: BANK_TRANSFER
recipient.type: BUSINESS or INDIVIDUAL
`recipient.account: Will require bank-specific details like:
accountNumber: The recipient's bank account number.
bankCode: A code identifying the recipient's bank.
branchCode: (If applicable) The bank branch code.
accountHolderName: Full name matching the bank account.

Note: Make sure you provide all required details accurately, especially account holder names, bank codes, and identification numbers.

Sample cURL Request (Bank Transfer - Business-to-Business):

 
curl --location --request POST 'https://api.me-cash.com/v1/payout' \
--header 'x-api-key: API_KEY_:YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient": {
    "firstName": "Zen",
    "lastName": "Lui",
    "idType": "HONGKONG_MACAO_TAIWAN_PERMIT", 
    "idNumber": "331081199609218031",      
    "mobileNumber": "+8611234567890",
    "relationship": "SELF",                  
    "type": "BUSINESS",                      
    "invoiceNo": "",                         
    "account": {
        "name": "Zen Lui",                   
        "accountNumber": "6222040000030016", 
        "type": "INDIVIDUAL",                
        "sortCode": "102100000000",         
        "bankName": "Industrial and Commercial Bank of China" 
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "CNY",
    "country": "CN",
    "stored": true
  },
  "quoteId": "9aef78b1-1b22-4c60-a123-987654321fed", 
  "reason": "Consulting fee payment"               
}'

Sample cURL Request (Bank Transfer - Business-to-Individual):

This example shows sending from a business (recipient.type: "BUSINESS") to an individual's bank account (recipient.account.type: "INDIVIDUAL"), including identity details.

curl --location --request POST 'https://api.me-cash.com/v1/payout' \
--header 'x-api-key: API_KEY_:YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient": {
    "firstName": "Zen",
    "lastName": "Lui",
    "idType": "HONGKONG_MACAO_TAIWAN_PERMIT", 
    "idNumber": "331081199609218031",      
    "mobileNumber": "+8611234567890",
    "relationship": "SELF",                  
    "type": "BUSINESS",                      
    "invoiceNo": "",                         
    "account": {
        "name": "Zen Lui",                   
        "accountNumber": "6222040000030016", 
        "type": "INDIVIDUAL",                
        "sortCode": "102100000000",         
        "bankName": "Industrial and Commercial Bank of China" 
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "CNY",
    "country": "CN",
    "stored": true
  },
  "quoteId": "9aef78b1-1b22-4c60-a123-987654321fed", 
  "reason": "Consulting fee payment" 
}

Payout Transaction States

The payout transaction can have one of the following states:

State	Description
`COMPLETED`	The payout was successfully processed.
`PENDING`	The payout is still being processed.
`FAILED`	The payout failed to process.
`REFUNDED`	The payout has been sent back to sender.

Error Handling

Status Code	Meaning	Example Response
`400`	Bad Request	`{ "message": "Invalid parameters" }`
`401`	Unauthorized	`{ "message": "Invalid API key" }`
`422`	Unprocessable Entity	`{ "message": "Invalid quote ID" }`
`500`	Internal Server Error	`{ "message": "An internal error occurred" }`

Best Practices

✅ Ensure Id is valid and linked to an existing quote.
✅ Confirm that the recipient’s AliPay account number is correct.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.

NGN - NGN Payout Example How Wallets work in meCash