Integrate to PayEx Credit Account API

Todo: Saknar operation för att hitta konton som tillhör en person/ett personnummer

Changelog

2020-02-21
Transactions resource changes:

removed "billed" property on transactions resource
removed reservedate property from transactions resource
added "initiatedFromPointOfSale" property on transactions resource

2020-02-13

Changed name on resource recurring-payment-setting to recurring-payment-configuration
Adjusted propertynames om resource recurring-payment-configuration
recurringPaymentMethod -> paymentMethod
recurringPaymentScope -> paymentScope
fixedRecurringAmount -> fixedAmount

2020-02-06
Added resource "active-payment-orders"

2020-01-31
renamed resource "recurring-payment-consent" to "recurring-payment-setting" (not implemented in API yet)

Introduction

This api is used to retrieve information and to change properties related to the customer's credit 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 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
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/credit-account/v1/ api. The accounts- and its sub-resources are used to create, read and modify information related to a credit-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 specific account

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@id": "/ledger/credit-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": 50.0,
   "openBill" : "/ledger/credit-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/credit-account/v1/XXX/accounts/NNN/active-payment-orders",
   "recurringPaymentConfiguration": "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-configuration",
   "cards": "/ledger/credit-account/v1/XXX/accounts/123456/cards",
   "transactions": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions",
   "currency": "sek",
   "bills": "/ledger/credit-account/v1/XXX/accounts/NNN/bills",
   "customer": "/ledger/customers/v1/XXX/customer/123456",
   "operation" : [
        {
           "rel" : "add-card-info",
           "method" : "post",
           "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/cards"
        },
        {
           "rel" : "request-close-account",
           "method" : "post",
           "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/request-close-account"
        },
        {
           "rel" : "apply-for-raised-credit-limit",
           "method" : "post",
           "href" : "/ledger/credit-account-onboardings/v1/XXX/accounts/NNN/apply-for-raised-credit-limit"
        },
        {
           "rel" : "partial-update",
           "method" : "patch",
           "href" : "/ledger/credit-account-onboardings/v1/XXX/accounts/NNN"
        }
    ]
}

Account resource properties

Property	Data type	Format	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 PendingClose: the customer has requested the account to be closed, the account will be closed when possible. Open: the account is open and active Closed: the account has been closed
creditLimit	decimal		The creditlimit of the account, support patch operation but only lower
totalBalance	decimal		Total current sum of all balances (including capital / interest / fees, etc.)
reservedAmount	decimal		Sum of all outstanding reservations (which are valid and not captured)
availableAmount	decimal		Available credit (cannot be calculated from the above amounts as fees can be included there, which does not affect available credit)
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
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: AUTOGIRO
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

Bills

The bills resources contains all the documents produced in the accounts billing cycle.

List all bills of an account

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/bills HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@id": "/ledger/credit-account/v1/501/accounts/NNN/bills?status=open",
   "items" : [
        {
           "@id": "/ledger/credit-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",
           "activePaymentDetails": {
               "minimumAmountToBePayed": 240.00,
               "bankAccountNo": "123",
               "bankAccountType": "BGSE",
               "bic": "123456",
               "iban": "SE12345678945631",
               "paymentReference": "5465164654663",
               "paymentOrdersExists": true,
            },
           "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
        },
        {
           "@id": "/ledger/credit-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",
           "activePaymentDetails": null,
           "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
        },
        {
           "@id": "/ledger/credit-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",
           "activePaymentDetails": null,
           "document": "/ledger/credit-account/v1/XXX/accounts/NNN/bills/reminder-124645/document"
        }
    ]
}

Get specific bill

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/bills/456 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@id": "/ledger/credit-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",
   "activePaymentDetails": {
       "minimumAmountToBePayed": 240.00,
       "bankAccountNo": "123",
       "bankAccountType": "BGSE",
       "bic": "123456",
       "iban": "SE12345678945631",
       "paymentReference": "5465164654663",
       "paymentOrdersExists": true,
    },
   "document": "/ledger/credit-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: Bill Reminder1 Reminder2 Collection
status	string		"open" / "closed"
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: BKSE (swedish bankaccount) PKSE (swedish plusgiro) BGSE (swedish bankgiro) PGSE (swedish plusgiro OCR)
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

Request

POST /ledger/credit-account/v1/XXX/accounts/NNN/cards HTTP/1.1
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

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/cards HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
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/credit-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/credit-account/v1/XXX/accounts/NNN/cards/274c8699-b38f-47a2-b568-668b8837dat7"
        }
    ],
   "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards",
   "view": {
       "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/cards?$top=2&$skip=0",
       "next": "/ledger/credit-account/v1/XXX/accounts/NNN/cards?$top=2&$skip=2"
    }
}

Get a specific card

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
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/credit-account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8",
   "parentHREF": "/ledger/credit-account/v1/XXX/accounts/NNN",
   "operation" : [
        {
           "rel" : "partial-update",
           "method" : "patch",
           "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8"
        }
    ]
}

Card resource properties

Property	Data type	Format	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

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/transactions HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
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/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01",
   "view": {
       "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01&$top=2&$skip=0",
       "next": "/ledger/credit-account/v1/XXX/accounts/NNN/transactions?fromDate=2019-10-01&$top=2&$skip=2"
    }
}

Transaction resource properties

Property	Data type	Description
type	string	Type of transaction Payment Purchase Credit
description	string	Description of the transaction, for purchases it usually includes "point of sale" and "receipt reference"
amount	decimal
billed	bool	Indicates wheter a bill has been created after the transaction (ie. if the transaction is included in any bill or not)
date	date	Date when the transaction was initiated (Authorization date)

Reservations

List reservations in an account

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/reservations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 201 Created
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/credit-account/v1/XXX/accounts/NNN/reservations",
}

Reservation resource properties

Property	Data type	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

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-configuration/ HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@id" : "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-configurations",
   "paymentMethod" : "autogiro",
   "paymentScope" : "fixedRecurring",
   "fixedAmount" : 1500.00,
   "parentHREF": "/ledger/credit-account/v1/XXX/accounts/NNN",
   "operation" : [
        {
           "rel" : "partially-update-recurring-payment-consent",
           "method" : "patch",
           "href" : "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-consent"
        }
    ]
}

Update settings on an account

Execute http patch towards this resource to change how recurring payments should behave on the specified account

Request

PATCH /ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-configuration HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"paymentScope" : "billedAmount",
"fixedAmount" : 0.00
}

Recurring-payment-configuration resource properties

Property	Data type	Description
recurringMethod	string	recurringPaymentMethods: autogiro
recurringScope	string	recurringPaymentScopes: fixedRecurring (Fixed amount to debit monthly) totalDebt (Total credit-account debt will be debited) billedAmount (Only the minimum amount to pay will be debited) NotSet
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

Request

GET /ledger/credit-account/v1/XXX/accounts/NNN/active-payment-orders/ HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "operations": null,
   "items": [
        {
           "paymentMethod": "autogiro",
           "executeDate": "2020-02-15",
           "amount": 200.00
        }
    ],
   "view": {
       "@id": "/ledger/credit-account/v1/XXX/accounts/NNN/active-payment-orders?$top=2&$skip=0",
       "next": "/ledger/credit-account/v1/XXX/accounts/NNN/active-payment-orders?$top=2&$skip=2"
    }
}

Active-payment-orders resource properties

Property	Data type	Description
paymentMethod	string	paymentMethods: autogiro
executeDate	Date	The date when the payment order will be executed
amount	decimal	The amount to debit the owner of the consent

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

Response

HTTP/1.1 400 Error
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"
        }
    ]
}

credit-account

../credit-account

Changelog

Introduction

Accounts

Get a specific account

Account resource properties

Bills

List all bills of an account

Get specific bill

Bill resource properties

Cards

Add card to account

List cards on an account

Get a specific card

Card resource properties

Transactions

List transactions on an account

Transaction resource properties

Reservations

List reservations in an account

Reservation resource properties

Recurring-payment-configuration

Get settings on an account

Update settings on an account

Recurring-payment-configuration resource properties

Active-payment-orders

Get active payment orders for an account

Active-payment-orders resource properties

Problems