CNY Payout – ALIPAY (EMAIL)

This guide explains how to initiate a CNY payout to an AliPay user via email 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

ℹ️

Note: You must generate a quote using the Quote API before making a payout. The quoteId from the response is required in the payout request.

Example Request (AliPay via EMAIL)

curl --location 'https://{{baseURL}}com/v1/payout' \
--header 'x-api-key: YOUR_API_KEY_HERE \
--form 'transaction="{
  \"recipient\": {
    \"name\": \"Zen Lui\",
    \"firstName\": \"Zen\",
    \"lastName\": \"Lui\",
    \"email\": \"random@example.com\",
    \"relationship\": \"SELF\",
    \"type\": \"EMAIL\",
    \"account\": {
      \"accountNumber\": \"861\"
    },
    \"paymentChannel\": \"ALI_PAY\",
    \"currency\": \"CNY\",
    \"country\": \"CN\"
  },
  \"stored\": true,
  \"quoteId\": \"859b19e8-8a00-4d59-9970-xxxxxxxxxxxxxx\",
  \"reason\": \"Gift\"
"}'

ℹ️

Payout Request body uses form data multipart/form-data.

Request Breakdown

Form Data Parameters

Parameter	Type	Description
`transaction`	JSON	JSON string containing all transaction details

Transaction Object

Field	Type	Description
`stored`	Boolean	Whether to store recipient details for future use
`quoteId`	String	Unique identifier for the FX quote
`reason`	String	Purpose of the transaction (e.g., "Gift")

Recipient Object

Field	Type	Description
`name`	String	Full name of recipient
`firstName`	String	Recipient's first name
`lastName`	String	Recipient's last name
`email`	String	Recipient's email address
`relationship`	String	Relationship to sender (e.g., "SELF")
`type`	String	Identifier type ("EMAIL")
`paymentChannel`	String	Payment method ("ALI_PAY")
`currency`	String	Currency code ("CNY")
`country`	String	Country code ("CN")

Account Object (within Recipient)

Field	Type	Description
`accountNumber`	String	Recipient's account identifier

Success Response 200K

{
    "message": "transaction created successfully",
    "status": "success",
    "data": {
        "id": "cb9c1def-ed41-44db-9e9e-xxxxxxxxxxxxx",
        "remark": "",
        "reason": "Bills",
        "referenceNumber": "OK0JPSXXXXXXX",
        "type": "SEND",
        "state": "COMPLETED",
        "quote": {
            "id": "1813914b-6ddd-498d-89a6-xxxxxxxxxxxxx",
            "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",
            "email": "random@example.com",
            "type": "EMAIL",
            "account": {
                "accountNumber": "861"
            },
            "paymentChannel": "ALI_PAY",
            "currency": "CNY",
            "country": "CN"
        },
        "created": "2025-05-19T21:13:20.527698839",
        "processed": "2025-05-19T21:13:20.527698839"
    }
}

Response Breakdown

General Information

Field	Type	Description
`message`	String	Transaction status message
`status`	String	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 tracking reference
`type`	String	Transaction type (`SEND`)
`state`	String	Current status (`COMPLETED`)
`created`	String	ISO 8601 creation timestamp
`processed`	String	ISO 8601 processing timestamp

Quote Details

Field	Type	Description
`quote.id`	String	Unique quote id generated for the payout
`quote.rate`	Number	FX rate applied (232.00000000)
`quote.expiresInSeconds`	Number	Quote validity (0 = expired/used)

Source Funds

Field	Type	Description
`quote.source.currency`	String	Source currency (`NGN`)
`quote.source.country`	String	Source country (`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 (`CN`)
`quote.target.amount`	Number	Converted received amount

Fees & Summary

Field	Type	Description
`quote.fee.amount`	Number	Transaction fee charged
`quote.summary.total`	Number	Total deducted (amount + 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.email`	String	Recipient email address
`recipient.type`	String	Identifier type (`EMAIL`)
`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	Account identifier/email

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 USD NGN to CNY AliPay (Mobile)