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
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
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"
}
Content-Type: application/json
{
"authorizationId": "YYY",
"@id": "/ledger/card-transaction/v1/XXX/authorizations/YYY",
"parentHREF": "/",
"operations": []
}
Get authorizations
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
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
| |
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 |
Purchases
Post purchases
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
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
List purchases
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Resource purchases
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 |
corrections | string | Uri |
Cash-withdrawals
Post cash-withdrawals
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
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
List cash-withdrawals
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Resource cash-withdrawals
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
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
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
List reversals
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Resource reversals
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
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
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
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 |
|
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.
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"
}
]
}