Create a gateway token
You have two ways to save the user's payment method(s) and get the gateway token generated by EVO Cloud:
- Create the gateway token while payment
- Create a gateway token and make payment later
For card payment, you can choose either based on your business needs. For WeChat Pay and Alipay, following the PSP's policy, you need to create gateway token before the payment.
Create the gateway token while payment
For card payment, send additional parameters to create a gateway token when your user makes a payment. EVO Cloud will collect the payment information from the user and generate a gateway token. The processing flow is the same as the one in chapter Payment.
From your server, you can make an HTTP POST request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/payment
and specify the additional parameters below.
| Body parameter | Required | Description |
|---|---|---|
paymentMethod.type | M | Only card is applied. |
paymentMethod.card | M | Specify paymentMethod.card.tokenize is true to request EVO Cloud to perform tokenization for this payment, and specify related card information and tokenization attributes in paymentMethod.card object. |
paymentMethod.recurringProcessingModel | O | This is to indicate whether a transaction is recurring.You can use Subscription for recurring transaction saved credentials. |
authentication | O | The information used for the user authentication before tokenization. |
userInfo | M | Detailed information about the buyer. Specify user reference related to token. |
returnURL | M | The URL to redirect your customer back to after your customer completes or cancels the payment. |
More details about the additional parameters in paymentMethod.card object:
paymentMethod.card.tokenize: A Boolean value to request EVO Cloud. Set is it as true if you want to tokenize the card information for your user, required.paymentMethod.card.vaultID: The group ID which the token belongs to, required. You can get this ID assigned by EVO Cloud from your account manager before integration.paymentMethod.card.tokenValidDays: The validity period for the token, optional. 0 or not present means the token to be generated is permanent valid, and you can set it between 1 to 365 to specify the validity days for the token.
More details about the additional parameters in userInfo object:
userInfo.reference: A unique identifier for a user, required. You need to specify it as a reference for the token.
For the details about authentication object, see chapter Authentication for more details.
Here is an example of requesting a gateway token while making a 10 USD payment by credit card:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
10. "merchantTransTime": "2021-12-31T08:30:59+08:00"
11. },
12. "transAmount": {
13. "currency": "USD",
14. "value": "10.00"
15. },
16. "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
17. "paymentMethod": {
18. "type": "card",
19. "card": {
20. "cardInfo": {
21. "cardNumber": "4761340000000019",
22. "expiryDate": "2212",
23. "cvc": "946"
24. },
25. "tokenize": true,
26. "vaultID": "11111902_00001"
27. }
28. },
29. "userInfo": {
30. "reference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
31. },
32. "transInitiator": {
33. "browserInfo": {
34. "acceptHeader": "application/json, text/plain, */*",
35. "colorDepth": "1",
36. "javaEnabled": true,
37. "language": "US",
38. "screenHeight": "300",
39. "screenWidth": "200",
40. "timeZoneOffset": "480",
41. "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36"
42. }
43. },
44. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
45. "metadata": "This is a metadata"
46.}'Usually, it requires further action to perform user authentication before completing the tokenization and payment. See chapter Authentication for more details. The gateway token will be sent to your server in the response parameter paymentMethod.token object when the user authentication and payment get finished.
Here is an example of a successful payment response with gateway token:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success",
5. "pspResponseCode": "00",
6. "pspMessage": " Approval and completed successfully; Accepted and processed"
7. },
8. "paymentMethod": {
9. "card": {
10. "first6No": "476134",
11. "last4No": "0019",
12. "paymentBrand": "Visa",
13. "fundingType": "credit"
14. },
15. "token": {
16. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
17. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
18. "vaultID": "11111902_00001",
19. "fingerprint": "286fcea14de3eaf021f0304ca34d3f4c",
20. "status": "enabled"
21. }
22. },
23. "authentication": {
24. "type": "threeDSPage",
25. "threeDS": {
26. "mpiData": {
27. "status": "Y",
28. "eci": "05"
29. }
30. }
31. },
32. "payment": {
33. "status": "Authorised",
34. "merchantTransInfo": {
35. "merchantTransID": "f2d45e3397704f2a818b7b74bc94e7ce",
36. "merchantTransTime": "2021-12-31T08:30:59+08:00"
37. },
38. "evoTransInfo": {
39. "evoTransID": "8a0d5cd24b5b4156b94010cee115bceb",
40. "evoTransTime": "2021-12-31T00:30:59Z"
41. },
42. "pspTransInfo": {
43. "pspTransTime": "2021-12-31T08:30:59+08:00",
44. "authorizationCode": "091410"
45. },
46. "transAmount": {
47. "currency": "USD",
48. "value": "10.00"
49. }
50. },
51. "pspData": {
52. "name": "Visa"
53. },
54. "metadata": "This is a metadata"
55.}TIP
You need to store the token information received in your server for further use.
Create a gateway token and make payment later
For both card payment and E-Wallet payment including WeChat Pay or Alipay, you can create gateway token first with the PaymentMethod API, and make payment later, allowing you to guide your user to add the payment method to the account now and make payment later.
Special note for WeChat Pay: Following the PSP's policy, you can only create gateway token within the WeChat mini-program. Except API integration mode, EVO Cloud also provides the SDK solution to simplify the mini-program integration. See EVO Cloud SDK Integration Guide and contact your EVO Cloud account manager to get prepared before the integration.
The diagram above describes both server-side integration and the client-side implementation that you have to build.
Step 1: Get available payment method(s)
When a user is ready to pay or enters your payment page, get a list of the available payment method(s) with the corresponding information that needs to be filled in by the user.
See Step 1 in chapter Payment for more details.
Step 2: Collect user's payment information
Collect your user's payment info based on the fields required by each payment method, then send them to your host.
See Step 2 in chapter Payment for more details.
Step 3: Submit the tokenization request
After the user chooses the payment method and submits the required payment information, you need to make a payment request to EVO Cloud.
From your server, you can make an HTTP POST request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify the parameters below.
| Body parameter | Required | Description |
|---|---|---|
merchantTransInfo | M | The reference for the payment, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request. |
paymentMethod | M | Use paymentMethod.type to specify e-wallet or card that the user want to tokenize, with different payment information that you collect in the previous step. |
transInitiator | O | The information of device to initiate the transaction. |
authentication | O | The information used for user authentication before the tokenization, required for card payment. |
userInfo | M | Detailed information about the buyer. Specify user reference related to token. |
storeInfo | M | The supplemental store information. When your store is assigned with multiple MCCs in EVO Cloud, this field is required to indicate which MCC you are using for this payment. |
returnURL | O | The URL to redirect your customer back to after your customer completes or cancels the payment. |
webhook | O | The URL to receive notification. Specify this to get the notification from EVO Cloud after the tokenization succeeds. |
metadata | O | A self-defined reference information that you can specify in the request, and will be echoed back in the response. The metadate message in the response is the same as the metadata in your request message, except of GET request. The metadata in GET response message is the same as the metadata in the POST request message. And the metadata in the notification is the same as the metadata in the POST request message. |
More details about paymentMethod and userInfo object:
A. When the user chooses to tokenize with E-Wallet:
paymentMethod.type: Set ase-walletin your request.paymentMethod.e-wallet.paymentBrand: The Payment Brand of the wallet that the user chooses to tokenize with, required.WeChat_PayandAlipayare applied.userInfo.reference: A unique identifier for a user, required. You need to specify it as a reference for the token.paymentMethod.e-wallet.vaultID: The group ID which the token belongs to, required. You can get this ID assigned by EVO Cloud from your account manager before integration.paymentMethod.e-wallet.planID: The WeChat auto debit contract template ID, required when the user tokenizes with WeChat Pay (paymentMethod.e-wallet.paymentBrandisWeChat_Pay) in your WeChat mini-program (transInitiator.platformisMINI). Get this ID when you apply for the auto debit service from WeChat.paymentMethod.e-wallet.subOpenID: The user ID for a user in your WeChat mini-program, required when the user tokenizes with WeChat Pay (paymentMethod.e-wallet.paymentBrand=WeChat_Pay) in your WeChat mini-program (transInitiator.platform=MINI). Get this ID when the user logs into your
B. When the user chooses to tokenize with card:
paymentMethod.type: Set ascardin your request.paymentMethod.card.encryptedCardInfo: The encrypted card information. If you use EVO Cloud client-side solution to securely encrypt your user's card details, your frontend will get the value from EVO Cloud SDK, and you need to send it to your host, then forward the original data from your host to EVO Cloud.paymentMethod.card.cardInfo: The raw data of the card information. If you collect and send raw card data to EVO Cloud, you need to specify thecardNumber,expiryDate, andcvc(optional) andholderNamewithin this object. Note that for some of the UnionPay debit cards, theexpiryDateis also optional.
(If bothpaymentMethod.card.encryptedCardInfoandpaymentMethod.card.cardInfoare present,paymentMethod.card.cardInfowill be applied.)userInfo.reference: A unique identifier for a user, required. You need to specify it as a reference for the token.paymentMethod.card.vaultID: The group ID which the token belongs to, required. You can get this ID assigned by EVO Cloud from your account manager before integration.paymentMethod.card.tokenValidDays: The validity period for the token, optional. 0 or NOT presented means the token to be generated is permanently valid, and you can set it between 1 to 365 to specify the validity days for the token.
About the details of authentication object, see chapter Authentication for more details.
Here is an example of tokenization with Alipay:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "bfd0092cbbf24a619742a5aba85cd473",
10. "merchantTransTime": "2021-12-31T08:30:59+08:00"
11. },
12. "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
13. "paymentMethod": {
14. "type": "e-wallet",
15. "e-wallet": {
16. "paymentBrand": "Alipay",
17. "vaultID": "11111902_00001"
18. }
19. },
47. "userInfo": {
48. "reference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
49. },
20. "transInitiator": {
21. "platform": "APP",
22. "deviceType": "iOS",
23. "osVersion": "iOS 15.2"
24. },
25. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
26. "metadata": "This is a metadata"
27.}'Usually, the response contains an action object to inform you about the additional steps required to complete the tokenization. You need to send the action object to your web frontend or client APP, then proceed to the next step.
Here is an example of the response that requires you to redirect your user to complete the tokenization:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "action": {
7. "type": "redirectUser",
8. "redirectData": {
9. "url": "https://YOUR_AGREEMENT_SIGN_URL",
10. "method": "GET"
11. }
12. },
13. "paymentMethod": {
14. "merchantTransInfo": {
15. "merchantTransID": "bfd0092cbbf24a619742a5aba85cd473",
16. "merchantTransTime": "2021-12-31T08:30:59+08:00"
17. }
18. },
19. "metadata": "This is a metadata"
20.}Here is an example of tokenization with WeChat Pay:
1.curl -X POST https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE" \
7.-d '{
8. "merchantTransInfo": {
9. "merchantTransID": "ddbe7e10206b497e84891968bdcd35ab",
10. "merchantTransTime": "2021-12-31T08:30:59+08:00"
11. },
12. "paymentMethod": {
13. "type": "e-wallet",
14. "e-wallet": {
15. "paymentBrand": "WeChat_Pay",
16. "vaultID": "11111902_00001",
17. "planID": "YOUR_PLAN_ID",
18. "subOpenID": "YOUR_SUB_OPEN_ID"
19. }
20. },
21. "userInfo": {
22. "reference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
23. },
24. "transInitiator": {
25. "platform": "APP",
26. "deviceType": "iOS",
27. "osVersion": "iOS 15.2"
28. },
29. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
30. "metadata": "This is a metadata"
31.}'Here is an example of the response that requires you to invoke WeChat APP to complete the tokenization:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "action": {
7. "type": "invokeWallet",
8. "walletData": {
9. "paymentString": "YOUR_AGREEMENT_SIGN_ID"
10. }
11. },
12. "paymentMethod": {
13. "merchantTransInfo": {
14. "merchantTransID": "ddbe7e10206b497e84891968bdcd35ab",
15. "merchantTransTime": "2021-12-31T08:30:59+08:00"
16. }
17. },
18. "metadata": "This is a metadata"
19.}Step 4: Perform additional actions
If your server receives an action object in the (/g2/v1/payment/mer/{sid}/paymentMethod) response, your next steps depend on the action.type.
| Type of the action | Description | Next steps |
|---|---|---|
threeDSRedirect | This is applied to 3DS 1 or 2 when processing authentication in which paymentMethod.type is card and authentication.type is threeDSPage or threeDSIntegrator. | Redirect the user to another website to complete the 3DS 1 or 2 authentication with action.threeDSData in the same response. See chapter Authentication for more details. |
threeDSIdentify | This is applied to 3DS 2 when processing authentication in which paymentMethod.type is card with authentication.type is threeDSIntegrator. | Redirect the user to another website to complete the 3DS 2 frictionless authentication with action.threeDSData in the same response. See chapter Authentication for more details. |
threeDSChallenge | This is applied to 3DS 2 when processing authentication in which paymentMethod.type is card with authentication.type is threeDSIntegrator. | Redirect the user to another website to complete the 3DS 2 challenge authentication with action.threeDSData in the same response. See chapter Authentication for more details. |
inputMobilePhone | This is applied to SecurePlus authentication for paymentMethod.type is card and authentication.type is SecurePlus. | Present an input box on your payment page to ask the user to input the mobile phone number, and submit it to EVO Cloud. See chapter Authentication for more details. |
inputSMSCode | This is applied to SecurePlus authentication for paymentMethod.type is card and authentication.type is SecurePlus. | Present an input box on your payment page to ask the user to input the SMS code received on the mobile phone, and submit it to EVO Cloud. See chapter Authentication for more details. |
redirectUser | This is applied to tokenization with Alipay on PC WEB, mobile WAP and client APP. | Redirect the user to the action.redirectData.url with HTTP method specified in action.redirectData.method. If action.redirectData.method is POST and action.redirectData.parameter exists, specify the sub field(s) in the parameter object as the form data of the POST request. The user is then redirected to a page where they need to take additional action to sign an electronic contract with wallet operator to complete the tokenization. After the user completes signing the electronic contract, they are redirected back to your returnURL with an HTTP GET. You can optionally display a loading page to the user before you get the tokenization result. 1.You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/paymentMethod to get the tokenization result. See Step 6 for more details. Or you can wait for the notification webhook to know the tokenization result. See chapter After Payment for more details. |
invokeWallet | This is applied to tokenization with WeChat Pay in WeChat mini-program. | Redirect the user to the action.redirectData.url with HTTP method specified in action.redirectData.method. If action.redirectData.method is POST and action.redirectData.parameter exists, specify the sub field(s) in the parameter object as the form data of the POST request. The user is then redirected to a page where they need to take additional action to sign an electronic contract with wallet operator to complete the tokenization. After the user completes signing the electronic contract, they are redirected back to your returnURL with an HTTP GET. You can optionally display a loading page to the user before you get the tokenization result. 1.You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/paymentMethod to get the tokenization result. See Step 6 for more details. Or you can wait for the notification webhook to know the tokenization result. See chapter After Payment for more details. |
Step 5: Submit additional tokenization information
When the payment method is the card, if the user performs the authentication flow, you need to submit the additional authentication details to EVO Cloud to complete the tokenization. See chapter Authentication for more details.
For WeChat Pay, the user will be switched to WeChat APP to sign an electronic contract with WeChat, and you need to submit the result to EVO Cloud to complete the tokenization.
From your server, you can make an HTTP PUT request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify the parameters below.
| Query parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial tokenization request. |
| Body parameter | Required | Description |
|---|---|---|
paymentMethod.e-wallet.contractID | M | For tokenization with WeChat Pay, specify this field as the contract_id returned by WeChat. You need to submit it to EVO Cloud to complete the tokenization processing. |
Here is an example of HTTP PUT request for tokenization with WeChat Pay:
1.curl -X PUT https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_TOKENIZATION_REQUEST} \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
6.-H "Authorization: YOUR_MESSAGE_SIGNATURE"
7.-d '{
8. "paymentMethod": {
9. "e-wallet": {
10. "contractID": "YOUR_CONTRACT_ID"
11. }
12. }
13.}'A successful tokenization response contains a paymentMethod.token object to describe the token information, which contains:
paymentMethod.token.value: The token value generated by EVO Cloud.paymentMethod.token.userReference: The unique identifier of the user, same asuserInfo.referencein your POST request.paymentMethod.token.vaultID: The group ID which the token belongs to, same aspaymentMethod.e-wallet.vaultIDorpaymentMethod.card.vaultIDin your POST request.paymentMethod.token.expiryDate: The token expiration date and time, for example 2017-07-17T13:42:40+01:00. For card payment, it is generated according topaymentMethod.card.tokenValidDaysin your POST request. If you don't sendtokenValidDaysin your POST request, or specify it as 0, theexpiryDatewill NOT be presented in the response, meaning that the token is permanent valid. While for E-Wallet payment, it is decided by the user when signs the electronic contract with wallet operator.paymentMethod.token.fingerprint: The token's fingerprint, applied for card payment. It is a unique value mapping to the card number. You can use it as a reference to check if a card is tokenized in EVO Cloud.paymentMethod.token.status: The status of the token. For a valid token, the value of this field is enabled.paymentMethod.token.createTime: The date and time when the token is created, for example 2017-07-17T13:42:40+01:00.paymentMethod.token.updateTime: The date and time when the token is updated, for example 2017-07-17T13:42:40+01:00.
If this is a recurring transaction which needs saving credentials and the transaction is successful, you can receive paymentMethod.recurringReference in response. You will use it for recurring subsequent transactions.
A. For E-Wallet payment, the successful tokenization response also contains a paymentMethod.e-wallet object to describe the E-Wallet information related to the token, which contains:
paymentMethod.e-wallet.paymentBrand: The payment brand of the wallet that the user chooses to tokenize with, same aspaymentMethod.e-wallet.paymentBrandin your POST request.paymentMethod.e-wallet.planID: The WeChat auto debit contract template ID, applied when the user tokenizes with WeChat Pay in your WeChat mini-program, same aspaymentMethod.e-wallet.planIDin your POST request.paymentMethod.e-wallet.subOpenID: The user ID for a user in your WeChat mini-program, applied when the user tokenizes with WeChat Pay in your WeChat mini-program, same aspaymentMethod.e-wallet.planIDin your POST request.paymentMethod.e-wallet.contractID: Thecontract_idreturned by WeChat, applied when the user tokenizes with WeChat Pay in your WeChat mini-program, same aspaymentMethod.e-wallet.contractIDin your PUT request.
B. For card payment, the successful tokenization response also contains a paymentMethod.card object to describe the card information related to the token, which may contains:
paymentMethod.card.paymentBrand: The payment brand of the card that the user chooses to tokenize with, same aspaymentMethod.card.paymentBrandin your POST request.paymentMethod.card.first6No: The first 6 digits of the card number.paymentMethod.card.last4No: The last 4 digits of the card number.paymentMethod.card.holderName: The cardholder name.paymentMethod.card.fundingType: The type of the card. credit, debit or prepaid.paymentMethod.card.issuingBank: The name of issuing bank.paymentMethod.card.issuingCountry: The card issuing country.paymentMethod.card.issuerCountry: The cardholder's country.paymentMethod.card.isCommercial: Whether the card is a business card.
Here is an example of a successful tokenization response for WeChat Pay:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success",
5. "pspResponseCode": "200",
6. "pspMessage": "Processing succeeded"
7. },
8. "paymentMethod": {
9. "merchantTransInfo": {
10. "merchantTransID": "ddbe7e10206b497e84891968bdcd35ab",
11. "merchantTransTime": "2021-12-31T08:30:59+08:00"
12. },
13. "e-wallet": {
14. "paymentBrand": "WeChat_Pay",
15. "planID": "YOUR_PLAN_ID",
16. "contractID": "YOUR_CONTRACT_ID",
17. "subOpenID": "YOUR_SUB_OPEN_ID"
18. },
19. "token": {
20. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
21. "expiryDate": "2029-12-31T23:59:59+08:00",
22. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
23. "vaultID": "11111902_00001",
24. "createTime": "2021-12-31T00:30:59Z",
25. "updateTime": "2021-12-31T00:30:59Z",
26. "status": "enabled"
27. }
28. }
29.}Step 6: Retrieve the tokenization result
For E-Wallet payment, if you redirect the user to another website or APP, you can make a request to EVO Cloud to retrieve the tokenization result if you don't use the Accept Notification webhook.
From your server, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify the parameter below.
| Query parameter | Required | Description |
|---|---|---|
merchantTransID | M | The merchantTransInfo.merchantTransID of the initial tokenization request. |
The following example shows how you retrieve the tokenization result:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_TOKENIZATION_REQUEST} \
2.-H "Content-Type: application/json" \
3.-H "DateTime: 2021-12-31T08:30:59+0800" \
4.-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \
5.-H "SignType: SHA256" \
-H "Authorization: YOUR_MESSAGE_SIGNATURE"If the tokenization is successfully completed, the GET response is the same as the PUT response. See Step 5 for more details.
Step 7:Present tokenization result
After the user completes the tokenization and no further actions are required on the frontend or client APP, you can use the result.code and paymentMethod.status to inform the user of the tokenization status.
| Result code | Description |
|---|---|
| S0000 | Success |
| C0004 | Request resource merchantTransID {XXX} not exist |
| C0006 | Request resource vault ID {XXX} not exist |
| C0007 | Request resource userReference {XXX} not exist |
| C0008 | Request resource paymentMethod token {XXX} not exist |
| B0005 | Unsupported function {XXX}, please check your profile setup in EVO Cloud |
| B0006 | Unsupported payment brand {XXX}, please check your profile setup in EVO Cloud |
| B0009 | Unsupported card BIN {XXX}, please check your profile setup in EVO Cloud |
| B0012 | Invalid transaction status {XXX} to complete the request |
| B0015 | Cannot complete the request because token in the request is expired |
| B0019 | Authentication required, please ask user to input authentication info, please ask user to input authentication info |
| B0020 | Token update failed, please check your request message |
| B0021 | {Payment / Tokenization} failed due to user authentication results with high risk, please ask user to try again |
For other possible result.code values and recommended messages that you can present to user, see Appendix in EVO Cloud API Specification.
If the result.code is S0000, you need to check the paymentMethod.status to judge and inform your user the tokenization status.
| Status | Description |
|---|---|
| Success | Means the token is created |
| Failed | Means token creation is failed |
For other possible paymentMethod.status values and description, see paymentMethod.status in EVO Cloud API Specification.
Create a Network token when creating gateway token
When you create a gateway token while payment or create a gateway token standalone, meanwhile you can create a network token. You need to profile the “Network token Service” for your merchant on EVO Cloud portal first and initiate the create gateway token request as same as the introduction in chapter 4.2.1 or 4.2.2.
If the card brand is in below list and the issuer support network token tokenization, EVO Cloud will return networkToken object in the response message of Payment or PaymentMethod. | Card brand | Support network token | | --- | --- | | Visa | Yes | | Mastercard | Yes |
A successful network token tokenization response extra contains a paymentMethod.networkToken object to describe the networkToken information, which contains:
paymentMethod.networkToken.tokenID: The unique ID of the network token assigned by card scheme.paymentMethod.networkToken.status: The status of the network token. For a valid network token, the value of this field is enabled.paymentMethod.networkToken.supportDeviceBinding: The indicator of the network token support deviceBinding or not (The function is not yet open).
After above steps, you will get a gateway token associated with the network token. You can use this gateway token make a payment same as ordinary gateway token (See the chapter 4.3). EVO Cloud will intelligently decide whether to use network token or PAN to initiate authorization.
Meanwhile the 3D Secure 2 will also Applicable to this scenario.
FIDO Authentication for Network Token Creation
In addition to 3D Secure 2, when creating a gateway token and associating it with a network token, you can use FIDO for authentication.
If the card brand is in the list below and the issuer supports network token tokenization, EVO Cloud will support you in using FIDO to authenticate the user.
| Card brand | Support network token | Support FIDO Authentication |
|---|---|---|
| Visa | Yes | No |
| Mastercard | Yes | Yes |
You can find the details of FIDO authentication in chaptre FIDO authentication.
Error handling
For HTTP POST request to EVO Cloud: It is suggested to wait at least 45 seconds after the request is sent to EVO Cloud. If you don't receive the response within the time frame, you need to retrieve the result from EVO Cloud, follow Step 6 to initiate the request.
For HTTP PUT request to EVO Cloud: The HTTP PUT request is idempotent, meaning that if you don't get the response from EVO Cloud within a certain time frame, for example 45 seconds, you can resend the request with exactly the same request message. If you still fail to receive the response after several times of the request, you can initiate another tokenization request instead.
For HTTP GET request to EVO Cloud: The HTTP GET request is idempotent. You can initiate the request several times until get the result, and it is suggested to wait at least 45 seconds before you initiate the subsequent request. If you still fail to get the result after several times of the request, you can initiate another tokenization request instead.
