​
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
HeaderValueRequired
x-api-keyYOUR_API_KEY✅ Yes

​
Example Request (AliPay via EMAIL)

    ​
    Request Breakdown

    ​
    Form Data Parameters

    ParameterTypeDescription
    transactionJSONJSON string containing all transaction details

    ​
    Transaction Object

    FieldTypeDescription
    storedBooleanWhether to store recipient details for future use
    quoteIdStringUnique identifier for the FX quote
    reasonStringPurpose of the transaction (e.g., “Gift”)

    ​
    Recipient Object

    FieldTypeDescription
    nameStringFull name of recipient
    firstNameStringRecipient’s first name
    lastNameStringRecipient’s last name
    emailStringRecipient’s email address
    relationshipStringRelationship to sender (e.g., “SELF”)
    typeStringIdentifier type (“EMAIL”)
    paymentChannelStringPayment method (“ALI_PAY”)
    currencyStringCurrency code (“CNY”)
    countryStringCountry code (“CN”)

    ​
    Account Object (within Recipient)

    FieldTypeDescription
    accountNumberStringRecipient’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

    FieldTypeDescription
    messageStringTransaction status message
    statusStringOperation status (success/error)

    ​
    Transaction Data

    FieldTypeDescription
    idStringUnique transaction identifier
    remarkStringOptional remarks/notes
    reasonStringTransaction purpose (e.g., "Bills")
    referenceNumberStringUnique tracking reference
    typeStringTransaction type (SEND)
    stateStringCurrent status (COMPLETED)
    createdStringISO 8601 creation timestamp
    processedStringISO 8601 processing timestamp

    ​
    Quote Details

    FieldTypeDescription
    quote.idStringUnique quote id generated for the payout
    quote.rateNumberFX rate applied (232.00000000)
    quote.expiresInSecondsNumberQuote validity (0 = expired/used)

    ​
    Source Funds

    FieldTypeDescription
    quote.source.currencyStringSource currency (NGN)
    quote.source.countryStringSource country (NG)
    quote.source.amountNumberOriginal amount sent

    ​
    Target Funds

    FieldTypeDescription
    quote.target.currencyStringDestination currency (CNY)
    quote.target.countryStringDestination country (CN)
    quote.target.amountNumberConverted received amount

    ​
    Fees & Summary

    FieldTypeDescription
    quote.fee.amountNumberTransaction fee charged
    quote.summary.totalNumberTotal deducted (amount + fees)

    ​
    Recipient Details

    FieldTypeDescription
    recipient.nameStringFull recipient name
    recipient.firstNameStringFirst name
    recipient.lastNameStringLast name
    recipient.relationshipStringSender relationship (SELF)
    recipient.emailStringRecipient email address
    recipient.typeStringIdentifier type (EMAIL)
    recipient.paymentChannelStringTransfer method (ALI_PAY)
    recipient.currencyStringRecipient currency (CNY)
    recipient.countryStringRecipient country (CN)

    ​
    Recipient Account

    FieldTypeDescription
    recipient.account.accountNumberStringAccount identifier/email

    ​
    Error Handling

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