Capture

It is applicable to both EC and In-Store Scenario.

For some payment methods, the payment process is completed in two steps:

Authorization: Verifies the payment details of the user and reserves the funds.

Capture: Transfers the reserved funds from the user’s account to your account.

For instant payment methods, the payment is captured immediately after authorization.

For non-instant payment methods that support separate authorization and capture, you can capture the payment later. This allows for cancellation in case of any issues.

Here is the matrix for the payment methods and whether separate authorization and capture are supported.

Payment Method	Payment Brand	Support
Card	VISA	Yes
	Mastercard	Yes
	AMEX	Yes
	JCB	Yes
	Diners / Discover	Yes
	UnionPay	Yes
	TPN	No

Manual capture

To capture a payment, make an HTTP POST request to the EVO Cloud endpoint:
/g2/v1/payment/mer/{sid}/capture
Key Points:

Default Behavior: If you do NOT specify the captureAfterHours field in the initial payment request to /g2/v1/payment/mer/{sid}/payment, the default capture setting will apply for payment methods that support separate authorization and capture.

No Separate Capture: For payment methods that do not support separate authorization and capture, the captureAfterHours field is ignored, as payments are captured immediately after authorization.

Timing: It is recommended to send the capture request within 7 days after authorization, as most issuers will expire the authorization after this period.

Amount Limit: The capture amount CANNOT exceed the initial payment amount.

Automatic capture

Payment can be captured automatically by EVO Cloud after authorization, which means you do NOT need to request for capture endpoint.

You need to specify the captureAfterHours field when you make an HTTP POST request to EVO Cloud endpoint (/g2/v1/payment/mer/{sid}/payment) to enable this feature. Then EVO Cloud backend will setup an automatic capture task according to the captureAfterHours you specified.

0 to 168 is the valid range for captureAfterHours, meaning that you can set up to 168 hours (7 days) later for automatic capture after authorization. 0 means capture the payment immediately after authorization.

Setting up a delay between authorization and capture allows you to cancel the payment before it is captured, for example, when the good is out of stock. EVO Cloud will cancel the backend automatic capture task if you cancel the payment.

Even a payment is authorized with automatic capture mode, you can choose to capture it manually following the manual capture mode before it is automatically captured by EVO Cloud. If the capture is triggered manually in this way, the backend automatic capture task in EVO Cloud will be cancelled to avoid double capture.

Partial capture

With some payment methods, you can also capture a payment partially. Here is the matrix for the payment methods and Payment Brands that support partial capture.

Payment Method	Payment Brand
Token & Card	VISA
	Mastercard
	AMEX
	JCB
	Diners / Discover
	UnionPay

Please note that you can only capture a payment once, and if you partially capture it, any unclaimed amount left will be automatically cancelled.

Make capture request

Step 1: Make a capture request

When you get a payment result with the payment.status with Authorised, you can make an HTTP POST request from your server to EVO Cloud endpoint

/g2/v1/payment/mer/{sid}/capture

to manual capture the payment,

and specify the parameters below.

Parameter	Required	Description
merchantTransID	M	The `merchantTransInfo.merchantTransID` of the initial payment.
merchantTransInfo	M	The reference for the capture, 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.
initiatingReason	O	You can state the reason for this request in this field.
webhook	O	The URL to receive notification. Specify this to get the notification from EVO Cloud after the payment succeeds.
paymentMethod	O	Payment method object.
paymentMethod.type	O	Must be `card` for this document's scenario.
metadata	O	A self-defined reference information that you can specify in the request, echoed back in the response. Metadata

More details about the paymentMethod object:

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.

Here is an example of making a 10 USD capture:

If the request is successful, the response will include a capture object and a payment object. Here are the details of the capture object:

Detail information about capture object:

capture.status: The status of the capture, required. The value can be Success, Failed, or Received. If you get a capture.status with Received, you need to either make another HTTP GET request to get the final status of the capture (see Step 2 for more details), or wait for the notification webhook from EVO Cloud.

capture.transAmount: The currency and value of the capture, required. It is echoed back from your request.

capture.merchantTransInfo: The object that is a reference for the capture, generated by your host, required. It is echoed back from your request.

capture.evoTransInfo: The object that is a reference for the capture, generated by EVO Cloud, required. It contains evoTransID, evoTransTime, and traceNum (optional) and retrievalReferenceNum for some PSPs such as Visa or Mastercard.

capture.pspTransInfo: The object that is a reference for the capture, generated by PSP, optional. It contains pspTransID, pspTransTime, and authorizationCode. EVO Cloud forwards this information from PSP to your host if PSP returns.

capture.billingAmount and capture.billingFXRate: The user's billing currency and value of the capture, and the FX rate between capture.transAmount.currency and capture.billingAmount.currency, optional. EVO Cloud forwards this information from PSP to your host if PSP returns. This is applied to some E-Wallet payment when PSP conducts the currency conversion, or to some card payment when you enable the DCC feature. You can contact EVO Cloud account manager for more details.

capture.convertTransAmount and capture.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 capture.transAmount.currency and capture.convertTransAmount.currency, optional. 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.

Here is an example of a successful response:

Step 2: Retrieve the capture result

If you get a capture.status with Received and you don't use the Accept Notification webhook, you can retrieve the final result from EVO Cloud.

From your server, you can make an HTTP GET request to EVO Cloud endpoint

/g2/v1/payment/mer/{sid}/capture

and specify the parameter below.

Parameter	Required	Description
merchantTransID	M	The `merchantTransInfo.merchantTransID` of the initial capture.

Here is an example of retrieving the capture result:

Here is an example of the GET response. The POST response is similar to the GET response.

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 get the response within the time frame, you need to retrieve the result from EVO Cloud. See Step 2 to initiate the request.
For HTTP GET request to EVO Cloud: You can initiate the request several times until get the result, and it is suggested to wait at least 45 seconds before you initiate the next request. If you still fail to get the result after several times of the request, you can initiate another capture request instead.

Manual capture#

Automatic capture#

Partial capture#

Make capture request#

Step 1: Make a capture request#

Step 2: Retrieve the capture result#

Error handling#

Manual capture

Automatic capture

Partial capture

Make capture request

Step 1: Make a capture request

Step 2: Retrieve the capture result

Error handling