1. Payment
Merchant Connect API
HASE
  • latest
  • HASE
  • Integration Guide
    • EC Payment
      • Merchant API
        • Overview
        • Payment
        • Payment Methods
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
        • Features
          • Account Status Inquiry (ASI)
          • COF
          • Recurring
          • Instalment
          • Authentication
            • 3D Secure
            • Authorization only
          • Tokenization
            • Gateway Tokenization
            • Create a gateway token
            • Network Tokenization
            • Pay with gateway token
            • Manage token
    • In-store Payment
      • Merchant API
        • Payment
          • CPM
          • MPM
          • MPM static QR code
        • After Payment
          • Capture
          • Cancel
          • Refund
          • Cancel or Refund
          • Accept Notification
  • API Explorer
    • API Rules
    • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
      • PaymentMethod
    • Payment
      • Payment
      • Payment
      • Payment
    • Capture
      • Capture
      • Capture
    • Cancel
      • Cancel
      • Cancel
    • Refund
      • Refund
      • Refund
    • Cryptogram
      • Cryptogram
      • Cryptogram
    • Cancel or Refund
      • Cancel or Refund
      • Cancel or Refund
    • Notification
      • Notification for PaymentMethod
      • Notification for Payment
      • Notification for Capture
      • Notification for Cancel
      • Notification for Refund
      • Notification for MPM Static QR Code
      • Notification for Token Status Update
      • Notification for Cryptogram
    • Appendix
      • Result Code
      • Payment Brands
      • Payment Method Variant
      • Currency list
      • Country and region list
    • HealthCheck
      • HealthCheck
    • TransactionHistoryInquiry
      • TransactionHistoryInquiry
    • Instalment
      • Instalment Plan Inquiry
HASE
  • latest
  • HASE
  1. Payment

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 parameterRequiredDescription
paymentBrandOThe 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.
CurrencyOThe 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:
The response includes the list of available payment method(s) in a paymentBrandList array, containing below fields in each payment method.
1.
brandName: The brand name of the payment method.
2.
brandImage: The logo image of the payment method, a URL for you to get the logo to display on your payment page.
3.
paymentScenario: The supported scenario of the payment method.
4.
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:
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 parameterRequiredDescription
merchantTransInfoMThe reference for the payment, including a unique merchantTransID and merchantTransTime to specify the time you initiate the request.
transAmountMThe currency and value of the payment. The value must follow the currency's minor unit.
paymentMethodMUse 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.
transInitiatorMThe information of device to initiate the transaction.
storeInfoOThe 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.
tradeInfoOThis field is required when paymentMethod.e-wallet.paymentBrand is Alipay to indicate the detailed information about this payment.
WebhookOThe URL to receive notification. Specify this to get the notification from EVO Cloud after the payment succeeds.
MetadataOA 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:
1.
paymentMethod.type: Set as e-wallet in your request.
2.
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:
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:

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 parameterRequiredDescription
merchantTransIDMThe merchantTransInfo.merchantTransID of the requesting payment.
Here is an example of retrieving the payment result:
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:
1.
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.
2.
payment.failureCode: The error code for the payment, which will be returned when the payment.status is Failed.
3.
payment.failureReason: The error message for the payment, which will be returned when the payment.status is Failed.
4.
payment.transAmount: The currency and value of the payment, required. It is echoed back from your request.
5.
payment.merchantTransInfo: The object that is a reference for the payment, required and generated by your host. It is echoed back from your request.
6.
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.
7.
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.
8.
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 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.
9.
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 the EVO Cloud account manager for more details.
10.
paymentMethod.e-wallet.paymentBrand: The actual payment brand for the payment; EVO Cloud will distinguish this through the payment code.
11.
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 codeDescription
S0000Success
V0008Field {} is not applied with {...}
C0004Request resource merchantTransID {XXX} not exist
B0005Unsupported function {XXX}, please check your profile setup in EVO Cloud
B0006Unsupported payment brand {XXX}, please check your profile setup in EVO Cloud
B0033The transaction was rejected for security violation
I0111Payment 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.
StatusDescription
CapturedIf card transaction, means transaction authorization and capture are successfully completed; If e-wallet transaction, means transaction is successfully completed.
FailedPayment 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.
Previous
Manage token
Next
MPM
Built with