../credit-account

Integrate to PayEx Credit Account API 

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

Changelog

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

This api is used to retrieve information and to change properties related to the customer's credit account.
1579213343157-343.png

Introduction

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 credit-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/credit-account/v1/ apiThe 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

Requesting details of 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 | pending-close | 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", "recurringPaymentConsent": "/ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting", "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" } ] }

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
  • pending-close: 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
totalBalancedecimal  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)
openBillstringUri  
charityDonation bool  If donations should be made from the account
interestRate.debtInterestdecimalPercentage yearly debt interestrate
interestRate.penaltyInterestdecimalPercentage yearly penalty interestrate
offer stringUri  
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
     

Bills

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

Requesting list of bills belonging to a specific 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" } ] }

Requesting details of a 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" }

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"
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

recurring-payment-setting

This resource contain information/settings related to how recurring payments should behave on this account.


Requesting the resource
Request
GET /ledger/credit-account/v1/XXX/accounts/NNN/recurring-payment-setting/ 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-setting", "recurringPaymentMethod" : "autogiro", "recurringPaymentScope" : "fixedRecurring", "fixedRecurringAmount" : 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

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-setting HTTP/1.1 Host: - Authorization: Bearer <Token> Content-Type: application/json { "recurringPaymentScope" : "billedAmount", "fixedRecurringAmount" : 0.00 }
PropertyData typeFormatModify (patch)Description
recurringPaymentMethodstring  recurringPaymentMethods:
  • autogiro
recurringPaymentScopestring  

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)
fixedRecurringAmountdecimal  amount to monthly debit end-customers bankaccount (Only valid if recurringPaymentScope is set to "fixedRecurring")

Cards

Post

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

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

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" } ] }
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

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, "billed": false|true, "date": "2019-10-09", "reserveDate": null }, { "type": "purchase", "description": "testbutiken, köpref. 12345689", "amount": 200.00, "billed": false|true, "date": "2019-10-09", "reserveDate": "2019-10-05", }, { "type": "credit", "description": "", "amount": 200.00, "billed": false|true, "date": "2019-10-09", "reserveDate": "2019-10-05" } ], "@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" } }
PropertyData typeFormatDescription
typestring 

Type of transaction

  • Payment
  • Purchase
  • Credit
descriptionstring Description of the transaction, for purchases it usually includes "point of sale" and "receipt reference"
amountdecimal  
billedbool Indicates wheter a bill has been created after the transaction (ie. if the transaction is included in any bill or not)
datedate Valuedate

Reservations

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", }
PropertyData typeFormatDescription
amountdecimal  
descriptionstring Description of the reservation, normally "point of sale".
datedate Date when the reservation occured
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" } ] }
Created by Helge Dahl on 2020/02/06 17:55