GuidesAPI ExplorerSupport

Getting started with Card Payments

Check the Card Payments API reference here.

PPaaS supports a variety of payment functionalities that include in-store payment and omnichannel services. In-store payment is the payment acceptance from any payment method used by a consumer to buy a product or service from a merchant in a store. Traditional in-store payment methods include debit and credit cards issued by a bank. Omnichannel services are payment-related services such as refund and cancel that are available both for in-store and web-based transactions.

Before you make a payment with our Payment API, ensure that you have gone through the necessary enrolment steps.

This includes:

  1. Sign in with your developer account on our Client portal and register your application.

  2. Retrieve the application's credentials and add them to your application.

  3. Build your integration.

With our payments services you can build an integration for your payment devices in-store. Payment API allows you to accept any global card payment methods in-store or online from your payment application running on a payment device, in the cloud, or from your payment gateway.

Payment acceptance with debit and credit cards leverages the following payment technologies from a payment device:

  • Contact or chip-and-PIN

  • Contactless

  • Magstripe

Payment methods

Initiate a sale transaction

To initiate a sale transaction, call the payment API from your payment application running on a payment device, from a cloud application, or from a payment gateway. This routes the transaction to PPaaS, which routes the transaction to the selected acquirer or bank for processing. Once routed, you will receive the status of the transaction in the Payment response.

The operation may be:

  • an authorization only, if the capture is deferred

  • authorization and capture, if the capture is immediate

The behaviour depends on the configuration and the transaction accepted by the payment gateway, bank, or acquirer. Check the parameter description in the API reference. Based on ISO 4217 standard, express the amount in smaller units of the selected currency: €1,5 euros is set as 150, 20662 ¥ is set as 20662 as yen has no decimal.

To make a payment transaction, call the method POST /payment/v1/transactions/process.

Capture

Capture transaction is a two-step process the initial step is performing an authorization of the payment details of the customer followed by a transferring full or partial amount that is reserved from the customer to the merchant. To capture a transaction and trigger a settlement that is authorized and transfer the funds from the customer to the merchant, call the POST method POST /payment/v1/transactions/{transaction_id}/capture. Here, the capture can be done on the total amount or partial amount.

To capture all the transactions to trigger the transfer of funds that are authorized and transfer the funds from the customers to the merchant, call the POST method POST /payment/v1/transactions/captureall. Here, the capture can be done on the total amount or on a partial amount.

Refund a transaction

To refund a payment that was approved and captured, you can use the Refund API and proceed to either a partial or full refund.

Call the POST method POST /payment/v1/transactions/{transaction_id}/refund, here transactionId can either be the Client Transaction Identifier or the Server Transaction Identifier specified in the refund request. Refund is an asynchronous process; the transaction may not be completed immediately.

Cancel a transaction

For the transactions that are successful and resulted in either technical or functional errors need to be paid back to the respective account with a proper cancel request. Here, a cancel transaction as a result of cancelReason that is Technical is referred to as reversal and a cancel transaction as a result of cancelReason that is Functional is referred to as void.

For the transactions that were not captured, the cancellation can be full or partial. The acceptance of the partial cancellation depends on the acquirer's capability to process partial cancellations. If the transaction has already been captured, proceed to request a refund. Call the POST method POST /payment/v1/transactions/{transactionId}/cancel and process the reversal or void transaction respectively. They transactionId can either be the Client Transaction Identifier or the Server Transaction Identifier specified in the cancel request.

Refund and cancel by web

If you want to integrate the refund or cancel by web endpoints of the PPaaS Payment API to support the omnichannel cases on your portal or from payment application running on the device or in the cloud, call the GET method GET /payment/v1/transactions/{transactionId}/allowedoperations. This endpoint lists the operations allowed on the selected transaction and the maximum amount to cancel or refund, which can be useful to decide whether to show or hide the cancel or refund by web buttons and control the cancel or refund amount. To select the transaction, you need to provide the identifier of the transaction. Two types of transaction identifiers are supported: client Transaction ID that you generated already and provided in the request of the sale transaction processed, and server Transaction ID generated and returned by PPaaS for the sale transaction processed previously. Both client and server transaction identifiers are provided in the response of the sale transaction in the Payment Response. As a response to this endpoint, you get an indicator of whether the operation is allowed or not: allowed = true or false. The maximum amount available for the operation with its currency: maxAmount and currency.

Call the POST method POST /payment/v1/transactions/{transactionId}/refundbyweb to trigger a cancellation or a refund by web transaction. The amount in the payment API should be provided in the smaller unit of the currency based on ISO 4217 standard.

Get transaction status

To get the status of a transaction and the related history events, call the GET method GET payment/v1/transactions/{transactionId}, here provide the associated client transactionId or server transactionId. In the response, you will get the details of the transaction and the list of all the events associated with this transaction.

Offline payments

In some cases, the connection between the point of sale (POS) device and the server may be down due to different reasons, including network, and server issues. In such cases, the Merchants can continue to accept sale transactions locally where the authorizations are processed in offline mode for the cards supporting it. Here, the transactions do not require systematic authorization to be sent to the server and the acquirer. Once the connection is back or the server is available again, the APOS device sends the transactions that were processed offline to the PPaaS payment server. The transactions processed offline are stored locally in the APOS terminal and are not available in the PPaaS server. The offline payment is a two-step process, to check PPaaS server availability and send offline transactions to the PPaaS payment server. To identify the status of the server, call the GET method GET /payment/v1/transactions/technical/isAvailable. If the PPaaS payment server is unavailable, enable the offline payment mode.

To send the offline sale transaction to the PPaaS payment server, call the method POST /payment/v1/transactions/process, here configure the offlineTransaction parameter to true.

Mail Order/Telephone Order (MOTO)

PPaaS supports MOTO transactions with or without Address Verification Service. To process a MOTO sale transaction with or without AVS, call the method POST payment/v1/transactions/process. Provide the corresponding fields for MOTO and AVS.

  • To request the MOTO transactions without AVS, the fields indicating the address in the instrument must be e-mail or phone.

  • To request the MOTO transactions with AVS, the fields indicating the orderChannel, zipCode , and houseNumber to be verified and added to the request.

MOTO transactions are accepted with entryMode those that have the value Keyed. If you use another value ContactlessChip for entryMode, the transaction will not be processed successfully, and a validation message will be returned.

Manual Keyed Entry (MKE) payment

MKE allows a manual typing of the cardholder's card details into the payment device. When the payment device fails to get the card details from the card's chip or magnetic stripe, call the POST method POST /payment/v1/transactions/process. Here, set the entryMode to Keyed.

Online PIN translation

During the transit on intermediate systems (between networks), different parties can use the PIN translation service to re-encrypt a PIN block from one key to another. The PIN translation service ensures that PINs are not displayed during the process and the keys to encrypt the PIN are isolated in their own networks. Call the POST method POST /payment/v1/transactions/process. Here, set the Online PIN translation parameters ksn, pinblock, and pinblockFormat.

Merchant supervisor approval for refund/cancel transactions

For refund or cancel transactions, the merchant supervisor can provide the approval code. The approval code that is added to the transaction body is validated and then the transactions are processed to refund or cancel. Approval code is an optional parameter and it could be found in the payload of Cancel/Refund APIs. However, if Merchant Aggregator has opted for an approval code and if the approval code is not available or incorrect during the transaction processing, the validation fails and results in an error.

This approval code functionality is not applicable for Refund/cancel ByWeb and is applicable only for terminal-based transactions.