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

​
Example Request (AliPay via Mobile)

    ​
    Successful 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

    FieldTypeDescription
    messageStringTransaction status message
    statusStringOverall operation status (success/error)

    ​
    Transaction Data

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

    ​
    Quote Details

    FieldTypeDescription
    quote.idStringUnique quote identifier
    quote.rateNumberFX rate used (e.g., 232.00000000)
    quote.expiresInSecondsNumberQuote validity period (0 = expired/immediate)

    ​
    Source Funds

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

    ​
    Target Funds

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

    ​
    Fees

    FieldTypeDescription
    quote.fee.amountNumberTransaction fee charged

    ​
    Summary

    FieldTypeDescription
    quote.summary.totalNumberTotal amount deducted (source + fees)

    ​
    Recipient Details

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

    ​
    Recipient Account

    FieldTypeDescription
    recipient.account.accountNumberStringMobile number/account ID

    ​
    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