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

queryTopup

POST /ams/api/v1/topups/queryTopup

Use this API to obtain the current top-up status from DWS.

Note:

  • Before a query, the user has to perform the applyTopup API and create an order.

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

topupId

String

No

DWS internal top-up ID, given by response of the top-up application.

20220304190077000001165100221516728

topupRequestId

String

No

The unique ID that is assigned by a merchant to identify a top-up request. DWS uses this field for idempotence control.

More information about this field:

  • Maximum length: 64 characters

Note: This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

20220302190077000001163010221223552

** one of topUpId or topUpRequest has to exist at a single request [if both data exist, merchants are free to send both of them]

Response parameters

Field

Data type

Required

Description

Examples

result

Result

Yes

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

  • If the value of resultStatus is S, it does not mean that the user successfully tops up.

{

"resultCode": "SUCCES",

"resultStatus": "S",

"resultMessage": "success"

}

topupResult

Result

No

The top-up result, which contains information for top-up or top-up status.

  • If the value of resultStatus is S, it means that the user successfully tops up.

{

"resultCode": "PAYMENT_IN_PROCESS",

"resultStatus": "U",

"resultMessage": "payment in processing"

}

topupDetailSummaries

List<TopupDetailSummary>

No

List of bounded top-up method.

[

{

"enabled": true,

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

"topUpMethodType": "MOMO_WALLET",

"preferred": false

}

]

topupRequestId

String

No

The unique ID that is assigned by a merchant to identify a top-up request. DWS uses this field for idempotence control.

More information about this field:

  • Maximum length: 64 characters

topupId

String

No

DWS internal top-up ID, given by response of top-up application.

More information about this field:

  • Maximum length: 64 characters

completeTime

Date

No

The time when the top-up is completed.

actionForm

ActionForm

No

Verification method, if the user needs to perform additional action.

Contains one of these models:

  • RedirectActionForm
  • ChallengeActionForm
  • PaymentCodeForm

Result processing logic

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

Result status

Description

S

The queryTopup request is accepted successfully.

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

U

The status of the queryTopup 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 queryTopup 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

/

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.

PAYMENT_IN_PROCESS

U

payment in process

Payment is still pending for processing and pending from DWS or a financial institution.

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.

Samples

Request

The merchant sends a request to DWS.

copy
{
  "topupRequestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553"
}

Response

When the top-up result is pending from the bank, DWS returns PAYMENT_IN_PROCESSas the top-up result.

  • The merchant can re-query DWS to obtain the top-up status after some moment.
  • The merchant can wait for DWS from sending the webhook and the status.
copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topupResult": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultStatus": "U",
    "resultMessage": "payment in processing"
  },
  "topupRequestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553",
  "topupDetailSummaries": [
    {
      "customerId": "2165210039309494",
      "extendInfo": "{\"payProvider\":\"KASITHBK\",\"authCode\":\"047407\",\"cardIndexNo\":\"20210312190279001699I8800024560\",\"maskedCardNo\":\"123456******1234\"}",
      "topupAmount": {
        "currency": "THB",
        "value": "10000"
      },
      "topupMethodType": "MIXEDCARD"
    }
  ],
  "topupAmount": {
    "currency": "THB",
    "value": "10000"
  }
}

When the top-up result is successful, DWS returns SUCCESS.

  • When the value of topupResult.resultStatus is S or F, the transaction has been finalized.
copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topupResult": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topupRequestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553",
  "topupDetailSummaries": [
    {
      "customerId": "2165210039309494",
      "extendInfo": "{\"payProvider\":\"KASITHBK\",\"authCode\":\"047407\",\"cardIndexNo\":\"20210312190279001699I8800024560\",\"maskedCardNo\":\"123456******1234\"}",
      "topupAmount": {
        "currency": "THB",
        "value": "10000"
      },
      "topupMethodType": "MIXEDCARD"
    }
  ],
  "topupAmount": {
    "currency": "THB",
    "value": "10000"
  }
}

When verification of a top-up notification is required from DWS, DWS returns PAYMENT_IN_PROCESSas with ChallengeActionForm.

  • Once the merchant receives ChallengeActionForm, the merchant shall proceed with the transaction to the verification process.
  • Once the user has submitted the information, the merchant can re-query queryTopup or wait for the notifyTopup webhook to obtain the final status.
copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topupResult": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultStatus": "U",
    "resultMessage": "payment in processing"
  },
  "topupRequestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553",
  "topupDetailSummaries": [
    {
      "customerId": "2165210039309494",
      "extendInfo": "{\"payProvider\":\"KASITHBK\",\"authCode\":\"047407\",\"cardIndexNo\":\"20210312190279001699I8800024560\",\"maskedCardNo\":\"123456******1234\"}",
      "topupAmount": {
        "currency": "THB",
        "value": "10000"
      },
      "topupMethodType": "MIXEDCARD"
    }
  ],
  "topupAmount": {
    "currency": "THB",
    "value": "10000"
  },
  "actionForm": {
    "actionFormType": "ChallengeActionForm",
    "challengeRenderValue": "************9528",
    "challengeType": "CARD_PLAIN_TEXT",
    "extendInfo": "{\"verifyId\":\"c29dc56218941e03bc0f6139d8ea2805_qk_site\"}",
    "triggerSource": "IPAY"
  }
}

When verification of a top-up notification is required from the bank, DWS returns PAYMENT_IN_PROCESSas with RedirectActionForm.

  • Once the merchant receives RedirectActionForm, the merchant shall redirect their user to the bank page through the given URL.
  • After the user has finished their ChallengeActionForm, the user is still required to complete the additional verification from the bank side (double challenge is possible).
  • Once the user submitted the information, the merchant can re-query queryTopup or wait for the notifyTopup webhook to obtain the final status.
copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topupResult": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultStatus": "U",
    "resultMessage": "payment in processing"
  },
  "topupRequestId": "20220302190077000001163010221223552",
  "topupId": "20220302190077000001163010221223553",
  "topupDetailSummaries": [
    {
      "customerId": "2165210039309494",
      "extendInfo": "{\"payProvider\":\"KASITHBK\",\"authCode\":\"047407\",\"cardIndexNo\":\"20210312190279001699I8800024560\",\"maskedCardNo\":\"123456******1234\"}",
      "topupAmount": {
        "currency": "THB",
        "value": "10000"
      },
      "topupMethodType": "MIXEDCARD"
    }
  ],
  "topupAmount": {
    "currency": "THB",
    "value": "10000"
  },
  "actionForm": {
    "actionFormType": "RedirectActionForm",
    "method": "POST",
    "parameters": "{\"MD\":\"2022031989031300002509253462073~2022031989031300002509253462073~ECPYW3PK~pNEdDTzphLeiaqMsV+HRM6jKB1k/zkSC6Ndeo+CpbEe5VZU26W1k6i8zwv8QVnh8jMgi9zc+Z8omVVWOlMm/4ByBcZz7vnwkf/WWhNeSZaOhs8M2bFbIWSQjy+VH9FpqtunD9Po0Nc5II1xFjdsdtOOkIHmTfOrpiCPUI1tTS5TWUxrgV8JJanNLMm87p1Rt/CxRnT+HtOluNBlPp2Qy9VVfl1LAFcG3x6EIJ+obhIFcckwas3D4k0R+BEu1n6sHhpDozPM2ePG4gur6F5DN5wOZkXiG+mezbFBiFkhqJmM+yYC3w0B1dU6owfW/sMv+orOi4ngs+V6eqkiSV1dpyg==\",\"PaReq\":\"eAFVUl1vgjAUfTfxPxDeR0uxCOZagzPL1Gwh6LKPtwYaYVPAgkP3uF+z37VfshZ1bm89596enntuYbTfrI13IausyIembWHTEHlcJFm+GpoPy5srzxyxbgeWqRRishDxTgoGd6Kq+EoYWaLuYIxpn1LqEt83GYRBJLYMTppMSVoE0BmqqzJOeV4z4PF2PL1nPUyoZwM6QdgIOZ0wpUps6ji26/b7vgPoSEPON4JNgih4scI5oBZCXOzyWh4Y9VxAZwA7uWZpXZfVAKGmaayES/5hlW+AdAXQxUm4054qNdg+S9hsRXjzvJfzfLzySDmxY/zUpIWgh+kQkO6AhNeCEUwIdmzfwP7AdgcOBdTywDfaDwvnkfH9+eV7xMJYzXdkodSPBUegarr0lwKVsFQrOE9zRiD2ZZELpavS/D0Duni/vtWZxrVKr6BReJg9SjKP7GIxrpM+2U7p6/uBb7WTY5NWzFRqpIe9VlIDQFoGnZaoMmoXrZh/H6Db+QHqvrjb\",\"TermUrl\":\"https://open-pk.alipay.com/isupergw/mpgs22/mpgs221202.htm\"}",
    "redirectUrl": "https://authentication.cardinalcommerce.com/ThreeDSecure/V1_0_2/PayerAuthentication?issuerId=598231ef0063ac1ce0671a64&transactionId=o5RPyJWr2KR1oSBtd72qI5jvyaq0"
  }
}