Manage token
The user may need to update the payment method(s) stored or remove a previously stored payment method. You can retrieve a particular user's stored payment method(s) and complete the user's request.
Retrieve gateway token
To see the gateway token(s) stored for a user, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify either parameter below.
| Query Parameter | Required | Description |
|---|---|---|
userReference | O | The reference for the user. With this parameter specified, you can retrieve all the payment method(s) stored for the user. |
token | O | The token value for a specific stored payment method. With this parameter specified, you can retrieve the specific payment method stored with this token value. |
If both parameters are specified, the parameter userReference will be ignored.
Here is an example of retrieving all the payment method(s) stored for a specific user:
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?userReference={YOUR_USER_REFERENCE} \
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"The paymentMethodList array in the response contains the user's stored payment method(s).
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethodList": [
7. {
8. "token": {
9. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
10. "expiryDate": "2029-12-31T23:59:59+08:00",
11. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
12. "vaultID": "11111902_00001",
13. "createTime": "2021-12-31T00:30:59Z",
14. "updateTime": "2021-12-31T00:30:59Z",
15. "status": "enabled"
16. },
17. "e-wallet": {
18. "paymentBrand": "Alipay"
19. }
20. },
21. {
22. "token": {
23. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
24. "expiryDate": "2029-12-31T23:59:59+08:00",
25. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
26. "vaultID": "11111902_00001",
27. "fingerprint": "286fcea14de3eaf021f0304ca34d3f4c",
28. "createTime": "2021-12-31T00:30:59Z",
29. "updateTime": "2021-12-31T00:30:59Z",
30. "status": "enabled"
31. },
32. "card": {
33. "first6No": "476134",
34. "last4No": "0019",
35. "fundingType": "credit",
36. "paymentBrand": "Visa"
37. }
38. }
39. ]
40.}Update gateway token
For card payment, the user can request to change the stored payment method(s). The details associated with a gateway token are card number, expiry date (month and year of the card), and the cardholder name (optional). You can update the expiryDate and holderName of a card, and the userReference, vaultID, and tokenValidDays of the token. The gateway token value remains the same when you update these details. If the user updates with a new card number, you need to store it as a new gateway token.
For tokens of E-Wallet payment, including WeChat Pay and Alipay, only userReference and vaultID can be updated.
To update the token details, 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 |
|---|---|---|
| token | M | The token value for the stored payment method to be updated. |
| Body Parameter | Required | Description |
|---|---|---|
paymentMethod | M | - For E-Wallet updates: Specify paymentMethod.type as e-wallet with userInfo.reference and/or paymentMethod.e-wallet.vaultID that you are going to update.- For Card updates: Specify paymentMethod.type as card with paymentMethod.card.cardInfo.expiryDate, paymentMethod.card.cardInfo.holderName, userInfo.reference, paymentMethod.card.vaultID, and/or paymentMethod.card.tokenValidDays that you are going to update. For tokenValidDays, specify 0 to set the token as permanently valid, or 1-365 to extend the valid time by 1-365 days from the request date. |
metadata | O | A self-defined reference information that you can specify in the request and will be echoed back in the response. |
Here is an example:
1.curl -X PUT https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?token={YOUR_TOKEN_VALUE_TO_BE_UPDATED}\
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. "type": "e-wallet",
10. "e-wallet": {
11. "vaultID": "11111902_00002"
12. }
13. },
14. "userInfo": {
15. "reference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
16. },
17. "metadata": "This is a metadata"
18.}'Here is an example of the response with the paymentMethod object to show the updated token information:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethod": {
7. "token": {
8. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
9. "expiryDate": "2029-12-31T23:59:59+08:00",
10. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b25",
11. "vaultID": "11111902_00002",
12. "createTime": "2021-12-31T00:30:59Z",
13. "updateTime": "2021-12-31T06:30:59Z",
14. "status": "enabled"
15. },
16. "e-wallet": {
17. "paymentBrand": "WeChat_Pay",
18. "planID": "YOUR_PLAN_ID",
19. "contractID": "YOUR_CONTRACT_ID",
20. "subOpenID": "YOUR_SUB_OPEN_ID"
21. }
22. },
23. "metadata": "This is a metadata"
24.}Remove gateway token
A user may request to delete a certain stored payment method or remove their account on your platform. To delete the token(s) of a user's stored payment method(s), make an HTTP DELETE request to the EVO Cloud endpoint:
/g2/v1/payment/mer/{sid}/paymentMethod
and specify the parameters below.
| Query Parameter | Required | Description |
|---|---|---|
userReference | O | The reference for the user. With this parameter specified, you can disable all payment method(s) stored for the specific user. |
token | O | The token value for a specific stored payment method. With this parameter specified, you can disable the specific payment method stored with this token value. |
| Body Parameter | Required | Description |
|---|---|---|
metadata | O | A self-defined reference information that you can specify in the request and will be echoed back in the response. |
initiatingReason | O | You can state the reason for the request in this field, which is required when the user is trying to delete the token for WeChat Pay. |
You can specify either of the query parameters above, and if both specified, the userReference will be ignored.
Here is an example of disabling all the payment method(s) stored for a specific user:
1.curl -X DELETE https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/paymentMethod?userReference={YOUR_USER_REFERENCE} \
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. "initiatingReason": "User logged out"
9.}'Here is an example of the response with the paymentMethodList array to show the deleted token information.
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethodList": [
7. {
8. "token": {
9. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
10. "expiryDate": "2029-12-31T23:59:59+08:00",
11. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
12. "vaultID": "11111902_00001",
13. "createTime": "2021-12-31T00:30:59Z",
14. "updateTime": "2021-12-31T00:30:59Z",
15. "status": "enabled"
16. },
17. "e-wallet": {
18. "paymentBrand": "Alipay"
19. }
20. },
21. {
22. "token": {
23. "value": "pmt_9ab5560fb00c2fe9a56606593a8af294",
24. "expiryDate": "2029-12-31T23:59:59+08:00",
25. "userReference": "u89kxwycn61ejz5v0rmaqd7pilof3b24",
26. "vaultID": "11111902_00001",
27. "fingerprint": "286fcea14de3eaf021f0304ca34d3f4c",
28. "createTime": "2021-12-31T00:30:59Z",
29. "updateTime": "2021-12-31T00:30:59Z",
30. "status": "enabled"
31. },
32. "card": {
33. "first6No": "476134",
34. "last4No": "0019",
35. "fundingType": "credit",
36. "paymentBrand": "Visa"
37. }
38. }
39. ]
40.}Remove Network Token
When you delete the gateway token, the associated network token under the gateway token will also be deleted.
Error Handling
For HTTP PUT/GET/DELETE requests to EVO Cloud:
- The HTTP PUT/GET/DELETE request is idempotent, meaning that if you don't receive a response from EVO Cloud within a certain time frame (e.g., 45 seconds), you can resend the request with exactly the same message.
- If you still do not receive a response after several attempts, please contact your EVO Cloud account manager for assistance.
