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:

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:

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:

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 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 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.billingAmount and payment.billingFXRate: The user's billing currency and value of the payment, and the FX rate between payment.transAmount.currency and payment.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.convertTransAmount and payment.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 the currency conversion feature in EVO Cloud and this capture applies currency conversion. You can contact EVO Cloud account manager for more details.

10.

paymentMethod.e-wallet.walletName: The child wallet name when the payment brand is Alipayplus.

Here is an example of a successful payment response:

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.

Step 1: Get available payment method(s)#

Step 2: Make a payment#

Step 3: Perform additional actions#

Step 4 Retrieve the payment result#