Integrate to PayEx Ledger Card transaction API

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-03-06
Cancellations resource added, cancels the authorization when posted

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

Request

POST /ledger/card-transaction/v1/XXX/authorizations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "sourceAuthorizationTransactionId": "789",
   "sellerNumber": "654",
   "cardToken": "5646735165",
   "type": "Purchase|Reversal|CashWithdrawal",
   "pointOfSale": "Testshop",
   "authorizationAmount": 300.0,
   "currency": "SEK"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
   "authorizationId": "YYY",
   "@id": "/ledger/card-transaction/v1/XXX/authorizations/YYY",
   "parentHREF": "/",
   "operations": []
}

Get authorizations

Request

GET /ledger/card-transaction/v1/XXX/authorizations/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "sourceAuthorizationTransactionId": "789",
   "authorizationId": 123,
   "sellerNumber": "654",
   "cardToken": "546415646315",
   "type": "Purchase|Reversal|CashWithdrawal",
   "pointOfSale": "Testshop",
   "validToDate": "2019-11-28",
   "authorizationAmount": 300.0,
   "remainingAmount" : 150.0,
   "currency": "SEK",
   "@id": "/ledger/card-transaction/v1/XXX/authorizations/NNN",
   "purchases": "/ledger/card-transaction/v1/XXX/purchases?authorizationId=123",
   "cash-withdrawals": "/ledger/card-transaction/v1/XXX/cash-withdrawals?authorizationId=123",
   "reversals": "/ledger/card-transaction/v1/XXX/reversals?authorizationId=123",
   "parentHREF": "/",
   "operations": []
}

Resource properties authorizations

Property	Data type	Format	Description
@id	string	Uri
sourceAuthorizationTransactionId	string	Maxlength: 50	Unique identifier of the specific authorization, generated by source (typically the integrating system)
authorizationId	string	Maxlength: 6	Unique identifier of the authorization, generated by PayEx. Should be stored and must be set when transactions is to be created (except for purchases in offline mode)
sellerNumber	string	Maxlength: 15	Identifier of the current seller/merchant
cardToken	string		Identifier of the card. The aurhotization is made on the account that the card is linked to
type	string		type of authorization Purchase Reversal CashWithdrawal
pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale, will be returned in reservation resource
validToDate	date	ISO 8601	Purchase can not be executed after this date
authorizeAmount	decimal	Amount	Original authorized amount
remainingAmount	decimal	Amount	Amount left on the authorization that can be Purchased
currency	string	ISO 4217
purchases	string	Uri
cash-withdrawals	string	Uri
reversals	string	Uri

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

Request

POST /ledger/card-transaction/v1/XXX/authorizations/NNN/cancellations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Get cancellations

Request

GET /ledger/card-transaction/v1/XXX/authorizations/NNN/cancellations/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource cancellations

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"cancellationDate" : "2019-11-20",
"@id" : "/ledger/card-transaction/v1/XXX/authorizations/NNN/cancellations",
"parentHREF" : "/ledger/card-transaction/v1/XXX/authorizations/NNN"
}

Resource properties cancellations

Property	Data type	Format	Description
@id	string	Uri
cancellationDate	date	ISO 8601	Date when the cancellation was made

Purchases

Post purchases

Request

POST /ledger/card-transaction/v1/XXX/purchases HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "authorizationId" : "AUTH71",
   "sourcePurchaseTransactionId" : "534313",
   "sellerReceiptId": "58743597125",
   "additionalReferences":{
       "acquirerBatchId": "200206885010",
       "acquirerTransactionId" : "534313"
    },
   "amount": 200.0,
   "date": "2019-11-28",
   "offlineInfo" : {
       "pointOfSale": "Testshop",
       "cardToken": "5646735165",
       "sellerNumber": "654",
       "currency": "SEK"
    }
}

Get purchases

Request

GET /ledger/card-transaction/v1/XXX/purchases/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List purchases

Request

GET /ledger/card-transaction/v1/XXX/purchases HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource purchases

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
   "description": "stora butiken test, köpref. 12345689",
   "authorizationId" : "AUTH71",
   "sourcePurchaseTransactionId" : "534313",
   "sellerReceiptId": "58743597125",
   "additionalReferences":{
       "acquirerBatchId": "200206885010",
       "acquirerTransactionId" : "534313"
    },
   "amount": 200.0,
   "date": "2019-11-28",
   "offlineInfo" : {
       "pointOfSale": "Testshop",
       "cardToken": "5646735165",
       "sellerNumber": "654",
       "currency": "SEK",
    },
   "corrections": "/ledger/card-transaction/v1/XXX/purchases/YYY/corrections",
   "@id": "/ledger/card-transaction/v1/XXX/purchases/YYY",
   "operations": [
        {
           "rel": "create-correction",
           "method": "post",
           "href": "/ledger/card-transaction/v1/XXX/authorizations/NNN/purchases/YYY/corrections"
        }
    ]
}

Resource properties purchases

Property	Data type	Format	Description
@id	string	Uri
description	string	Maxlength: 200	Describes the current Purchase (derives from info sent in the authorization), may be printed on the bill, output only
authorizationId	string	Maxlength: 6	The id of the authorization from which this purchase originated from (not required if the purchase was made offline)
sourcePurchaseTransactionId	string	Maxlength: 50	Unique identifier of the Purchase transaction
additionalReferences.acquirerBatchId	string	Maxlength: 50	Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionId	string	Maxlength: 50	Unique acquirer identifier of the transaction
sellerReceiptId	string	Maxlength: 50
amount	decimal
date	date	ISO 8601	valuedate of the transaction
offlineInfo.pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale, will be returned in reservation resource
offlineInfo.cardToken	string		Identifier of the card. The purchase will be made on the account that the card is linked to
offlineInfo.sellerNumber	string	Maxlength: 15	Identifier of the current seller/merchant
offlineInfo.currency	string	ISO 4217
corrections	string	Uri

Cash-withdrawals

Post cash-withdrawals

Request

POST /ledger/card-transaction/v1/XXX/cash-withdrawals HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "authorizationId" : "AUTH71",
   "sourceCashWithdrawalTransactionId" : "534313",
   "sellerReceiptId": "54313546",
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313"
    },
   "amount": 200.0,
   "date": "2019-11-28"
}

Get cash-withdrawals

Request

GET /ledger/card-transaction/v1/XXX/cash-withdrawals/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List cash-withdrawals

Request

GET /ledger/card-transaction/v1/XXX/cash-withdrawals HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource cash-withdrawals

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
   "description": "stora butiken test, köpref. 12345689",
   "authorizationId" : "AUTH71",
   "sourceCashWithdrawalTransactionId" : "534313",
   "sellerReceiptId": "541687421",
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "amount": 200.0,
   "date": "2019-11-28",
   "corrections": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY/corrections",
   "@id": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY",
   "operations": [
        {
           "rel": "create-correction",
           "method": "post",
           "href": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY/corrections"
        }
    ]
}

Resource properties cash-withdrawals

Property	Data type	Format	Description
@id	string	Uri
description	string	Maxlength: 200	Describes the current cash-withdrawals (derives from info sent in the authorization), may be printed on the bill, output only
authorizationId	string	Maxlength: 6	The id of the authorization from which this cash-withdrawal transaction originated from
sourceCashWithdrawalTransactionId	string	Maxlength: 50	Unique identifier of the cash-withdrawal transaction
additionalReferences.acquirerBatchId	string	Maxlength: 50	Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionId	string	Maxlength: 50	Unique acquirer identifier of the transaction
sellerReceiptId	string	Maxlength: 50
amount	decimal
date	date	ISO 8601	valuedate of the transaction
corrections	string	Uri

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

Request

POST /ledger/card-transaction/v1/XXX/reversals HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "authorizationId" : "AUTH71",
   "sellerReceiptId": "12345689",
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "sourceReversalTransactionId" : "534312",
   "amount": 200.0,
   "date": "2019-11-28"
}

Get reversals

Request

GET /ledger/card-transaction/v1/XXX/reversals/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List reversals

Request

GET /ledger/card-transaction/v1/XXX/reversals HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource reversals

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "authorizationId" : "AUTH71",
   "sellerReceiptId": "12345689",
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "sourceReversalTransactionId" : "534312",
   "amount": 200.0,
   "date": "2019-11-28",
   "@id" : "/ledger/card-transaction/v1/XXX/reversals/YYY",
   "operations" : [
                {
           "rel": "create-correction",
           "method": "post",
           "href": "/ledger/card-transaction/v1/XXX/reversals/YYY/corrections"
        }
    ]
}

Resource reversals properties

Property	Data type	Format	Description
@id	string	Maxlength:
authorizationId	string	Maxlength: 6	The id of the authorization from which this reversal originated from
sellerReceiptId	string	Maxlength: 50
additionalReferences.acquirerBatchId	string	Maxlength: 50	Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionId	string	Maxlength: 50	Unique acquirer identifier of the transaction
sourceReversalTransactionId	string	Maxlength: 50
amount	decimal
date	date	ISO 8601	valuedate of the transaction

Corrections

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

Create purchase corrections

Request

POST /ledger/card-transaction/v1/XXX/purchases/YYY/corrections HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "sourceCorrectionTransactionId" : "534313",
   "amount": 200.0,
   "date": "2019-11-28"
}

Create cash-withdrawal corrections

Request

POST /ledger/card-transaction/v1/XXX/cash-withdrawal/YYY/corrections HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "sourceCorrectionTransactionId" : "534313",
   "amount": 200.0,
   "date": "2019-11-28"
}

Create reversal corrections

Request

POST /ledger/card-transaction/v1/XXX/reversals/YYY/corrections HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "additionalReferences":{
       "acquirerBatchId": "200206885020",
       "acquirerTransactionId" : "534313"
    },
   "sourceCorrectionTransactionId" : "534313",
   "amount": 200.0,
   "date": "2019-11-28"
}

Corrections resource properties

Property	Data type	Format	Description
@id	string	Maxlength:
additionalReferences.acquirerBatchId	string	Maxlength: 50	Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionId	string	Maxlength: 50	Unique acquirer identifier of the transaction
sourceCorrectionTransactionId	string	Maxlength: 50
amount	decimal
date	date	ISO 8601	valuedate of the transaction

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][Cycle]

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

RKHA21 file header row description

Position	Field	Format	Description	Example
1	Transaction code	2 N	01
3	Processing date	6 N	YYMMDD	200206
9	Sender	4 N	"8850" (Babs)	8850
13	Cycle	2 AN	10/20	20
15	Filler	26 AN	Space characters
41	Vers.nr/serial number	6 N	File serial number
47	Transaction entry	1 AN
48	Filler	333 AN	Space characters

The rkha format actually has a 28 character filler at position 13 by default, but for "Babs" the first two positions in this filler are redefined to be "cycle" (position 13 and 14), which leaves the Filler to be 26 characters instead of 28.

Problems

If an error occur or any validation failed, a "problem" response will be returned.
Below is a list of problems that can occur:

HttpStatus 401 Unauthorized

Token expired
Token invalid
CompanyNumber does not match token

HttpStatus 400 Error

Validation: Argument required
Validation: Invalid value

HttpStatus 409 Conflict

Authorization declined
Card with token {cardtoken} does not exists
Duplicate authorization
Duplicate purchase
Duplicate cash-withdrawal
Duplicate reversal
Duplicate correction
Authorization has expired
Insufficient amount to correct
Insufficient amount on authorization

HttpStatus 501 NotImplemented

CompanyNumber XXX not configured
SellerNumber XXX not configured at PayEx
CompanyNumber XXX missing configuration

HttpStatus 404 NotFound

Authorization not found

Below is an example of a problem that will be returned if acquirerBatchId is not valid.

Response

HTTP/1.1 400 Error
Content-Type: application/problem+json

{
   "Type": "http://[DNS]/ledger/card-transaction/problems/validation",
   "Title": "A validation error occurred",
   "Status": 400,
   "Instance": null,
   "Detail": "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
   "Problems": [
        {
           "additionalReferences.acquirerBatchId": "Not a valid acquirerBatchId"
        }
    ]
}

credit-account

../card-transaction

Changelog

Authorizations

Post authorizations

Get authorizations

Resource properties authorizations

Cancellations

Post cancellations

Get cancellations

Resource 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

Create reversals

Get reversals

List reversals

Resource reversals

Resource reversals properties

Corrections

Create purchase corrections

Create cash-withdrawal corrections

Create reversal corrections

Corrections resource properties

RKHA21 format

Problems