notifyTopup

2022-07-04 05:45

Use this API to send the top-up result to the merchant asynchronously. With this API call, the needed information is stored in JSON.

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
notifyType	NotifyType	Yes	The type of notification.	TOPUP_RESULT/TOPUP_PROCESS
topupId	String	No	DWS internal top-up ID. More information about this field: Maximum length: 64 characters	20220303194010800100165270282977819
topupRequestId	String	No	The merchant top-up ID/ order ID. More information about this field: Maximum length: 64 characters	20990501203220303486416376910
topupAmount	Amount	No		{ "currency": "THB", "value": "349600" }
topupDetailSummaries	List<TopupDetailSummary>	No	List of payment details for this top-up.	{ "customerId": "**************", "extendInfo": "{\"payProvider\":\"KASITHBK\",\"authCode\":\"047407\",\"cardIndexNo\":\"2019070119027100165906606897704\",\"maskedCardNo\":\"439137****2494\"}", "paymentAmount": { "currency": "THB", "value": "349600" }, "paymentMethodType": "MIXEDCARD" }
completeTime	Date	No	The time when the top-up is completed.	2022-03-03T09:44:35Z
result	Result	Yes	Details about the top-up result, such as top-up status, result code, and result message.	{ "resultCode":"SUCCESS", "resultStatus":"S", "resultMessage":"success" }
actionForm	ActionForm	No	This field is filled in 3D cases.

Response parameters

Field	Data type	Required	Description
result	Result	Yes	The request result, which contains information such as status and error codes.

Result processing logic

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

Result status	Description
S	The notifyTopup request is accepted successfully. The corresponding result.resultCode is `SUCCESS`, and result.resultMessage is `SUCCESS`.
U	The status of the notifyTopup 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 notifyTopup request failed. The corresponding result.resultCode and result.resultMessage may vary based on different situations. For details, see the following Error codes section.

Error 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.
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.
TOPUP_SUCCESS	S	Top-up is success	Top-up order is successful.
TOPUP_FAILED	F	Top-up is failed	Top-up order fails, the merchant can re-initiate the order.
TOPUP_CLOSED	F	Top-up order is closed or expired	Top-up order is closed or expired, the merchant can re-initiate the order.
TOPUP_PROCESSING	U	Top-up order is still processing	Top-up order is still under process, the merchant can retry to query the top-up to fetch information.

Samples

Request

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

When the value of result.resultStatus is S or F, the transaction has been finalized.

copy

{
  "notifyType": "TOPUP_RESULT",
  "result": {
    "resultCode": "SUCCES",
    "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

{
  "notifyType": "TOPUP_PROCESS",
  "result": {
    "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 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

{
  "notifyType": "TOPUP_PROCESS",
  "result": {
    "resultCode": "PAYMENT_IN_PROCESS",
    "resultStatus": "U",
    "resultMessage": "payment in processing"
  },
  "toppRequestId": "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"
  }
}

Response

The merchant sends the receipt to DWS.

copy

{
 "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}