Integrate to PayEx Invoice API 

Introduction

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

1670584338716-116.png

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.
lf-api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Route segmentDescription
SubdomainIn this part of the API it will be invoice
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
InvoicesNNN (invoiceNo)
DocumentsYYY (type)

Invoice

The invoice resource is located under ledger/invoice/v1/ apiThis 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": [
    {
     "rel": "generate-invoice-portal-link",
     "method": "POST",
     "href": "/ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link"
    },
    {
     "rel": "transfer-to-account",
     "method": "POST",
     "href": "/ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account"
    }
  ],
}

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

Note! Response example below is an updated model which will be available in production on the 3rd of July 2024. 'currency' and 'invoiceDate' has been added to the response when listing invoices for a specific customer.

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,
           "currency" : "sek",
           "invoiceDate" : "2021-09-15T00:00:00",
           "dueDate" : "2021-10-01T00:00:00",
           "customerNo" : "XYZABC"
        },
        {    
           "@id" : "/ledger/invoice/v1/XXX/invoices/987654",
           "invoiceNo" : "987654",
           "status" : "open",
           "claimLevel" : "Invoice",
           "originalAmount" : 122.00,
           "currency" : "sek",
           "invoiceDate" : "2021-09-15T00:00: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,
           "currency" : "sek",
           "invoiceDate" : "2021-09-15T00:00:00",
           "dueDate" : "2020-08-01T00:00:00",
           "customerNo" : "XYZABC"
        }
    ]
}

Invoice resource properties

PropertyData typeFormatDescription
@id stringMaxlength: Uri of the specific account
createddate Date when the invoice was created in the system
invoiceNostringMaxlength: 50The identifier of the account
externalInvoiceIdstringMaxlength: 50External identifier of the invoice
statusstringMaxlength: 25Status 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
claimLevelstringMaxlength: 25Current 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
currentDebtdecimal 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)
originalAmountdecimal The original debt amount stated on the invoice.
currencystringISO 4217Currency of the invoice
invoiceDatedateISO 8601Date when the invoice was created (printed on the invoice document)
dueDatedateISO 8601Duedate of the invoice. This value does not exist for credit invoices
seller.namestring Name of the seller related to the invoice
seller.numberstring The identifier of the seller
debtobject Current debt of the invoices separated in the different debt types
   debt.capitaldecimal This value only exists if there is any capital amount
   debt.reminderFeedecimal This value only exists if there is any reminder fee (also includes businessRemiderFee)
   debt.collectionFeedecimal This value only exists if there is any collection fee
   debt.penaltyInterestdecimal This value only exists if there is any penalty interest
   debt.calculatedPenaltyInterestdecimal 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.
penaltyInterestRatedecimalPercentageyearly penalty interestrate (optional)
bankPaymentobject 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.bankAccountNostringMaxlength: 15bankaccount for payment
   bankPayment.bankAccountTypestringMaxlength: 10BankAccountTypes:
  • BKSE (swedish bank account)
  • PKSE (swedish plusgiro)
  • BGSE (swedish bankgiro)
  • PGSE (swedish plusgiro OCR)
  • BKNO (norwegian bank account)
  • BKDK (danish bank account)
   bankPayment.bicstringMaxlength: 11Bank Identifier Code (BIC)
   bankPayment.ibanstringMaxlength: 34International Bank Account Number (IBAN)
   bankPayment.paymentReferencestringMaxlength: 50

reference to specify on the payment

customerstringUriUri to the customer resource related to the invoice
transactionsstringUriList all transactions that has occured on the invoice
activePaymentOrdersstringUriView scheduled payment orders
journalstringUriLists events that has occured on the invoice
documentsstringUriView 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/852147",
           "date": "2018-11-15T00:00:00",
           "type" : "invoice",
           "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
           "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/852147/document"
        },
        {
           "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654",
           "date": "2018-11-15T00:00:00",
           "type" : "reminder",
           "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
           "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654/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/123645",
   "date": "2018-11-15T00:00:00",
   "type" : "reminder",
   "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
   "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123645/document"
}

Document resource properties

PropertyData typeFormatDescription
@idstringUri 
datedateISO 8601Date when the document was created
typestring 

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
  • BillAttachmentTypeName
    • SA   (summary)
    • SSA (Consolidated Summary)
    • SP    (Specification)
distributionMethodstring 
  • 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
documentstringUriUri 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

PropertyData typeDescription
@idstring 
typestringType of transaction
typeNamestring

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
referencestringTransaction reference
amountdecimalAmount ot the transaction
datedateDate when the transaction occured
causeobjectThis object is available when there is a specific cause to why the transaction has occured
   cause.typestringType of cause to why the transaction has occured
   cause.typeNamestringThe 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

PropertyData typeDescription
paymentMethodstringpaymentMethods:
  • autogiro
executeDateDate

The date when the customers bankaccount will be charged

amountdecimalThe 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

PropertyData typeDescription
typestringtype:
  • 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)
dateDate

The date when the journal entry occured

descriptionstringdetailed 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",
   "transactionCause" : "psp"
}

Register-direct-payment request properties

PropertyData typeRequiredDescription
amountdecimalYesThe amount of the direct payment
paymentDateDateYes

The date when the payment was made

transactionCausestringNo
  • 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

PropertyData typeRequiredDescription
debitInvoiceNostringYesinvoice number of the debit invoice that the credit invoice is to be settled against
creditAmountdecimalYes

Amount of the credit invoice to use

sendCopyboolNoWhether 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

Remission

operation to allow partialy remission of the debt. Usually used if there is a small debt left on the invoice after a payment hade been done, and the remaining amount should be offered. 

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

{
    "balanceType": "CollectionFee",      
    "amount": 12.00,
    "invoiceCurrentDebt": 12.00
}

remission request properties

PropertyData typeRequiredDescription
balanceTypestringYes

The balanceType to be affected

  • capital
  • reminderfee
  • penaltyinterest
  • collectionfee
amountdecimalYesThe amount of the specified balace type to exeute remission on
invoiceCurrentDebtdecimalYesThe amount must match the current debt (excl. Calculated interest) on the invoice.
currentDebt - debt.calculatedPenaltyInterest
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Write-down

operation to allow partialy or full write-down of the debt. the reason/cause of the write-down should be specified (affects accounting)

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

{
    "balanceType": "CollectionFee",      
    "amount": 12.00,
    "cause": "deceased",
    "invoiceCurrentDebt": 462.10
}

Write-down request properties

PropertyData typeRequiredDescription
balanceTypestringYes

The balanceType to be affected

  • Capital
  • ReminderFee
  • PenaltyInterest
  • CollectionFee
amountdecimalYesThe amount of the specified balace type to write-down
causestringYes

The cause of the write-down

  • Bankruptcy
  • Settlement
  • Deceased
  • Fraud
  • Dispute
  • Unknown

If field is null, Then defaults to "Unknown". Case-Sensitive

invoiceCurrentDebtdecimalYesThe amount must match the current debt (excl. Calculated interest) on the invoice.
currentDebt - debt.calculatedPenaltyInterest
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Respite

Resource to create or view respite

Get respite

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

{
    "validToDate": "2021-08-01",      
    "reason": "..."
}

Create respite

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

{
    "validToDate": "2021-08-01",      
    "reason": "..."
}
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

Respite request properties

PropertyData typeRequiredDescription
validToDateDateYesRespite is valid to this date
reasonstringYesReason for why the respite was created.

Active-disbursement-orders

View or create disbursement orders, only available for credit-invoices

Get active-disbursement-orders

Request
GET /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
"items" :
 [
 {
"@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456789",
"amount" : 10,
"norwegianBankAccount" : {
"accountNo" : "1234"
 }
 },
 {
"@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456788",
"amount" : 10,
"international" : {
"iban" : "123456",
"bic" : "SWED..."
 }
 },
 {
"@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456787",
"amount" : 10,
"swedishBankAccount" : {
"accountNo" : "123",
"accountType" : "BKSE | PGSE | BGSE"
 }
 },
 {
"@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456786",
"amount" : 10,
"swedishSus" : {
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
 },
"address" : {
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"coAddress" : null,
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "se"
 }
 }
 }
 ]
}

Create disbursement order towards a norwegian bank account

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "amount" : 10,
   "norwegianBankAccount" : {
     "accountNo" : "1234"
    }
}

Create disbursement order towards a international bank account (IBAN)

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "amount" : 10,
   "international" : {
       "iban" : "123456",
       "bic" : "SWED..."
    }
}

Create disbursement order towards a swedish bank account

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "amount" : 100,
   "swedishBankAccount" : {
       "accountNo" : "123",
       "accountType" : "BKSE | PGSE | BGSE"
    }
}

Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "amount" : 100,
   "swedishSus" : {
       "nationalIdentifier": {
           "regNo" : "YYYYMMDD-NNNN",
           "countryCode" : "SE"
        },
       "address" : {
           "addressee" : "Kalle Axelstopp",
           "streetAddress" : "Axelgatan 18",  
           "coAddress" : null,  
           "city" : "STOCKHOLM",
           "zipCode" : "16872",
           "countryCode" : "se",
        }
    }
}
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

Respite request properties

PropertyData typeRequiredDescription
amountdecimalYes 
norwegianBankAccountobjectNo* 
   accountNostringYes 
swedishBankAccountobjectNo* 
   clearingNostringYes 
   accountNostringYes 
internationalobjectNo* 
   ibanstringYes 
   bicstringYes 
swedishSusobjectNo* 
nationalIdentifierobjectYes 
      regNostringYes 
      countryCodestringYes 
addressobjectYes 
      addresseestringYes 
      streetAddressstringNo 
      coAddressstringNo 
      citystringYes 
      zipCodestringYes 
      countryCodestringYes 
    

* One and only one of the specified objects can be set at each request 

Transfer-to-account

operation transfer current capital debt on the invoice to a provided account. This will close the invoice.

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
     "accountNo" : "123",

}

Transfer-to-account request properties

PropertyData typeRequiredDescription
accountNostringYesaccount number to the to transfer current capital debt into
Response
HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Creates a new public available (no authorization needed) link to the targeted invoice. Default lifetime of a link is 120 days. Creating new links does not affect old links.

Request
POST /ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
}

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

{
    "invoicePortalLink": "https://public-invoice-example.com/sv/XXX?token=eyJhbGciOiJSUzI1Ni..."
}

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

Problem type (code)HttpstatusDescription
forbidden403occurs if access to method is not allowed.
customer-not-found404can occur if customernumber is part of the querystring towards invoice resource
invoice-not-found404 
missing-offer409Invoice is not a candidate for transfer-to-account. This has nothing to do with the provided Account
missing-account-for-billing-account409No account found on the provided AccountNo, can be expected on the us of transfer-to-account operation
not-acceptable-for-conversion409Invoice or account was not acceptable for transfer. This could be caused a number of parameters both on the invoice and the account.
credit-check-rejected422Score does not approve the conversion
customer-mismatch422Invoice and account is on separate customers in the transfer-to-account request
   
Created by Fredrik Nilsson on 2021/06/29 16:25