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:

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:

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.Common Payment fields

Field path	M/O	Description
`merchantTransInfo`	M	Merchant transaction identification object.
`storeInfo`	O	Supplemental store information.
`transAmount`	M	The currency and value of the payment. The value must follow the currency's minor unit.
`captureAfterHours`	O	Controls immediate, automatic, or manual Capture behavior.
`paymentMethod`	M	Payment method object.
`paymentMethod.type`	M	Must be `card` for this document's scenario.
`transInitiator`	M	Terminal initiation context.
`transInitiator.platform`	M	Must be `POS` for the POS route.
`transInitiator.paymentScenario`	O	`inStore` when required by deployment routing.
`transInitiator.terminalID`	O	Registered terminal identifier

More details about the paymentMethod object:

A. When the user chooses to pay with Offline Card:

1.paymentMethod.type: Set as card in your request.

2.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.

3.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),track2 and holderName in this object. For some of the UnionPay debit cards, the expiryDate is also optional.
(If both paymentMethod.card.encryptedCardInfo and paymentMethod.card.cardInfo are present, paymentMethod.card.cardInfo will be applied.)

4.paymentMethod.cardfields

Field path	M/O	Condition	Description
`paymentMethod.card`	M	`paymentMethod.type=card`	Card-related transaction object.
`paymentMethod.card.encryptedCardInfo`	O	Approved encrypted-card integration	Encrypted card information.
`paymentMethod.card.cardInfo`	O	Approved card-information integration	Card information container.
`paymentMethod.card.cardInfo.cardNumber`	M	Manual/MOTO or final schema requirement	Card number. Never use a real value in examples or test fixtures.
`paymentMethod.card.cardInfo.expiryDate`	O	MOTO requirement	Expiration date in `MMYY` format.
`paymentMethod.card.posEntryMode`	O	POS card route	Card data input mode.
`paymentMethod.card.pinFlag`	O	Terminal supports PIN	`true` means the terminal can accept PIN; `false` means it cannot.
`paymentMethod.card.termReadability`	O	Terminal capability is provided	Terminal card-data input capability.
`paymentMethod.card.icCardCondCode`	O	UnionPay IC scenario	UnionPay card condition code.
`paymentMethod.card.noSecretNoSignFlag`	O	UnionPay scenario	UnionPay no-secret/no-sign indicator.
`paymentMethod.card.cardInfo.track1`	O	Magnetic or channel-specific requirement	Track 1 data. The final field name must follow the approved schema.
`paymentMethod.card.cardInfo.track2`	O	Magnetic, ICC, contactless, or fallback requirement	Track 2 data. Must not be stored or logged in plaintext.
`paymentMethod.card.cardInfo.cardSequenceNum`	O	ICC or contactless requirement	IC card sequence number.
`paymentMethod.card.cardInfo.icCardData`	O	ICC or contactless requirement	EMV/ICC TLV data.
`paymentMethod.card.pin`	O	PIN transaction	PIN container, if included in the final schema.
`paymentMethod.card.pin.encryptedPin`	M	PIN transaction	Encrypted PIN block. Never log or persist as plaintext.
`paymentMethod.card.pin.pinEncryptMethod`	M	PIN transaction	Approved PIN encryption method, for example `3DES`, when supported.
`paymentMethod.card.pin.checkValue`	O	Key-version lookup is enabled	Value used to identify the applicable working-key version, when supported.

5.Card posEntryMode Modes

posEntryMode mode	Transaction activity	Typical conditional data
`magnetic`	Magnetic-stripe read	track2
`ICC`	Contact chip insertion	track2 、icCardData 、cardSequenceNum
`contactless`	NFC EMV tap	track2 、icCardData 、cardSequenceNum
`contactless magnetic`	Contactless transaction using a magnetic-stripe path	track2
`fallback`	EMV-to-magnetic fallback	track2
`manual`	Manual card entry	cardNumber 、expiryDate
`MOTO`	Mail order / telephone order	cardNumber 、expiryDate

The final API schema is the authority for exact field names, lengths, conditional requirements, and PSP-specific restrictions.

6.Purchase Request Example

The following example uses placeholders for all environment-specific and sensitive values.

Pre-authorization Request Example

Response and Status Handling

8.1 Representative Purchase response

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "merchantTransInfo": {
    "merchantTransID": "{{merchantTransId}}"
  },
  "payment": {
    "status": "Captured",
    "transID": "{{platformTransactionId}}",
    "transAmount": {
      "currency": "{{currency}}",
      "value": "{{amount}}"
    }
  },
  "paymentMethod": {
    "type": "card"
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "{{terminalId}}"
  }
}

8.2 Payment status model

Status	Meaning	Merchant action
`Pending`	Request accepted but processing is not final	Query the transaction or wait for Notification according to the integration contract.
`Authorised`	Authorization succeeded but Capture is outstanding	Send Capture or wait for automatic Capture.
`Captured`	Authorization and Capture completed	Fulfil the order and store the final transaction identifiers.
`Failed`	Validation, business, risk, or PSP processing failed	Do not fulfil the order. Inspect the result code and message.
`Reversed`	Authorization was reversed after timeout or recovery handling	Do not treat the transaction as captured. Reconcile the final result.

8.3 Notification

When a Payment Notification is configured, the merchant should use it to receive asynchronous state changes such as:

Purchase completed: Captured;

Pre-authorization completed: Authorised;

Capture completed: Captured;

PSP decline or processing failure: Failed;

Timeout/reversal: final status defined by the deployed contract.

The notification must not expose PIN blocks, key material, CVV/CVC, full track data, raw PAN, or unapproved raw EMV authentication data.

8.3 Follow-up APIs

Operation	Purpose	Expected source status
`POST Capture`	Complete a successful pre-authorization	`Authorised`
`POST Cancel`	Cancel an eligible authorization before capture	Contract-defined authorization status
`POST Refund`	Refund a captured transaction	`Captured` or eligible partially refunded status
`POST CancelOrRefund`	Select cancellation or refund behavior according to transaction state	Contract-defined status
`GET Payment`	Query the latest Payment status	Existing transaction identifier

These operations reuse the existing Merchant Connect transaction lifecycle. They do not create a separate card transaction mechanism.

Step 4: Retrieve the payment result

You will get the result of this payment，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

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "merchantTransInfo": {
    "merchantTransID": "{{merchantTransId}}"
  },
  "payment": {
    "status": "Captured",
    "transID": "{{platformTransactionId}}",
    "transAmount": {
      "currency": "{{currency}}",
      "value": "{{amount}}"
    }
  },
  "paymentMethod": {
    "type": "card"
  },
  "transInitiator": {
    "platform": "POS",
    "terminalID": "{{terminalId}}"
  }
}

Step 5: 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.

Step 1: Get available payment method(s)#

Step 2: Collect user's payment information#

Step 3: Make a payment#

Step 4: Retrieve the payment result#