Overview

A transaction in Cards Connect involves processing a card payment from a buyer to purchase goods/services. Cards Connect enables you to process card-not-present (CNP) transactions for card schemes such as American Express, JCB, MasterCard, and Visa with the following operations:

1. Authorisation: The first step for a transaction in Cards Connect is to get authorisation from the issuer. Authorisation checks if the cardholder has the permission to use the card and if there are enough funds available in their account. If successful, this operation reserves the transaction amount in the cardholder's account temporarily.
2. Capture: The usual second step after authorisation is to clear the transaction with the final amount of the purchase through a capture. Once the transaction amount is finalised, then the payment can be fully cleared from the cardholder's account and the transfer of funds can be processed during the settlement. When performing a capture operation, you may use an amount that is less than the authorised amount (partial capture) or greater than the authorised amount (over-capture). Over-capture needs to be enabled at the merchant level and a limit should be set based on percentage or fixed amount or both.
3. Void: If a transaction cannot be fulfilled for one reason or another such as the buyer changing their mind or the merchant does not have the goods in their inventory, the merchant may void the authorisation and release the hold on the cardholder's account. A void can be performed at any time before the authorisation expires. The expiry period may be different for various issuers and MCCs, but in general a capture needs to be performed within 7 days after the authorisation. Once the authorisation expires, the issuer releases the funds back to the cardholder's account.
4. Refund: When a cardholder wants to return the goods or services a transaction has been cleared and the merchant has received the payment, Refund operation is used to return the funds back to the cardholder's account. A refund can take much longer to complete compared to a void. You may perform multiple refunds on a captured transaction up to the full captured amount.

Initiating a new transaction or a new operation on an existing transaction has a generic approach in Cards Connect. A transaction starts with an authorisation, which requires you to pass an identifier unique at the merchant level in the API path as the transaction id and the respective properties in the body. Then, all subsequent operations on the transaction are initiated by using the same transaction id and a new identifier that is unique at the transaction level for the operation itself in the path, while setting all the relevant properties for the operation in the body where available.

• transactions/{transactionId}/authorization is the path of a PUT call to the Authorisation API to get authorisation from a card and create a transaction.
• transactions/{transactionId}/captures/{captureId} is the path to the Capture API for initiating a capture on the same transaction.

Retrieving data uses a similar approach.

• A GET call to the respective API with the identifier of the specific operation returns the details on that operation. So, transactions/{transactionId}/authorization returns the details of the authorisation on the transaction with the id in the path.
• You may specify the name of the operation after the transaction id and then provide the operation id to retrieve the details of a specific operation. For example transactions/{transactionId}/refunds/{refundId} returns a specific refund on a transaction.
• As an extension to the usage above, you may fetch all the respective operations under a specific transactions. For example transactions/{transactionId}/refunds returns all the refunds under the transaction.
• All of the above use cases return the details of an operation or a set of operations on a transaction. However, the Transaction Summary API returns all the details of a transaction including all the operations, along with its current state as a response to transactions/{transactionId} call.

📘

Transaction details vs. Operation details

Cards Connect provides multiple API endpoints to either return the details of the overall transaction or only for specific operations such as authorisation, void, captures, and refunds. For example Get Authorisation API will return information only for the authorisation, whereas Get Transaction API will return the state of transaction in full.

Error handling mechanism in Cards Connect validates your request from different perspectives. If your request fails to pass any of the validations, Cards Connect stops processing it and returns an error message that contains the details of the issue. Cards Connect does not create transaction or operation records for these types of failed attempts, so, if you try to retrieve the information for them, the system will return a transaction not found error. You may check the Error Codes page for Cards Connect error codes and their descriptions.

🚧

Timeout Errors and Retry Attempts

While creating a new transaction or operation on Cards Connect, if you encounter a timeout error, you shouldn't attempt to retry with a new transaction or operation identifier.

You may retry the initial request, without changing any info, which may result in an idempotency error if we have already received the initial request or you may try to retrieve the details of the respective operations first, then retry if necessary.