Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

applyTopup

POST /ams/api/v1/topups/applyTopup

Use this API to initiate a top-up request and increase user balance.

Note:

  • Before applying, the user has to perform the consult top-up process to obtain top-up payment method information.
  • If users plan to use a new top-up method, it is recommended to perform the cacheCard API prior to the top-up application process.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Note: Set the data type of each field (except array) as String. This means that you must use double quotation marks (" ") to enclose the field value. Examples:

  • If the data type of a field is Integer and its value is 20, set it as "20".
  • If the data type of a field is Boolean and its value is true, set it as "true".

Request parameters

Field

Data type

Required

Description

Examples

requestId

String

Yes

The merchant top-up ID/ order ID.

  • Indicates the idempotency of a top-up request
  • The value is unique.

More information about this field:

  • Maximum length: 64 characters

20220302190077000001163010221223552

topupDetails

List<TopupDetail>

Yes

The top-up detail information that is related to the top-up method, customer, and top-up amount.

[{

"topupAmount": { // can be rename to topupAmount

"value": 960000,

"currency": "PHP"

},

"topupMethod": {

"topupMethodType": "GCASH_EBANK",

"topupMethodId": "ALIPAYcAEuXghSHz5O/iQ7R6pyIFFafsPVSqPwIN93o0Ncxy25zQ/fGSpTHm1JOQKr/QRtyWCloE4MwfmN48sP1+rSPQ\u003d:",

"topupMethodMetaData": {

"channelOptionBill": "{\"maskCardNo\":\"*********3012\"}",

"bindPaymentMethod": "false",

"boundPaymentMethod": "true"

},

"customerId": "2163210007360016"

}

}]

notifyUrl

String

No

redirectUrl

String

No

env

Env

Yes

The environment-related information, which is used for fraud analysis.

  • env.terminalType is mandatory

Response parameters

Field

Data type

Required

Description

Examples

result

Result

Yes

The request result, which contains information such as status and error codes. The result does not contain top-up or top-up status.

  • The success value does not mean the user has been charged.

topupId

String

No

DWS internal top-up ID.

More information about this field:

  • Maximum length: 64 characters

requestId

String

No

The merchant top-up ID/ order ID.

  • Indicates the idempotency of a top-up request
  • The value is unique.

More information about this field:

  • Maximum length: 64 characters

topupDetailSummaries

List<TopupDetailSummary>

No

List of the bounded top-up methods.

[

{

"enabled": true,

"topUpMethodDetail": "{\"card\":{\"cardIssuer\":\"MOMO\",\"cardToken\":\"ALIPAYHWuKSBwokmmIZVmVlkRiSbrZRgzKc+SKuKP6Nh2lH5U+UytZNXEsH43GVtfH2uUgecG+d5jFylCRsGrtK8j0YA\u003d\u003d\",\"instUserName\":{},\"topUpMethodDetailMetadata\":\"{\\\"cardIndex\\\":\\\"20210312190279001699I8800024560\\\"}\"},\"type\":\"card\"}",

"topUpMethodType": "MOMO_WALLET",

"preferred": false

}

]

actionForm

ActionForm

No

The next action to do when the processing result is not the final status, as a reference for the next action. According to challengeType, you can determine the factor to be verified in the next step.

When need to do OTP verification:

{

"challengeRenderValue": "+6222***508",

"challengeType": "SMS"

}

When need to do PIN verification

{

"challengeRenderValue": "",

"challengeType": "PAYMENT_PASSWORD"

}

Result processing logic

In the response, the result.resultStatus field indicates the result of the applyTopUp request. The following table describes each result status:

Result status

Description

S

The applyTopup request is accepted successfully.

The corresponding result.resultCode is SUCCESS, and result.resultMessage is SUCCESS.

U

The status of the applyTopup request is unknown.

The corresponding result.resultCode is UNKNOWN_EXCEPTION, and result.resultMessage is An API call failed, which is caused by unknown reasons. For details, see the Common error codes section.

F

The applyTopup request failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

Result codes

Result code

Result status

Result message

Further action

SUCCESS

S

Success

N/A

PROCESS_FAIL

F

A general business failure occurred. Don't retry.

Human intervention is usually needed. It is recommended that you contact the technical support team to troubleshoot the issue.

PARAM_ILLEGAL

F

Illegal parameters. For example, non-numeric input, or invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

UNKNOWN_EXCEPTION

U

API failed due to unknown reasons.

Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.

NO_PAY_OPTIONS

F

No addable payment options were found.

Contact Alipay Technical Support.

USER_STATUS_ABNORMAL

F

The user status is abnormal.

Contact the digital wallet to check the user status.

USER_NOT_EXIST

F

The user does not exist.

Contact Alipay Technical Support to know the specific reasons.

KEY_NOT_FOUND

F

Key is not found.

Check whether the private key or public key exists. If not, upload the private key in Alipay Developer Center.

INVALID_API

F

API is invalid (or not active).

Check whether the API name, HTTP method, or request format is correct when sending the request.

INVALID_CLIENT

F

Invalid client.

Check whether the client ID is correct, or contact Alipay Technical Support for detailed reasons.

INVALID_SIGNATURE

F

Signature is invalid.

Check whether the private key used to sign a request matches the public key of Alipay Developer Center.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

Request traffic exceeds the limit.

Call the interface again to resolve the issue. If the issue persists, contact Alipay Technical Support.

ACCESS_DENIED

F

Access denied.

Contact Alipay Technical Support for detailed reasons.

SEND_TIMES_EXCEED_LIMIT

F

The send times exceed the limit.

Contact Alipay technical support to know the specific limitation.

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

REPEAT_REQ_INCONSISTENT

F

Repeated requests are inconsistent.

Ensure the fields in the requests are the same.

RISK_REJECT

F

Reject by risk control.

Prompt the user that the request is rejected because the risk control failed.

RISK_CHALLENGE

F

Risk challenge.

Prompt the user to go through the user information verification.

AML_REJECT

F

AML reject the transaction.

Prompt the user that the request is rejected because of the high risk.

USER_BALANCE_EXCEED_LIMIT

F

The total balance amount exceeded amount limit.

Consult Alipay Technical Support about the amount limit.

USER_NOT_KYC

F

The user not complete the KYC.

Prompt the user to complete KYC.

LOWER_EXCEED_AMOUNT_LIMIT

F

The total amount exceeded min-amount limit.

Consult Alipay Techncal Support about the minimum amount.

UPPER_EXCEED_AMOUNT_LIMIT

F

The total amount exceeded max-amount limit.

Consult Alipay Techncal Support about the maximum amount.

Samples

Request

The merchant sends a request to DWS.

copy
{
  "requestId": "20220302190077000001163010221223552",
  "topupDetail": [{ 
    "topupAmount": { 
      "value": 10000,
      "currency": "PHP"
    },
    "topupMethod": { 
      "topupMethodType": "GCASH_EBANK",
      "topupMethodId": "ALIPAYHWuKSBwokmmIZVmVlkRiSbrZRgzKc+SKuKP6Nh2lH5U+UytZNXEsH43GVtfH2uUgecG+d5jFylCRsGrtK8j0YA\u003d\u003d",
      "topupMethodMetaData": {
        "channelOptionBill": "{\"maskCardNo\":\"*********3012\"}",
        "bindPaymentMethod": "false",
        "boundPaymentMethod": "true"
      },
      "customerId": "2165210039309494"
    }
  }],
  "env": {
    "clientIp": "180.74.64.146",
    "sessionId": "GZ00x9wKFvPfMf8BaCrKqBPr5iHMn6imobilegwGZ00",
    "deviceTokenId": "QMHYNKSPtQkvhh5cj/NDdJpyuLzS1f5+FN+B657n8dB63ZRKfwEAAA",
    "terminalType": "IPAY_APP",
    "language": "en_MY",
    "clientUmid": "null",
    "userAgent": "mozilla/5.0 (linux; u; android 11; zh-cn; cph1969 build/rp1a.200720.011) applewebkit/537.36 (khtml,like gecko) version/4.0 chrome/69.0.3497.100 uws/3.22.1.205 mobile safari/537.36 aliapp(la/6.94.3) ucbs/2.11.1.1 ttid/600***@lazada_android_6.94.3 windvane/8.5.0 1080x2228",
    "cookieId": "null",
    "umidTokenId": "null",
    "osType": "android",
    "osVersion": "11",
    "deviceModel": "unknow",
    "deviceVersion": "null",
    "appVersion": "6.94.3",
    "browserVersion": "4.0",
    "browserType": "Android  Browser",
    "isPastedCard": false,
    "operateEntrance": "null",
    "longitude": "null",
    "latitude": "null",
    "imei": "null",
    "clientUuid": "null",
    "utdId": "null",
    "verifyEnvData": "null",
    "hideProcessPayment": false
  }
}

Response

DWS returns the request result.

copy
{
  "result": {
    "resultCode": "SUCCES",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "requestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553",
  "topupDetailSummaries": [
    {
      "customerId": "2165210039309494",
      "topupAmount": {
        "currency": "THB",
        "value": "10000"
      },
      "topupMethodType": "MIXEDCARD"
    }
  ]
}