CPM
Step 1: Get available payment method(s)
When a cashier is ready to collect payment on terminal, get a list of the available payment method(s).
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. |
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. |
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 ofpaymentBrand, 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.
- paymentScenario: The supported scenario of the payment method.
- 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.1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success"
5. },
6. "paymentMethod": {
7. "paymentBrandList": [
8. {
9. "brandName": "Alipay",
10. "brandImage": "https://Alipay_LOGO_IMAGE_URL.com",
11. "type": "e-wallet",
12. "paymentScenario": ["EC","inStore"],
13. },
14. {
15. "brandName": "AlipayHK",
16. "type": "e-wallet",
17. "paymentScenario": ["EC","inStore"],
18. "brandImage": "https://ALIPAYHK_LOGO_IMAGE_URL.com"
19. },
20. {
21. "brandName": "Alipay+",
22. "type": "e-wallet",
23. "paymentScenario": ["EC"],
24. "brandImage": "https://ALIPAYPLUS_LOGO_IMAGE_URL.com",
25. "promotionInfo": [
26. "en_US":"RM1 Voucher",
27. "zh_CN":"1元 红包"
28. ]
29. },
30. ]
31. }
32.}If you want to display the payment methods’ logo on your terminal, you can use paymentMethod.paymentBrandList.brandImage.
Step 2: Collect user's payment code
In CPM scenario, you need to collect your user's raw data of payment code by scan the payment code that display on user’s phone.
Step 3: Make a payment
After getting the raw data of payment code, 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. |
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 raw data of the user’s payment code. 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. "paymentMethod": {
17. "type": "e-wallet",
18. "e-wallet": {
19. "paymentCode": "280000000000000000"
20. }
21. },
22. "transInitiator": {
23. "platform": "POS",
24. "paymentScenario": "inStore",
25. "inStorePaymentScenario": "CPM",
26. "terminalID": "00001"
27. },
28. "tradeInfo": {
29. "tradeType": "Sale of goods",
30. "goodsName": "iPhone 13",
31. "goodsDescription": "This is an iPhone 13",
32. "totalQuantity": "2"
33. },
34. "webhook": "https://YOUR_COMPANY.com/WEBHOOK",
35. "metadata": "This is a metadata"
36.}'If you don't receive an action object in the response, you can go to Step 5 to use the result.code and payment.status to present the payment result to your user.
Sometimes, CPM transaction needs user to confirm the pay in their wallet APP through password, fingerprint or Face ID etc. So, you need to prompt user comfirm the payment and retrieve payment result from EVO Cloud.
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": "promptUser",
10. "promptInfo": {
11. "message": "Prompt user enter the password"
12. }
13. "paymentMethod": {
14. "e-wallet": {
15. "paymentBrand": "Alipay"
16. }
17. },
18. "payment": {
19. "status": "Pending",
20. "merchantTransInfo": {
21. "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
22. "merchantTransTime": "2021-12-31T08:30:59+08:00"
23. },
24. "evoTransInfo": {
25. "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
26. "evoTransTime": "2021-12-31T00:30:59Z"
27. },
28. "pspTransInfo": {
29. "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",
30. "pspTransTime": "2021-12-31T08:30:59+08:00"
31. },
32. "transAmount": {
33. "currency": "USD",
34. "value": "10.00"
35. }
36. },
37. "pspData": {
38. "name": "Alipay"
39. },
40. "metadata": "This is a metadata"
}Step 4: Retrieve the payment result
When the payment.status = Pending, 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.
| Query parameter | Required | Description |
|---|---|---|
| merchantTransID | M | The merchantTransInfo.merchantTransID of the requesting payment. |
Here is an 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 a result object in the response, you can go to Step 5 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 and paymentMethod object in the response to show the details of this payment:
payment.status: The status of this capture, required, can be Pending, Cancelling, Cancelled, 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 thepayment.statusis Failed.payment.failureReason: The error message for the payment, which will be returned when thepayment.statusis 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 containsevoTransID,evoTransTime, andtraceNum(optional) andretrievalReferenceNumfor 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 containspspTransID,pspTransTime, andauthorizationCode. 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 betweenpayment.transAmount.currencyandpayment.billingAmount.currency, if applicable. 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 currency conversion, or to some card payment scenarios when you enable the DCC feature. You can contact the EVO Cloud account manager for more details.payment.convertTransAmountandpayment.convertTransFXRate: The currency and value calculated by EVO Cloud based ontransAmountand the FX rate fromtransAmount.currencyto a different currency when the transaction is sent out to PSP, and the FX rate betweenpayment.transAmount.currencyandpayment.convertTransAmount.currency. The FX rate will be provided if you enable the currency conversion feature in EVO Cloud and this capture applies currency conversion. You can contact the EVO Cloud account manager for more details.paymentMethod.e-wallet.paymentBrand: The actual payment brand for the payment; EVO Cloud will distinguish this through the payment code.paymentMethod.e-wallet.walletName: The child wallet name when the payment brand is Alipayplus.
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"
}Step 5 Present the payment result
After the user confirms the payment, 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 |
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 |
B0033 | The transaction was rejected for security violation |
I0111 | Payment Code expired or error |
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 |
|---|---|
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.
