Integrate to PayEx Account API
Changelog
Introduction
This api is used to retrieve information and to change properties related to the customer's account.
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 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 |
Accounts | NNN |
Bills | reminder-123 bill-456 |
Cards | 954c8699-b38f-47a2-b568-668b8837dad8 274c8699-b38f-47a2-b568-668b8837dat7 |
Accounts
The accounts resource is located under ledger/account/v1/ api. The accounts- and its sub-resources are used to create, read and modify information related to a account.
The accounts resource provides an overview of the end customer's account, it contains information such as current balance, credit limit etc. The resource also contains URIs for additional sub-resources such as bills, cards, recurring payments, etc.
The following operations is supported
- Change the account credit limit
- Add extra cards
- Request cancellation of account
- Turn on/off charity donation
- Set behaviour of recurring payments
Get a list of accounts
These querystring parameters are optional. preferably select one or the other, If both accountNo and customerNo is provided in querystring accountNo have to belong to the customerNo
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"items": [
{
"@id": "/ledger/account/v1/XXX/accounts/NNN",
"accountNo": "1234567",
"startDate": "2018-05-21",
"description": null,
"accountProfileType": "accountType1 | accountType2 | accountType3 etc.",
"accountAlias" : "accountAlias1 | accountAlias2 etc.",
"customerNo" : "123789654",
"status" : "Open | PendingClose | Closed",
"creditLimit": 2000.00,
"totalBalance" : -1900.00,
"reservedAmount": 50.00,
"availableAmount": 3850.00,
"maxPaymentAmount": 51900.00,
"openBill" : "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-456",
"charityDonation": true,
"interestRate": {
"debtInterest" : 10.00,
"penaltyInterest": 15.00
},
"bankPayment": {
"bankAccountNo": "123",
"bankAccountType": "BGSE",
"bic": "123456",
"iban": "SE12345678945631",
"paymentReference": "54867165675646"
},
"activePaymentOrders": "/ledger/account/v1/XXX/accounts/NNN/active-payment-orders",
"recurringPaymentConfiguration": "/ledger/account/v1/XXX/accounts/NNN/recurring-payment-configuration",
"cards": "/ledger/account/v1/XXX/accounts/123456/cards",
"transactions": "/ledger/account/v1/XXX/accounts/NNN/transactions",
"currency": "sek",
"bills": "/ledger/account/v1/XXX/accounts/NNN/bills",
"customer": "/ledger/customers/v1/XXX/customer/123456",
"operation" : [
{
"rel" : "add-card-info",
"method" : "post",
"href" : "/ledger/account/v1/XXX/accounts/NNN/cards"
},
{
"rel" : "request-close-account",
"method" : "post",
"href" : "/ledger/account/v1/XXX/accounts/NNN/request-close-account"
},
{
"rel" : "apply-for-raised-credit-limit",
"method" : "post",
"href" : "/ledger/account-onboardings/v1/XXX/accounts/NNN/apply-for-raised-credit-limit"
},
{
"rel" : "partial-update",
"method" : "patch",
"href" : "/ledger/account-onboardings/v1/XXX/accounts/NNN"
}
]
}
],
"navigation": {
"@id": "/ledger/account/v1/XXX/accounts",
"first": "/ledger/account/v1/XXX/accounts?skip=0",
"previous": "/ledger/account/v1/XXX/accounts?skip=0"
}
}
Get a specific account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"@id": "/ledger/account/v1/XXX/accounts/NNN",
"accountNo": "1234567",
"startDate": "2018-05-21",
"description": null,
"accountProfileType": "accountType1 | accountType2 | accountType3 etc.",
"accountAlias" : "accountAlias1 | accountAlias2 etc.",
"customerNo" : "123789654",
"status" : "Open | PendingClose | Closed",
"creditLimit": 2000.00,
"totalBalance" : -1900.0,
"reservedAmount": 50.0,
"availableAmount": 3850.0,
"maxPaymentAmount": 51900.0,
"openBill" : "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-456",
"charityDonation": true,
"interestRate": {
"debtInterest" : 10.00,
"penaltyInterest": 15.00
},
"bankPayment": {
"bankAccountNo": "123",
"bankAccountType": "BGSE",
"bic": "123456",
"iban": "SE12345678945631",
"paymentReference": "54867165675646"
},
"activePaymentOrders": "/ledger/account/v1/XXX/accounts/NNN/active-payment-orders",
"recurringPaymentConfiguration": "/ledger/account/v1/XXX/accounts/NNN/recurring-payment-configuration",
"cards": "/ledger/account/v1/XXX/accounts/123456/cards",
"transactions": "/ledger/account/v1/XXX/accounts/NNN/transactions",
"currency": "sek",
"bills": "/ledger/account/v1/XXX/accounts/NNN/bills",
"customer": "/ledger/customers/v1/XXX/customer/123456",
"operation" : [
{
"rel" : "add-card-info",
"method" : "post",
"href" : "/ledger/account/v1/XXX/accounts/NNN/cards"
},
{
"rel" : "request-close-account",
"method" : "post",
"href" : "/ledger/account/v1/XXX/accounts/NNN/request-close-account"
},
{
"rel" : "apply-for-raised-credit-limit",
"method" : "post",
"href" : "/ledger/account-onboardings/v1/XXX/accounts/NNN/apply-for-raised-credit-limit"
},
{
"rel" : "partial-update",
"method" : "patch",
"href" : "/ledger/account-onboardings/v1/XXX/accounts/NNN"
}
]
}
Change charitydonation
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"charityDonation": false
}
Content-Type: application/json
Request for closing an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
Lower the creditlimit
The creditlimit can only be lowered through this patch API call. Increasing of the creditlimit requires signing and has not been implemented yet.
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"creditLimit": 2000.00
}
Content-Type: application/json
Account resource properties
Property | Data type | Format | Modify (patch) | Description |
---|---|---|---|---|
@id | string | Maxlength: | Uri of the specific account | |
accountNo | string | Maxlength: 50 | The identifier of the account | |
startDate | date | ISO 8601 | Date when the account was started | |
description | string | Maxlength: 200 | A description of the type of account | |
accountProfileType | string | Maxlength: 50 | The defined code of the accounttype, Examples: kontodebet, kontokredit, kontofaktura | |
accountAlias | string | Maxlength: 50 | A descriptive name for the account type, Examples: kontokredit1, matkonto1 | |
customerNo | string | Maxlength: 50 | Identifier of the customer (account owner) | |
status | string | Maxlength: 25 | Status of the account
| |
creditLimit | decimal | The creditlimit of the account, support patch operation but only lower. This value can only be 0 or positive. | ||
totalBalance | decimal | Total current sum of all balances (including capital / interest / fees, etc.). This value can be either positive or negative. Negative means it is a surplus and positive means it is a debt. | ||
reservedAmount | decimal | Sum of all outstanding reservations (which are valid and not captured). This value can only be positive. | ||
availableAmount | decimal | Available credit (cannot be calculated from the above amounts as fees can be included there, which does not affect available credit). This value can only be positive. | ||
maxPaymentAmount | decimal | The largest amount possible to deposit on the account at this moment. | ||
openBill | string | Uri | ||
charityDonation | bool | If donations should be made from the account | ||
interestRate.debtInterest | decimal | Percentage | yearly debt interestrate | |
interestRate.penaltyInterest | decimal | Percentage | yearly penalty interestrate | |
bankPayment | object | Details on how to make a bank payment to the account | ||
bankAccountNo | string | Bank account number for payments against the current account | ||
bankAccountType | string | Type of bank account
| ||
bic | string | BIC/SWIFT (Business Identifier Code) | ||
iban | string | IBAN (International Bank Account Number) | ||
paymentReference | string | Payment reference of the current account | ||
recurringPaymentConsent | string | Uri | ||
cards | string | Uri | ||
transactions | string | Uri | ||
currency | string | ISO 4217 | ||
bills | string | Uri | ||
customer | string | Uri | ||
activePaymentOrder.paymentMethod | string | Maxlength: 15 |
| PaymentTypes:
|
activePaymentOrder.executionDate | date | ISO 8601 | Date when the paymentorder will be executed (when end-customer will be debited) | |
activePaymentOrder.amount | decimal | Amount that will be charged, this amount may be adjusted when the payment order is executed, if the "amount to pay" on the bill has decreased | ||
Register-psp-payment
Method: POST
Execution of this operation will result in an attempt to deposit the amount on the given account.
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"Amount": 2000.00,
"PaymentDate": "2021-01-01",
"sourcePspPaymentTransactionId": "123456789"
}
Content-Type: application/json
Register-psp-payment resource properties
Property | Data type | Format | Description |
---|---|---|---|
Amount | Decimal | Amount to deposit on account, max value is found on the account resource in the property "MaxPaymentAmount". | |
PaymentDate | Date | ISO 8601 | Date of the actual payment |
sourcePspPaymentTransactionId | String | Maxlength: 50 | Unique identifier for the payment |
Bills
The bills resources contains all the documents produced in the accounts billing cycle.
List all bills of an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"@id": "/ledger/account/v1/501/accounts/NNN/bills?status=open",
"items" : [
{
"@id": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-123645",
"dueDate": "2018-12-05",
"billDate": "2018-11-15",
"billNo": "124645",
"billAmount": 240.00,
"billType" : "reminder",
"status": "open",
"externalBillId": "27",
"activePaymentDetails": {
"minimumAmountToBePayed": 240.00,
"bankAccountNo": "123",
"bankAccountType": "BGSE",
"bic": "123456",
"iban": "SE12345678945631",
"paymentReference": "5465164654663",
"paymentOrdersExists": true,
},
"document": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
},
{
"@id": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-123645",
"dueDate": "2018-12-05",
"billDate": "2018-11-15",
"billNo": "124645",
"billAmount": 240.00,
"billType" : "bill",
"status": "closed",
"externalBillId": "37",
"activePaymentDetails": null,
"document": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
},
{
"@id": "/ledger/account/v1/XXX/accounts/NNN/bills/bill-123645",
"dueDate": "2018-12-05",
"billDate": "2018-11-15",
"billNo": "124645",
"billAmount": 240.00,
"billType" : "bill",
"status": "closed",
"externalBillId": "47",
"activePaymentDetails": null,
"document": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
}
]
}
Get specific bill
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"@id": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-123645",
"dueDate": "2018-12-05",
"billDate": "2018-11-15",
"billNo": "124645",
"billAmount": 240.00,
"billType" : "reminder",
"status": "open",
"externalBillId": "42",
"activePaymentDetails": {
"minimumAmountToBePayed": 240.00,
"bankAccountNo": "123",
"bankAccountType": "BGSE",
"bic": "123456",
"iban": "SE12345678945631",
"paymentReference": "5465164654663",
"paymentOrdersExists": true,
},
"document": "/ledger/account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
}
Bill resource properties
Property | Data type | Format | Description |
---|---|---|---|
@id | string | Uri | |
dueDate | date | ISO 8601 | |
billDate | date | Date when bill was created | |
billNo | string | Maxlength: 50 | The identifier of the bill |
billAmount | decimal | the amount that is stated on the actual bill/document | |
billType | string | Maxlength: 25 | BillTypes:
|
status | string | "open" / "closed" | |
externalBillId | string | Optional external reference | |
activePaymentDetails | object | only set if status of bill is "open" | |
activePaymentDetails.minimumAmountToBePayed | decimal | The least amount to pay on the bill | |
activePaymentDetails.bankAccountNo | string | Maxlength: 15 | bankaccount for payment |
activePaymentDetails.bankAccountType | string | Maxlength: 10 | BankAccountTypes:
|
activePaymentDetails.bic | string | Maxlength: 11 | Bank Identifier Code (BIC) |
activePaymentDetails.iban | string | Maxlength: 34 | International Bank Account Number (IBAN) |
activePaymentDetails.paymentReference | string | Maxlength: 50 | reference to specify on the payment |
activePaymentDetails.paymentOrdersExists | bool | if there is an active payment order to be executed related to this bill for "recurring payments". More detailed information about the payment order can be found on the accounts resource | |
document | string | Url | Url to download pdf document |
Cards
Add card to account
Execute http post towards this resource to add a new card to the specified account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"token": "954c8699-b38f-47a2-b568-668b8837dad8",
"PanTrunc": "85479*********648",
"deleted" : false,
"mainCard": true,
"cardHolder" : {
"number" : "123465",
"name": "test testsson",
"nationalConsumerIdentifier": {
"value": "19101010-1010",
"countryCode": "SE"
}
}
}
Add replacement card
This operation is used to replace an existing card, and is therefore executed on the card to be replaced. The contract of the postbody is the same as POST towards the cards resource.
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"token": "954c8699-b38f-47a2-b568-668b8837dad8",
"PanTrunc": "85479*********648",
"deleted" : false,
"mainCard": true,
"cardHolder" : {
"number" : "123465",
"name": "test testsson",
"nationalConsumerIdentifier": {
"value": "19101010-1010",
"countryCode": "SE"
}
}
}
List cards on an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"operations": null,
"items": [
{
"token": "954c8699-b38f-47a2-b568-668b8837dad8",
"PanTrunc": "85479*********648",
"deleted" : false,
"mainCard": true,
"cardHolder" : {
"number" : "123465",
"name": "test testsson",
"nationalConsumerIdentifier": {
"value": "19101010-1010",
"countryCode": "SE"
}
},
"@id": "/ledger/account/v1/XXX/accounts/NNN/cards/741"
},
{
"token": "274c8699-b38f-47a2-b568-668b8837dat7",
"PanTrunc": "78979*********321",
"deleted" : false,
"mainCard": false,
"cardHolder" : {
"number" : "987654",
"name": "test testsson",
"nationalConsumerIdentifier": {
"value": "19101010-1010",
"countryCode": "SE"
}
},
"@id": "/ledger/account/v1/XXX/accounts/NNN/cards/274c8699-b38f-47a2-b568-668b8837dat7"
}
],
"@id": "/ledger/account/v1/XXX/accounts/NNN/cards",
"view": {
"@id": "/ledger/account/v1/XXX/accounts/NNN/cards?$top=2&$skip=0",
"next": "/ledger/account/v1/XXX/accounts/NNN/cards?$top=2&$skip=2"
}
}
Get a specific card
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"token": "954c8699-b38f-47a2-b568-668b8837dad8",
"PanTrunc": "85479*********648",
"deleted" : false,
"mainCard": true,
"cardHolder" : {
"number" : "123465",
"name": "test testsson",
"nationalConsumerIdentifier": {
"value": "19101010-1010",
"countryCode": "SE"
}
},
"@id": "/ledger/account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8",
"parentHREF": "/ledger/account/v1/XXX/accounts/NNN",
"operation" : [
{
"rel" : "partial-update",
"method" : "patch",
"href" : "/ledger/account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8"
},
{
"rel": "add-replacement-card",
"href": "/ledger/account/v1/XXX/accounts/NNN/cards/5823a2d9-34d2-4bc4-8b6d-1e27f4511363/add-replacement-card",
"method": "POST"
}
]
}
Card resource properties
Property | Data type | Format | Modify (patch) | Description |
---|---|---|---|---|
token | string | token identifier of the card | ||
panTrunc | string | truncated PAN | ||
deleted | bool | indicates wheter the card has been deleted | ||
mainCard | bool | indicated whether this card is the main card of the account (cardholder is always owner of account) | ||
cardHolder.number | string | Cardholder customernumber | ||
cardHolder.name | string | Cardholder fullname | ||
cardHolder.nationalConsumerIdentifier.value | string | YYYYMMDD-NNNC | ||
cardHolder.nationalConsumerIdentifier.countryCode | string | ISO 3166-1 alpha-2 |
Transactions
List transactions on an account
You can filter transactions by date in two different ways. Either filtering can be done by date range or by listing transactions by month.
Date range example
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Monthly example
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Standard (default last 30 days)
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"operations": null,
"items": [
{
"type": "payment",
"description": "",
"amount": 200.00,
"initiatedFromPointOfSale": false,
"date": "2019-10-09"
},
{
"type": "purchase",
"description": "testbutiken, köpref. 12345689",
"amount": 200.00,
"initiatedFromPointOfSale": true,
"date": "2019-10-09"
},
{
"type": "credit",
"description": "",
"amount": 200.00,
"initiatedFromPointOfSale": true,
"date": "2019-10-09"
}
],
"@id": "/ledger/account/v1/XXX/accounts/NNN/transactions"
}
Transaction resource properties
Property | Data type | Format | Description |
---|---|---|---|
type | string | Type of transaction
| |
description | string | Description of the transaction, for purchases it usually includes "point of sale" and "receipt reference" | |
amount | decimal | This value can be either positive or negative. Negative means decreasing debt or increasing surplus. Positive transactions increases debt or decreases surplus. | |
initiatedFromPointOfSale | bool | Indicates whether the transaction was initiated from point of sale, or else it is a "ledger" transaction that was initiated internally in the ledgersystem. | |
date | date | Date when the transaction was initiated (Authorization date) |
Reservations
List reservations in an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"operations": null,
"items": [
{
"amount": 200.00,
"description" : "",
"date": "2019-10-05",
},
{
"amount": 450.00,
"description" : "",
"date": "2019-10-02",
},
],
"@id": "/ledger/account/v1/XXX/accounts/NNN/reservations",
}
Reservation resource properties
Property | Data type | Format | Description |
---|---|---|---|
amount | decimal | ||
description | string | Description of the reservation, normally "point of sale". | |
date | date | Date when the reservation occured |
Recurring-payment-configuration
This resource contain information/settings related to how recurring payments should behave on this account.
Get settings on an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"@id" : "/ledger/account/v1/XXX/accounts/NNN/recurring-payment-configurations",
"paymentMethod" : "autogiro",
"paymentScope" : "fixedRecurring",
"fixedAmount" : 1500.00,
"parentHREF": "/ledger/account/v1/XXX/accounts/NNN",
"operation" : [
{
"rel" : "partially-update-recurring-payment-consent",
"method" : "patch",
"href" : "/ledger/account/v1/XXX/accounts/NNN/recurring-payment-consent"
}
]
}
Create settings on an account
Execute http POST towards this resource to create recurring payments configuration for specified account.
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"paymentMethod" : "autogiro",
"paymentScope" : "billedAmount",
"fixedAmount" : 0.00
}
Update settings on an account
Execute http PATCH towards this resource to update the recurring payment configuration
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"paymentScope" : "billedAmount",
"fixedAmount" : 0.00
}
Delete settings on an account
Execute http DELETE to delete the recurring payment settings for the specified account. By deleting the settings, the account will not use the consent registered on the customer for recurring payments.
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{}
Recurring-payment-configuration resource properties
Property | Data type | Format | Modify (patch) | Description |
---|---|---|---|---|
paymentMethod | string | paymentMethods:
| ||
paymentScope | string | paymentScopes:
| ||
fixedAmount | decimal | amount to monthly debit end-customers bankaccount (Only valid if recurringPaymentScope is set to "fixedRecurring") |
Active-payment-orders
This resource corresponds to an active / scheduled payment order placed against the specific account, the end-customer will be debited at the given executeDate.
Get active payment orders for an account
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Content-Type: application/json
{
"operations": null,
"items": [
{
"paymentMethod": "autogiro",
"executeDate": "2020-02-15",
"amount": 200.00
}
],
"view": {
"@id": "/ledger/account/v1/XXX/accounts/NNN/active-payment-orders?$top=2&$skip=0",
"next": "/ledger/account/v1/XXX/accounts/NNN/active-payment-orders?$top=2&$skip=2"
}
}
Active-payment-orders resource properties
Property | Data type | Format | Modify (patch) | Description |
---|---|---|---|---|
paymentMethod | string | paymentMethods:
| ||
executeDate | Date | The date when the payment order will be executed | ||
amount | decimal | The amount to debit the owner of the consent |
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.
Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation
Example
Content-Type: application/problem+json
{
"Type" : "ledger/{domain}/v1/problems/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
Problem type (code) | Httpstatus | Description |
---|---|---|
validation | 400 | occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation |
forbidden | 403 | occurs if access to method is not allowed. |
customer-not-found | 404 | can occur if customernumber is part of the querystring towards account resource |
card-not-found | 404 | |
duplicate-card-token | 409 | |
card-update-failed | 422 | |
account-not-found | 404 | |
invalid-reg-no | 400 |