Qodex.ai

Rapyd Payment Gateway API

Number of APIs: 8

The Payment Gateway API is intended for large merchants or payment processors that need extended flexibility in their payment processing flows, and have in place necessary customer facing user interfaces to capture payments online.

RAPYD Acquires KORTA

July 7th, 2020 Rapyd completed the acquisition of Korta. For details click-here.

This documentation refers to the KORTA Payment Gateway API, and will be referenced as such to avoid any confusion with other Rapyd API's. This API will remain available until further noticed.

It is strongly recommended all new payment integrations will be done using Rapyd API's and by doing so get access to the extended payment capabilities supported by Rapyd.

For Rapyd API Documentation refer to:

Audience

This documentation is intended for programmers, product owners, and systems integrators who are responsible for integration to the KORTA Payment Gateway to enable merchants to accept card payments, and explains the technical integration to the KORTA Payment Gateway API.

Getting Started

To get started with KORTA Payment Gateway API you’ll need to sign up for merchant agreement. For more information regarding merchant agreements please contact us via hallo@rapyd.net or give us a call at +354 558 8000 during business hours, Monday – Friday 09:00 – 17:00 GMT.

Payment Scenarios

Overview

when you interact with this API, you can segment the payment scenarios into 6 primary stages, i.e.:

  • Store CredentialsA stored credential (CoF) is information that is stored by a Merchant or its agent, a payment facilitator, or a staged digital wallet operator to process future transactions. This is the preferred method handling payments due to the high approval rate Credentials on File (CoF) bring.
  • Issuer Approval:Get permissions from the issuing bank to charge the Customer's card
  • Cancel Approval:It is important to Cancel (a.k.a. Void or Reversal) all transactions where the Merchant has received approval to charge the Customer, but for some reason the Customer decides not to go ahead with the purchase. In this scenario the Customer's usage limit on his card has been affected, and will not be reset until the Merchant has cancelled the authorised amount or the authorisation expires.
  • Confirm Charge:With confirmation (a.k.a. Capturing Transaction) the Customer's card is charged, either in same message as the authorisation, or in a separate message where the amount can be lower than the amount approved.
  • Refund Customer:The Merchant wants to return money to the Customer, e.g. items or service not possible to deliver, or discounts to name some.
  • Bad-Day-Scenario's Handling: In case of time-outs, the client shall attempt to send reverse message on the request that timed out, so Customer will not be charged more often than wanted.

Customer Authentication:

When requesting approval (a.k.a. authorisation) from the Issuer to charge the Customer's card, the customer may need to be authenticated.

Two types of authentication methods are supported, i.e. using 3DSecure (3 Domain Security) or CVC (Cardholder Verification Code). In both scenarios, the Customer wants to make a purchase, but cannot physically present the card for the Merchant's visual examination at the time of payment:

  • CVC Authentication:
    The Customer provides the 3-digit CVC code printed on his card to the Merchant via Telephone, Mail/Fax, or by entering the code himself at the Merchant's checkout page. This value is provided in element d47 in the sale request. Note! This scenario is applicable for MAIL, TELEPHONE and INTERNET transactions.

  • 3DSecure Authentication:
    The Merchant wants the Customer be authenticated by the Issuer of the card, and by doing so get a liability shift for the transaction over to the Issuer/Customer. Once the Customer has been authenticated by the Issuer, the details provided by the issuer must be included with the sale transaction. These are: TXcavv, TransactionStatus, PurchaseXID, and DsTransId. Note! This scenario is NOT applicable for MAIL nor TELEPHONE transactions.

Point Of Interaction:

Another important thing to be aware of is the Merchant needs to provide details on how the transaction he is requesting is created. This is often referred to as Point Of Interaction or POI.

Typically transactions are initiated by the Customer, this is called Cardholder Initiated Transaction (CIT), but in other cases it may be the Merchant that initiates the transaction on behalf of the Customer. In such scenarios these transactions are referred to as Merchant Initiated Transactions (MIT) and example of such could be transactions generated by call centres.

The Point Of Interaction is specified in field d22cp in transaction requests or as follows:

  • INTERNET:Transaction performed by Customer using the Merchant's checkout page over the Internet.
  • MAIL:Transactions performed by the Merchant on behalf of the Customer based on mail/fax order sent by Customer to the Merchant.
  • TELEPHONE:Transactions performed by the Merchant on behalf of the Customer based on conversation with the Customer over the telephone.
  • RPA: Recurring Internet Transactions, used for special conditions where the Customer has agreed to allow the Merchant to perform repeated transaction on his/her card, where the first transaction used for reference was initiated by the Customer over the Internet. For further details refer to Credentials On File (CoF).

Use Cases

The following chapters illustrate common use cases related to payments, including references to which endpoints to use for each case.

Sale / Charge Customer:

The Customer has chosen to pay for products and/or services purchased using his/her card. The final amount to charge is known, and no special business process is required to take place prior delivery, so the Merchant wants the sale to be done in a single request.

For details on the sale request refer to Sale

Refund / Customer Returns Goods:

The Merchant needs to refund the Customer for the full or partial amount charged to the Customer's card and doesn't have the card details from the Customer. Using the original sale he want's to refund the Customer.

For details refer to Refund

Authorisation / Reserve Funds on Customer's card:

Reserve Funds on card, or in other words get authorisation to charge the Customer's card, e.g. to ensure sufficient funds are available on card before sending sales order to warehouse for delivery, and charge will be done on the final amount based on items sent for shipping.

For details refer to Authorisation

Cancel / Cancel Previously Reserved Funds:

The Customer cancels his order before the products have been shipped. However the Merchant has reserved funds for the order's total amount. Merchant wants to CANCEL the funds previously reserved on the Customer's card.

For request details refer to Cancel

Capture / Charge Customer Using Previously Reserved Funds:

Merchant has completed his processes after authorisation has been granted for a purchase on a card. The final amount is known, and products sold have been shipped. Now the Merchant wants to charge the card for the final amount, which can be lower than the initially authorised amount.

For request details refer to Capture

Credentials On File / CoF:

Credentials On File (CoF) is used for payment related information stored by a Merchant or his agent, e.g. a payment facilitator, or a staged digital wallet operator, to process future transactions such as recurring payments and/or ad-hoc purchases on behalf of the Customer or by the Customer himself.

To qualify for a CoF transaction, the Merchant or his agent must store the first transaction where the Customer is authenticated successfully, preferably using 3DSecure, but CVC is still accepted in this context. And in such an initial transaction it needs to be clarified for what purpose the credentials are being stored, see further CoF Transaction Types.

This first transaction can either be part of the Customer's first purchase, or the first transaction is solely performed to Store Credentials, such as when a Customer creates his profile in a wallet. In either case, the Customer is authenticated, and the card details provided are validated, either via sale request OR via check card method.

After successful validation, the transaction is stored in the system, and results provided to the client including references the Merchant shall store to use as reference for future CoF transactions.

The aim with Credentials On File is to improve approval rate by card issuers, as well overall customer experience among all stakeholders involved in the payment life cycle.

Store Credentials

Two scenarios apply when storing credentials:

Customer Stores Credentials Only

Customer has created a profile in a wallet, and now he wants to store his credit card with his profile to use for future purchases. The Customer is redirected to a page where he enters his/hers card details, and subsequently the Customer is authenticated using 3DSecure. Once successfully done, the initial transaction is created by send an request, where the card details shall be checked and stored as credentials on file.

Customer Stores Credentials with Purchase

Customer has selected items to purchase online, and now selects checkout. The Customer has provided all necessary details, such as card details, shipping details, name, and finally selects to store his/hers profile in the Merchant's system for later use. Now the Customer is authenticated successfully using 3DSecure, and last step is requesting authorisation to the issuer for the purchase. If the sale is approved by the issuer, the Credentials on File for the Customer are stored.

For request details refer to Store Credentials

CoF Transaction Types

Three transaction types using stored credentials are supported, i.e. recurring payments initiated by the Merchant (MIT), ad-hoc payments using credentials initiated by the Merchant (MIT) or the Customer (CIT), and finally Merchant initiated (MIT) recurring payments where the duration of the contract is known:

Recurring CoF Transaction

Customer purchased a subscription, and stored his credentials successfully when he/she subscribed. Now the Merchant wants to charge for the next months subscription where he wants to charge the Customer using the credentials on file the Customer provided when he/she signed up. In this scenario, it is the Merchant that initiates the transaction on behalf of the Customer. The Merchant's system sends sale request to the payment gateway containing the previously stored credentials.

Unscheduled CoF Transaction

Customer has previously stored credentials successfully in the Merchant's system. The Customer is logged into the Merchant's system and has again selected a number of items to purchase. Now the Customer goes to checkout and when he/she presses buy, the Merchant's system provides CoF reference for the Customer with the sale request to the payment gateway. If the issuer approves, the sale process has ended.

Installment CoF Transaction

Customer has purchased product or services, and his card shall be charged every month for 10 months straight for the same amount each time. The first payment was done at the same time the Customer's card credentials were stored by the Merchant, and now the second Installment payment will be conducted using the Customer's stored credentials. The transaction is automatically initiated by the Merchant (MIT) without any intervention by the Customer.

For details on creating transactions using stored credentials refer to CoF

Reversal / Handling Bad-Day-Scenarios & Timeouts:

The client, i.o.w. the Merchant's Server, sends Check Card, Authorisation, Capture, or Sale request to the Payment Gateway API, but no response is received before the client's time-out limit has been reached. The client shall be able to reverse the request in case it was successfully received by the Acquiring System, so the Customer will not be affected.

For request details refer to Reversal

Authentication

The client authenticates using the following credentials that shall be present in the request body for every request sent to the host:

  • user = {userName}
  • pwd = {passWord}
  • d41 = {terminalID}
  • d42 = {merchantID}

Credentials are provided by KORTA Merchant Services Team. Refer to Getting Started chapter above.

Endpoints

KORTA test environment endpoint

KORTA production environment endpoint

Error Codes

The expected error responses are:
Response code d39 determinates the result of the authorisation request:

  • 000 = Approved
  • 100 = Rejected. No specific reason provided
  • 107 = Rejected. Call card issuer
  • 123 = Rejected. Authentication required
  • 200 = Rejected. Pick up card.
  • 909 = Rejected. Payment error - Contact Service Provider
  • 946 = Rejected. Payment error - Try same request again or contact Service Provider

{{api_version}}

  1. Sale POST {{base_path_test}}{{endpoint_sale}}

  2. Refund POST {{base_path_test}}{{endpoint_refund}}

  3. Cancel POST {{base_path_test}}{{endpoint_cancel}}

  4. Capture POST {{base_path_test}}{{endpoint_capture}}

  5. Store Credentials POST {{base_path_test}}{{endpoint_store_credentials}}

  6. CoF POST {{base_path_test}}{{endpoint_cof}}

  7. Reversal (Time-Out) POST {{base_path_test}}{{endpoint_reversal}}

  8. Authorisation POST {{base_path_test}}{{endpoint_authorisation}}