Integrate to PayEx Ledger Card transactions API
The credit account acquiring api contains functions that are used in payment scenarios: online, in-store and offline. Before transactions can be created an account must exists.
Changelog
Authorizations
An authorization is made to try to use an account for payment. A successful authorization leads to a reservation on the account, the account is identified through the cardToken or the accountNo. The authorization is not a financial transaction, to make the financial transaction a Purchase must posted on the authorization.
Post authorizations
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"sourceAuthorizationTransactionId": "789",
"sellerNumber": "654",
"cardToken": "5646735165",
"type": "purchase|reversal|cash-withdrawal",
"pointOfSale": "Testshop",
"authorizationAmount": 300.0,
"currency": "SEK"
}
Content-Type: application/json
{
"@id": "/ledger/credit-account-acquiring/v1/XXX/authorization/YYY",
}
Get authorizations
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"sourceAuthorizationTransactionId": "789",
"authorizationId": 123,
"sellerNumber": "654",
"cardToken": "546415646315",
"accountNo": null,
"pointOfSale": "Testshop",
"validToDate": "2019-11-28",
"authorizationAmount": 300.0,
"remainingAmount" : 150.0,
"currency": "SEK",
"@id": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN",
"purchases": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases",
"cancellations": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/cancellations",
"schemaUri": "/ledger/invoice-purchase/v1/PayEx.AR.InvoicePurchase.Api.Resources.Authorizations.Resource",
"parentHREF": "/",
"operations": [
{
"rel": "create-Purchase",
"method": "post",
"href": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases"
},
{
"rel": "create-cancellation",
"method": "post",
"href": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/cancellations"
}
]
}
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 used in Purchase |
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 | |
accountNo | string | identifier of the account | |
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 | |
cancellations | string | Uri |
Purchases
Post purchases
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"sourcePurchaseTransactionId" : "534313",
"sellerReceiptId": "2019-11-28",
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313"
},
"amount": 200.0
}
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",
"sourcePurchaseTransactionId" : "534313",
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313",
},
"sellerReceiptId": "12345689",
"amount": 200.0,
"corrections": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases/YYY/corrections",
"@id": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/Purchase/YYY",
"parentHREF": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN",
"operations": [
{
"rel": "create-reversal",
"method": "post",
"href": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases/YYY/reversal"
}
]
}
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 |
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 | ||
corrections | string | Uri |
Correction
Used to reverse a Purchase transaction
Create corrections
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313",
},
"sellerReceiptId" : "534313",
"sourceReversalTransactionId" : "534313",
"amount": 200.0
}
Get corrections
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
List corrections
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Resource corrections
Content-Type: application/json
{
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313",
},
"sourceReversalTransactionId" : "534313",
"amount": 200.00,
"currency": "SEK",
"@id" : "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases/YYY/credits/ZZZ",
"parentHREF": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/purchases/YYY",
"operations" : []
}
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 |
sourceReversalTransactionId | string | Maxlength: 50 | |
amount | decimal | ||
currency | string | ISO 4217 |
Reversals
Used to refund a transaction without any reference to it.
Create reversals
Execute post towards this resource to place the amount on the specified account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"pointOfSale": "stora butiken test, köpref. 12345689",
"cardToken" : "1564316498964156",
"sellerReceiptId": "12345689",
"sellerNumber" : "654",
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313",
},
"sourceRefundTransactionId" : "534312",
"amount": 200.0,
"currency": "SEK"
}
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
{
"pointOfSale": "stora butiken test, köpref. 12345689",
"cardToken" : "1564316498964156",
"sellerReceiptId": "12345689",
"sellerNumber" : "654",
"additionalReferences":{
"acquirerBatchId": "fdsfsdfsd",
"acquirerTransactionId" : "534313",
},
"sourceRefundTransactionId" : "534313",
"amount": 200.00,
"currency": "SEK",
"@id" : "/ledger/credit-account-acquiring/v1/XXX/corrections/YYY",
"parentHREF": "",
"operations" : []
}
reversals 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 |
sourceRefundTransactionId | string | Maxlength: 50 | |
amount | decimal | ||
currency | string | ISO 4217 | |
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 | |
pointOfSale | string | Maxlength: 50 | Name of the location/point/shop of sale, will be returned in reservation resource |
sellerReceiptId | string | Maxlength: 50 |
RKHA21 format
If the original source for the transactions towards purchases/corrections/reversals/Offline-purchases 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
- SellerNumber does not match token
- CompanyNumber does not match token
HttpStatus 400 Error
- Validation: Argument required
- Validation: Invalid value
HttpStatus 422 Unprocessable entity
- Authorization declined
HttpStatus 409 Conflict
- Invoice already authorized
- Duplicate InvoiceNumber
- Authorization is cancelled
- Authorization already Purchased
- Authorization has expired
- Insufficient debited amount XXX
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 buyer.nationalConsumerIdentifier.value is not valid in the authorization post request.
Content-Type: application/problem+json
{
"Type": "http://[DNS]/ledger/invoice-purchase/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": [
{
"buyer.nationalConsumerIdentifier.value": "Not a valid SE nationalConsumerIdentifier"
}
]
}