## credit-account

# card-transaction

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-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 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.
api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

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 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",
"cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",
"channel": "POS|UnattendedPOS|Ecom "
}
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",
"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 (Normal transaction in store / terminal) ChipSign (Transaction made in a store / terminal where the buyer shows his identification and gives his signature) PanCvcExpr (E-com transaction. Transaction made online by entering the cards pan, cvc and expiredate) 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

Request
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

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

#### Get purchases

Request
GET /ledger/card-transaction/v1/XXX/purchases/PPP 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",
"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 (Normal transaction in store / terminal) ChipSign (Transaction made in a store / terminal where the buyer shows his identification and gives his signature) PanCvcExpr (E-com transaction. Transaction made online by entering the cards pan, cvc and expiredate) RecurringToken MagStripePin
offlineInfo.channel | string |  | Type of channel (optional) POS UnattendedPOS Ecom
corrections | string | Uri |
withdrawalAmount | decimal? |  |

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

#### Get cash-withdrawals

Request
GET /ledger/card-transaction/v1/XXX/cash-withdrawals/WWW 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",
"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

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

#### Get reversals

Request
GET /ledger/card-transaction/v1/XXX/reversals/RRR 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",
"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

Request
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

Request
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

Request
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 "type" : "purchase" | Purchase is the financial clearing-transaction describing a purchase
../purchases/../corrections | Financial Transaction | ../transactions "type" : "credit" | A correction of a purchase transaction,
../cash-withdrawals | Financial Transaction | ../transactions "type" : "purchase" | Cash-withdrawal is the financial clearing transaction describing a cash-withdrawal at point of sales. Requires special agreement.
../cash-withdrawals/../corrections | Financial Transaction | ../transactions "type" : "credit" | A correction of a cash-withdrawal transaction.
../reversals | Financial Transaction | ../transactions "type" : "credit" | Reversal is the financial clearing-transaction describing a deposit/return at point of sale
../reversals/../corrections | Financial Transaction | ../transactions "type" : "purchase" | A correction of a reversal transaction.

Complete specification of credit-account-api can be found 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][1:st character of Cycle]

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

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

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

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

Tags: px-custom-page-content
Created by David Persson on 2024/02/21 07:48