PayEx Developer Portal

Integrate to PayEx Invoice API

Introduction

This api is used to retrieve information related to the customer's invoices.

PayEx supports HTTP headers for tracking that are used for troubleshooting purposes, implement according to specification

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 invoice
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
Invoices	NNN (invoiceNo)
Documents	YYY (type)

Invoice

The invoice resource is located under ledger/invoice/v1/ api. This resource is used to get general information about existing invoices and its current state. Creation of new invoices is done through other resource.

Get specific invoice

Request

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

Response

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

{
   "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
   "created" : "2019-05-06T00:00:00",
   "invoiceNo" : "12345",
   "externalInvoiceId" : "987654321",
   "status" : "pending|open|closed",
   "claimLevel" : "Invoice|RestReminder|Reminder|SecondReminder|CollectionClaim|DebtCollection",
   "currentDebt" : 463.42,
   "originalAmount" : 354.10,
   "currency" : "sek",
   "invoiceDate" : "2018-10-01T00:00:00",
   "dueDate" : "2018-10-01T00:00:00",
   "seller" : {
       "name" : "testshop",
       "number" : "12345"
    },
   "debt" : {
       "capital" : 354.10,
       "remiderFee" : 20.00,
       "collectionFee" : 80.00,
       "penaltyInterest" : 8.00,
       "calculatedPenaltyInterest" : 1.32
    },
   "penaltyInterestRate": 15.00,
   "bankPayment": {
       "bankAccountNo": "123",
       "bankAccountType": "BGSE",
       "bic": "123456",
       "iban": "SE12345678945631",
       "paymentReference": "54867165675646"
    },
   "customer" : "/ledger/customer/v1/customers/XYZABC",
   "transactions" : "/ledger/invoice/v1/XXX/invoices/12345/transactions",
   "activePaymentOrders": "/ledger/invoice/v1/XXX/invoices/NNN/active-payment-orders",
   "journal" : "/ledger/invoice/v1/XXX/invoices/12345/journal",
   "documents": "/ledger/invoice/v1/XXX/invoices/NNN/documents",
   "operations" : null
}

Get specific customers invoices

Use the querystring parameter "customerNo" to list invoices for a specific customer.

Request

GET /ledger/invoice/v1/XXX/invoices?customerNo=XYZABC HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "items": [
        {
           "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
           "invoiceNo" : "12345",
           "status" : "pending",
           "claimLevel" : "Invoice",
           "originalAmount" : 354.10,
           "dueDate" : "2021-10-01T00:00:00",
           "customerNo" : "XYZABC"
        },
        {
           "@id" : "/ledger/invoice/v1/XXX/invoices/987654",
           "invoiceNo" : "987654",
           "status" : "open",
           "claimLevel" : "Invoice",
           "originalAmount" : 122.00,
           "dueDate" : "2020-10-01T00:00:00",
           "customerNo" : "XYZABC"
        },
        {
           "@id" : "/ledger/invoice/v1/XXX/invoices/456321",
           "invoiceNo" : "456321",
           "status" : "closed",
           "claimLevel" : "Invoice",
           "originalAmount" : 846.50,
           "dueDate" : "2020-08-01T00:00:00",
           "customerNo" : "XYZABC"
        }
    ]
}

Invoice resource properties

Property	Data type	Format	Description
@id	string	Maxlength:	Uri of the specific account
created	date		Date when the invoice was created in the system
invoiceNo	string	Maxlength: 50	The identifier of the account
externalInvoiceId	string	Maxlength: 50	External identifier of the invoice
status	string	Maxlength: 25	Status of the invoice Pending: the invoice has not been created yet, awaiting transactions Open: the invoice is open and active Closed: the invoice has been closed
claimLevel	string	Maxlength: 25	Current claim level of the invoice. Invoice: This is the first state the invoice get when it is created, it will have this state until due date is passed (and possibly later depending on companys claim process configuration) RestReminder: Reminder to pay remaining fees of the invoice (all capital has been payed) has been created/sent Reminder: First reminder to pay invoice that has been past due date has been creted/sent SecondReminder: Second reminder to pay invoice has been created/sent CollectionClaim: Debt collection claim has been created/sent to the customer DebtCollection: The invoice has been exported to other system for further handling of collection claims
currentDebt	decimal		Total current debt of all balances (including capital / interest / fees, etc.). This value can be either positive or negative. (positive value means it is a debt)
originalAmount	decimal		The original debt amount stated on the invoice.
currency	decimal	ISO 4217	Currency of the invoice
invoiceDate	date	ISO 8601	Date when the invoice was created (printed on the invoice document)
dueDate	date	ISO 8601	Duedate of the invoice. This value does not exist for credit invoices
seller.name	string		Name of the seller related to the invoice
seller.number	string		The identifier of the seller
debt	object		Current debt of the invoices separated in the different debt types
debt.capital	decimal		This value only exists if there is any capital amount
debt.reminderFee	decimal		This value only exists if there is any reminder fee (also includes businessRemiderFee)
debt.collectionFee	decimal		This value only exists if there is any collection fee
debt.penaltyInterest	decimal		This value only exists if there is any penalty interest
debt.calculatedPenaltyInterest	decimal		Todays pending calculated penalty interest. Will be valid if a payment is made today. This value only exists if there is any calculated penalty interest.
penaltyInterestRate	decimal	Percentage	yearly penalty interestrate (optional)
bankPayment	object		optional. This object is only visible if the invoice is ready to be paid. Does not exists for invoices with status "closed", or for creditinvoices
bankPayment.bankAccountNo	string	Maxlength: 15	bankaccount for payment
bankPayment.bankAccountType	string	Maxlength: 10	BankAccountTypes: BKSE (swedish bankaccount) PKSE (swedish plusgiro) BGSE (swedish bankgiro) PGSE (swedish plusgiro OCR)
bankPayment.bic	string	Maxlength: 11	Bank Identifier Code (BIC)
bankPayment.iban	string	Maxlength: 34	International Bank Account Number (IBAN)
bankPayment.paymentReference	string	Maxlength: 50	reference to specify on the payment
customer	string	Uri	Uri to the customer resource related to the invoice
transactions	string	Uri	List all transactions that has occured on the invoice
activePaymentOrders	string	Uri	View scheduled payment orders
journal	string	Uri	Lists events that has occured on the invoice
documents	string	Uri	View the actual invoice document (and other related documents), how it has been distributed etc.

Documents

The documents resources contains basic info of each invoice, reminder, letters etc. that has been produced related to the invoice. It also includes a url to download the actual document.

List all documents of an invoice

Request

GET /ledger/invoice/v1/XXX/invoices/NNN/documents HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "@id": "/ledger/invoice/v1/501/invoices/NNN/documents",
   "items" : [
        {
           "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/invoice",
           "date": "2018-11-15T00:00:00",
           "type" : "invoice",
           "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
           "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/invoice/document"
        },
        {
           "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/reminder",
           "date": "2018-11-15T00:00:00",
           "type" : "reminder",
           "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
           "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/reminder/document"
        }
    ]
}

Get specific document

Request

GET /ledger/invoice/v1/XXX/invoices/NNN/documents/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/reminder",
   "date": "2018-11-15T00:00:00",
   "type" : "reminder",
   "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
   "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/letter-123645/document"
}

Document resource properties

Property	Data type	Format	Description
@id	string	Uri
date	date	ISO 8601	Date when the document was created
type	string		Currently available types of document Invoice - the actual invoice Reminder - reminder of the invoice RestReminder - reminder of rest amounts Collection - Collection claim of the invoice CreditInvoice
distributionMethod	string		NotDistributed - the letter has been created but not distributed Postal - Distributed through usual post Kivra - Digitally distributed through Kivra EInvoice - Digitally distributed through EInvoice EMail - Digitally distributed through email
document	string	Uri	Uri to download the actual document, usually pdf (content type in response).

Transactions

This resource lists all transactions that has occured on the invoice. The resource does not support "GET" on individual transactions, only listing of all transactions.
Property "typeName" is ment to be displayed directly "as is" in a customer portal, it is translated to a readable text in the language configured on the current company.

List all transactions that has occured on an invoice

Request

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

Response

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

{
   "@id": "/ledger/invoice/v1/501/invoices/NNN/transactions",
   "items" : [
        {
           "type": "disbursement",
           "typeName": "Utbetalningsuppdrag skapat",
           "reference": "",
           "amount": 50.00,
           "date": "2019-11-09T00:00:00"
        },
        {
           "type": "payment",
           "typeName": "Betalning",
           "reference": "",
           "amount": -100.00,
           "date": "2019-11-09T00:00:00"
        },
        {
           "type": "credit",
           "typeName": "Kreditering",
           "reference": "",
           "amount": -100.00,
           "date": "2019-11-02T00:00:00",
           "cause" : {
               "type": "bankruptcy",
               "typeName": "Konkurs"
            }
        },
        {
           "type": "credit",
           "typeName": "Kreditering",
           "reference": "korrigering dröjsmålsränta",
           "amount": -00.85,
           "date": "2019-11-02T00:00:00",
           "cause" : {
               "type": "remission",
               "typeName": "Efterskänkes"
            }
        },
        {
           "type": "credit",
           "typeName": "Kreditering",
           "reference": "reglering mot kreditfaktura NNN",
           "amount": -100.00,
           "date": "2019-11-02T00:00:00",
        },
        {
           "type": "collectionFee",
           "typeName": "Inkassoavgift",
           "reference": "",
           "amount": 180.00,
           "date": "2019-11-02T00:00:00",
        },
        {
           "type": "reminderFee",
           "typeName": "Påminnelseavgift",
           "reference": "",
           "amount": 30.00,
           "date": "2019-11-02T00:00:00",
        },
        {
           "type": "interest",
           "typeName": "ränta",
           "reference": "",
           "amount": 2.00,
           "date": "2019-11-02T00:00:00",
        },
        {
           "type": "invoice",
           "typeName": "Faktura",
           "reference": "butiksnamn, Orderref. 345",
           "amount": 200.00,
           "date": "2020-10-09T00:00:00"
        }
    ]
}

Transaction resource properties

Property	Data type	Description
@id	string
type	string	Type of transaction
typeName	string	The type of transaction in form of a readable translated text (the local language of the current company) The following types can occur on a invoice Invoice (the transaction that is the basis for the invoice) CreditInvoice (the transaction that is the basis for the credit invoice) Credit (credited amount) Interest Payment Disbursement (If, for example, a surplus occur on the invoice, it can be paid out) DisbursementReturned (amount that failed to be paid out for any reason is returned on the invoice) InvoiceFee ReminderFee CollectionFee
reference	string	Transaction reference
amount	decimal	Amount ot the transaction
date	date	Date when the transaction occured
cause	object	This object is available when there is a specific cause to why the transaction has occured
cause.type	string	Type of cause to why the transaction has occured
cause.typeName	string	The type of cause in form of a readable translated text (in the local language of the current company)

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/invoice/v1/XXX/invoices/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
        }
    ]
}

Active-payment-orders resource properties

Property	Data type	Description
paymentMethod	string	paymentMethods: autogiro
executeDate	Date	The date when the customers bankaccount will be charged
amount	decimal	The amount that will be withdrawn from the bankaccount

Journal

This resource lists all events that has occured on the invoice, in a sorted timeline.

Get journal entries for the invoice

Request

GET /ledger/invoice/v1/XXX/invoices/NNN/journal/ 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": "ComplaintReceived",
           "date" : "2020-09-01T00:00:00",
           "description" : ""
        },
        {
           "type": "SecondReminderSent",
           "date" : "2020-09-01T00:00:00",
           "description" : ""
        },
        {
           "type": "ReminderSent",
           "date" : "2020-09-01T00:00:00",
           "description" : ""
        }
    ],
   "view": {
       "@id": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=0",
       "next": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=2"
    }
}

Journal resource properties

Property	Data type	Description
type	string	type: ReminderSent (an invoice reminder has been sent to the customer) SecondReminderSent (a second invoice reminder has been sent to the customer) CollectionClaimSent (a collection claim has been sent to the customer) RestReminderSent (a reminder including only interest and fees has been sent to the customer) DebtCollection (the invoice has been transferred to collection) Respite (the claim is stopped for further claimprocess steps until valid to data of respite or respite is removed) RespiteRemoved (respite has been removed fro claim) Stop (the claim is stopped for further claim process steps until stop is removed) StopRemoved (stop has been removed from claim) ComplaintReceived (complaint has been registered) ComplaintResolved (complaint has been resolved) InvoiceClosed (status of the invoice in the accounts receivable has been set to closed) PaymentOrderFailed (scheduled paymentorder failed to be executed)
date	Date	The date when the journal entry occured
description	string	detailed description of the entry (if available)

Register direct payment

operation for registration of direct payments against invoices

Request

POST /ledger/invoice/v1/XXX/invoices/NNN/register-direct-payment HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "amount" : 100.00,
   "paymentDate" : "2021-04-27",
   "cause" : "psp"
}

Register-direct-payment request properties

Property	Data type	Required	Description
amount	decimal	Yes	The amount of the direct payment
paymentDate	Date	Yes	The date when the payment was made
cause	string	No	psp

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Settle-credit-invoice

operation to settle an existing credit invoice towards debit invoice. This operation is only be available/valid on credit-invoices

Request

POST /ledger/invoice/v1/XXX/invoices/NNN/settle-credit-invoice HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
    "debitInvoiceNo": "12345",
    "creditAmount": 250.00,
    "sendCopy": false
}

Settle-credit-invoice request properties

Property	Data type	Required	Description
debitInvoiceNo	string	Yes	invoice number of the debit invoice that the credit invoice is to be settled against
creditAmount	decimal	Yes	Amount of he credit invoice to use
sendCopy	bool	No	Whether a new copy should be distributed to the end-customer with updated balances (after settlement has been executed) Default false

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

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.invoice.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.invoice." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.invoice.validation".

Problem type (code)	Httpstatus	Description
customer-not-found	404	can occur if customernumber is part of the querystring towards invoice resource
invoice-not-found	404

Ledger and Factoring

4. Invoice

Introduction

Invoice

Get specific invoice

Get specific customers invoices

Invoice resource properties

Documents

List all documents of an invoice

Get specific document

Document resource properties

Transactions

List all transactions that has occured on an invoice

Transaction resource properties

Active payment orders

Get active payment orders for an account

Active-payment-orders resource properties

Journal

Get journal entries for the invoice

Journal resource properties

Register direct payment

Register-direct-payment request properties

Settle-credit-invoice

Settle-credit-invoice request properties

Problems

Example

Problem types