Payment
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.
Although we highly recommend using the below endpoint to ensure you always offer the most up-to-date payment method(s) list to your customer, the step is optional. You can also cache the API response and update it once a week.
From your server, you can make an HTTP GET request to EVO Cloud endpoint
/g2/v1/payment/mer/{sid}/paymentMethod
and specify either of the parameters below.
| Query parameter | Required | Description |
|---|---|---|
paymentBrand | O | The specific Payment Brand which you intend to provide to user. With this parameter, you will get the available payment method(s) and payment information for this specific Payment Brand in response. |
cardBIN | O | The specific card BIN which the user intends to use to pay. With this parameter, you will get the available payment method(s) and payment information for this specific card BIN in response. |
Currency | O | The specific currency which the user intends to use to pay. With this parameter, you will get the available payment method(s) and payment information for this specific currency in response. |
Tokenize | O | The Boolean filed. Used to indicate Inquiry the payment method which support tokenization. With the value true, you will get the payment method(s) and payment information which support tokenization. |
Only one parameter above is allowed to be used for each request. If multiple parameters are sent, the system will reply you with a priority of cardBIN, paymentBrand, and then currency.
If no query parameter is specified, you will get all the payment method(s) and payment information required to be collected based on your integration with EVO Cloud.
Here is an example of requesting the API without any query parameter:
1.curl 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"The response includes the list of available payment method(s) in a paymentBrandList array, containing below fields in each payment method.
- brandName: The brand name of the payment method.
- brandImage: The logo image of the payment method, a URL for you to get the logo to display on your payment page.
- paymentInfo: The payment information that required by the Card Scheme or E-Wallet to initiate the payment.
- authenticationInfo: The authentication information that required by the Card Scheme to initiate the user authentication.
- promotionInfo: The list of the promotion names supported by the payment method.
See EVO Cloud API Specification for more details.
Here is an example of the response:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethod": {
7. "paymentBrandList": [
8. {
9. "brandName": "Visa",
10. "brandImage": "https://VISA_LOGO_IMAGE_URL.com",
11. "type": "card",
12. "paymentInfo": [
13. {
14. "key": "Card Number",
15. "optional": false,
16. "type": "number",
17. "minLength": "12",
18. "maxLength": "19"
19. },
20. {
21. "key": "Expiry date",
22. "optional": false,
23. "type": "number",
24. "minLength": "4",
25. "maxLength": "4",
26. "defaultValue": "MMYY",
27. "regEx": "/^(0[1-9]|1[0-2]){2}$/"
28. },
29. {
30. "key": "CVC",
31. "optional": true,
32. "type": "number",
33. "minLength": "3",
34. "maxLength": "4"
35. },
36. {
37. "key": "Cardholder Name",
38. "optional": true,
39. "type": "string",
40. "maxLength": "50"
41. }
42. ],
43. "authenticationInfo": [
44. {
45. "key": "Card Number",
46. "optional": false,
47. "type": "number",
48. "minLength": "12",
49. "maxLength": "19"
50. },
51. {
52. "key": "Cardholder Name",
53. "optional": true,
54. "type": "string",
55. "maxLength": "50"
56. },
57. {
58. "key": "Cardholder Email",
59. "optional": true,
60. "type": "string",
61. "maxLength": "254",
62. "regEx": "/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/"
63. },
64. {
65. "key": "Billing Address",
66. "optional": true,
67. "type": "Object"
68. },
69. {
70. "key": "Billing Address",
71. "subKey": "Country",
72. "optional": false,
73. "type": "string"
74. },
75. {
76. "key": "Billing Address",
77. "subKey": "State Or Province",
78. "optional": true,
79. "type": "string"
80. },
81. {
82. "key": "Billing Address",
83. "subKey": "City",
84. "optional": false,
85. "type": "string",
86. "maxLength": "50"
87. },
88. {
89. "key": "Billing Address",
90. "subKey": "addressLine1",
91. "optional": true,
92. "type": "string",
93. "maxLength": "50"
94. },
95. {
96. "key": "Billing Address",
97. "subKey": "addressLine2",
98. "optional": true,
99. "type": "string",
100. "maxLength": "50"
101. },
102. {
103. "key": "Billing Address",
104. "subKey": "addressLine3",
105. "optional": true,
106. "type": "string",
107. "maxLength": "50"
108. },
109. {
110. "key": "Billing Address",
111. "subKey": "Postal Code",
112. "optional": false,
113. "type": "string"
114. },
115. {
116. "key": "Delivery Address",
117. "optional": true,
118. "type": "Object"
119. },
120. {
121. "key": "Delivery Address",
122. "subKey": "Country",
123. "optional": false,
124. "type": "string"
125. },
126. {
127. "key": "Delivery Address",
128. "subKey": "State Or Province",
129. "optional": true,
130. "type": "string"
131. },
132. {
133. "key": "Delivery Address",
134. "subKey": "City",
135. "optional": false,
136. "type": "string",
137. "maxLength": "50"
138. },
139. {
140. "key": "Delivery Address",
141. "subKey": "addressLine1",
142. "optional": true,
143. "type": "string",
144. "maxLength": "50"
145. },
146. {
147. "key": "Delivery Address",
148. "subKey": "addressLine2",
149. "optional": true,
150. "type": "string",
151. "maxLength": "50"
152. },
153. {
154. "key": "Delivery Address",
155. "subKey": "addressLine2",
156. "optional": true,
157. "type": "string",
158. "maxLength": "50"
159. },
160. {
161. "key": "Delivery Address",
162. "subKey": "Postal Code",
163. "optional": false,
164. "type": "string"
165. }
166. ]
167. },
168. {
169. "brandName": "Alipay",
170. "type": "e-wallet",
171. "brandImage": "https://ALIPAY_LOGO_IMAGE_URL.com"
172. },
173. {
174. "brandName": "AlipayHK",
175. "type": "e-wallet",
176. "brandImage": "https://ALIPAYHK_LOGO_IMAGE_URL.com"
177. },
178. {
179. "brandName": "Alipay+",
180. "type": "e-wallet",
181. "brandImage": "https://ALIPAYPLUS_LOGO_IMAGE_URL.com",
182. "promotionInfo": [
183. "en_US":"RM1 Voucher",
184. "zh_CN":"1元 红包"
185. ]
186. },
187. ]
188. }
189.}If you want to guide your user to pay on your frontend page or client APP, you can use paymentMethod.paymentBrandList.paymentInfo to provide the list of payment methods and the required payment information for each payment method.
If you want to guide your user to conduct a payment authentication, you can use paymentMethod.paymentBrandList.authenticationInfo. See chapter Authentication for more details.
You can add additional tips or format check by your own if needed.
Please note that for the following fields, after you collect it from the user, before you send them to EVO Cloud, you need to ensure your request follows the ISO specification. See EVO Cloud API Specification for more details.
| Key name in paymentBrandList | Field name in EVO Cloud API | ISO specification |
|---|---|---|
| Country (in Delivery Address) | userInfo.deliveryAddress.country | ISO-3166-1 alpha-3. For example, SGP. |
| State or Province(in Delivery Address) | userInfo.deliveryAddress.stateOrProvince | ISO-3166-2. For example, North East. |
| Country (in Billing Address) | userInfo.billingAddress.country | ISO-3166-1 alpha-3. For example, SGP. |
| State or Province(in Billing Address) | userInfo.billingAddress.stateOrProvince | ISO-3166-2. For example, North East. |
Step 2: Collect user's payment information
Collect your user's payment information based in the fields required by each payment method, then send them to your host. Please note that if the user selects to pay with a card, the merchant must obtain the PCI DSS compliance. You have 2 ways to collect card details:
- Use EVO Cloud client-side solution to securely encrypt your user's card details. This option ensures you meet the PCI DSS compliance, as you're only required to submit PCI DSS Self-Assessment Questionnaire A (SAQ A). See EVO Cloud SDK Integration Guide for more details.
- Collect and send raw card data. This option requires you to assess your PCI DSS compliance according to PCI DSS Self-Assessment Questionnaire D (SAQ D), the most extensive form of self-certification.
Step 3: Make a payment
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}/payment
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. |
transAmount | M | The currency and value of the payment. The value must follow the currency's minor unit. |
paymentMethod | M | Use paymentMethod.type to specify different payment method type, such as e-wallet or card payment, with different payment information that you collect in the previous step. |
transInitiator | M | The information of device to initiate the transaction. |
storeInfo | O | 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. |
tradeInfo | O | This field is required when paymentMethod.e-wallet.paymentBrand is Alipay to indicate the detailed information about this payment. |
userInfo | O | Detailed information about the buyer. Specify this parameter if you can obtain the information from the user. This helps EVO Cloud laundering and fraud detection, and increases payment success rates. |
validTime | O | This is applied when paymentMethod.type is e-wallet to indicate the effective time (minutes) of the order. The payment can only be executed before the time. If you have any special requirements for this value definition, please contact EVO Cloud account manager for details and suggestion. |
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 payment 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 the paymentMethod object:
A. When the user chooses to pay with E-Wallet:
paymentMethod.type: Set as e-wallet in your request.paymentMethod.e-wallet.paymentBrand: The Payment Brand of the e-wallet that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.paymentMethod.e-wallet.subOpenID: The user ID for the user in your WeChat mini-program, required when the user pays with WeChat Pay (paymentMethod.e-wallet.paymentBrandis WeChat_Pay) in your WeChat mini-program (transInitiator.platformis MINI). Get this ID when the user logins your WeChat mini-program.paymentMethod.e-wallet.subAppID: The APP ID assigned by WeChat, required when the user pays with WeChat Pay (paymentMethod.e-wallet.paymentBrandis WeChat_Pay) in your WeChat mini-program (transInitiator.platformis MINI) or your client APP (transInitiator.platformis APP). Get this ID when you register your mini-program or APP to WeChat.paymentMethod.e-wallet.mobilePhone: The user's mobile number registered in E-wallet, required when the user pays with TrueMoney wallet.
B. When the user chooses to pay with card:
paymentMethod.type: Set as card in 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 your host needs to forward the original data 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 the cardNumber, expiryDate, and cvc (optional) and holderName in this object. For some of the UnionPay debit cards, the expiryDate is also optional.
(If bothpaymentMethod.card.encryptedCardInfoandpaymentMethod.card.cardInfoare present,paymentMethod.card.cardInfowill be applied.)
C. When the user chooses to pay with UnionPay SecurePay:
paymentMethod.type: Set as onlineBanking in your request.paymentMethod.onlineBanking.paymentBrand: The Payment Brand of the payment method, required. Set as UnionPay in your request.paymentMethod.onlineBanking.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 your host needs to forward the original data to EVO Cloud.paymentMethod.onlineBanking.cardInfo: The raw data of the card information. If you collect and send raw card data to EVO Cloud, it is optional to specify the cardNumber in this object.
(If bothpaymentMethod.onlineBanking.encryptedCardInfoandpaymentMethod.onlineBanking.cardInfoare present,paymentMethod.onlineBanking.cardInfowill be applied.)
D. When the user chooses to pay with Online Banking:
paymentMethod.type: Set as onlineBanking in your request.paymentMethod.onlineBanking.paymentBrand: The Payment Brand of the online banking that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.
E. When the user chooses to pay with Points:
paymentMethod.type: Set as points in your request.paymentMethod.points.paymentBrand: The Payment Brand of the points payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.
F. When the user chooses to pay with Bank Transfer:
paymentMethod.type: Set as bankTransfer in your request.paymentMethod.bankTransfer.paymentBrand: The Payment Brand of the bank transfer payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.paymentMethod.bankTransfer.name: This field indicates the given name and family name of the user. You need to specify the givenName and familyName in this object when the paymentBrand is Bank_Transfer_JPN or PayEasy. See the details of this object in EVO Cloud API Specification.paymentMethod.bankTransfer.mobilePhone: The user's mobile number. This field must be sent when the paymentBrand is Bank_Transfer_JPN or PayEasy.
G. When the user chooses to pay with Buy Now Pay Later:
paymentMethod.type: Set as buyNowPayLater in your request.paymentMethod.buyNowPayLater.paymentBrand: The Payment Brand of the buy now pay later payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.userInfo.name: The user’s name. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressCity: The name of the city that users live in. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressLine1: The building name and apartment number that the user lives in. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressLine2: The district, land number, and land number extension that users live in. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressState: The name of the state or prefecture that users live in. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressPostalCode: The postal code that the user's address belongs to. This field must be sent when the paymentBrand is Paidy.userInfo.shippingAddressCountry: The name of the country that users live in. This field must be sent when the paymentBrand is Paidy.
H. When the user chooses to pay with Carrier Billing:
paymentMethod.type: Set as carrierBilling in your request.paymentMethod.carrierBilling.paymentBrand: The Payment Brand of the carrier billing payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.
I. When the user chooses to pay with Prepaid Card:
paymentMethod.type: Set as prepaidCard in your request.paymentMethod.prepaidCard.paymentBrand: The Payment Brand of the prepaid card payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.paymentMethod.prepaidCard.prepaidNumber: Prepaid card number. This field must be sent when prepaid card payment.
J. When the user chooses to pay with Cash:
paymentMethod.type: Set as cash in your request.paymentMethod.cash.paymentBrand: The Payment Brand of the cash payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.
K. When the user chooses to pay with Google Pay™️:
paymentMethod.type: Set as googlePay in your request.paymentMethod.googlePay.paymentBrand: The Payment Brand of the Google Pay™️ payment that the user chooses to pay with, required. See the full list of all the payment brands in EVO Cloud API Specification.
You need to include additional parameters in your payment if you request to:
- Tokenize the user's payment information. See chapter Tokenization for more details.
- Authenticate the user with 3D Secure or SecurePlus. See chapter Authentication for more details.
- Place a hold to reserve funds and capture it later. See chapter After Payment for more details.
Here is an example of using Alipay to make a 10 USD payment:
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": "e05b93cc849046a6b570ba144c328c7f",
10. "merchantTransTime": "2021-12-31T08:30:59+08:00"
},
12. "transAmount": {
13. "currency": "USD",
14. "value": "10.00"
15. },
16. "validTime": "120",
17. "returnURL": "https://YOUR_COMPANY.com/RETURNURL",
18. "paymentMethod": {
19. "type": "e-wallet",
20. "e-wallet": {
21. "paymentBrand": "Alipay"
22. }
23. },
24. "transInitiator": {
25. "platform": "WEB"
26. },
27. "tradeInfo": {
28. "tradeType": "Sale of goods",
29. "goodsName": "iPhone 13",
30. "goodsDescription": "This is an iPhone 13",
31. "totalQuantity": "2"
32. },
33. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
34. "metadata": "This is a metadata"
35.}'If you don't receive an action object in the response, you can go to Step 7 to use the result.code and payment.status to present the payment result to your user.
Otherwise, additional steps are required to complete the payment. You need to send the action object to your frontend page or client APP, then proceed to the next step.
Here is an example of receiving a response with an action object requiring a redirection:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success",
5. "pspResponseCode": "PAYMENT_IN_PROCESS",
6. "pspMessage": "Payment is processing."
7. },
8. "action": {
9. "type": "redirectUser",
10. "redirectData": {
11. "url": "https://ALIPAY_REDIRECT_URL.com",
12. "method": "GET"
13. }
14. },
15. "paymentMethod": {
16. "e-wallet": {
17. "paymentBrand": "Alipay"
18. }
19. },
20. "payment": {
21. "status": "Pending",
22. "merchantTransInfo": {
23. "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
24. "merchantTransTime": "2021-12-31T08:30:59+08:00"
25. },
26. "evoTransInfo": {
27. "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
28. "evoTransTime": "2021-12-31T00:30:59Z"
29. },
30. "pspTransInfo": {
31. "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
32. "pspTransTime": "2021-12-31T08:30:59+08:00"
33. },
34. "transAmount": {
35. "currency": "USD",
36. "value": "10.00"
37. }
38. },
39. "pspData": {
40. "name": "Alipay"
41. },
42. "metadata": "This is a metadata"
43.}Step 4: Perform additional actions
If your server receives an action object in the payment response (/g2/v1/payment/mer/{sid}/payment), you need to follow the action.type to conduct the next step.
| 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 payment and authentication when redirection is required. The following payment methods and Payment Brands are applied: (a) Alipay, Alipay+ and JkoPay on PC WEB. (b) Alipay, Alipay+, Alipay HK, WeChat Pay and Jkopay on Mobile WAP. (c) WeChat Pay in WeChat official account. (d) UnionPay SecurePay on PC WEB and Mobile WAP. | 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, depending on the PSP. After the user completes the payment, the user is redirected back to your returnURL with an HTTP GET or POST. You can ignore this redirection, or optionally display a loading page to the user before you get the payment result. 1. You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/payment to get the payment result. See Step 6 result for more details. 2. Or you can wait for the notification webhook to know the payment result. See chapter After Payment for more details. |
redirectInIframe | This is applied to E-Wallet payment on PC WEB with AlipayHK merchant account, including user paying with AlipayHK wallet APP and Alipay wallet APP. | Render an iframe on your payment page and perform a redirection in the iframe 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) within the parameter object as the form data of the POST request. The user is then prompted with a QR code in the iframe which the user needs to scan and pay with the E-Wallet APP. 1. You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/payment to get the payment result. See Step 6 for more details. 2. Or you can wait for the notification webhook to know the payment result. See chapter After Payment for more details. |
presentQRCode | This is applied to E-Wallet payment on PC WEB using WeChat Pay. | Render the QR code with the data specified by action.qrData object. The user is then prompted with a QR code which the user needs to scan and pay with the E-Wallet APP. 1. You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/payment to get the payment result. See Step 6 for more details. 2. Or you can wait for the notification webhook to know the payment result. See chapter After Payment for more details. |
invokeWallet | This is applied to: (a) E-Wallet payment in wallet APP and mini-program using WeChat Pay or Alipay. (b) SecurePay of UnionPay in wallet APP. | 1. Invoke the wallet SDK with action.walletData.paymentString to trigger the switch to the wallet APP. See WeChat Pay In-APP pay integration guide or Alipay APP payment integration guide or UnionPay In-APP integration guide. Or you can choose EVO Cloud SDK to realize the same function. See EVO Cloud SDK Integration Guide for more details. The user is then switched to wallet APP where the user needs to take additional action to complete the payment. 2. After the user completes the payment, the user will be redirected back by the callback function you specify when invoking the SDK. You can optionally display a loading page to the user before you get the payment result. 3. You can optionally make an HTTP GET request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/payment to get the payment result. See Step 6 for more details. 4. Or you can wait for the notification webhook to know the payment result. See chapter After Payment for more details. |
presentEcontext | This is applied to cash payment and bank transfer. | Present the texts in the object action.econtext on your payment page to ask the user to complete the follow-up payment process. If the field action.econtext.instructionURL is returned you can also present it on your payment page to guide user. |
Here are more details on the frontend action you need to perform when handling redirectUser, redirectInIframe, presentQRCode and invokeWallet.
A. redirectUser
If action.redirectData.method is GET, redirect the user to the action.redirectData.url.
curl {action.redirectData.url}
If action.redirectData.method is POST and action.redirectData.parameter exists, for example, if the user is performing the payment with SecurePay for UnionPay on PC WEB or Mobile WAP, here is an example of action.redirectData.parameter:
{
"accNo": "ZgTg0d4%2BWJeM7GBq9EbxjSu0wvQQYpS8%2F%2B9NJ848bx1tLlqWc%2FbtUSzFiMaKaFHNEJMT3PPvv8RY8C9lcOeoWJpFBUA4en%2FSw2OlqY%2Fmj1zcikLMg5O4XgO8aqELQUDZNin1mtlkDGx1%2B%2FR9NNX4a%2F2E8x2%2Fme4haxUdO%2BVY76v7edaj30pR2n%2BbLfB70pDnc9XisZrL5cNPE9Wj83Mirh2rLwEtreS%2FktCYqzpopLEcu115sd%2BJOdj1E0z3Bp2x5EBLrdiz714kOV0FmY7HQz0UfwV3MnY7PofuQ7MwnilYYnTsFBcTKxNpSwAZlZAB0eSijnFpIG3tYjnIephVFg%3D%3D",
"accessType": "1",
"acqInsCode": "YOUR_ACQUIRER_IIN",
"backUrl": "https%3A%2F%2F%7BEVO_Cloud_DOMAIN_NAME.com%7D%2FpspNotify%2FUPI%2F%7BYOUR_ACQUIRER_IIN%7D",
"bizType": "000201",
"certId": "69798631478",
"channelType": "07",
"currencyCode": "840",
"encoding": "UTF-8",
"encryptCertId": "69026275926",
"frontUrl": "https%3A%2F%2FYOUR_COMPANY.com%2FRETURNURL",
"merAbbr": "AbbrName",
"merCatCode": "5411",
"merId": "999290058120001",
"merName": "This is your merchant name",
"orderId": "YOUR_TRANS_ID",
"payTimeout": "20211231183059",
"signMethod": "01",
"signature": "EashQx%2F4eLvGenbKThFNeqssyg6tSXlj5mT3GbF2ll9TV8ObzqYpMd%2Fl2Ymv0UKkWOi05QeRM9c2UajjzAM92CUGp8KhVkfcK4BUH1BXNgAWAEZwB8ZLLuMPvnTQZJ%2F03HQ6hOeyIXOCE1lOm4HlL9n5B5bg2ACRFpxK%2FmGVPZ%2FuGumAMyEWq5%2B8HwRlcTBepzDYNuSqCLegofT7bTAQZIELf%2BjxKSgV3D3cCI9PwOg44uFlRwSdtg%2Fr0FnIh%2BhQTVDgY0ttJm99GWYwJIKzdsEdN9tihpgxJVoxveoJBwll2M6mrv7THXMFvI3p3zFCpLIjU%2FxqvvUQmViYC3lniA%3D%3D",
"txnAmt": "1000",
"txnSubType": "01",
"txnTime": "20211231083059",
"txnType": "01",
"version": "5.1.0"
}B. redirectInIframe
This is similar to processing the redirectUser action, but you need to initiate the HTTP GET or POST request within the iframe rendered on your payment page. It is suggested to set the iframe size to 200x200 px.
C. presentQRCode
Render the QR code with the data specified by the action.qrData object and prompt it to your user. The details of action.qrData include:
- action.qrData.qrCode: The contents of the QR code, a UTF-8 string. Use this to render the QR code.
- action.qrData.qrDownloadURL: The download URL of the QR code. This field will be returned when
action.qrData.qrCodeis not returned. - action.qrData.expiredAt: The date and time when the payment expires. For example:
2017-07-17T13:42:40+01:00.
D. invokeWallet
If you choose to use the wallet SDK, refer to the wallet SDK guides for more details on how to invoke the SDKs.
If you use the EVO Cloud SDK, see the EVO Cloud SDK Integration Guide. You can contact your EVO Cloud account manager to obtain these guides.
Step 5: Submit the additional payment information
When the payment method is the card, if the user performs the authentication flow, you need to submit the additional payment details to EVO Cloud to complete the payment. See chapter Authentication for more details.
Step 6: Retrieve the payment result
When the payment method is the E-Wallet, if you redirect the user to another website or APP, or if you present the QR code for the user to scan and pay, you can make a request to EVO Cloud to retrieve the payment 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}/payment
and specify the parameter below.
| Parameter | Required | Description |
|---|---|---|
| merchantTransID | M | The merchantTransInfo.merchantTransID of the requesting payment. |
Example of Retrieving the Payment Result
1.curl https://{EVO_Cloud_DOMAIN_NAME.com}/g2/v1/payment/mer/{sid}/payment?merchantTransID={YOUR_TRANS_ID_OF_INITIAL_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"If you receive an action object in the response, similar with Step 3, additional steps are required to complete the payment. You need to send the action object to your frontend page or client APP, then proceed to the next step. Back to Step 4 to perform the required action.
If not, you can go to Step 7 to use the result.code and payment.status to present the payment result to your user.
If the payment is completed, you will get a payment object in the response to show the details of this payment:
payment.status: The status of this capture, required, can be Verifying, Verified, Pending, Authorised, Cancelling, Cancelled, Capturing, Captured, Refunding, Refunded, Partial Refunded or Failed. See EVO Cloud API Specification for more details.payment.failureCode: The error code for the payment, which will be returned when the payment.status is Failed.payment.failureReason: The error message for the payment, which will be returned when the payment.status is Failed.payment.transAmount: The currency and value of the payment, required. It is echoed back from your request.payment.merchantTransInfo: The object that is a reference for the payment, required and generated by your host. It is echoed back from your request.payment.evoTransInfo: The object that is a reference for the payment, required and generated by EVO Cloud. It contains evoTransID, evoTransTime and traceNum (optional) and retrievalReferenceNum for some PSPs such as Visa or Mastercard.payment.pspTransInfo: The object that is a reference for the capture, optional and generated by the PSP. It contains pspTransID, pspTransTime and authorizationCode. EVO Cloud forwards this information from PSP to your host if PSP returns.payment.billingAmountandpayment.billingFXRate: The user's billing currency and value of the payment, and the FX rate between payment.transAmount.currency and payment.billingAmount.currency, if has. EVO Cloud forwards this information from PSP to your host if PSP returns. This is applied to some E-Wallet payment scenarios when PSP conducts the currency conversion, or to some card payment scenarios when you enable the DCC feature. You can contact EVO Cloud account manager for more details.payment.convertTransAmountandpayment.convertTransFXRate: The currency and value calculated by EVO Cloud based on transAmount and the FX rate from transAmount.currency to a different currency when the transaction is sent out to PSP, and the FX rate between payment.transAmount.currency and payment.convertTransAmount.currency. The FX rate will be provided if you enable currency conversion feature in EVO Cloud and this capture applies currency conversion. You can contact EVO Cloud account manager for more details.
Here is an example of a successful payment response:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success",
5. "pspResponseCode": "SUCCESS",
6. "pspMessage": "success"
7. },
8. "paymentMethod": {
9. "e-wallet": {
10. "paymentBrand": "Alipay"
11. }
12. },
13. "payment": {
14. "status": "Captured",
15. "merchantTransInfo": {
16. "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
17. "merchantTransTime": "2021-12-31T08:30:59+08:00"
18. },
19. "evoTransInfo": {
20. "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
21. "evoTransTime": "2021-12-31T00:30:59Z"
22. },
23. "pspTransInfo": {
24. "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
25. "pspTransTime": "2021-12-31T08:30:59+08:00"
26. },
27. "transAmount": {
28. "currency": "USD",
29. "value": "10.00"
30. }
31. },
32. "pspData": {
33. "name": "Alipay"
34. },
35. "metadata": "This is a metadata"
36.}Step 7: Present the payment result
After the user completes the payment and no further actions are required on the frontend or client APP, you can use the result.code and payment.status to inform the user of the payment status.
| Result Code | Description |
|---|---|
S0000 | Success |
V0008 | Field {} is not applied with |
C0004 | Request resource merchantTransID {XXX} not exist |
C0006 | Request resource vault ID {XXX} not exist |
C0008 | Request resource paymentMethod token {XXX} not exist |
B0005 | Unsupported function {XXX}, please check your profile setup in EVO Cloud |
B0012 | Invalid transaction status {XXX} to complete the request |
B0019 | Authentication required, please ask user to input authentication info |
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 your user, see Appendix in EVO Cloud API Specification.
If the result.code is S0000, you need to check the payment.status to judge and inform your user the payment status.
| Status | Description |
|---|---|
| Authorised | Used for card transaction, means the transaction authorization is successfully completed and pending for Capture (merchant can submit cancel). |
| Captured | If card transaction, means transaction authorization and capture are successfully completed; If e-wallet transaction, means transaction is successfully completed. |
| Failed | Payment failed. |
For other possible payment.status values and description, see payment.status in EVO Cloud API Specification.
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 GET request to EVO Cloud: You can initiate the request several times until you get the result, and it is suggested to wait at least 45 seconds before you initiate the subsequent request. If you still fail to receive the result after several times of the request, you can initiate a Cancel or Refund request (based on your capture mode) to cancel the payment. See chapter After Payment for more details.
