MPM
Step 1: Get available payment method(s)
Refer to the chapter in the CPM
Step 2: Make a payment
After the user chooses the payment method, 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. |
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 WeChat Pay 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. "paymentBrand": "WeChat_Pay"
20. }
21. },
22. "transInitiator": {
23. "platform": "POS",
24. "paymentScenario": "inStore",
25. "inStorePaymentScenario": "MPM",
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.
Otherwise, additional steps are required to complete the payment. You need to send the action object to your terminal, then proceed to the next step.
Here is an example of receiving a response with an action object requiring to present a QR code:
1.{
2. "result": {
3. "code": "S0000",
4. "message": "Success",
5. "pspMessage": "Success",
6. "pspResponseCode": "SUCCESS"
7. }
8. "action": {
9. "qrData": {
10. "qrCode": "weixin://wxpay/bizpayurl?pr=YZSLeOAzz"
11. },
12. "type": "presentQRCode"
13. },
14. "payment": {
15. "evoTransInfo": {
16. "evoTransID": "f70cf59bfa9a4a87aca67e9bd15e3d3f",
17. "evoTransTime": "2023-04-20T01:51:09Z"
18. },
19. "merchantTransInfo": {
20. "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
21. "merchantTransTime": "2021-12-31T08:30:59+08:00"
22. },
23. "pspTransInfo": {
24. "pspTransTime": "2021-12-31T00:30:59Z"
25. },
26. "status": "Pending",
27. "transAmount": {
28. "currency": "USD",
29. "value": "10.00"
30. }
31. },
32. "paymentMethod": {
33. "e-wallet": {
34. "paymentBrand": "WeChat_Pay"
35. }
36. },
37. "pspData": {
38. "name": "WeChat_Pay"
39. },
40.}Step 3: 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 |
|---|---|---|
| presentQRCode | This is applied to MPM scenario of In-Store payment. 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 4 for more details.2. Or you can wait for the notification webhook to know the payment result. See chapter After Payment for more details. |
Step 4 Retrieve the payment result
When the paymentScenario is instore and inStorePaymentScenario is MPM, you need to present the QR code for the user to scan and pay. After that, 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 the 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 an action object in the response, similar to Step 2, additional steps are required to complete the payment. You need to send the action object to your terminal, then proceed to the next step. Back to Step 3 to perform the required action.
If not, 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 object in the response to show the details of this payment:
payment.status: The status of this capture, required, can bePending,Cancelling,Cancelled,Captured,Refunding,Refunded,Partial Refunded, orFailed. See EVO Cloud API Specification for more details.payment.failureCode: The error code for the payment, which will be returned when thepayment.statusisFailed.payment.failureReason: The error message for the payment, which will be returned when thepayment.statusisFailed.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 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 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 EVO Cloud account manager for more details.paymentMethod.e-wallet.walletName: The child wallet name when the payment brand isAlipayplus.
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": "WeChat_Pay"
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": "WeChat_Pay"
34. },
35. "metadata": "This is a metadata"
36.}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 |
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 of 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.
