The card transaction api contains functions that are used in payment scenarios: online, in-store and offline. Before transactions can be created an account must exists with associated cards.

Changelog

2020-05-19
PointOfSale property added to the resources purchase, cash-withdrawal and reversal

2020-05-14
Changed instructions of extracting AcquireBatchId from RKHA file

2020-05-07
Added CardAuthenticationMethod and Channel to Purchase resource (offlineinfo)

2020-04-15
Added CardAuthenticationMethod and Channel to Authorizations resource

2020-03-06
Cancellations resource added, cancels the authorization when posted

Summary

The card transactions has two major concepts Authorizations and Financial Transactions.

Authorizations

Validates if payments can be done, account has sufficient funds etc..The authorizations will end up as reservations on the credit-account. Authorization will in most cases end up in financial transaction, a "Purchase".

Authorizations and Cancellations are the only real-time transactions, they take place instantly on at the point of sale (POS) (eg. cache register or online payment).
 

Financial transactions

The financial transactions are the actual monetary transactions. There are three different type of financial transactions: Purchase, Cache-Withdrawals and Reversals. Each financial transaction can be reversed using reversals.
 

Transaction flow

Most transactions follow the flow where a authorization is initially made and is later followed by a financial transaction, however there are cases with financial transactions without corresponding authorizations. The typical scenario is when a POS-Terminal loses connection with the internet. To prevent an all-stand-still at the point of sales, the cards can contain an offline-limit.The offline-limit restricts maximum amount of a purchase that can be made unauthorized. The offline-limit (if such exist) is regulated in the agreement between the card-issuer and the consumer. 

Route description

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Routes that occurs in examples of this documentation will use the following identifiers

Authorizations

An authorization is done as the first step in using an account as payment. A successful authorization leads to a reservation on the account, the account is identified through the cardToken. The authorization is not a financial transaction, to make the financial transaction a Purchase (or other type of transaction) must be posted on the authorization.

Post authorizations

Get authorizations

Resource properties authorizations

Cancellations

The authorization must be cancelled if the seller aborts the process (for any reason) after a successful call to authorizations has been made.
This is done by sending a post request to the cancellation URL that was provided in the response of the actual authorization call.

Post cancellations

Resource properties cancellations

Purchases

Post purchases

Get purchases

List purchases

Resource purchases

Resource properties purchases

Cash-withdrawals

Post cash-withdrawals

Get cash-withdrawals

List cash-withdrawals

Resource cash-withdrawals

Resource properties cash-withdrawals

Reversals

Used to refund a purchase for any reason

Create reversals

Execute post towards this resource to add the amount on the card (account) specified in the authorization

Get reversals

List reversals

Resource reversals

Resource reversals properties

Corrections

Each type of transactions can be corrected by making a POST call against its correction resource

Create purchase corrections

Create cash-withdrawal corrections

Create reversal corrections

Corrections resource properties

Mapping card-transaction to credit-account

Complete specification of credit-account-api can be found here.

RKHA21 format

If the original source for the transactions towards purchases/cash-withdrawals/reversals/corrections is the RKHA21 file the below rules should be used to set the AcquirerBatchId.

AcquirerBatchId = [Processing date][Sender][1:st character of Cycle]

For the example values in the table below the AcquirerBatchId will be "20020688502".

RKHA21 file header row description

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Example

Problem types