CNY Payout – ALIPAY (MOBILE)

This guide explains how to initiate a CNY payout to an AliPay user via mobile number using the meCash API. The request must be sent as multipart/form-data with the transaction payload provided as a stringified JSON object under a transaction field.

Endpoint

POST {{baseURL}}/v1/payout

Header

Header	Value	Required
x-api-key	`YOUR_API_KEY`	✅ Yes

Example Request (AliPay via MOBILE)

curl --location 'https://{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--form 'transaction="{
  \"recipient\": {
    \"name\": \"Zen Lui\",
    \"firstName\": \"Zen\",
    \"lastName\": \"Lui\",
    \"mobile\": \"+86139XXXXXXXX\",
    \"relationship\": \"SELF\",
    \"type\": \"MOBILE\",
    \"account\": {
      \"accountNumber\": \"+86139XXXXXXXX\"
    },
    \"paymentChannel\": \"ALI_PAY\",
    \"currency\": \"CNY\",
    \"country\": \"CN\"
  },
  \"stored\": true,
  \"quoteId\": \"859b19e8-8a00-4d59-9970-xxxxxxxxxxxxxx\",
  \"reason\": \"Family Support\"
"}'

Success Response (200 OK)

 
{
    "message": "transaction created successfully",
    "status": "success",
    "data": {
        "id": "b5f82f72-ecb1-49a1-aafa-ac681d7e0bab",
        "remark": "",
        "reason": "Bills",
        "referenceNumber": "VWP090265YRTT",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "6f518f6f-1791-4638-b5fd-2ef9895d4179",
            "source": {
                "currency": "NGN",
                "country": "NG",
                "amount": 3000.00
            },
            "target": {
                "currency": "CNY",
                "country": "CN",
                "amount": 12.93
            },
            "rate": 232.00000000,
            "fee": {
                "amount": 5.00
            },
            "summary": {
                "total": 3005.00
            },
            "expiresInSeconds": 0
        },
        "recipient": {
            "name": "Zen Lui",
            "firstName": "Zen",
            "lastName": "Lui",
            "relationship": "SELF",
            "type": "MOBILE",
            "account": {
                "accountNumber": "8612343562723"
            },
            "paymentChannel": "ALI_PAY",
            "currency": "CNY",
            "country": "CN"
        },
        "created": "2025-05-19T20:56:53.884728164",
        "processed": "2025-05-19T20:56:53.884728164"
    }
}

Response Breakdown

General Information

Field	Type	Description
`message`	String	Transaction status message
`status`	String	Overall operation status (`success`/`error`)

Transaction Data

Field	Type	Description
`id`	String	Unique transaction identifier
`remark`	String	Optional remarks/notes
`reason`	String	Transaction purpose (e.g., `"Bills"`)
`referenceNumber`	String	Unique reference for tracking
`type`	String	Transaction type (`SEND`)
`state`	String	Current status (`PENDING`)
`created`	String	ISO 8601 creation timestamp
`processed`	String	ISO 8601 processing timestamp

Quote Details

Field	Type	Description
`quote.id`	String	Unique quote identifier
`quote.rate`	Number	FX rate used (e.g., `232.00000000`)
`quote.expiresInSeconds`	Number	Quote validity period (0 = expired/immediate)

Source Funds

Field	Type	Description
`quote.source.currency`	String	Source currency (`NGN`)
`quote.source.country`	String	Source country code (`NG`)
`quote.source.amount`	Number	Original amount sent

Target Funds

Field	Type	Description
`quote.target.currency`	String	Destination currency (`CNY`)
`quote.target.country`	String	Destination country code (`CN`)
`quote.target.amount`	Number	Converted received amount

Fees

Field	Type	Description
`quote.fee.amount`	Number	Transaction fee charged

Summary

Field	Type	Description
`quote.summary.total`	Number	Total amount deducted (source + fees)

Recipient Details

Field	Type	Description
`recipient.name`	String	Full recipient name
`recipient.firstName`	String	First name
`recipient.lastName`	String	Last name
`recipient.relationship`	String	Sender relationship (`SELF`)
`recipient.type`	String	Identifier type (`MOBILE`)
`recipient.paymentChannel`	String	Transfer method (`ALI_PAY`)
`recipient.currency`	String	Recipient currency (`CNY`)
`recipient.country`	String	Recipient country (`CN`)

Recipient Account

Field	Type	Description
`recipient.account.accountNumber`	String	Mobile number/account ID

Error Handling

Status Code	Meaning	Example Response	How to Handle
400	Bad Request (No API Key)	"No API key found in request"	Ensure `x-api-key` header is sent with a valid key
400	Validation Error	"Required field missing or invalid request"	Check API documentation for required fields and input formats
400	Expired Quote	"Quote expired"	Generate a new quote using the Quote API and resubmit with fresh `quoteId`
400	Transaction Limit	"Minimum Transaction Limit is: 10.00CNY"	Ensure transaction amount meets minimum requirements (10.00 CNY equivalent in source currency)
401	Unauthorized (Invalid API Key)	"Invalid authentication credentials"	Verify API key in the header is correct and active in dashboard settings
403	Forbidden (Non-whitelisted IP)	"Your IP address is not allowed to access this service"	Whitelist your IP address in the API Management settings on the dashboard
422	Unprocessable Entity (Semantic Error)	"Invalid value in request body"	Review request body for semantic errors (e.g., invalid values or logic errors)
429	Too Many Requests (Rate Limited)	"API rate limit exceed"	Implement retry with exponential backoff; respect rate limits (e.g., 50 requests/sec)
500	Internal Server Error	"An unexpected error occurred on the server"	Retry after some time; if persistent, contact support

NGN to CNY AliPay (Email) NGN to CNY Bank Transfer (Company)