Integrate to PayEx Account API 

Changelog

Introduction

This api is used to retrieve information and to change properties related to the customer's account.

1692966354374-564.png

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 segmentDescription
SubdomainIn this part of the API it will be account
LedgerNumberThe ledger identifier/number at PayEx
resource1IdIdentifier of resource1
resource2Ididentifier of resource2, subresource to resource1
resource3Ididentifier of resource3, subresource to resource2

Routes that occurs in examples of this documentation will use the following identifiers

ResourceIdentifier
LedgerNumberXXX
AccountsNNN
Billsreminder-123
bill-456
Cards954c8699-b38f-47a2-b568-668b8837dad8
274c8699-b38f-47a2-b568-668b8837dat7

Accounts

The accounts resource is located under ledger/account/v1/ apiThe 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

Request
GET /ledger/account/v1/XXX/accounts?accountNo=123&customerNo=456 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
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

Request
GET /ledger/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/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

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

{
   "charityDonation": false
}
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Request for closing an account

Request
POST /ledger/account/v1/XXX/accounts/NNN/request-close-account HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Response
HTTP/1.1 204 NO CONTENT
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.

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

{
   "creditLimit": 2000.00
}
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Account resource properties

PropertyData typeFormatModify (patch)Description
@id stringMaxlength:  Uri of the specific account
accountNo stringMaxlength: 50 The identifier of the account
startDate dateISO 8601 Date when the account was started
description stringMaxlength: 200 A description of the type of account
accountProfileType stringMaxlength: 50 The defined code of the accounttype, Examples: kontodebet, kontokredit, kontofaktura
accountAlias stringMaxlength: 50 A descriptive name for the account type, Examples: kontokredit1, matkonto1
customerNo stringMaxlength: 50 Identifier of the customer (account owner)
status stringMaxlength: 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. This value can only be 0 or positive.
totalBalancedecimal  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.
maxPaymentAmountdecimal  The largest amount possible to deposit on the account at this moment.
openBillstringUri  
charityDonation bool  If donations should be made from the account
interestRate.debtInterestdecimalPercentage yearly debt interestrate
interestRate.penaltyInterestdecimalPercentage yearly penalty interestrate
bankPaymentobject  Details on how to make a bank payment to the account
   bankAccountNostring  Bank account number for payments against the current account
   bankAccountTypestring  

Type of bank account

  • BGSE
  • PGSE
  • BKNO
   bicstring  BIC/SWIFT (Business Identifier Code)
   ibanstring  IBAN (International Bank Account Number)
   paymentReferencestring  Payment reference of the current account
recurringPaymentConsentstringUri  
cards stringUri  
transactions stringUri  
currency stringISO 4217  
bills stringUri  
customer stringUri  
activePaymentOrder.paymentMethodstringMaxlength: 15

 

PaymentTypes:

  • AUTOGIRO
activePaymentOrder.executionDatedateISO 8601 Date when the paymentorder will be executed (when end-customer will be debited)
activePaymentOrder.amountdecimal  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.

Access to this operation is not normally granted, unless otherwise agreed.

Request
POST /ledger/account/v1/XXX/accounts/NNN/register-psp-payment HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "Amount": 2000.00,
   "PaymentDate": "2021-01-01",
   "sourcePspPaymentTransactionId": "123456789"
}
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json
Register-psp-payment resource properties
PropertyData typeFormatDescription
AmountDecimal Amount to deposit on account, max value is found on the account resource in the property "MaxPaymentAmount".
PaymentDateDateISO 8601Date of the actual payment
sourcePspPaymentTransactionIdStringMaxlength: 50Unique identifier for the payment

Bills

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

List all bills of an account

Request
GET /ledger/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/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

Request
GET /ledger/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/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

PropertyData typeFormatDescription
@idstringUri 
dueDatedateISO 8601 
billDatedate Date when bill was created
billNostringMaxlength: 50The identifier of the bill
billAmountdecimal the amount that is stated on the actual bill/document
billTypestringMaxlength: 25

BillTypes:

  • Bill
  • Reminder1
  • Reminder2
  • Collection
statusstring 

"open" / "closed"

externalBillIdstring Optional external reference
activePaymentDetailsobject only set if status of bill is "open"
activePaymentDetails.minimumAmountToBePayeddecimal The least amount to pay on the bill
activePaymentDetails.bankAccountNostringMaxlength: 15bankaccount for payment
activePaymentDetails.bankAccountTypestringMaxlength: 10BankAccountTypes:
  • BKSE (swedish bankaccount)
  • PKSE (swedish plusgiro)
  • BGSE (swedish bankgiro)
  • PGSE (swedish plusgiro OCR)
activePaymentDetails.bicstringMaxlength: 11Bank Identifier Code (BIC)
activePaymentDetails.ibanstringMaxlength: 34International Bank Account Number (IBAN)
activePaymentDetails.paymentReferencestringMaxlength: 50reference to specify on the payment
activePaymentDetails.paymentOrdersExistsbool 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
documentstringUrlUrl 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/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"
        }
    }
}

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.

Request
POST /ledger/account/v1/XXX/accounts/NNN/cards/954c8699-b38f-47a2-b568-668b8837dad8/add-replacement-card 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/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/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

Request
GET /ledger/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/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

PropertyData typeFormatModify (patch)Description
tokenstring  token identifier of the card
panTruncstring  truncated PAN
deletedbool  indicates wheter the card has been deleted
mainCardbool  indicated whether this card is the main card of the account (cardholder is always owner of account)
cardHolder.numberstring  Cardholder customernumber
cardHolder.namestring  Cardholder fullname
cardHolder.nationalConsumerIdentifier.valuestringYYYYMMDD-NNNC  
cardHolder.nationalConsumerIdentifier.countryCodestringISO 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

Request
GET /ledger/account/v1/XXX/accounts/NNN/transactions?fromDate=2020-02-10&todate=2020-06-01 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Monthly example

Request
GET /ledger/account/v1/XXX/accounts/NNN/transactions?month=2020-04 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Standard (default last 30 days) 

Request
GET /ledger/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/account/v1/XXX/accounts/NNN/transactions"    
}

Transaction resource properties

PropertyData typeFormatDescription
typestring 

Type of transaction

  • Payment
  • Purchase
  • Credit
  • AdministrationFee
  • BillingFee
  • CollectionFee
  • Deduction
  • Disbursement
  • DisbursementReturned
  • Interest
  • LateFee
  • ReminderFee
  • MigratedBalance (Amount of the initially migrated balance on the account)
descriptionstring Description of the transaction, for purchases it usually includes "point of sale" and "receipt reference"
amountdecimal This value can be either positive or negative. Negative means decreasing debt or increasing surplus. Positive transactions increases debt or decreases surplus.
initiatedFromPointOfSalebool Indicates whether the transaction was initiated from point of sale, or else it is a "ledger" transaction that was initiated internally in the ledgersystem.
datedate Date when the transaction was initiated (Authorization date)

Reservations

List reservations in an account

Request
GET /ledger/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/account/v1/XXX/accounts/NNN/reservations",
}

Reservation resource properties

PropertyData typeFormatDescription
amountdecimal  
descriptionstring Description of the reservation, normally "point of sale".
datedate 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/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/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.

Request
POST /ledger/account/v1/XXX/accounts/NNN/recurring-payment-configuration HTTP/1.1
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

Request
PATCH /ledger/account/v1/XXX/accounts/NNN/recurring-payment-configuration HTTP/1.1
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.

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

{}

Recurring-payment-configuration resource properties

PropertyData typeFormatModify (patch)Description
paymentMethodstring  paymentMethods:
  • autogiro
paymentScopestring  

paymentScopes:

  • fixedRecurring (Fixed amount to debit monthly)
  • totalDebt (Total account debt / used credit will be debited each month)
  • billedAmount (Only the "minimum amount to pay" will be debited each month)
fixedAmountdecimal  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/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/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

PropertyData typeFormatModify (patch)Description
paymentMethodstring  paymentMethods:
  • autogiro
executeDateDate  

The date when the payment order will be executed

amountdecimal  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

Response
HTTP/1.1 400 Error
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

Note, each problem typecode is preceded by "ledger/account/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/account/v1/problems/validation".

Problem type (code)HttpstatusDescription
validation400occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
forbidden403occurs if access to method is not allowed.
customer-not-found404can occur if customernumber is part of the querystring towards account resource
card-not-found404 
duplicate-card-token409 
card-update-failed422 
account-not-found404 
invalid-reg-no400 
Created by David Persson on 2024/02/21 07:42