Main.credit-account.api.card-transaction - card-transaction 
Page of - last modified by David Persson on 2024/02/21 07:48 
card-transaction 

David Persson

2024/02/21 07:48
Table of Contents
Changelog
Summary
Route description
Authorizations
Cancellations
Purchases
Cash-withdrawals
Reversals
Corrections
Mapping card-transaction to credit-account
RKHA21 format
Problems
Example
Problem types

  
Integrate to 
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  and 
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 transaction api is used for making card payments against credit-accounts, it uses card terminology. All card transactions ends up on a credit-account that maintains all balances. Complete mapping of the card-transactions to the account.
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.

Route segment	Description	
Subdomain	In this part of the API it will be credit-account	
LedgerNumber	The ledger identifier/number at PayEx	
resource1Id	Identifier of resource1	
resource2Id	identifier of resource2, subresource to resource1	
resource3Id	identifier of resource3, subresource to resource2	
Routes that occurs in examples of this documentation will use the following identifiers
Resource	Identifier	
LedgerNumber	XXX	
AuthorizationId	YYY	
SourcePurchaseTransactionId	PPP	
SourceCashWithdrawalTransactionId	WWW	
SourceReversalTransactionId	RRR	
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  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

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",
      "cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",
      "channel": "POS|UnattendedPOS|Ecom  "
}

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

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

Get authorizations

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",
      "cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",
      "channel": "POS|UnattendedPOS|Ecom  ",
      "@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)
Used for idempotency	
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	  	
cardAuthenticationMethod	string	  	Method of authentication (optional)
�	ChipPin 
�	ChipSign
�	PanCvcExpr
�	RecurringToken
�	MagStripePin	
channel	string	  	Type of channel (optional)
�	POS  
�	UnattendedPOS  
�	Ecom  	

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

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

{
"cancellationDate" : "2019-11-20"
}
Resource properties cancellations
Property	Data type	Format	Description	
@id  	string	Uri	  	
cancellationDate	date	ISO 8601	    Date when the cancellation was made	

Purchases
Post purchases

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",
      "pointOfSale": "Testshop",
      "offlineInfo" : {
              "pointOfSale": "Testshop",
              "cardToken": "5646735165",
              "sellerNumber": "654",
              "currency": "SEK",
              "cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",
              "channel": "POS|UnattendedPOS|Ecom  "
        }
}
Get purchases

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

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

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",
      "pointOfSale": "Testshop",
      "offlineInfo" : {
              "pointOfSale": "Testshop",
              "cardToken": "5646735165",
              "sellerNumber": "654",
              "currency": "SEK",
              "cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",
              "channel": "POS|UnattendedPOS|Ecom  "
        },
      "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
Used for idempotency	
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. Equals field "BABS reference number" position 18-28 in the RKHAS400 Original transaction	
sellerReceiptId	string	Maxlength: 50	Equals field ”Retrieval reference number” position 333-344 in the RKHAS400 Original transaction	
amount	decimal	  	  	
date	date	ISO 8601	valuedate of the transaction	
pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale. This new property will replace the below property, however both should be set in an transition period.	
offlineInfo.pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale, will be returned in reservation resource. This property is to be removed after the above property (PointOfSale) has been fully implemented in all systems (VAS/PxR), but should be set as before until then.	
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	  	
offlineInfo.cardAuthenticationMethod	string	  	Method of authentication (optional)
�	ChipPin 
�	ChipSign
�	PanCvcExpr
�	RecurringToken
�	MagStripePin	
offlineInfo.channel	string	  	Type of channel (optional)
�	POS  
�	UnattendedPOS  
�	Ecom  	
corrections	string	Uri	  	
withdrawalAmount	decimal?	  	  	

Cash-withdrawals
Post cash-withdrawals

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",
      "pointOfSale": "Testshop"
}
Get cash-withdrawals

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

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

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",
      "pointOfSale": "Testshop",
      "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. Used for idempotency	
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	
pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale	
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

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",
      "pointOfSale": "Testshop"
}
Get reversals

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

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

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",
      "pointOfSale": "Testshop",
      "@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	Equals field ”Retrieval reference number” position 333-344 in the RKHAS400 Original 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. Equals field "BABS reference number" position 18-28 in the RKHAS400 Original transaction	
sourceReversalTransactionId	string	Maxlength: 50	Unique identifier of the Reversal transaction. Used for idempotency	
amount	decimal	  	  	
date	date	ISO 8601	valuedate of the transaction	
pointOfSale	string	Maxlength: 50	Name of the location/point/shop of sale.	
Corrections
Each type of transactions can be corrected by making a POST call against its correction resource
Create purchase corrections

POST /ledger/card-transaction/v1/XXX/purchases/PPP/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

POST /ledger/card-transaction/v1/XXX/cash-withdrawals/WWW/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

POST /ledger/card-transaction/v1/XXX/reversals/RRR/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	Unique identifier of the correction transaction. Used for idempotency	
amount	decimal	  	  	
date	date	ISO 8601	valuedate of the transaction	
Mapping card-transaction to credit-account
Card Transaction Api (this api)	Type	Credit Account Api	Description	
../authorizations	Authorization	../reservations	Successful authorizations will end up as reservations in the credit-account api. The credit account/accounts api will also include a property with the total reservation amount that has not yet received a corresponding financial transaction in the "reservedAmount" property.  	
../authorization/../cancellations	Authorization	n/a	Cancellations are used to free up authorizations/reservations, if the consumer of the api know that a financial transaction will not occur. Authorizations automatically times-out after a configurable time.	
../purchases	Financial Transaction	../transactions 	Purchase is the financial clearing-transaction   describing a purchase	
../purchases/../corrections	Financial Transaction	../transactions 	A correction of a purchase transaction,  	
../cash-withdrawals	Financial Transaction	../transactions 	Cash-withdrawal is the financial clearing transaction describing a cash-withdrawal at point of sales. 	
../cash-withdrawals/../corrections	Financial Transaction	../transactions 	A correction of a cash-withdrawal transaction.	
../reversals	Financial Transaction	../transactions 	Reversal is the financial clearing-transaction   describing a deposit/return at point of sale	
../reversals/../corrections	Financial Transaction	../transactions 	A correction of a reversal transaction.	
here.
Financial card-transactions will end up on the account-statement/bill, along with other financial transactions associated to the account.
Financial card-transactions of type purchase that do not have a corresponding authorization are usually subject to liability shift, meaning that if the transaction I disputed by the consumer the financial risk is held by the merchants.
Financial card-transactions are batch processed in clearing files and do not occur in real time.  
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][ character of Cycle]
For the example values in the table below the AcquirerBatchId will be "".

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 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
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

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

{
    "Type" : "ledger.card-transaction.validation",
    "Title" : "A validation error occurred",
    "Status" : 400,
    "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
    "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
    "Problems" : [
            {
                "amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
            }
      ]
}
Problem types
Note, each problem typecode is preceded by "ledger.card-transaction." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.card-transaction.validation".
Problem type (code)	Httpstatus	Description	
validation	400	occurs if any of the inputvalidation fails	
card-token-not-found	400	Occurs on post towards "authorizations" when no card could be found according to the specified cardToken.	
seller-no-not-registered	501	  	
currency-not-supported	422	  	
company-not-configured	501	  	
duplicate-authorization	409	occurs if specified SourceAuthorizationTransactionId hase already has been used on another authorization	
duplicate-transaction-reference	409	occurs if any of the references that is required to be unique already has been used on another transaction of the same type	
insufficient-funds	409	occurs if there is not enough funds in the account. Depending on the type of account, the reason may be that there is not enough prepaid funds or that the total debt (including the new authorization) exceeds the creditlimit of the account	
authorization-not-found	422	occurs when trying to execute purchase (or other transaction) on authorization that does not exists	
authorization-has-been-used	409	the referenced authorization has already been used (captured)	
authorization-not-active	409	transaction cannot be executed toward the specified authorization since it is not active	
authorization-expired	422	transaction cannot be executed toward the specified authorization since it has expired	
cancel-authorization-prohibited	422	cancellation cannot be made on the specified authorization (for any reason)	
authorization-type-invalid	409	Occurs when trying to execute transaction on authorization of an another type (i.e. purchase transaction towards authorization of type reversal)	
account-blocked	409	Occurs when trying to execute transaction on an account with a claim level blocked for new purchases.