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

API integration guide

Before you start

  1. Refer to the sample use case of user paying with wallet balance for a better understanding of the product features and APIs in the following sections.
  2. Identify what Open APIs you would like to implement to support developers. The following sections illustrate the commonly used Open APIs in most of the use cases:
  • Payment Open APIs
  • Authorization Open APIs
  • Customer Open APIs

For a complete list of Open APIs, please refer to Open API Version 2.

  1. Generate a public-private key pair (or reuse it if you already have a key pair for this purpose). You will also need to have a mechanism to issue Client ID to developers and configure its corresponding public key. Before server integration with developers, you need to exchange public keys with developers, for encryption and signature verification purposes.

Information Exchange

Direction

Description

DWS public key

Merchant --> Wallet

The merchant-associated public key is used for signature and encryption.

Endpoints URLs

Wallet --> Merchant

To connect to Wallet's endpoints, such as https://{host}/api/{restful_path}.

Client ID

Wallet --> Merchant

Client ID to identify a merchant.

Merchant private key

Wallet --> Merchant

The merchant-associated public key is used for signature and encryption.

How it works

51d5217a1ee4d6698f7bc168f8e3f4f6.svg

Member

Account management

Open account

1. Introduction

This function allows users to open a wallet account.

Note:

  1. If the user's mobile number is registered on the merchant platform, the merchant sends the user's mobile number to the wallet to ensure it is synchronized between the merchant and wallet.
  2. Else, the user is allowed to enter the mobile number via the wallet.

2. User experience

The following diagram shows the user experience of this function.

User experience-3.1.2-1.jpg

3. Pre-requisite

Note: The user's mobile number must be obtained.

4. Workflow

The following diagram details how operations are carried out in the wallet account opening process:

API integration guide
  1. The user enters the mobile phone number to open a wallet account.
  2. The merchant server calls the initAuthentication API to initialize the authentication process to verify the user's identity.
  3. The wallet server returns authenticationId to the merchant server.
  4. The merchant server calls the triggerChallenge API to trigger the authentication process.
  5. The wallet server returns challengeType to specify the method to verify the user's identity.
  6. The merchant server guides the user to verify identity based on challengeType.
  7. If the value of challengeType is SMS, the user's mobile phone that is bound to the account will receive an OTP.
  8. The user enters the OTP.
  9. The merchant server calls the verifyAuthentication API to verify whether the OTP is correct.
  10. DWS returns the verification result to the merchant server.
  11. The merchant server returns the verification result to the user.
  12. (Optional) The user enters an email address.
  13. The merchant server calls the registerCustomerWithProduct API to activate the account.
  14. The wallet server returns the activation result to the merchant server. If activation succeeded, the customerId will also be returned to the merchant server.
  15. The merchant server returns the activation result to the user.
  16. The user sets the PIN.
  17. The merchant server calls the applyPublicKey API to obtain the public key and salt.
  18. The wallet server returns the public key and salt, along with the unique ID to identify the public key in each API call.
  19. The merchant server encrypts the PIN with the public key and salt via the RSA algorithm.
  20. The merchant server calls the modifyAuthentication API to send the encrypted PIN and customerId to the wallet server. Then wallet server sets the PIN for the account.
  21. The wallet server returns the result for the PIN settings to the merchant server.
  22. The merchant server returns the final registration result to the user.

Note: The entire user registration process is not completed until the user completes the PIN setting. Users who have not set a PIN will be considered to have not successfully registered and will not be able to successfully call other functions.

5. Procedure

You need to take the following integration steps to enable the user to complete the wallet account registration process:

Step 1: Initialize authentication

When the user enters the mobile phone number, the merchant server calls the initAuthentication API to initialize the authentication process. If this API call succeeds, the wallet server returns authenticationId to trigger the challenge and actionForm to guide the user to do the identity verification.

Sample request

The merchant server sends the request of initializing authentication to the wallet server.

copy
{
	"authenticationRequestId": "MDEDUCT001bd856ad81cec1e91a620c270bcba5a4223",
	"authenticationMethod": "OTP",
	"authenticationType": "SMS",
	"identityType": "MOBILENO",
	"identityValue": "60-8517846353",
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en-US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }
}

Sample response

The wallet returns the request result and references to initialize authentication to the merchant.

copy
{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType":"sms"
  },
  "authenticationId":"20220105190077000000162140200586657",
  "authenticationRequestId":"c2c25606-9f1e-4697-853d-da2517bf67be",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 2: Trigger authentication challenge

After the authentication challenge is initiated successfully, the merchant server calls the triggerChallenge API to trigger a challenge to verify the user's identity. If this API call succeeds, the wallet server returns the challenge data to specify the method to do the identity verification. If the wallet server specifies to complete the SMS verification, the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of challengeId used in the triggerChallenge API must be the same as the value of authenticationId returned by the initAuthentication API.

Sample request

The merchant server sends the request of triggering the challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20220105190077000000162140200586657"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 3: Verify authentication challenge

After the user enters and confirms the OTP, the merchant server calls the verifyAuthentication API to verify whether the OTP is correct.

  • The value of pass is true, which indicates the verification passed. The user can proceed to the next step.
  • The value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, which indicates the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of authenticationId returned by the initAuthentication API.

Sample request

The merchant server sends the request of verifying OTP to the wallet server.

copy
{
  "authenticationId":"20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en-US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }
}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "20220105190077000000162140200586657",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong otp value,can input again",
    "resultStatus": "F"
  }
}
Step 4: Register user

When the user completes the verification, the merchant server calls the registerCustomerWithProduct API to activate the wallet account. If the activation succeeds, the wallet will return customerId to the merchant server. Then the merchant can guide the user to set a PIN.

Request parameters need to follow the requirements below:

  • The value of customer.user.mobileNoInfo used in the registerCustomerWithProduct API must be the same as the mobile phone number entered by the user.

Note: The merchant needs to store the status of the account opening and customerId.

Sample request

The merchant server sends the activation request to the wallet server.

copy
 {
    "applyRequestId":"rgdp4U8coUGIWjDOkRW8kkP",
    "env": {
        "language":"ko-KR",
        "osVersion":"8.1.0",
        "osType":"ios8929",
        "pastedCard":false,
        "clientUmid":"sdjoi02082",
        "sessionId":"1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType":"APP",
        "clientIp":"123.136.111.19",
        "hideProcessPayment":false
    },
    "customer": {
        "customerType":"USER",
        "accounts": [
             {
                "currency":"SGD",
                "accountType":"BALANCE_ACCOUNT"
            }
        ],
        "user": {
            "address": {
                "zipCode":"3100000",
                "address2":"XihuDistrict",
                "city":"Hangzhou",
                "address1":"ShentonWay1",
                "state":"Zhejiang"
            },
            "occupation":"Student",
            "gender":"MALE",
            "nationality":"TH",
            "mobileNoInfo": {
                "countryCode":"60",
                "verified":true,
                "phoneNo":"8517846353"
            },
            "userName": {
                "firstName":"John",
                "lastName":"Doe",
                "nickName":"word",
                "companyName":"word",
                "fullName":"JohnDoe",
                "middleName":"Jerry"
            },
            "email":"example@example.com"
        },
        "referenceCustomerId":"231341413144"
    }
}

Sample response

The wallet server returns the activation result to the merchant server.

copy
 {
        "applyRequestId":"rgdp4U8coUGIWjDOkRW8kkP",
        "customerId":"2188210123456789",
        "referenceCustomerId":"231341413144",
        "resultInfo": {
                "resultCodeId":"IPAY_RS_100000200",
                "resultMsg":"success",
                "resultStatus":"S"
        },
}
Step 5: Apply public key

After the user enters and confirms the PIN, the merchant server calls the applyPublicKey API to obtain a public key and salt to encrypt the PIN via the RSA algorithm. The wallet server will also return a unique ID to identify the public key.

Note: Once the public key is used for the PIN encryption, it will be invalid. The merchant needs to apply a new public key again.

Sample request

The merchant server requests to obtain a public key from the wallet server.

copy
{
	"customerId": "2188210123456789",
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "publicKeyInfo": {
    "uniqueId": "s8NeKdTshiXVAPXzBRTIQigKh4PbnIiS",
    "salt": "IRfe92wH04sh",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 6: Set PIN

After the merchant server encrypts the PIN, the merchant calls the modifyAuthentication API again to send the encrypted PIN to the wallet server. The wallet server sets the PIN for the account.

  • If this API call succeeds, the overall registration process is completed.
  • If the PIN setup result is failed, the merchant should display a prompt page that the account opening is successful but the PIN setting fails. The merchant can prompt the user to set PIN again during balance check or other requests.

Request parameters need to follow the requirements below:

  • The value of publicKeyUniqueId used in the modifyAuthentication API is the same as the value of uniqueId returned by the applyPublicKey API.
  • The value of customerId used in the initAuthentication API is the same as the value of customerId returned by the registerCustomerWithProduct API.

Sample request

The merchant server sends the request of setting the PIN to the wallet server.

copy
 { 
        "authenticationBizScene":"NEW_SET",
        "authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"2188210123456789",
        "identityType":"CIPHERTEXT",
        "identityValue":"aHh91grWBD6OXb4JYjeSE8G048ys3HegfC0eaHrmxaOvdUk1+KocJysb0s9TvA0HvT8+a2ED1OJNorzxp7ju0Ir8EuJvw1eH0YNrmFyX2nFZxmdI3FcLegq5M7QngjtuHyRgXbfS8pZPam8Yn3OC/IYpLT4Xi42wQ2BzjznIpzPilBNR+byhRG4PTIdePjyseiYuyHScxkRMqBcIJKJB8qZ7ZAYgvuMXXiUkKXIseIKdfldVq6TaWaLA5p9Z5rj7YzsEadZQjIGPiThGRvGqALBLtieqRwOQOrswPt9XXw1uPALQhTJQ/41Me90xwLi5+ZgCxHDEtHbYQx++s5CaPA==",
        "publicKeyUniqueId":"Fno5AgHDX2SqnAtwnbkZVKVnD0jfLiEn"
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

initAuthentication

Merchant --> DWS

Use this API to initiate a registered customer request and obtain an authentication ID. This is the first step in the entire registration process.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

registerCustomerWithProduct

Merchant --> DWS

Use this API to register an account for the user after the user passes the challenge verification successfully.

applyPublicKey

Merchant --> DWS

Use this API to apply a public key and slat, which is used to encrypt a plaintext password.

5.3.1.2 Check balance

1. Introduction

After completing the account opening, the merchant checks and displays the available balance. If PIN was not successfully set during account opening, the merchant needs to prompt the user to set PIN again.

The payments regulation mandates Strong Customer Authentication (SCA) for many online payments in the European Economic Area (EEA). So, for users in Europe, a form of two-factor authentication is required.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.1.2-1.jpg

3. Pre-requisite

Note: Wallet account must be activated.

4. Workflow

API integration guide

The merchant calls the queryAccountAndBenefit API to check and display the users' balance. (Step 2-3)

If the user is located in the European region, DWS requires the user to complete the identity verification for regulatory reasons. Call the triggerChallenge API to trigger challenge and complete the verification by the verifyAuthentication API. (Step 4-17) And then call the queryAccountAndBenefit API again to complete the balance checking.

5. Procedure

Step 1: Check balance

The merchant calls the queryAccountAndBenefit API to check the user's balance and display the balance with availability and status.

Request parameters need to follow the requirements below:

  • The value of the processId field is null on the first call of the queryAccountAndBenefit API.

Sample request

The merchant server requests to check the balance from the wallet server.

copy
{
  "environment": {
    "clientIp": "",
    "deviceTokenId": "",
    "language": "",
    "sessionId": "",
    "termonalType": "APP",
    "umidTokenId": ""
  },
  "customerId": "2162265049047338",
  "queryAccountConditions": [{
    "accountType": "BALANCE_ACCOUNT"
  }]
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "accounts": {
    "accountNo": "********************",
    "accountStatus": "available",
    "accountType": "BALANCE_ACCOUNT",
    "availableAmount": {
      "currency": "MYR",
      "value": "23"
    },
    "createTime": "2020-01-13T01:16:44-08:00",
    "crossSiteCustomerId": "2162265049047338",
    "currency": "MYR",
    "customerTntInstId": "HLOPW3MY",
    "frozenAmount": {
      "currency": "MYR",
      "value": "0"
    },
    "holderName": {
      "middleName": ""
    },
    "totalAmount": {
      "currency": "MYR",
      "value": "23"
    }
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 2: Authenticate and check balance

DWS requires authentication for users in Europe, sometimes it only needs an SMS challenge or PIN challenge, and sometimes it needs a two-factor challenge (PIN first, OTP then). For these situations, the queryAccountAndBenefit API returns processId and actionForm to guide the user to complete the identity verification.

The value of challengeType in result is PAYMENT_PASSWORD or SMS_OTP.

Sample

Response

The wallet returns the balance checking result and the risk challenge.

OTP challenge

copy
{
    "actionForm":{
        "actionFormType":"ChallengeActionForm",
        "challengeRenderValue":"57d8c5c03bf2403591e2eace1642fbc4_us_site",
        "challengeType":"SMS_OTP"
    },
    "processId":"20220112110077000000190830201924924",
    "result":{
        "resultCode":"SUCCESS",
        "resultMessage":"success.",
        "resultStatus":"S"
    }
}

PIN challenge

copy
{
    "actionForm":{
        "challengeRenderValue":"",
        "challengeType":"PAYMENT_PASSWORD"
    },
    "processId":"20220112110077000000190830201924924",
    "result":{
        "resultCode":"SUCCESS",
        "resultMessage":"success.",
        "resultStatus":"S"
    }
}

Trigger authentication challenge

Request parameters need to follow the requirements below:

  • The value of the challengeId field used in the triggerChallenge API must be the same as the value of the processId field returned by the queryAccountAndBenefit API.

Sample request

The merchant server sends the request of triggering the challenge to the wallet server. If challengeType is PAYMENT_PASSWORD, the public key is returned to encrypt the old PIN that the user entered.

Call the triggerChallenge API and obtain the public key to encrypt the old PIN by the encryption algorithm RSA.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20220112110077000000190830201924924"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

PIN

copy
{
  "challengeRenderData": {
    "challengeRenderValueType": "encryptionInput",
    "challengeRenderValue": "{\"public_key\":\"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB\",\"salt\":\"WWXSzmVj06et\"}",
    "canRetryChallenge": false,
    "isChallengeFinish": false,
    "challengeLeftTimes": null
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

OTP

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verify authentication challenge

a. Two-factor challenge:

The merchant calls the verifyAuthentication API to verify the challenge. If a form of two-factor is required, actionForm in response when you first call the verifyAuthentication API is not null. The merchant needs to complete the next verification.

1. Verify PIN

The user enters the old PIN, and then the merchant server encrypts the old PIN with the public key and salt returned by the triggerChallenge API via RSA algorithm. Then, the merchant server calls the verifyAuthentication API to verify whether the PIN is correct.

  • If the value of pass is true, the verification passed. The user can proceed to verify OTP by the actionForm.challengeType field, which is sms.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the value of the inquiryProcessId field returned by the inquiryAccountAndBenefit API.
  • The challengeData.passwordValue field is filled with the old PIN encrypted.

Sample request

The merchant server sends the request of verifying the old PIN to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId": "cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717",
  "challengeData":{
    "challengeType":"PAYMENT_PASSWORD",
    "passwordValue":"y+ySfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A=="
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded and OTP verification is needed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "actionForm": {
    "challengeRenderValue": "",
    "challengeType":"sms"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "2",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value,can input again",
    "resultStatus": "F"
  }
}

2. Verify OTP

After the old PIN is verified successfully, a new OTP verification challenge is triggered automatically. So, DWS returns actionForm with chanllengeType issms at the first time you call the verifyAuthentication API.

The user's mobile phone receives an SMS with OTP. Then the merchant server calls the verifyAuthentication API to verify whether the OTP is correct.

  • If the value of pass is true and the actionForm field is null, the verification passed.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of the authenticationId field used in the verifyAuthentication API must be the same as the value of the authenticationId field returned by the modifyAuthentication API.
  • The challengeData.otpValue field is filled with the OTP.

Sample request
The merchant server sends the request of verifying the value to the wallet server.

copy
{  
  "authenticationId":"20220112110077000000190830201924924",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en-US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }
}


Sample response
The wallet server returns the verification result to the merchant server.

copy
{
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

b. One-factor challenge (OTP)

The challengeType returned for the queryAccountAndBenefit API at the first call is SMS_OTP.


Verification succeeded without OTP verification (not a two-factor challenge) at the first call of the verifyAuthentication API.

Sample response

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Check balance

After completing the verification, the merchant calls the queryAccountAndBenefit API to check the balance again.

Request parameters need to follow the requirements below:

  • The value of the processId field can not be null.

Sample request

The merchant server requests to check the balance from the wallet server.

copy
{
    "environment":{
        "clientIp":"176.***.**.***",
        "deviceTokenId":"LD6WB1sraOEUjfoV6L5uhpa38KZFxicsDUQ5CykVZYY5jQ1NfgEAAA==",
        "language":"fr_FR",
        "sessionId":"**********************************************_al_b_I",
        "terminalType":"APP",
        "umidTokenId":"NUtL1LJLOuIEezV+TTZjXwYpDZOqg55T"
    },
    "customerId":"2188210291658265",
    "queryAccountConditions":[
        {
            "account****":"BALANCE_ACCOUNT"
        },
    ],
    "processId":"20220112110077000000190830201924924"
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "accounts": {
    "accountNo": "21628473652453536635212",
    "accountStatus": "available",
    "accountType": "BALANCE_ACCOUNT",
    "availableAmount": {
      "currency": "MYR",
      "value": "23"
    },
    "createTime": "2020-01-13T01:16:44-08:00",
    "crossSiteCustomerId": "2162265049047338",
    "currency": "MYR",
    "customerTntInstId": "HLOPW3MY",
    "frozenAmount": {
      "currency": "MYR",
      "value": "0"
    },
    "holderName": {
      "middleName": ""
    },
    "totalAmount": {
      "currency": "MYR",
      "value": "23"
    }
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

queryAccountAndBenefit

Merchant --> DWS

Use this API to check the wallet balance of the user and present it to them.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and trigger challenge, call this API to verify the challenge.

Check & update mobile number

1. Introduction

This function allows users to check and update the mobile number that is used to open the wallet account.

Note:

  1. If the user's mobile number is registered on the merchant platform:
  1. The user is only allowed to update the mobile number via the merchant platform to ensure it is synchronized between the merchant and wallet.
  2. The merchant verifies the update of the user's mobile number and ensures the mobile number is unique.
  1. Otherwise, the user is allowed to update the mobile number via wallet.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.1.3.jpg

3. Pre-requisite

Note: Modification consult must be done before initiating the modification request.

4. Workflow

The following diagram details how operations are carried out in the wallet account opening process:

API integration guide
  1. The user chooses to modify the mobile number. (Step 1)
  2. The merchant server calls the modifyCustomer API to initiate a modification consult for this user. (Step 2)
  3. The wallet server returns risk accept/reject /challenge (with authenticationId and actionForm) to the merchant server. (Step 3)
  4. If the wallet returns a risk challenge. The merchant server calls the triggerChallenge API to trigger the authentication process. (Step 4)
  5. The wallet server returns challengeType to specify the method to verify the user's identity. (Step 5)
  6. The merchant server guides the user to verify identity based on challengeType. If the value of challengeType is SMS, the user's old mobile phone will receive an OTP.
  7. The user enters the OTP or PIN.
  8. If the risk challenge is the PIN, the merchant needs to encrypt the PIN with the public key and salt returned by step 5. (Step 8).
  9. The merchant server calls the verifyAuthentication API to verify. (Step 9)
  10. DWS returns the verification result to the merchant server. (Step 10)
  11. The user inputs the new mobile number. (Step 12)
  12. The merchant server calls the modifyCustomer API to modify the customer's mobile number. (Step 13)
  13. The wallet server returns the new mobile number verification authenticationId. (Step 14)
  14. The merchant server calls the triggerChallenge API to trigger the authentication process to verify the new phone number. (Step 15)
  15. The wallet server returns challengeType to specify the method to verify the user's identity. (Step 16)
  16. The merchant server guides the user to verify identity based on challengeType.
  17. If the value of challengeType is SMS, the user's new mobile phone will receive an OTP. (Step 18)
  18. The user enters the OTP number. (Step 19)
  19. The merchant server calls the verifyAndResume API to verify and resume modify request (scene = MODIFY_CUSTOMER). (Step 20)
  20. The wallet server returns verification and modification results. (Step 21)

5. Procedures

You need to take the following integration steps to enable the user to complete the wallet account registration process:

Step 1: Modify customer information consult

When the user chooses to modify the mobile phone number, the merchant server calls the modifyCustomer API to initialize the modification consult process. If this API call succeeds, the wallet server may return risk accept or the authenticationId to trigger the challenge and actionForm to guide the user to complete the identity verification.

Request parameters need to follow the requirements below:

  • Only fill in customerId and businessSceneCode will be considered as a modification consult request.
  • The value of businessSceneCode is MOBILE_AVAILABLE or MOBILE_UNAVAILABLE (depends on whether the user's old mobile number is available)

Sample request

The merchant server sends the request for modification consult to the wallet server.

copy
{
    "requestId": "12314356786543545324",
    "customerInfo": {
      "customerId": "2188000000000000000",
    },
    "businessSceneCode": "MOBILE_AVAILABLE",
}

Sample response

The wallet returns the request result and the risk result.

copy
{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType":"sms"
  },
  "customerId": "2188000000000000000",
  "authenticationId":"20220105190077000000162140200586657",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 2: Trigger authentication challenge

If the modification consult returns authenticationId and actionForm, the merchant server needs to call the triggerChallenge API to trigger a challenge to verify the user's identity by verifying the PIN or sending an OTP to the user's original mobile phone number. If this API call succeeds, the wallet server returns the challenge data to specify the method to complete the identity verification. If the wallet server specifies to complete the SMS verification, the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of the challengeId used in the triggerChallenge API must be the same as the value of the authenticationId returned by the modifyCustomer API.

Sample request

The merchant server sends the request of triggering the challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20220105190077000000162140200586657"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 3: Verify authentication challenge

After the user enters the OTP or PIN, the merchant server calls the verifyAuthentication API to verify whether the values are correct.

  • If the value of pass is true, the verification passed. The user can proceed to the next step.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of the authenticationId used in the verifyAuthentication API must be the same as the value of the authenticationId returned by the modifyCustomer API.

Sample request

The merchant server sends the request of verifying the value to the wallet server.

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "authenticationMethod": "OTP",
  "authenticationType": "SMS",
  "authenticationId":"20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en-US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }
}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong verify value,can input again",
    "resultStatus": "F"
  }
}
Step 4: Modify customer information

After consulting to modify customer information and passeing the risk, the merchant server calls the modifyCustomer API to modify the user's information.

Request parameters need to follow the requirements below:

  • The value of the customerInfo.user.mobileNoInfo in the modifyCustomer API should be filled in the user's new phone number.

Sample request

The merchant server sends the request to modify the user's information to the wallet server.

copy
{
    "authenticationId": "20220105190077000000162140200586657",
    "customerInfo": {
      "customerId": "2188000000000000000",
      "user": {
         "mobileNoInfo": {
             "countryCode":"65",
             "phoneNo":"85555555"
         }
      }
    }
}

Sample response

The wallet server returns the verification information of the user's new mobile number to the merchant server.

copy
{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType":"sms"
  },
  "customerId": "2188000000000000000",
  "authenticationId":"20290077000201051140200586657000162",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 5: Trigger authentication challenge

If the modification returns authenticationId and actionForm, the merchant server needs to call the triggerChallenge API to trigger a challenge to verify the user's new phone number. If this API call succeeds, the wallet server returns the challenge data to specify the method to complete the identity verification. If the wallet server specifies to complete the SMS verification, the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of the challengeId used in the triggerChallenge API must be the same as the value of the authenticationId returned by the modifyCustomer API (step 4).

Sample request

The merchant server sends the request of triggering the challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20290077000201051140200586657000162"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 6: Verify and resume modify

After the user enters OTP, the merchant calls the verifyAndResume API to verify the value and continue to modify the user's action.

Request parameters need to follow the requirements below:

  • The value of the scene used in the verifyAndResume API should be filled in MODIFY_CUSTOMER.
  • The value of the authenticationid used in the verifyAndResume API is the same as the value of the authenticationid returned by the modifyCustomer API.(step4)

Sample request

The merchant server sends the request of setting the PIN to the wallet server.

copy
 {
	"scene": "MODIFY_CUSTOMER",
	"authenticationId":"20290077000201051140200586657000162",
	"verifyRequestId":"1324324327436",
	"challengeData": {
		"challengeType": "SMS_OTP",
		"otpValue": "666666"
	}
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
	"challengeInfo": {
		"canReValidate": false,
		"challengeLeftTimes": 0
	},
	"verifyRequestId": "1324324327436",
	"result": {
		"resultCode": "SUCCESS",
		"resultMessage": "success.",
		"resultStatus": "S"
	}
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

modifyCustomer

Merchant --> DWS

Use this API to change a user's mobile phone number or email address.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and trigger challenge, call this API to verify the challenge.

verifyAndResume

Merchant --> DWS

This API allows users to verify authentication and resume original requests.

Check & update email address

1. Introduction

During account opening, this function allows the user to check and update the email address.

Note:

  1. If the user's email address is registered on the merchant platform:
  1. The user is only allowed to update their email address via the merchant platform to ensure it is synchronized between merchant and wallet.
  2. The merchant verifies the user’s email address update to ensure it is unique.
  1. Otherwise, the user is allowed to update the mobile number via wallet.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.1.4.jpg

3. Pre-requisite

Note: Modification consult must be done before initiating the modification request.

4. Workflow

The following diagram details how operations are carried out in the wallet account opening process:

API integration guide
  1. The user chooses to modify the email.
  2. The merchant server calls the modifyCustomer API to initiate a modification consult for this user.
  3. The wallet server returns risk accept / risk reject / risk challenge (authenticationId and actionForm) to the merchant server.
  4. If the wallet returns a risk challenge. The merchant server calls the triggerChallenge API to trigger the authentication process.
  5. The wallet server returns challengeType to specify the method to verify the user's identity.
  6. The merchant server guides the user to verify identity based on challengeType.
  7. The user enters the OTP or payment password
  8. If the risk challenge is the payment password, the merchant needs to encrypt the password with the public key and salt returned by step5.
  9. The merchant server calls the verifyAuthentication API to verify.
  10. DWS returns the verification result to the merchant server.
  11. The merchant server returns the verification result to the user.
  12. The user enters a new email.
  13. The merchant server calls the modifyCustomer API to modify the customer's email.
  14. The wallet server returns modification results.
  15. The merchant server returns the final modification result to the user.


5. Procedures

You need to take the following integration steps to enable the user to complete the wallet account registration process:

Step 1: Modify customer information consult

When the user chooses to modify the email, the merchant server calls the modifyCustomer API to initialize the modification consult process. If this API call succeeds, the wallet server may return risk accept or authenticationId to trigger the challenge and actionForm to guide the user to complete the identity verification.

Request parameters need to follow the requirements below:

  • Only filling in customerId and businessSceneCode will be considered as a modification consult request.
  • The value of businessSceneCode should be filled in MODIFY_EMAIL.

Sample request

The merchant server sends the request of modification consult to the wallet server.

copy
{
    "customerInfo": {
      "customerId": "2188000000000000000"
    },
    "businessSceneCode": "MODIFY_EMAIL"
}

Sample response

The wallet returns the request result and the risk result.

copy
{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType":"sms"
  },
  "customerId": "2188000000000000000",
  "authenticationId":"20220105190077000000162140200586657",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 2: Trigger authentication challenge

If the modification consult returns authenticationId and actionForm, the merchant server needs to call the triggerChallenge API to trigger a challenge to verify the user's identity. If this API call succeeds, the wallet server returns the challenge data to specify the method to complete the identity verification. If the wallet server specifies to complete the SMS verification, the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of challengeId used in the triggerChallenge API must be the same as the value of authenticationId returned by the modifyCustomer API.

Sample request

The merchant server sends the request of triggering challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20220105190077000000162140200586657"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 3: Verify authentication challenge

After the user enters the OTP or payment password, the merchant server calls the verifyAuthentication API to verify whether the values are correct.

  • If the value of pass is true, the verification passed. The user can proceed to the next step.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of authenticationId returned by the modifyCustomer API.

Sample request

The merchant server sends the request of verifying the value to the wallet server.

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "authenticationMethod": "OTP",
  "authenticationType": "SMS",
  "authenticationId":"20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en-US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }
}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "c2c25606-9f1e-4697-853d-da2517bf67be",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong verify value,can input again",
    "resultStatus": "F"
  }
}
Step 4: Modify customer information

After consulting to modify customer information and passeing the risk, the merchant server calls the modifyCustomer API to modify the user's information.

Request parameters need to follow the requirements below:

  • The value of customerInfo.user.email in the modifyCustomer API should be filled in the user's new email.

Sample request

The merchant server sends the request to modify the user's information to the wallet server.

copy
{
    "customerInfo": {
      "customerId": "2188000000000000000",
      "user": {
            "email":"example@example.com"
        }
    }
}

Sample response

The wallet server returns the verification information of the user's new mobile number to the merchant server.

copy
{
  "customerId": "2188000000000000000",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

modifyCustomer

Merchant --> DWS

Use this API to change a user's mobile phone number or email address.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and trigger challenge, call this API to verify the challenge.

Delete account COMING SOON

1. Introduction

This function allows users to delete a wallet account.

Note:

  1. If the user wants to delete a merchant account, the merchant has to firstly check if the user has a wallet account:
  1. If there is no wallet account, the merchant may proceed with merchant account deletion
  2. Else the merchant requests the user to contact customer service to find out the necessary actions to clear the pending status in order to delete the wallet account and merchant account.
  1. Else if the user wants to delete only the wallet account, the user may contact customer service to check if the wallet account has any pending status:
  1. If there is no pending status, the merchant may request for wallet account deletion
  2. Else the user will be advised on the necessary actions to clear the pending status in order to delete the wallet account.

2. User experience

The following diagram shows the user experience of this function.

image.png

Security setting

Set PIN

1. Introduction

This function allows users to set a PIN for security authentication.

Note:

  1. The user is required to set a PIN as a part of account opening.
  2. However, there may be exceptional cases where a PIN was not successfully set during account opening. So, the merchant needs to check if the user's PIN has been set during the following requests. If not, the merchant needs to prompt the user to set a PIN before proceeding to check the balance.
  1. Check balance
  2. Perform transactions such as top-up, payments, withdrawal etc.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.2.1.jpg

3. Pre-requisite

Note: Before the user sets the PIN, activate the wallet's account.

4. Workflow

See the workflow of Open Account if the user sets the PIN during the account opening process.

When the PIN setting is unsuccessful during the account opening process, it needs to be supplemented. This process requires authentication due to the risk of account theft. The workflow is as follows:

API integration guide

The PIN setting process contains the following steps:

  1. The user is prompted to set aPIN. (Step 1)
  2. The merchant server calls the modifyAuthentication API to initialize the authentication process to set PIN. (Step 2)
  3. DWS returns authenticationId and actionForm.challengeType to specify the method that is used to verify the user's identity. The value of challengeType in this process is sms. (step 3)
  4. The merchant server calls the triggerChallenge API to trigger the authentication process. (Step 4-5)
  5. The merchant server guides the user to verify identity based on challengeType.
  6. The user's mobile phone that is bound to the account will receive an OTP. (Step 7)
  7. The user enters the OTP. (Step 8)
  8. The merchant server calls the verifyAuthentication API to verify whether the OTP is correct. (Step 9-10)
  9. The user sets the PIN. (Step 12)
  10. The merchant server calls the applyPublicKey API to obtain the public key and salt, along with the unique ID to identify the public key in each API call. (Step 13-14)
  11. The merchant server encrypts the PIN with the public key and salt via the RSA algorithm. (Step 15)
  12. The merchant server calls the modifyAuthentication API to send the encrypted PIN to the wallet server to set PIN. (16-17)

5. Procedure

The PIN setting process contains the following steps.

Step 1: Initialize the authentication

When the user sets the PIN, the merchant server calls the modifyAuthentication API to initialize the authentication process. If this API call succeeds, the wallet server returns authenticationId to trigger the challenge and actionForm to guide the user to complete the identity verification.

Sample request

The merchant server sends the request of initializing authentication to the wallet server.

copy
 {
        "authenticationBizScene":"SET",
   			"authenticationMethod":"PASSWORD",
        "authenticationType":"PAYMENT",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": null,
   			"merchantId":"216333333333"
}

Sample response

The wallet returns the request result and references to initialize authentication to the merchant.

copy
{
  "actionForm":{
    "challengeRenderValue":"+60******6353",
    "challengeType": "sms"
  },
  "authenticationId":"20220105190077000000162140200586657",
  "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 2: Trigger authentication challenge

After the authentication challenge is initiated successfully, the merchant server calls the triggerChallenge API to trigger a challenge to verify the user's identity. If this API call succeeds, the wallet server returns the challenge data to specify the method to complete the identity verification. This process requires to do the SMS verification, the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of challengeId used in the triggerChallenge API must be the same as the value of authenticationId returned by the initAuthentication API.

Sample request

The merchant server sends the request of triggering the challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "20220105190077000000162140200586657"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******6353",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 3: Verify OTP

After the user enters and confirms the OTP, the merchant server calls the verifyAuthentication API to verify whether the OTP is correct.

  • The value of pass is true, which indicates the verification passed. The user can proceed to the next step.
  • The value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, which indicates the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of authenticationId returned by the modifyAuthentication API.

Sample request

The merchant server sends the request of verifying OTP to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId":"20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong otp value,can input again",
    "resultStatus": "F"
  }
}
Step 4: Apply public key

After the user enters and confirms the PIN, the merchant server calls the applyPublicKey API to obtain a public key and salt to encrypt the PIN via the RSA algorithm. The wallet server will also return a unique ID to identify the public key.

Note: Once the public key is used for the PIN encryption, it will be invalid. The merchant needs to apply a new public key again.

Sample request

The merchant server requests to obtain a public key from the wallet server.

copy
{
	"customerId": "2188210123456789",
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "publicKeyInfo": {
    "uniqueId": "s8NeKdTshiXVAPXzBRTIQigKh4PbnIiS",
    "salt": "IRfe92wH04sh",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 5: Setting PIN

After the merchant encrypts the PIN, the merchant calls the modifyAuthentication API again to send the encrypted PIN to the wallet server.

  • If this API call succeeds, the PIN setting is completed.
  • If the PIN setting failed, the merchant should display a prompt page that the account opening is successful but the PIN setting failed. The merchant can prompt the user to set the PIN again during balance check or other requests.

Request parameters need to follow the requirements below:

  • The value of publicKeyUniqueId used in the modifyAuthentication API is the same as the value of uniqueId returned by the applyPublicKey API.

Sample request

The merchant server sends the request of setting the PIN to the wallet server.

copy
{
        "authenticationBizScene":"SET",
        "authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"2188210123456789",
        "identityType":"CIPHERTEXT",
        "identityValue":"aHh91grWBD6OXb4JYjeSE8G048ys3HegfC0eaHrmxaOvdUk1+KocJysb0s9TvA0HvT8+a2ED1OJNorzxp7ju0Ir8EuJvw1eH0YNrmFyX2nFZxmdI3FcLegq5M7QngjtuHyRgXbfS8pZPam8Yn3OC/IYpLT4Xi42wQ2BzjznIpzPilBNR+byhRG4PTIdePjyseiYuyHScxkRMqBcIJKJB8qZ7ZAYgvuMXXiUkKXIseIKdfldVq6TaWaLA5p9Z5rj7YzsEadZQjIGPiThGRvGqALBLtieqRwOQOrswPt9XXw1uPALQhTJQ/41Me90xwLi5+ZgCxHDEtHbYQx++s5CaPA==",
        "publicKeyUniqueId":"Fno5AgHDX2SqnAtwnbkZVKVnD0jfLiEn"
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

modifyAuthentication

Merchant --> DWS

Use this API to set, change, and reset a PIN of the user.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and triggers a challenge, call this API to verify the challenge.

applyPublicKey

Merchant --> DWS

Use this API to apply a public key and slat, which is used to encrypt a plaintext password.

Change PIN

1. Introduction

This function allows users to change their PIN for security authentication.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.2.2.jpg

3. Pre-requisite

Note:

  1. In circumstances of PIN modification, users are required to enter a unique PIN or SMS code (one time PIN, OTP) to protect user account security according to region regulations and DWS's risk control requirements.
  2. So before calling the API to change or reset the PIN, you must use the API to initialize the authentication flow, and then use the triggerChallenge API to trigger authentication.

4. Workflow

The data flow to change a PIN with PIN challenge is illustrated as below:

API integration guide

The flow consists of the following steps:

  1. The user wants to change the PIN. (Step 1)
  2. The merchant server calls the modifyAuthentication API to initialize the authentication flow. (Step 2)
  3. DWS returns authenticationId and actionForm.challengeType to specify the method to verify the user's identity. The value of challengeType in this process is PAYMENT_PASSWORD. (Step 3)
  4. The merchant server calls the triggerChallenge API to trigger the authentication process. (Step 4-5)
  5. The merchant server guides the user to verify identity based on challengeType.
  6. The user enters the old PIN. (Step 7)
  7. The merchant server encrypts the old PIN with the public key and salt returned by step 5 via RSA algorithm. (Step 8)
  8. The merchant server calls the verifyAuthentication API to verify whether the old PIN is correct. (Step 9-10)
  9. The merchant server calls the applyPublicKey API to get the public key, slat, and unique ID to encrypt the new PIN user entered. This step is only required before the user enters a new PIN. (Step 13-15)
  10. The merchant server calls modifyAuthentication API to change the PIN with the same authenticationRequestId as the authentication initialization. (Step 16-17)

The data flow to change a PIN with the two-factor challenge is illustrated as below:

API integration guide

When DWS risk control detects that the user account is at high risk, the user's request to modify the PIN might be rejected, or the user is required to complete further verification through OTP, which called the two-factor challenge. In this case, the user needs to verify the old PIN first, and then verify the OTP sent by DWS. So, the process is different after triggering the challenge:

  1. The actionForm.challengeType field of the consultation result is PAYMENT_PASSWORD, which means that the old PIN needs to be verified. (Step 3)
  2. The merchant calls the verifyAuthentication API to validate the encrypted old PIN, which is entered by the user after triggering the challenge, and then gets the next challenge typesms. (Step 7-11)
  3. The user receives a verification code sent by DWS if the old PIN is verified successfully. (Step 12)
  4. The merchant calls the verifyAuthentication API to validate the OTP. (Step14-15)
  5. The merchant calls the applyPublicKey API to get the public key, slat, and unique ID to encrypt the new PIN that the user entered. This step is only required before the user enters a new PIN. (step 18-20)
  6. The merchant server calls modifyAuthentication API to change the PIN with the same authenticationRequestId as the authentication initialization. (step 21-22)

5. Procedure

a. Change a PIN with PIN challenge:

Step 1: Initialize the authentication flow

Before changing the PIN, DWS requires verification of the user's identity for security. Therefore, the merchant needs to initialize the verification process first. This needs to be done at every authentication step.

Call the modifyAuthentication API to initialize the authentication process.

Sample request

The merchant server sends the request of initializing authentication to the wallet server.

copy
 {
        "authenticationBizScene":"MODIFY",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": null
}

Sample response

The wallet returns the request result and references to initialize authentication to the merchant.

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": null,
  "locked": null,
  "lastErrorTime": null,
  "actionForm": {
    "challengeRenderValue": "",
    "challengeType": "[\"PAYMENT_PASSWORD\"]"
  },
  "authenticationId": "cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717",
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}

Step 2: Trigger authentication challenge

After initializing the process of verifying the identity, the verification challenge is triggered. The public key is returned to encrypt the old PIN that the user entered.

Call the triggerChallenge interface and obtain the public key to encrypt the old PIN by the encryption algorithm RSA.

Sample request

The merchant server sends the request of triggering challenge to the wallet server.

copy
{
	"triggerRequestId":"341431413542775745075669",
	"challengeId":"cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "challengeRenderValueType": "encryptionInput",
    "challengeRenderValue": "{\"public_key\":\"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB\",\"salt\":\"SJnsXGep49iL\"}",
    "canRetryChallenge": false,
    "isChallengeFinish": false,
    "challengeLeftTimes": null
  },
  "extendInfo": null,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}

Step 3: Verify old PIN

After the user enters the old PIN, the merchant server encrypts the old PIN with the public key and salt returned by the triggerChallenge API via RSA algorithm. Then the merchant server calls the verifyAuthentication API to verify whether the PIN is correct.

  • If the value of pass is true, the verification passed. The user can proceed to the next step.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of authenticationId returned by the modifyAuthentication API.
  • The challengeData.passwordValue field is filled with the encrypted old PIN.

Sample request

The merchant server sends the request of verifying the old PIN to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId": "cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717",
  "challengeData":{
    "challengeType":"PAYMENT_PASSWORD",
    "passwordValue":"y+ySfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A=="
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value,can input again",
    "resultStatus": "F"
  }
}

Step 4: Apply public key for new PIN.

Request the public key to encrypt the new PIN via the applyPublicKey API.

Sample request

The merchant server requests to obtain a public key from the wallet server.

copy
{
	"customerId": "2188000000000000000",
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "publicKeyInfo": {
    "uniqueId": "s8NeKdTshiXVAPXzBRTIQigKh4PbnIiS",
    "salt": "IRfe92wH04sh",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

Step 5: Set a new PIN

The merchant calls the modifyAuthentication API to set a new PIN, which needs to be encrypted with the public key and slat generated in step 4 via RSA algorithm.

Request parameters need to follow the requirements below:

  • The publicKeyUniqueId field is the same as the publicKeyInfo.uniqueId filed.

Sample request

The merchant server sends the request of setting a new PIN to the wallet server.

copy
 {
        "authenticationBizScene":"MODIFY",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": "m+qPSfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A==",
        "publicKeyUniqueId":"pWBuJqB7MXBf5qEyvDmXtP0bWvt7Uj0B"
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "authenticationRequestId": null,
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": "0",
  "locked": null,
  "lastErrorTime": null,
  "actionForm": null,
  "authenticationId": null,
  "bizDate": null,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
  }
}
b. Change a PIN with two-factor (PIN and OTP) challenge:

Step 1: Initialize the authentication flow

Before changing the PIN, DWS requires verification of the user's identity for security. Therefore, the merchant needs to initialize the verification process first. This needs to be done at every authentication step.

Sample request

The merchant server sends the request of initializing authentication to the wallet server.

copy
 {
        "authenticationBizScene":"MODIFY",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": null,
   			"merchantId":"216333333333"
}

Sample response

The wallet returns the request result and references to initialize authentication to the merchant.

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": null,
  "locked": null,
  "lastErrorTime": null,
  "actionForm": {
    "challengeRenderValue": "",
    "challengeType": "[\"PAYMENT_PASSWORD\"]"
  },
  "authenticationId": "74dbd38c848e82e3e689ed41e58a6efccd0d91d38156c42292c3cbf8dac21b41",
  "bizDate": null,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}

Step 2: Trigger authentication challenge

After initializing the process of verifying the identity, the verification challenge is triggered. The public key is returned to encrypt the old PIN that the user entered.

Call the triggerChallenge API and obtain the public key to encrypt the old PIN by the encryption algorithm RSA.

Sample request

The merchant server sends the request of triggering the challenge to the wallet server.

copy
{
  "triggerRequestId": "fba0b644-2f9b-4600-b761-faaed5329fc8",
  "challengeId": "74dbd38c848e82e3e689ed41e58a6efccd0d91d38156c42292c3cbf8dac21b41"
}

Sample response

The wallet server returns the request result and challenge data to the merchant server.

copy
{
  "challengeRenderData": {
    "challengeRenderValueType": "encryptionInput",
    "challengeRenderValue": "{\"public_key\":\"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB\",\"salt\":\"WWXSzmVj06et\"}",
    "canRetryChallenge": false,
    "isChallengeFinish": false,
    "challengeLeftTimes": null
  },
  "extendInfo": null,
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Step 3: Verify old PIN

After the user enters the old PIN, the merchant server encrypts the old PIN with the public key and salt returned by the triggerChallenge API via RSA algorithm. Then the merchant server calls the verifyAuthentication API to verify whether the PIN is correct.

  • If the value of pass is true, the verification passed. The user can proceed to verify OTP by the actionForm.challengeType field, which is sms.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of authenticationId returned by the modifyAuthentication API.
  • The challengeData.passwordValue field is filled with the encrypted old PIN.

Sample request

The merchant server sends the request of verifying the old PIN to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId": "cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717",
  "challengeData":{
    "challengeType":"PAYMENT_PASSWORD",
    "passwordValue":"y+ySfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A=="
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded and need to verify OTP

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "actionForm": {
    "challengeRenderValue": "",
    "challengeType":"[\"sms\"]"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "2",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value,can input again",
    "resultStatus": "F"
  }
}

Step 4: Verify OTP

After the old PIN is verified successfully, a new OTP verification challenge will be triggered automatically, and the user's mobile phone will receive an SMS with OTP. Then the merchant server calls the verifyAuthentication API to verify whether the OTP is correct.

  • The value of pass is true and the value of actionForm is null, which indicates the verification passed.
  • The value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, which indicates the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of authenticationId used in the verifyAuthentication API must be the same as the value of the authenticationId returned by the modifyAuthentication API.
  • The challengeData.otpValue field is filled with the OTP.

Sample

Request

The merchant server sends the request of verifying OTP to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId": "cb3153b48564e5faace8efaea6fd5b06435d6ee976603285e7fe262e17e07717",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
    },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "2",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value,can input again",
    "resultStatus": "F"
  }
}

Step 5: Apply public key for a new PIN

Request the public key to encrypt the new PIN.

Sample request

The merchant server requests to obtain a public key from the wallet server.

copy
{
	"customerId": "2188000000000000000",
}

Sample response

The wallet server returns the request result to the merchant server.

copy
{
  "publicKeyInfo": {
    "uniqueId": "s8NeKdTshiXVAPXzBRTIQigKh4PbnIiS",
    "salt": "IRfe92wH04sh",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}

Step 6: Set a new PIN

The merchant calls the modifyAuthentication API to set a new PIN, which needs to be encrypted with the public key and slat generated in step 5 via RSA algorithm.

Request parameters need to follow the requirements below:

  • The value of publicKeyUnique is the same as the value of publicKeyInfo.uniqueId.

Sample request

The merchant server sends the request of setting a new PIN to the wallet server.

copy
{
    "identityType":"CIPHERTEXT",
    "customerId":"2161220160693313",
    "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
    "identityValue":"AFgjAIFvBfpV3kj3xFMdW2+uMAKjWvgcDbmxe2gL50NJpG2hOOJ+f/0hE5v4fdeDA38p8Q4ygY54moRd3QrfvobuiNpx6z7T3PPtyUWbKrqxJDwpoEG7YKkUdjP9SiNjm0Ln7Pijr9Ap1RicwhRyPkAkcMq+buy3snB8QvkjxP6E5cChWUbP9vJJCy3sCVNABiIwh9u/SivUMErwoVvHzeR+2dpU0RUZSe19NxGQxb5g7ODMsJ0zCNyf4WiRMosRR0ex1Nak3Qb9DGMSneMIBpsXBnkjC+K6P4uQLRb3fw6mrXjQ0W8MmbANQ/XNATYpofrMh4JF2C9KpyHULBMGpw==",
    "authenticationBizScene":"MODIFY",
    "authenticationMethod":"PASSWORD",
    "publicKeyUniqueId":"B8QmlpGLweUIO1wFLfIh4tK1hmZXvV4n",
    "authenticationType":"PAYMENT"
}

Sample response

The wallet server returns the request result to the merchant server.

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

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

modifyAuthentication

Merchant --> DWS

Use this API to set, change, and reset a PIN of the user.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and trigger a challenge, call this API to verify the challenge.

applyPublicKey

Merchant --> DWS

Use this API to apply a public key and slat, which is used to encrypt a plaintext password.

5.3.2.3 Reset PIN

1. Introduction

This function allows users to reset their PIN for security authentication if they forget the existing PIN.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.2.3.jpg

3. Pre-requisite

Note: Before the user resets the PIN, activate the wallet's account.

4. Workflow

The data flow to reset a PIN with OTP challenge is illustrated as below:

API integration guide

The flow consists of the following steps:

  1. The user wants to reset the PIN. (step 1)
  2. The merchant server calls the modifyAuthentication API to initialize the authentication flow. (step 2)
  3. DWS returns authenticationId and actionForm.challengeType to specify the method that is used to verify the user's identity. The value of challengeType in this process is sms. (step 3)
  4. The merchant server calls the triggerChallenge API to trigger the authentication process. (Step 4-5)
  5. The user receives an OTP. (Step 7)
  6. The user enters the OTP. (Step 8)
  7. The merchant server calls the verifyAuthentication API to verify whether the OTP is correct. (Step 9-10)
  8. The user sets the PIN. (Step 12)
  9. The merchant server calls the applyPublicKey API to obtain the public key and salt, along with the unique ID to identify the public key in each API call. (Step 13-14)
  10. The merchant server encrypts the PIN with the public key and salt via the RSA algorithm. (Step 15)
  11. The merchant server calls the modifyAuthentication API to send the encrypted PIN to the wallet server to set a PIN. (16-17)

5. Procedures

Reset a PIN with OTP challenge:

Step 1: Initialize the authentication flow

Before resetting the PIN, the merchant calls the modifyAuthentication API to initialize the authentication process.

Sample request

The merchant server sends the request of initializing authentication to the wallet server.

copy
{
        "authenticationBizScene":"RESET",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": null
}

Sample response

The wallet returns the request result and references to initialize the authentication to the merchant.

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": null,
  "locked": null,
  "lastErrorTime": null,
  "actionForm": {
    "challengeRenderValue": "+6222***508",
    "challengeType": "[\"sms\"]"
  },
  "authenticationId": "ea3c40047c8d1781167bb00486242e0ebe0d53139f23e356eaa24d09f415bbf0",
  "bizDate": null,
  "success": true,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}
Step 2: Trigger authentication challenge

After the authentication challenge is initiated successfully, the merchant server calls the triggerChallenge API to trigger a challenge to verify the user's identity. If this API call succeeds, the wallet server returns the challenge data to specify the method to complete the identity verification. The SMS verification needs to be completed and the user will receive the OTP via SMS.

Request parameters need to follow the requirements below:

  • The value of ChallengeId used in the triggerChallenge API must be the same as the value of authenticationId returned by the initAuthentication API.

Sample request

The merchant server sends the request of triggering challenge to the wallet server.

copy
{
	"triggerRequestId":"341431413542775745075669",
	"challengeId":"ea3c40047c8d1781167bb00486242e0ebe0d53139f23e356eaa24d09f415bbf0"
}

Sample response

The wallet returns the request result and references to trigger a challenge to the merchant.

copy
{
  "challengeRenderData": {
    "canRetryChallenge": false,
    "challengeRenderValue": "+60******2735",
    "challengeRenderValueType": "mobile",
    "isChallengeFinish": false
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 3: Verify OTP

After the user enters the OTP, the merchant server calls the verifyAuthentication API to verify whether the OTP is correct.

  • If the value of pass is true, the verification passed. The user can proceed to the next step.
  • If the value of pass is falseand resultCode is SECURITY_VERIFY_FAILURE, the verification failed. The user needs to retry.

Request parameters need to follow the requirements below:

  • The value of the authenticationId used in the verifyAuthentication API must be the same as the value of the authenticationId returned by the modifyAuthentication API.

Sample request

The merchant server sends the request of verifying OTP to the wallet server.

copy
{
  "authenticationMethod": "PASSWORD",
  "authenticationType": "PAYMENT",
  "authenticationId":"20220105190077000000162140200586657",
  "challengeData":{
        "challengeType":"SMS_OTP",
        "otpValue":"666666"
  },
  "env": {
        "osVersion": "8.1.0",
        "tokenId": "giaGTonn30X9AJPc0MN9lpjK-SZXq6PifXy3Gs4ufmI4BC87awEAAAAA",
        "clientIp": "123.136.111.19",
        "clientUmid": "sdjoi02082",
        "osType": "ios 8929",
        "language": "en_US",
        "sessionId": "1e32d8b642590af5c3cba8ad5d111c2c",
        "terminalType": "APP"
    }

}

Sample response

The wallet server returns the verification result to the merchant server.

Verification succeeded

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "true",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Verification failed

copy
{
  "authenticationRequestId": "1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
  "pass": "false",
  "remainTryTimes": "1",
  "result": {
    "resultCode": "SECURITY_VERIFY_FAILURE",
    "resultMessage": "wrong value,can input again",
    "resultStatus": "F"
  }
}
Step 4: Apply the public key for a new PIN

After the user enters the PIN, the merchant server calls the applyPublicKey API to obtain a public key and salt to encrypt the PIN via the RSA algorithm. The wallet server returns a unique ID to identify the public key.

Note: Once the public key is used for the PIN encryption, it will be invalid. The merchant needs to apply a new public key again.

Sample request

The merchant server requests to obtain a public key from the wallet server.

copy
{
	"customerId": "2188000000000000000",
}

Sample response

The wallet returns the request result to the merchant.

copy
{
  "publicKeyInfo": {
    "uniqueId": "s8NeKdTshiXVAPXzBRTIQigKh4PbnIiS",
    "salt": "IRfe92wH04sh",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxn/zCJXInbQiQpJpnV6KmK/Cci3sXhymx2vgs+s/tss9ny6pZNmrO9bG/lYUEm69+L/Mfq/mWxBHee3BGCSvtACYrYjWE5jKP3X91RcxFfYDH8dwTfMBNFatRINm3oHpdWDqOdX5FPtHNNX69prMC+/2IrdIvN/ui1JWXhqgk5Z9h8CJuf6hrEW0fjJLeeN9MHmPi/uWRXLHQUHjJb3a9oaHEur/6jDxpHLo2IGldlHjy9UHAZAIcpNMhw+ufKbA4IzS+gATE0jORLTOU2x+v0FfxnnSCbiQ1LNvaDFrwSQ2ttf9FAdKl2AW5g5cFELxMZ5TYvKMOkkIwhcclw1QvwIDAQAB"
  },
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"success.",
    "resultStatus":"S"
  }
}
Step 5: Reset a new PIN

The merchant calls the modifyAuthentication API to set a new PIN, which needs to be encrypted with the public key and slat generated in step 4 via RSA algorithm.

Request parameters need to follow the requirements below:

  • The value of publicKeyUniqueId used in the modifyAuthentication API is the same as the value of uniqueId returned by the applyPublicKey API.

Sample request

The merchant server sends the request for a new PIN resetting to the wallet server.

copy
{
        "authenticationBizScene":"RESET",
   			"authenticationMethod":"PASSWORD",
        "authenticationRequestId":"1471cc85-c6d7-44a9-b6b8-9ff2a084301a",
        "authenticationType":"PAYMENT",
        "customerId":"216276867889",
        "identityType":"CIPHERTEXT",
        "identityValue": "m+qPSfvHVzoIXJw3bKckgtHdMXknQ4lt1A9hR8Jg/WIrAUyYA0g5obCdvY/S50wbb2A5fOfWEK+E/8iGbDjOaxpa62UbwKh1VUIqBhVFGesBTOfn/B7lb3+F9HtWU3SaeSodcXWKH0IZJvYgMSDrzit29vsW67NQOX1aAvtWHVwRbP0Rx015lH/L2uTfqBm6pwqR1muGCxy9VnjgTjtpKrDw2Y/abIt5iEYBFA+iZro4v4r+9RC092BLX4mIUZbebI0Q2WblvzGCiMRDLSlZShmnPCzJXTZ674A/zpvh+kjouFL3Lekcgos6l6KUzw9VupyWkSXJyRKU1JTs+zI67A==",
        "publicKeyUniqueId":"pWBuJqB7MXBf5qEyvDmXtP0bWvt7Uj0B"
}

Sample response

The wallet returns the request result and references to reset PIN to the merchant.

copy
{
  "authenticationRequestId": null,
  "expirySeconds": null,
  "expiryTime": null,
  "length": null,
  "genCount": null,
  "value": null,
  "totalErrorTimes": null,
  "remainTryTimes": "0",
  "locked": null,
  "lastErrorTime": null,
  "actionForm": null,
  "authenticationId": null,
  "bizDate": null,
  "result": {
		"resultCode": "SUCCESS",
		"resultStatus": "S",
		"resultMessage": "success"
	}
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

modifyAuthentication

Merchant --> DWS

This API call allows the user to change and reset a password. With this API call, a merchant can reset or change a user's payment password when they miss the payment password or want to change it.

triggerChallenge

Merchant --> DWS

Use this API to trigger a challenge. With this API call, a merchant can trigger an SMS challenge or a PIN challenge.

verifyAuthentication

Merchant --> DWS

Use this API to verify authentication. When the merchant performs verification initialization and trigger a challenge, call this API to verify the challenge.

applyPublicKey

Merchant --> DWS

Use this API to apply a public key and slat, which is used to encrypt a plaintext password.

Assets management

Bind payment card

1. Introduction

This function allows users to bind their own payment methods.

Binding a payment method is the process that requires merchants to obtain users' authorization to bind their own payment methods to the wallet. The payment methods include credit cards, debit cards, bank accounts, APM, and third-party wallets.

During this process, the user is redirected to the bank's page from the merchant's authorization page for 3DS challenge. Users can authenticate themselves on the bank's page before being redirected back to the merchant's platform. After the users have added payment methods to the wallet, they can top up the wallet's balance by their binded payment methods and withdraw the wallet's balance to a card.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.3.1.jpg

3. Pre-requisite

Notes:

  1. If the merchant has PCI DSS qualifications, the user can enter the card's information on the merchant's page. Call the cacheCard API to cache the information of the card.
  2. If the merchant doesn't have PCI DSS qualifications, the user will be redirected to DWS H5 page to enter the card information.
  3. Payout bank account same name check needs to be done during account binding, DWS needs to verify the bank account name with KYC name. The account name is case insensitive, without verifying spaces and the decimal point.

4. Workflow

API integration guide

The workflow consists of the following steps:

  1. The user wants to bind a card to the wallet's account, then the merchant calls the consultAddablePaymentMethod API to get the available payment methods list. (Step 1)
  2. The user enters the required information of the payment method after selecting a payment method for binding. For example, the user needs to provide the card number, expiration date, security code, and card holder's name for a credit/debit card. (Step 5)
  • Anyone involved with the processing, transmission, or storage of card data must comply with the Payment Card Industry Data Security Standards (PCI DSS).
  • When the payment method type is CARD, the merchant with complied PCI DSS must call the cachCard API to cache card information and generate a temporary card token to transmission for information security. (Step 6-7)
  1. The merchant calls the addPaymentMethod API to a bind payment card. (Step 8)
  2. The card binding process is handled synchronously and processed asynchronously. The merchant can call the queryPaymentMethod API to get the processing result and DWS notifies the merchant of the result. If the binding process required 3DS, the queryPaymentMethod API will return the authorization URL with the status field shows PROCESS. (Step 11-12)
  3. DWS notifies the payment method binding status via iPayNotifyAddCardResult SPI if the merchant integrates this interface. (Step 19-21)

5. Procedure

To bind a payment card, the following steps are contained:

Step 1: Consult available payment methods

The merchant calls the consultAddablePaymentMethod API to get the available payment methods list, then present to the user.

  • The supported payment methods are returned, If the payment methods are not returned, the reason is returned.
  • The supported card brands, currencies, rates, and limits are returned.

When handling the consultAddablePaymentMethod API requests, the merchant needs to take the following things into consideration:

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
  "customerId": "2161220160649200",
  "environment": {
    "appVersion": "6.84.2",
    "clientIp": "175.***.**.***",
    "deviceModel": "TECNO LD7",
    "deviceTokenId": "wiQ5Hlwx3QLMkRS3R3OMtOAnznRWKJ6lFPgs7GDgihiuimC9fQEAAA==",
    "language": "en-PH",
    "operateEntrance": "LZD",
    "osType": "Android",
    "osVersion": "10",
    "sessionId": "********************************",
    "terminalType": "APP",
    "umidTokenId": "DYQAEhpLPO4XcQN9vXk/RHl6C7oLX+41"
  },
  "scenes": ["PAYMENT"]
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
  "paymentOptions": [
    {
      "enabled": true,
      "paymentMethodCategory": "MIXEDCARD",
      "paymentMethodType": "MIXEDCARD",
      "paymentOptionDetail": "{\"card\":{\"bankInfos\":[],\"supportCardBrands\":[{\"cardBrand\":\"MASTERCARD\",\"supportedCurrencies\":[\"PHP\"]},{\"cardBrand\":\"VISA\",\"supportedCurrencies\":[\"PHP\"]}]},\"type\":\"card\"}",
      "preferred": false,
      "rank": 5000,
      "disableReason": 'null', 
	    "disableDetail": null, 
      "rate": null,
      "supportedCurrencies": [
        "PHP"
      ]
    },
    {
      "enabled": true,
      "paymentMethodCategory": "GCASH_EBANK",
      "paymentMethodType": "GCASH_EBANK",
      "paymentOptionDetail": "{\"type\":\"card\",\"card\":{\"bankInfos\":[{\"bankShortName\":\"GNGCASH\",\"cardIssuedCode\":\"GNGCASH\",\"enabled\":false}],\"paymentOptionMetadata\":\"{\\\"isSupportPaySimulate\\\":\\\"true\\\"}\",\"supportCardBrands\":[]}}",
      "preferred": false,
      "rank": 4800,
      "supportedCurrencies": [
        "PHP"
      ]
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 2: Add payment method and authorization

The user chooses one of the avaliable payment methods and the merchant calls the addPaymentMethod API to bind.

Cache card information (optional)：

  • If the user chooses to bind a credit/debit card, the merchant must call the cacheCard API to cache card elements and return a temporary token.
  • Except for entering the card information when the user binds the card at the first time, the temporary card token or permanent card token, which is returned by the queryPaymentMethod API to get all bound cards, is used as the transmission card information in any situation.
  • The temporary card token is only valid within the time range, and the merchant needs to obtain it again next time.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
  "paymentMethodDetail": {
    "paymentMethodDetailType": "card",
    "card": {
      "cardNo": "1234561234561234",
      "brand": "VISA",
      "securityCode": "444",
      "expiryYear": "2019",
      "expiryMonth": "07",
      "instUserName": {
        "firstName": "xxx",
        "lastName": "xxx",
      },
      "billingAddress": {
        "region": "China",
        "state": "Zhejiang",
        "city": "Hangzhou",
        "zipCode": "3100000",
        "address1": "xxx",
        "address2": "xxx",
      }
    }
  }
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMsg":"success"
  },
  "expiryTime":"2001-07-04T12:08:56+05:30",
  "paymentMethodDetail": {
    "paymentMethodDetailType":"card",
    "card": {
      "cardToken": "85246e15131d44feb36c80e1a1e39",
      "mask":"123456******1234",
      "last4": "1234",
      "brand": "VISA",
      "expiryYear": "2019",
      "expiryMonth": "07",
      "instUserName": {
        "firstName": "xxx",
        "lastName": "xxx",
      },
      "billingAddress": {
        "region": "China",
        "state": "Zhejiang",
        "city": "Hangzhou",
        "zipCode": "3100000",
        "address1": "xxx",
        "address2": "xxx",
      }
    }
  }
}

Add payment method：

The merchant specifies paymentmethodDetailType and card information to bind the card. The mixed card uses a temporary card token.

  • DWS decides whether to redirect the user to a third party's page to complete the verification based on the user's account risk and card issue capability.
  • Risk challenge is configurable based on the merchant and channels involved, allowing to authenticate by OTP or PIN.
  • For mixed cards, rely on 3-D Secure (3DS). If a high risk is identified, the user will be redirected to the authorization page of the issuer to authenticate to ensure that the user and the holder are the same person.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
    "customerId":"2162220004751145",
    "environment":{
        "clientIp":"203.***.***.***",
        "deviceTokenId":"mu-b3Ess_Qoq3zYaaBecD-mJ52tH7RzQ0-4AhB12n7mysEYgfwEAAAAA",
        "language":"en-SG",
        "sessionId":"********************************",
        "terminalType":"APP",
        "umidTokenId":"BKFLtqFLOh9E/zV/KkRprBxhbakBCMZ+"
    },
    "isTemp":false,
    "paymentMethodDetail":{
        "card":{
            "cardToken":"PYMT1342cf7ca558402cb2d77af09066d906",
            "paymentMethodDetailMetadata":"{\"externalUserId\":\"1023240523\"}"
        },
        "paymentMethodDetailType":"CARD"
    },
    "requestId":"c9f9dfc2-a30f-40f8-ac60-3ba32e3e1ac2",
    "redirectUrl":"https://pages.merchant.com/member/payment-method-add?wh_weex=true&channel=payment-options&redirectUrl=https%3A%2F%2Fpages.xxx.com%2Fwow%2Fi%2Fsg%2Fmember%2Fpayment-options%3Fhybrid%3D1&xxx_event_id=379_1645760576329_47947&merchantTransId=c9f9dfc2-a30f-40f8-ac60-3ba32e3e1ac2"
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
    "actionForm":{

    },
    "requestId":"c9f9dfc2-a30f-40f8-ac60-3ba32e3e1ac2",
    "paymentMethodDetail":{
        "card":{},
        "paymentMethodDetailType":"CARD"
    },
    "result":{
      "resultStatus":"S",
      "resultCode":"SUCCESS",
      "resultMsg":"success"
  },
}
Step 3: Get the authorization URLs

After the payment card binding request is initiated, the merchant needs to call the queryPaymentMethod API to query the binding result since DWS processes the request asynchronously. For many payment methods or card payments with 3DS, the merchant needs to redirect the user to a webpage or app to verify the payment. In this case, the queryPaymentMethod API will return the redirectUrl field.

The queryPaymentMethod API executes different logic with different parameters:

  • The requestId field is required when the merchant get the binding result.
  • The requestId field must be same as the adding payment methods.
  • The requestId field uniquely identifies a request of adding payment methods.
  • The requestId field must be empty when the merchant obtains all payment methods.

The binding result is returned in the field of status:

  • If the value of status is PROCCESS, the payment card binding is still being processed and has not reached the final state. If the value of actionForm.actionFormType is REDIRECT, the merchant needs to redirect the user to the authorization page.
  • If the value of status is SUCCESS , the payment card is bound successfully.
  • If the value of status is FAIL , the payment card binding failed.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
    "customerId":"2162220004751145",
    "requestId":"c9f9dfc2-a30f-40f8-ac60-3ba32e3e1ac2"
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
    "actionForm":{
        "actionFormType":"REDIRECT",
        "method":"POST",
        "parameters":"{\"MD\":\"eyJkaWdlc3QiOiJFOVdVdmpUeXJsajlsaGtuV05uU2ZVcmtMUnM5U3AwNWh5VmlUcVlQSFpvVWVodUVuQWNUbTJuWStkMWUxQnI3bEEwczg3RmRaL041UlpGcHBzaXpJUldiVHgzTXdGZC8vTEUyNTJPeE5uNGlScHdEZUF0Tm1XaGZOT0wrMDBodFFwc0l0SUo2dnNDdzVsQnZ6ZjdaVzlqTEYrUXd3eXJOa20vN3FVZHRoRTNFTDNBMk9DS0h4WmR6Nmx3elM4YlJYUjdmaWdWc2orZ2RFYmFxVzBkVVZ2aDRVLzFKSjY3UVE0QlZJSjE1MXZzL3djU0VGbzFsa3hnVStwUW9yMm4vWE9jQ2FManF6OUlBRjFOdjNBajlTKzhEempFSnBaYzVRZGEraG9oZ25WUHcxUSsxWWlkQ25nTUszRGhNMUhNVzRYQzh0b2NWdnp4TE9hNGJHSTNMRnc9PSIsImluU2VyaWFsTm8iOiIyMDIyMDIyNDg5MDMxMzAwMDAxODM2OTUxNjg1MjY3Iiwib3V0T3JkZXJObyI6IjIwMjIwMjI0ODkwMzEzMDAwMDE4MzY5NTE2ODUyNjcifQ==\",\"PaReq\":\"eAFVUl1vgjAUfV/ifyC8jxYC+JFrDc4sGud0qFn22EAFpnzIx8T9+t0izC3pQ89p7+m55xYmdXxSvkReRGkyVnWNqopIvNSPkmCs7nfPjwN1wnoPsAtzIWZb4VW5YLASRcEDoUQ+1lBKLWswpLpp2yqDjeOKM4NWk6GkZgDpIJbmXsiTkgH3ztPFKzOtPu1TIC2EWOSLGaNUH+oDi1J7aAG5cZDwWLAX/s19rpRpVmVAGgq8tErK/IpaAyAdgCo/sbAss2JEyOVy0U5NpealsRZfgchjIHc/m0o6K7C9OvLZdT5d65/VZeeJ/SY4ZtE+sZxtViyyYAxE3gCfl4IZ1JDLVKg9MvWRgQYaHngsTbHVh6u4K0xBtnijIJMvOTeA8QH5SwBGnOMMum46BKLO0kSgJMb5uwdyt/00l6F6JcZniehQO+/LrcFDV5/O99F6eQiOzvRtge7bS1IxwtQMm/YbSQmASBnSThHjaSaNzL8f0Hv4Afnyul8=\",\"TermUrl\":\"https://open.alipaymo.com/api/open/mpgs22/MPGSNEW221202.htm\"}",
        "redirectUrl":"https://secure5.arcot.com/acspage/cap?RID=85032&VAA=B"
    },
    "customerId":"****************",
    "paymentMethodDetails":[
        {
            "card":{
                "instUserName":{},
                "paymentMethodDetailMetadata":"{\"orderId\":\"2022022419055002162838006178385\",\"bindingStatus\":\"PROCCESS\",\"merchantTransId\":\"d6851c33-0125-4d7a-8e2d-a180******98\",\"useScene\":\"SELFT_HELP_BIND\",\"bingingDT\":\"2022-02-24T06:41:26Z\",\"verifyCardType\":\"CREDIT_CARD\"}"
            },
            "paymentMethodDetailType":"CARD"
        }
    ],
    "result":{
      "resultStatus":"S",
      "resultCode":"SUCCESS",
      "resultMsg":"success"
    },
    "status":"PROCCESS"
}
Step 4: Redirect the user back to the merchant

When the user completes the verification, the merchant needs to redirect the user back to their page.

The merchant can specify the redirectUrl field in the addPaymentMethod API to set the URL that redirects the user to their page.

Step 5: Query the payment card binding result

Call the queryPaymentMethod API to query the binding result after initiating the binding request. If the value of status is SUCCESS , the payment card is bound successfully.

Step 6: Notify the merchant of the binding result

After handling the card binding process, DWS will notify the merchant of the card binding result by the notify.addPaymentMethod SPI. The merchant needs to implement notify.addPaymentMethod SPI that is provided by DWS to notify the binding result asynchronously to ensure the binding result to be synced with the wallet.

  • DWS only notifies the merchant after the payment card is successfully bound.

Retry mechanism

After receiving the notification, the merchant must respond with an HTTP status code of 200 and send an acknowledgement with the result.resultStatus value of SUCCESS to indicate that the merchant server received and processed the call. If the merchant responds with other status codes or acknowledges with other values, DWS regards the notification delivery as unsuccessful. Therefore, DWS will retry sending the notification.

Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to seven times, with an interval of 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

Sample request

DWS sends a success notification to the merchant after the payment card is bound successfully.

copy
{
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMsg":"success"
  },  
  "referenceUserId": "2161220160649200",
  "requestId": "2015032412007101547201355678",
  "operateSource": "MERCHANT",
  "paymentMethodDetail": {
    "paymentMethodDetailType":"card",
    "card": {
      "cardToken": "85246e15131d44feb36c80e1a1e39",
      "mask":"123456******1234",
      "last4": "1234",
      "brand": "VISA",
      "expiryYear": "19",
      "expiryMonth": "07",
      "instUserName": {
        "firstName": "Example Inc",
        "lastName": "Acc"
      },
      "billingAddress": {
        "region": "China",
        "state": "Zhejiang",
        "city": "Hangzhou",
        "zipCode": "3100000",
        "address1": "xxx",
        "address2": "xxx"
      }
    }
  }
}

Sample response

The merchant returns a response to DWS.

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

6. List of APIs

The following table lists the APIs and SPI that are used for this function.

API

Direction

Description

consultAddablePaymentMethod

Merchant --> DWS

Use this API to retrieve the addable payment methods with the corresponding use scenes, such as bind, top-up, pay and so on. With this API call, the merchant can show the addable payment methods for their users before they want to bind a payment method.

cacheCard

Merchant --> DWS

Use this API to generate a temporary card token to transmission for information security.

addPaymentMethod

Merchant --> DWS

After consulting addable payment methods, the merchant uses this API to bind the selected payment method to the wallet, or redirect the user to a third party's page, such as a bank's page, a third-party wallet's page, to finish the binding process.

queryPaymentMethod

Merchant --> DWS

Use this API to view the payment method the user has bound, and the merchant presents the result to the user. The merchant can also use this API to query the status of binding payment method.

notify.addPaymentMethod

DWS --> Merchant

DWS uses this API to send the binding result to the merchant asynchronously. With this SPI call, the needed information is stored in JSON.

Check payment cards

1. Introduction

This function allows the user to check assets bound in the wallet.

During the process, the user will go to the merchant's page to see all the payment methods that are bound already. The merchant needs to send a request to DWS to query bound assets and DWS will give the result synchronously.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.3.2.jpg

3. Pre-requisite

Note: When quering a bound payment method, choose at least one payment method type to query.

4. Workflow

API integration guide

The user only needs to send a request to the merchant of querying bound assets and DWS will send the result synchronously.

5. Procedures

After the card is bound, there will be a token that encrypts all the card information to refer to the card.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
  "customerId": "****************",
  "paymentMethodDetailTypes": ["card"]
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
  "customerId": "****************",
  "paymentMethodDetails": [{
    "card": {
      "billingAddress": {},
      "brand": "MASTERCARD",
      "cardIssuer": "CIMB BANK BERHAD",
      "cardToken": "ALIPAYnMegKUM09Qu6cM0CxEvNm4/sEX0+lprK6rEg/SaQSak3dMATEwxZQKlw/myujdYSyWCloE4MwfmN48sP1+rSPQ==",
      "countryIssue": "MY",
      "expiryMonth": "**",
      "expiryYear": "**",
      "hashCode": "18a87763a17e14d4e60f4ee421a010d0ab9a2376d493549431c01e39695a1f89",
      "instUserName": {
        "firstName": "*** CHOOI",
        "lastName": "LI"
      },
      "mask": "519603******8111",
      "paymentMethodDetailMetadata": "{\"ipayCardIndex\":\"2021020419027100162059624568402\",\"ipayCardDetailIndex\":\"2021020419027100162871528763223\",\"bingingDT\":\"2021-02-04T06:25:12Z\",\"defaultCard\":\"F\"}"
    },
    "paymentMethodDetailType": "CARD"
  }],
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

queryPaymentMethod

Merchant --> DWS

This API allows users to see the payment method they have bound. With this API call, the merchant will call DWS and show the result to the user.

Unbind payment card

1. Introduction

This function allows users to unbind their bound payment methods.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.3.3.jpg

3. Pre-requisite

Note: Before removing a payment method, the merchant needs to call the queryPaymentMethod API to get the respective card token, which is used to remove the payment method.

4. Workflow

API integration guide

The workflow consists of the following steps:

  1. Query all payment methods bound by the user in the wallet and obtain permanent tokens.
  2. The merchant only needs to send the request to DWS to remove bound cards.
  3. DWS will notify the merchant of the result asynchronously.

5. Procedure

Step 1: Query all bound payment methods.

Call the queryPaymentMethod API to get all the permanent card tokens.

Step 2: Remove bound payment method, which is specified by card token.

The user chooses a payment method in the bound list to remove. The merchant uses the corresponding permanent card token to request the unbinding.

Note: The user can only remove one payment method at a time.

Sample

Request

Refer to the following sample to handle the request parameters properly.

copy
{
    "customerId":"21661000000635",
    "environment":{
        "clientIp":"200.**.***.**",
        "deviceTokenId":"t/dugoanTC9G5ZugwCYfGKu9j9/4meS0UQ8TAFuBoOnZrI/EfwEAAA==",
        "language":"es_US",
        "sessionId":"***********************************************_al_b_I",
        "terminalType":"APP",
        "umidTokenId":"YgSi0EEtk2MDAMACYWWfYRFN"
    },
    "paymentMethodDetail":{
        "card":{
            "cardToken":"ALIPAYcdvytJ//3s7FA5Nvg+Eqyfe0BClaM4IWFFH9XDVpYLx3s1IKn/9YAfRnRQEyK8chyWCloE4MwfmN48sP1+rSPQ=="
        },
        "paymentMethodDetailType":"card"
    },
    "requestId":"d5fc622c-d4f2-4499-ba17-22d0424474dc"
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
  "requestId": "d5fc622c-d4f2-4499-ba17-22d0424474dc",
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}{
  "paymentMethodRequestId": "d5fc622c-d4f2-4499-ba17-22d0424474dc",
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
 }
}
Step 3: Notify the merchant of the unbinding result asynchronously.

The merchant needs to implement the notify.removePaymentMethod SPI that is provided by DWS to notify the unbinding result asynchronously to ensure the unbinding result to be synced with the wallet.

Retry mechanism

After receiving the notification, the merchant must respond with an HTTP status code of 200 and send an acknowledgement with the result.resultStatus of SUCCESS to indicate that the merchant server received and processed the call. If the merchant responds with other status codes or acknowledges with other values, DWS regards the notification delivery as unsuccessful. Therefore, DWS will retry sending the notification.

Resending of the notification will be performed within 24 hours after the first notification is sent. The notification will be resent up to seven times, with an interval of 2min, 10min, 10min, 1h, 2h, 6h, and 15h.

Sample request

DWS sends a success notification to the merchant after the payment card is bound successfully

copy
{
  "referenceUserId": "216610000006358131449",
  "requestId": "2015032412007101547201355678",
  "operateSource": "MERCHANT",
  "paymentMethodDetail": {
    "paymentMethodDetailType":"card",
    "card": {
      "cardToken": "85246e15131d44feb36c80e1a1e39"
    }
  }
}

Sample response

The merchant returns a response to DWS.

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

6. List of API

The following table lists the API and SPI that are used for this function.

API

Direction

Description

removePaymentMethod

Merchant --> DWS

Use this API to remove a selected payment method from the user's wallet. The user selects a payment method to remove, and a one-to-one correspondence between the payment method and its card token exists.

notify.removePaymentMethod

DWS --> Merchant

DWS uses this API to send the unbinding result to the merchant asynchronously. With this API call, the needed information is stored in JSON.

Transaction management COMING SOON

Check transaction history

1. Introduction

This function allows users to view wallet transaction history and details.

Note:

  1. For EU users, SCA authentication may be required.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.3.4.1-1.jpg

Security

Authentication

Note: Integration of device fingerprint SDK is required, please refer to Native SDK integration solution.

Verify PIN

1. Introduction

This function allows users to be authenticated by using a PIN.

Note:

  1. If the user exceeds the maximum number of attempts, authentication will fail and an error will be returned.
  2. If the user exceeds the maximum cumulative number of attempts, authentication will be frozen for a period of time and the user can only retry authentication thereafter.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.4.1.1.jpg

3. List of feature

The following table lists the features that may require PIN authentication.

Product

Feature

Member

Account management

Check balance

Check & update email address

Check & update mobile number

Security settings

Change PIN

Transaction management

Check transaction history

Fund

Top-up

Top-up with card

5.4.1.2 Verify OTP

1. Introduction

This function allows users to be authenticated by using OTP.

Note:

  1. If the user exceeds the maximum number of attempts, authentication will fail and an error will be returned.
  2. If the user exceeds the maximum cumulative number of attempts, authentication will be frozen for a period of time and the user can only retry authentication thereafter.

2. User experience

The following table shows the user experience of this function.

User experience-5.4.1.2.jpg

3. List of feature

The following table lists the features that may require OTP authentication.

Product

Feature

Member

Account management

Check balance

Check & update email address

Check & update mobile number

Change PIN

Security settings

Check balance

Reset PIN

Transaction management

Check transaction history

Fund

Top-up

Top-up with card

5.4.1.3 Workflow

The standard workflow of the customer authentication product is illustrated as below:

API integration guide

DWS provides the ability to verify the user's identity to verify the real identity of the user in the interaction. When the risk control challenge is hit, the corresponding authentication needs to be performed according to the data returned by the API, such as consultTopUp, modifyAuthentication, and so on.

The above diagram details how operations are carried out in the wallet authentication process:

  1. The user triggers a feature by clicking a button or link on the user interface page. (Step 1)
  2. The merchant returns more data for rendering the page if needed and displays it to the user. (Step 2-5)
  3. The user enters additional information to initiate a request. (Step 6)
  4. The merchant calls the API to initiates the DWS feature after the user submit the data. (Step 7-8)
  5. DWS Risk Control evaluates the risk level of each interaction in real time, and decides whether to accept, reject, or require verification (Step 9). If it is accepted, it will continue the transaction. If it is rejected, the transaction will be rejected. If it is a challenge, the user needs to authenticate. (3DS only appears when binding cards and swiping cards for payment, users need to be redirected to a third-party card issuer for verification.)
  • DWS provides risk assessments for some transaction types and takes the following 4 actions:
  • Request 3DS authentication
  • Challenge
  • Accept
  • Reject
  1. In the case of a challenge, DWS initializes the identity verification request and returns the challenge data. (Step 10)
  2. The merchant needs to trigger the feature by calling the triggerChallenge API. (Step 11-12)
  3. The merchant renders the challenge page (PIN, OTP and so on). (Step 13-14)
  4. The user enters the information required for the challenge on the page and submits it. (Step 16)
  5. If more data is required to complete the feature, the merchant should call the verifyAuthentication API to verify and obtain further information. (Step 18-19).
  6. Call the verifyAndResume API to complete the verification and transaction. (Step 20-21)
  7. After DWS returns the verification result, the merchant displays the result to the user. (Step 22-23)
  8. If authentication fails, retry the request until the limit is reached.

Fund

Top-up

Top-up with card

1. Introduction

This function allows users to top up by using debit/credit cards.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.5.1.1.jpg

3. Pre-requisite

Notes:

  1. The wallet account has to be opened in order to top up.
  2. For EU, the user is required to complete partial KYC.

4. Workflow

The workflow of top-up is illustrated as below:

API integration guide

A. The flow consists of the following steps:

  1. The user wants to top up for balance and checks available top-up method. (Step 1)
  2. The merchant calls the consultTopUp API to obtain available methods for top-up and user's eligibility from DWS. (Step 2-3)
  3. If the user wants to bind a new top-up card, the user can perform cacheCard API first before proceeding to top up. (Step 5-8)
  4. User will choose one of the available top-up methods to top up wallet balance. The merchant calls the applyTopUp API to create a top-up order and gets the result of order creation. (Step 9-11)
  5. DWS will parallelly proceed with this transaction to DWS's financial institution partner and process the top-up.
  6. The merchant calls the queryTopUp API to obtain the current top-up result. (Step 12)
  7. While obtaining the top-up result through the queryTopUp API, DWS also provides a webhook capability to notify merchant through the notifyTopUp SPI. (Step 15-16)

B. On potential fraud detection by DWS, the workflow of top-up is illustrated as below:

API integration guide

The flow consists of the following steps :

  1. The user wants to top up for balance and checks the available top-up method. (Step 1)
  2. Merchant calls the consultTopUp API for obtaining a top-up method from DWS. (Step 2)
  3. As an available top-up method has been returned from Step 3 and 4, users are able to proceed to apply for top-up.
  4. If the user wants to bind a new top-up method, the user can call the cacheCard API first before proceeding to top up.
  5. User chooses one of the available top-up methods to top up the wallet's balance. Merchant calls the applyTopUp API to initiate the top-up process. (Step 10)
  6. When the transaction is counted as a potentially fraudulent transaction, the actionForm field in the applyTopUp API is returned. (Step 11)
  7. If the response times out, DWS also provides the queryTopUp API to obtain the current status (Step 12). Due to potential fraud transactions, the actionForm filed in the queryTopUp API is returned. (Step 13)
  8. The merchant proceeds to verification steps after obtaining the value of actionForm.
  9. To process the verification steps, the merchant is recommended to switch to the verification page and ask the user to verify.
  10. Once the user decided to verify, the merchant shall invoke the triggerChallenge API to send the verification message (Step 17).
  11. The user enters the verification code after receiving the message.
  12. The merchant shall forward this message to DWS through the verifyAndResume API to verify the potentially fraudulent transaction and reinitiate the overall transaction.
  13. DWS will parallelly proceed with this transaction to DWS's financial institution partner and the top-up process.
  14. The merchant invokes the queryTopUp API to obtain the current top-up status.
  15. After obtaining the transaction's top-up result (Step 12), in most cases, DWS's financial institution partners take time to process the payment. The final status of the top-up is not returned immediately.
  16. When the top-up is not finalized by DWS's partner, topUpResult in the queryTopUp API indicates PAYMENT_IN_PROCESS. The merchant is recommended not to apply for a new transaction.
  17. If the value of resultStatus isU, the merchant needs to retry the queryTopUp API for several times.
  18. Once DWS returns the final status, the merchant can proceed with the transaction for further steps.
  19. While obtaining the top-up result through the queryTopUp API, DWS also provides a webhook capability to notify the merchant through notifyTopUp SPI. (Step 29)
  20. The merchant can proceed with the transaction for further steps after receiving the final status.
  21. It is recommended that the merchant uses both the queryTopUp API and the notifyTopUp SPI to keep track of the top-up result.

C. On potential fraud detection by third-party financial institution, the work flow of top-up is illustrated as below:

API integration guide

The flow consists of the following steps:

  1. The user wants to top up the balance and checks the available top-up method. (Step 1)
  2. The merchant calls the consultTopUp API (Step 2) for obtaining the top-up method from DWS.
  3. As the available top-up method has been returned from Step 3 and 4, users are able to proceed to apply for a top-up.
  4. If the user wants to bind a new top-up method, the user can call the cacheCard API first before proceeding to top up.
  5. The user chooses one of the available top-up methods to top up the wallet's balance. Merchant calls the applyTopUp API to initiate the top-up process. (Step 10)
  6. The merchant receives the result of top-up order creation from DWS. (Step 11)
  7. The merchant shall loop to query for the top-up result from DWS (Step 12), and get the result with RedirectActionForm.(Step 13)
  8. Parallelly the merchant receives 3D notification through notifyTopUp.（Step 14）
  9. The merchant redirects the user to the bank verification page after receiving the notification. (Step 15)
  10. The user completes the verification, and the merchant redirects the user to the progress page. (Step 16-17)
  11. The merchant gets the user's verification result from the looped query. (Step 18-19)
  12. If the result is still processing, webhook will return the final result. (Step 20)
  13. For obtaining the top-up result through webhook, DWS will send notifyTopUp notification (Step 21), the merchant may acknowledge the notification. (Step 22)
  14. The merchant returns the top-up result to the user. (Step 23)

Note: After a transaction is being suspected as fraud, the transaction might also be suspected as fraud by banks and double security measures can be triggered.

5. Procedure

Step 1: Obtain available top-up payment method and top-up payment option

Before proceeding to top up, the user is required to obtain available payment methods and options for top-up. On this case, the merchant is required to obtain this information from the consultTopUp API.

Sample request

The merchant server sends the request of obtaining available payment method and options.

copy
{
  "productCode": "STANDARD_TOPUP",
  "consultTopUpRequestId":"999912314213",
  "customerId": "2165210039309494",
  "topUpAmount": {
    "value": 10000,
    "currency": "SGD"
  },
  "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
  }
}

Sample response

The wallet returns the available payment method and options.

copy
{
  "topUpMethodInfos": [
    {
      "enabled": true,
      "topUpMethodDetail": "{\"card\":{\"cardIssuer\":\"MOMO\",\"cardToken\":\"ALIPAYHWuKSBwokmmIZVmVlkRiSbrZRgzKc+SKuKP6Nh2lH5U+UytZNXEsH43GVtfH2uUgecG+d5jFylCRsGrtK8j0YA\u003d\u003d\",\"instUserName\":{},\"topUpMethodDetailMetadata\":\"{\\\"cardIndex\\\":\\\"20210312190279001699I8800024560\\\"}\"},\"type\":\"card\"}",
      "topUpMethodType": "MIXEDCARD",
      "preferred": false
    },
    {
      "enabled": true,
      "topUpMethodDetail": "{\"storeValue\":{\"accountNo\":\"21692200051185F81704\",\"availableAmount\":{\"currency\":\"SGD\",\"value\":\"0\"},\"frozenAmount\":{\"currency\":\"VND\",\"value\":\"0\"},\"topUpMethodDetailMetadata\":\"{\\\"balanceInfo\\\":\\\"{\\\\\\\"availableAmount\\\\\\\":{\\\\\\\"currency\\\\\\\":\\\\\\\"SGD\\\\\\\",\\\\\\\"value\\\\\\\":\\\\\\\"0\\\\\\\"},\\\\\\\"currency\\\\\\\":\\\\\\\"SGD\\\\\\\",\\\\\\\"frozenAmount\\\\\\\":{\\\\\\\"currency\\\\\\\":\\\\\\\"SGD\\\\\\\",\\\\\\\"value\\\\\\\":\\\\\\\"0\\\\\\\"},\\\\\\\"totalAmount\\\\\\\":{\\\\\\\"currency\\\\\\\":\\\\\\\"SGD\\\\\\\",\\\\\\\"value\\\\\\\":\\\\\\\"0\\\\\\\"}}\\\"}\",\"totalAmount\":{\"currency\":\"SGD\",\"value\":\"0\"}},\"type\":\"storeValue\"}",
      "topUpMethodType": "PAYMENT_ACCOUNT",
      "preferred": false
    }
  ],
  "topUpOptions": [
    {
      "amountLimitMap": {},
      "enabled": true,
      "topUpMethodCategory": "PAYMENT_ACCOUNT",
      "topUpMethodType": "PAYMENT_ACCOUNT",
      "preferred": false,
      "rank": 5000,
      "supportedCurrencies": [
        "SGD"
      ]
    },
    {
      "amountLimitMap": {
        "SGD": {
          "singleLimit": {
            "maxAmount": {
              "currency": "SGD",
              "value": "999999999999"
            },
            "minAmount": {
              "currency": "SGD",
              "value": "1"
            }
          }
        }
      },
      "enabled": true,
      "topUpMethodCategory": "MIXEDCARD",
      "topUpMethodType": "MIXEDCARD",
      "topUpOptionDetail": "{\"card\":{\"bankInfos\":[],\"supportCardBrands\":[{\"cardBrand\":\"NAPAS\",\"supportedCurrencies\":[\"SGD\"]},{\"cardBrand\":\"MASTERCARD\",\"supportedCurrencies\":[\"VND\"]},{\"cardBrand\":\"JCB\",\"supportedCurrencies\":[\"SGD\"]},{\"cardBrand\":\"VISA\",\"supportedCurrencies\":[\"SGD\"]}]},\"type\":\"card\"}",
      "preferred": false,
      "rank": 4800,
      "supportedCurrencies": [
        "SGD"
      ]
    }
  ],
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}
Step 2: Apply top-up

Cache card information (optional)

  • If the user chooses to use a new credit/ debit card, the merchant must call the cacheCard API to cache card elements and return a temporary token.
  • The temporary card token is only valid within the time range, and the merchant needs to obtain it again next time.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
  "paymentMethodDetail": {
    "paymentMethodDetailType": "card",
    "card": {
      "cardNo": "1234561234561234",
      "brand": "VISA",
      "securityCode": "444",
      "expiryYear": "2019",
      "expiryMonth": "07",
      "instUserName": {
        "firstName": "xxx",
        "lastName": "xxx",
      },
      "billingAddress": {
        "region": "China",
        "state": "Zhejiang",
        "city": "Hangzhou",
        "zipCode": "3100000",
        "address1": "xxx",
        "address2": "xxx",
      }
    }
  }
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMsg":"success"
  },
  "expiryTime":"2001-07-04T12:08:56+05:30",
  "paymentMethodDetail": {
    "paymentMethodDetailType":"card",
    "card": {
      "cardToken": "85246e15131d44feb36c80e1a1e39",
      "mask":"123456******1234",
      "last4": "1234",
      "brand": "VISA",
      "expiryYear": "2019",
      "expiryMonth": "07",
      "instUserName": {
        "firstName": "xxx",
        "lastName": "xxx",
      },
      "billingAddress": {
        "region": "China",
        "state": "Zhejiang",
        "city": "Hangzhou",
        "zipCode": "3100000",
        "address1": "xxx",
        "address2": "xxx",
      }
    }
  }
}

Apply top-up

The merchant invokes the applyTopUp API to initate the top-up process and create an order in DWS.

Sample request

The merchant server sends the request to initiate a top-up process.

copy
{
  "productCode": "STANDARD_TOPUP",
  "topUpRequestId": "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
  }
}

Sample response

The wallet returns the status of top-up request.

copy
{
  "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"
  }
}
Step 3: Obtain top-up result

The merchant calls the queryTopUp API or calls the notifyTopUp SPI to obtain top-up result and check the status of the top-up payment.

DWS sends the notifyTopUp SPI to the merchant when the user completes the top-up. Besides, the merchant can call the queryTopUp API to get the payment result from DWS. When the user completes the top-up but the merchant fails to receive the notifyTopUp SPI due to some network issues, the queryTopUp API can take effect to ensure the final top-up result is returned.

Query top-up result

Call the queryTopUp API to query the result of top-up. When the user needs authentication, the API returns a 3DS authentication page URL.

The following parameters must be configured properly in the request:

  • topUpRequestId: Used for idempotence control. The value must be the same as the one in the applyTopUp API request. For the top-up requests which are initiated with the same topUpRequestId value and reach a final status (S or F), DWS and the merchant must return the unique result.
  • topUpId: The value must be the same as the one in the applyTopUp API response.

DWS returns the following two kinds of results:

  • result: specifies the acceptance results of the queryTopUp request.
  • topUpResult: specifies the payment results.
  • Once topUpResult.resultStatus returned the value S or F, the transaction has been finalized.

When the top-up result is pending, DWS will return PAYMENT_IN_PROCESS as the top-up result. It is recommended to call the queryTopUp API in the form of polling: keep querying for 10 minutes with an incremental frequency, after the merchant server side gets the response of the queryTopUp API.

  • When a verification of the top-up result is required from DWS, DWS returns the actionForm.actionFormType field with the value ChallengeActionForm. And the merchant advances the transaction to the verification process.
  • When a verification of the top-up result is required from the bank, DWS returns the actionForm.actionFormType field with the value RedirectActionForm.
  • The merchant needs to redirect their user to the bank page through the given URL.
  • After the user completed the authorization, additional verification from the bank side is still required (double challenge is possible).

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
  "topUpRequestId": "20220302190077000001163010221223552",
  "topUpId": "20220302190077000001163010221223553"
}

Sample response

DWS returns a successful result of top-up payment

copy
{
  "result": {
    "resultCode": "SUCCES",
    "resultStatus": "S",
    "resultMessage": "success"
  },
  "topUpResult": {
    "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"
  }
}

DWS returns the result that top-up payment is in process

copy
{
  "result": {
    "resultCode": "SUCCES",
    "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"
  }
}

DWS returns the challenge action

copy
{
  "result": {
    "resultCode": "SUCCES",
    "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"
  }
}

DWS returns the redirection URL

copy
{
  "result": {
    "resultCode": "SUCCES",
    "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"
  }
}

Top-up result webhook from NotifyPayment

To obtain the payment result, the merchant can wait for the notifyTopUp webhook to get the status of the top-up payment.

The top-up result is returned in the filed of result:

  • If the value of result.resultStatus is S , the top-up rsesult is successful.
  • If the value of result.resultStatus is F , the top-up rsesult is failed.
  • If the value of result.resultStatus is U , the top-up rsesult is unknow.
  • If the value of topUpResult.resultCode is PAYMENT_IN_PROCESS , the top-up is in process.

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

When a verification of the top-up notification is requird from DWS, DWS returns the actionForm.actionFormType field with the value ChallengeActionForm.

  • Once the merchant receives ChallengeActionForm, the merchant shall proceed 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.

When a verification of the top-up notification is requird from the bank, DWS returns the actionForm.actionFormType field with the value 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.

Sample request

DWS sends a success notification to the merchant after the top-up payment is successfully

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"
  }
}

DWS sends a notification to the merchant after the top-up payment is in process

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"
  }
}

DWS sends a notification with the redirection URL to the merchant after the top-up payment is failed.

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": "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"
  }
}

Sample response

The merchant is required to send the receipt to Alipay.

copy
{
  "result": {
    "resultCode": "SUCCES",
    "resultStatus": "S",
    "resultMessage": "success"
  }
}

Verification when the transaction is challenged (optional)

Trigger challenge

If the user is required to submit verification, the merchant needs to trigger a challenge.

  • scene has to be determined as TOPUP.
  • authenticationId is topUpId in the applyTopUp API.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
	"scene": "TOPUP",
	"authenticationId": "20220302190077000001163010221223553",
	"triggerRequestId": "trigger_1024343767436",
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "challengeRenderData":{
        "challengeRenderValueType":"mobile",
        "challengeRenderValue":"13880324",
        "canRetryChallenge":true,
        "isChallengeFinish":false,
        "challengeLeftTimes":"3"
    }
}

Verify and resume

Once the user submitted triggerChallenge, the user can submit their verification code from the verifyAndResume API.

  • scene has to be determined as TOPUP.
  • orderId is topUpId in the applyTopUp API.

Sample request

Refer to the following sample to handle the request parameters properly.

copy
{
	"scene": "TOPUP",
	"orderId":"20220302190077000001163010221223553",
	"verifyRequestId":"20190608114010800100188820200355885",
	"challengeData":{
      "challengeType":"SMS_OTP",
      "otpValue":"200181"
	}
}

Sample response

Refer to the following sample to configure the response parameters properly.

copy
{
    "result":{
        "resultCode":"SUCCESS",
        "resultStatus":"S",
        "resultMessage":"success"
    },
    "orderId":"20220302190077000001163010221223553",
    "challengeInfo": {
      "canReValidate": false,
      "challengeLeftTimes": 0
    }
}

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

consultTopUp

Merchant --> DWS

Obtain available payment method and payment option for top up

cacheCard

Merchant --> DWS

Create temporary card token before payment

applyTopUp

Merchant --> DWS

Initiate top-up process using selected top up payment method

queryTopUp

Merchant --> DWS

Query initiated top-up process result from DWS

notifyTopUp

DWS --> Merchant

DWS will send webhook to merchant that inform about top-up result

triggerChallenge

Merchant --> DWS

Trigger a verification method to secure transaction from being fraudulent

verifyAndResume

Merchant --> DWS

Verify suspected fraudulent transactions and resume the transaction

Payment

Online payment

Pay with balance

1. Introduction

This function allows users to pay with their wallet balance.

2. User experience

The following diagram shows the user experience of this function.

User experience-5.6.1.1.jpg

3. Pre-requisite

Note:

The wallet account has to be opened in order to pay with balance.

4. Workflow

4.1 Pay

The work flow to pay is illustrated as below:

API integration guide

The workflow consists of the following steps:

  1. The user purchases the merchandise on a merchant platform and places an order. (Step 1)
  2. The merchant consults the acquirer on the user's available payment methods by calling the consultPayment API. (Step 2)
  3. The acquirer gets the user's information and balance from DWS if the user opened the balance account on DWS. (Step 3-5)
  4. The acquirer returns the available payment methods to the merchant. (Step 6)
  5. The merchant displays the payment methods to the user. (Step 7)
  6. The user selects the DWS wallet to pay. (Step 8)
  7. The merchant initiates the request by the pay API to the acquirer's server. (Step 9)
  8. The acquirer initiates the request to the DWS server. (Step 10)
  9. DWS server creates an order of payment and the risk control detects the risk of the account. (Step 11-13)
  • If the risk control is accepted, DWS server completes the payment and returns the payment result.
  • If the risk control is rejected, DWS server returns the failure result.
  • If the user needs to authenticate, DWS server returns the authentication URL of Merchant Challenge H5 page.
  1. The merchant gets the redirection URL and redirects the user to H5 page of Merchant for authentication. (Step 15)
  2. The Merchant H5 inquires the challenge data and renders the PIN verification page. (Step 16-18)
  3. The user enters the PIN. (Step 19)
  4. The Merchant verifies the PIN. If the verification succeeds, the DWS returns the verification result and renders the OTP verification page. (Step 20-25)
  5. The DWS sends an OTP to the user's phone that is bound to the wallet. (Step 26)
  6. The user enters the OTP. (Step 27)
  7. The Merhcant verifies the OTP. If the verification succeeds, DWS returns the verification result and redirects the user to the Merchant's page. (Step 28-32)
  8. After the user completes the payment successfully or the transaction reaches a final state of failure, DWS sever sends a payment result notification to the acquirer. (Step 33)
  9. The acquirer sends a payment result notification to the merchant. (Step 34)
  10. The merchant can also call the inquiryPayment API to obtain accurate payment results. (Step 35-38)

4.2 Refund

The workflow consists of the following steps:

  1. The user issues a refund against a successful payment. (Step 1)
  2. The merchant initiates the refund by the refund API. (Step 2)
  3. Acquirer accepts the refund and returns the acceptance result to the merchant. (Step 3-4)
  4. Acquirer initiates a refund request to DWS and gets the acceptance result from DWS. (Step 6-7)
  5. DWS returns the money to the balance. (Step 8)
  6. After the refund reaches a final state of success or failure, DWS sever sends the refund result notification to the acquirer. (Step 9)
  7. Acquirer sends the refund result notification to the merchant. (Step 10)
  8. The merchant can also call the inquiryRefund API to obtain accurate refund results. (Step 12-15)

Note: Cancel is integrated in a similar way.

5. Procedure

5.1 Pay
Step 1: Consult available payment methods

The merchant consults the acquirer on the available payment methods by the consultPayment API. The acquirer checks the DWS balance availability, remaining available amount, and corresponding currency. The first step is to pay with DWS balance. See the acquirer's payment integration solution for details.

Step 2: Pay with DWS

The user initiates an order on the merchant platform and selects an available wallet to pay. A server-side request is initiated via the pay API to the acquirer server. See the acquirer's payment integration solution for details.

Step 3: Get the redirection URL and redirect the user to complete verification

After the payment request is sent successfully, a response with a redirection URL is returned by the acquirer if verification is required and such verification URL can be provided either by the merchant or DWS. And then the merchant redirects the user to the H5 page for authentication. If the URL is provided the merchant, the merchant needs to inform DWS upon user completing the verification and DWS then returns the verification result. If a second verification is required, the next challenge will be returned at the same time along with the result for the first verification. After all verifications are passed, DWS proceeds to the payment.

Step 4: Get payment result

After the user completes the payment successfully or the transaction reaches a final state of failure, DWS sends a payment result notification to the acquirer, and the acquirer sends it to the merchant. The address used to receive the notification (Payment Notification URL) is specified in the pay request or configured in Acquirer. If the merchant specifies the Payment Notification URL in both the pay request and the cquirer, the value specified in the pay request takes precedence. See the acquirer's payment integration solution for details.

The merchant can also call the inquiryPayment API to obtain accurate payment results.

It is suggested that the merchant integrates both the payment result inquiry and the asynchronous notification services to ensure the payment result is obtained from any wallet, since some wallets might not return any notification when the payment fails.

5.2 Cancel or refund

Step 1: Cancel the transactions or refund

The user can cancel the transactions that have been successfully paid in the acquirer's system by using the cancel API. See the acquirer's payment integration solution for details.

The user can issue a refund by using the refund API. The refund service is only applicable to a transaction that has been successfully paid. See Acquirer's payment integration solution for details.

Step 2: Inquire about cancel or refund status

As long as the cancellation request is initiated, DWS guarantees that the transaction will be canceled or refunded:

  • If the user has not completed the payment, the transaction will be canceled.
  • If the user has completed the payment, the transaction will be refunded.

The cancellation result is returned in the result.resultStatus field of the cancel response. See Acquirer's payment integration solution for details.

To obtain the refund result, the merchant can either wait for the refund response or actively call the inquiryRefund API to inquire about the refund result. See Acquirer's payment integration solution for details.

6. List of API

The following table lists the APIs that are used for this function.

API

Direction

Description

triggerChallenge

Merchant --> DWS

Trigger a verification method to secure transaction from being fraudulent

verifyAndResume

Merchant --> DWS

Verify suspected fraudulent transaction resume the transaction

More information

Introduction

Getting started

Use case: Balance payment

Mobile SDK integration guide

API reference

Glossary

What's new