PayEx Developer Portal - 3. Invoice-service

Integrate to PayEx Invoice service API

Introduction

This API is used to create new invoices on existing customers

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

Route segment	Description
Subdomain	In this part of the API it will be invoice-service
LedgerNumber	The ledger identifier/number at PayEx
InvoiceNo	Identifier of resource invoice

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

Resource	Identifier
LedgerNumber	XXX
Invoices	NNN

Invoices

This resource is used to create new invoices, both debit invoices and credit invoices

Batches of multiple invoices should be processed sequentially towards the API. Each API call is intended for the creation of a single invoice

Example of a new debit invoice

Request

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

{
  "customerNo": "2992682",
  "invoiceNo": "0000003",
  "invoiceDate": "2021-05-15",
  "preferredDueDate": "2021-06-15",
  "externalInvoiceId": "900003",
  "currency": "NOK",
  "invoiceAddress": {
     "addressee": "Annie Testsson",
     "streetAddress": "Teststreet 1",
     "zipCode": "50000",
     "city": "Testcity",
     "coAddress": "CO Bengtsson",
     "countryCode": "SE"
   },
  "distribution": null,
  "invoiceReason": {
     "invoiceReasonCode": "CAS",
     "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
   },
  "legalMonetaryTotal": {
     "payableAmount": 97.99,
     "vatInclusiveAmount": 98.01,
     "vatExclusiveAmount": 98.01
   },
  "referenceInfo": {
     "invoicePeriod": {
        "startDate": "2021-04-07",
        "endDate": "2021-04-25"
      },
     "deliveryInfo": {
        "deliveryDate": "2021-04-27",
        "deliveryAddress": {
           "addressee": "Namn på mottagre",
           "streetAddress": "Testgatan 789",
           "zipCode": "11111",
           "city": "Sthlm",
           "coAddress": "C/O Andersson",
           "countryCode": "SE"
         }
      },
     "purchaseOrderReference": "Lorem ipsum dolor sit amet",
     "salesOrderReference": "Lorem ipsum dolor sit amet",
     "buyerReference": "Lorem ipsum dolor sit amet",
     "invoicedObjectIdentifier": "Lorem ipsum do",
     "contractReference": "Lorem ipsum dolor sit amet",
     "despatchReference": "Lorem ipsum dolor sit amet",
     "receiptReference": "Lorem ipsum dolor sit amet",
     "tenderReference": "Lorem ipsum dolor sit amet",
     "projectReference": "Lorem ipsum dolor sit amet"
   },
  "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
  "invoiceSpecification": {
     "inclVat": true,
     "roundingAmount": -0.01,
     "invoiceLines": [
         {
           "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
           "amount": 98.0,
           "datePeriod": {
              "StartDate": "2021-04-21",
              "EndDate": "2021-04-25"
            },
           "gTIN": "156789123",
           "itemObjectIdentifier": "itemObjectIdentifier",
           "quantity": 1,
           "unit": "ANN",
           "unitPrice": 98.0,
           "vatCategoryCode": "AE",
           "vatRate": 10
         },
         {
           "itemDescription": "Lorem ipsum dolor sit amet",
           "amount": 0.01
         }
      ],
     "invoiceVatSpecification": {
        "vatSubTotal": [
            {
              "taxableAmount": 98.01,
              "vatAmount": 0.0,
              "vatRate": 1,
              "vatCategoryCode": "Z"
            }
         ]
      },
     "taxCurrencyVatSpecification": {
        "vatSubTotal": [
            {
              "taxableAmount": 50.0,
              "vatAmount": 5.5,
              "vatRate": 1.0,
              "vatCategoryCode": "O"
            }
         ],
        "taxCurrencyCode": "GBP",
        "exchangeRate": 1.55
      },
     "taxReduction": {
        "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
        "taxReductionAmount": 0.01
      }
   }
}

Example of a new credit invoice

Request

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

{
  "customerNo": "2992682",
  "invoiceNo": "000004",
  "invoiceDate": "2021-05-17",
  "externalInvoiceId": "900004",
  "currency": "SEK",
  "invoiceAddress": {
     "addressee": "Annie Testsson",
     "streetAddress": "Teststreet 1",
     "zipCode": "50000",
     "city": "Testcity",
     "coAddress": "CO Bengtsson",
     "countryCode": "SE"
   },
  "distribution": null,
  "invoiceReason": {
     "invoiceReasonCode": "CAS",
     "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
   },
  "legalMonetaryTotal": {
     "payableAmount": -88.0,
     "vatInclusiveAmount": -88.01,
     "vatExclusiveAmount": -88.01
   },
  "referenceInfo": {
     "invoicePeriod": {
        "startDate": "2021-04-07",
        "endDate": "2021-04-25"
      },
     "deliveryInfo": {
        "deliveryDate": "2021-04-27",
        "deliveryAddress": {
           "addressee": "Name of recipient",
           "streetAddress": "Teststreet 789",
           "zipCode": "11111",
           "city": "Testcity",
           "coAddress": "C/O Andersson",
           "countryCode": "SE"
         }
      },
     "purchaseOrderReference": "Lorem ipsum dolor sit amet",
     "salesOrderReference": "Lorem ipsum dolor sit amet",
     "buyerReference": "Lorem ipsum dolor sit amet",
     "invoicedObjectIdentifier": "Lorem ipsum do",
     "contractReference": "Lorem ipsum dolor sit amet",
     "despatchReference": "Lorem ipsum dolor sit amet",
     "receiptReference": "Lorem ipsum dolor sit amet",
     "tenderReference": "Lorem ipsum dolor sit amet",
     "projectReference": "Lorem ipsum dolor sit amet",
     "debitInvoiceReferences": [
         {
           "debitInvoiceReference": "InvoiceNo xxxx"
         }
      ]
   },
  "InvoiceNote": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
  "invoiceSpecification": {
     "inclVat": true,
     "roundingAmount": 0.01,
     "invoiceLines": [
         {
           "itemDescription": "Description of item 1",
           "amount": -88.01
         }
      ],
     "invoiceVatSpecification": {
        "vatSubTotal": [
            {
              "taxableAmount": -88.01,
              "vatAmount": 0.0,
              "vatRate": 1,
              "vatCategoryCode": "Z"
            }
         ]
      },
     "taxCurrencyVatSpecification": {
        "vatSubTotal": [
            {
              "taxableAmount": 50.0,
              "vatAmount": 5.5,
              "vatRate": 1.0,
              "vatCategoryCode": "O"
            }
         ],
        "taxCurrencyCode": "GBP",
        "exchangeRate": 1.55
      }
   }
}

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
"invoice" : "..ledger/invoice/v1/XXX/invoices/NNN",
}

Get single "create-invoice" request

Request

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

Response

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

{
   "customerNo" : "900",
   "invoiceNo" : "0000001",
   "invoiceDate": "2021-05-15",
   "preferredDueDate": "2021-06-15",
   "externalInvoiceId": "900001",
   "currency": "SEK",
   "invoiceAddress": {
       "addressee": "Annie Testsson",
       "streetAddress": "Teststreet 1",
       "zipCode": "50000",
       "city": "Testcity",
       "coAddress": "CO Bengtsson",
       "countryCode": "SE"
    },
   "distribution": null,
   "invoiceReason": {
       "invoiceReasonCode": "CAS",
       "invoiceReasonDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
    },
   "legalMonetaryTotal": {
       "payableAmount": 88.00,
       "vatInclusiveAmount": 98.01,
       "vatExclusiveAmount": 98.01
    },
   "referenceInfo": {
   "invoicePeriod": {
       "startDate": "2021-04-07",
       "endDate": "2021-04-25"
    },
   "deliveryInfo": {
       "deliveryDate": "2021-04-27",
       "deliveryAddress": {
           "addressee": "Namn på mottagre",
           "streetAddress": "Testgatan 789",
           "zipCode": "11111",
           "city": "Sthlm",
           "coAddress": "C/O Andersson",
           "countryCode": "SE"
      }
    },
   "purchaseOrderReference": "Lorem ipsum dolor sit amet",
   "salesOrderReference": "Lorem ipsum dolor sit amet",
   "buyerReference": "Lorem ipsum dolor sit amet",
   "invoicedObjectIdentifier": "Lorem ipsum do",
   "contractReference": "Lorem ipsum dolor sit amet",
   "despatchReference": "Lorem ipsum dolor sit amet",
   "receiptReference": "Lorem ipsum dolor sit amet",
   "tenderReference": "Lorem ipsum dolor sit amet",
   "projectReference": "Lorem ipsum dolor sit amet"
    },
   "InvoiceNote": "InvoiceNote-Text e Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, ",
   "invoiceSpecification": {
       "inclVat": true,
       "roundingAmount": -0.01,
       "invoiceLines": [
            {
               "itemDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
               "amount": 98.00,
               "datePeriod": {
                   "StartDate": "2021-04-21",
                   "EndDate": "2021-04-25"
                },
               "gTIN": "156789123",
               "itemObjectIdentifier": "itemObjectIdentifier",
               "quantity": 8,
               "unit": "ANN",
               "unitPrice": 10.00,
               "vatCategoryCode": "AE",
               "vatRate": 10
            },
            {
               "itemDescription": "Lorem ipsum dolor sit amet",
               "amount": 0.01
            }
        ],
       "invoiceVatSpecification": {
           "vatSubTotal": [
                {
                   "taxableAmount": 98.01,
                   "vatAmount": 0.00,
                   "vatRate": 1,
                   "vatCategoryCode": "Z"
                }
            ]
        },
       "taxCurrencyVatSpecification": {
           "vatSubTotal": [
                {
                   "taxableAmount": 50.00,
                   "vatAmount": 5.50,
                   "vatRate": 1.00,
                   "vatCategoryCode": "O"
                }
            ],
           "taxCurrencyCode": "GBP",
           "exchangeRate": 1.55
        },
        "taxReduction": {
           "taxReductionDescription": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
           "taxReductionAmount": 10
        }

    }
}

Invoice resource properties

For basic string properties, all characters included in "Basic Latin" and "Latin-1 Supplement" are generally supported unless otherwise stated in below table

Property	Data type	Format	Required	Description
customerNo	string	MinLength: 1 MaxLength: 15* numeric, 1-9	Yes	The unique identifier of the customer MaxLength may differ depending on configuration KID (Norway)
invoiceNo	string	Maxlength: 15 Regex pattern: [A-Za-z0-9\-]+	Yes	Your unique identifier/invoice number of the invoice
invoiceDate	date	ISO 8601	Yes
invoiceAddress	object		No	Optional invoice address. Only used if different from customer name and legal address
addressee	string	Maxlength: 72	Yes	Full name of addressee
streetAddress	string	Maxlength: 72	No	Street address
zipCode	string	Maxlength: 9	Yes	Zipcode conforming to country standard
city	string	Maxlength: 27	Yes	City
coAddress	string	Maxlength: 72	No	Care of address
countryCode	string	ISO 3166-1 alpha-2	Yes	Country code according to ISO 3166
preferredDueDate	date	ISO 8601	No	Used if a specific duedate is preferred. Number of days between distributiondate, wich it set by PayEx based on invoicedate and processingdate, and preferred due date must exceed minimum payment terms for the specific country. Else minimum paymentterms for the country will be used. Number of days between distributiondate, which is set by PayEx based on invoicedate and processingdate, and preferred due date, can not exceed maximum paymentterms (default 60 days), if true an ERROR is created and the customer and its invoices will be rejected.
externalInvoiceId	string	MaxLength: 50 Regex pattern: ^[a-zA-Z0-9äåöÄÅÖ/_ -.]*$	No	Additional external unique invoice identfier in accountsreceivable
distribution	string		No	Postal Email EInvoiceB2B (some optional fields will be required if this is set)* ArchiveOnly (available 2023-04-19) If no distribution is set, default distribution priority order will apply.
currency	string		Yes	Valid currency supported in Your accountsreceivable
invoiceReason	object		Yes
invoiceReasonCode	string	UNCL7161	No	Invoice reason code according to format UNCL7161
invoiceReasonDescription	string	Maxlength: 200	Yes	Description of the reason for the invoice
legalMonetaryTotal	object		Yes	Contains total amount and currency of the invoice. Positive amount is used for debit invoice. Negative amount is used for credit invoice
PayableAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: -100000000	Yes	Total amount to by payed. LegalMonetary.VatInclusiveAmount + Invoicespecification.Roundingamount - InvoiceSpecification.TaxReductionAmount
VatInclusiveAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: -100000000	Yes	Total amount inclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount + VatAmount
VatExclusiveAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: -100000000	Yes	Total amount exclusive of Vat. Equals sum of InvoiceSpecification.InvoiceVatSpecification.VatSubTotal.TaxableAmount
referenceInfo	object		No	Containing invoice reference information
invoicePeriod	object		No	Optional invoiceperiod. Used in EDI
startDate	date	ISO 8601	Yes
endDate	date	ISO 8601	Yes
deliveryInfo	object		No	Optional deliveryinformation of product/service invoiced. Also used in EDI
deliveryDate	date	ISO 8601	No
deliveryAddress	object		Yes
addressee	string	Maxlength: 72	Yes
streetAddress	string	Maxlength: 72	No
zipCode	string	Maxlength: 9	Yes
city	string	Maxlength: 27	Yes
coAddress	string	Maxlength: 72	No
countryCode	string	ISO 3166-1 alpha-2	Yes
purchaseOrderReference	string	Maxlength: 50	No	Optional unique purchase order reference issued by the Buyer. Used in EDI
salesOrderReference	string	Maxlength: 50	No	Optional sales order reference issued by Seller. Used in EDI
buyerReference	string	Maxlength: 50	No	Optional reference of who ordered the products/services. Example being the name of the person ordering, employee number or a code identifying this person or department/group. Your ref is often used for internal routing at recipient, and hence it is important to fill this element with the correct values according to the need of the recipient. Used in EDI
invoicedObjectIdentifier	string	Maxlength: 50	No	Optional identifier for an object on which the invoice is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
contractReference	string	Maxlength: 50	No	Optional reference to a purchase contract. Used in EDI
despatchReference	string	Maxlength: 50	No	Optional reference to a despatch advice. Used in EDI
receiptReference	string	Maxlength: 50	No	Optional reference to a receipt advice. Used in EDI
tenderReference	string	Maxlength: 50	No	Optional reference to the tenderer or lot, in most cases the Procurement Procedure Identifier. Used in EDI
projectReference	string	Maxlength: 50	No	Optional reference to a project. Used in EDI
debitInvoiceReferences	list		No	If creditinvoice, optional reference to debit invoice. Used in EDI
debitInvoiceReference	string	Maxlength: 50	Yes	Reference to debit invoice
invoiceNote	string	Maxlength: 250	No	A textual note that gives unstructured information that is relevant to the Invoice as a whole
invoiceSpecification	object		Yes	Contains the specification of the invoice
inclVat	bool		Yes	If True, invoiceLine.amount must include Vat. If False, invoiceLine.amount must exclude Vat. EDI-distribution requires an excl vat InvoiceSpecification
roundingAmount	decimal	Fraction digits: 2 Max size: 0.99 Min size: -0.99	No	Roundingamount +- 0.99 not affected by VAT
invoiceLines	list		Yes
itemDescription	string	Maxlength: 250	Yes	Mandatory description of the invoiced item/service
amount	decimal		Yes	Mandatory amount rounded to two decimals. inclusive or exclusive of vat dependends of setting of the boolean attribute Invoicespecification.InclVat Sum of the amounts of all invoiceLines must equal to legalMonetaryTotal.VatInclusiveAmount or VatExclusiveAmount, depending on Invoicespecification.InclVat true/false.
datePeriod	object		No	Optional date/period
startDate	date	ISO 8601	Yes
endDate	date	ISO 8601	No
gtin	string	Maxlength: 15	No	Optional global trade item identifier (GS1 GTIN)
itemObjectIdentifier	string	Maxlength: 50	No	Optional identifier for an object on which the invoiceitem is based, given by the Seller. Examples may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable. Used in EDI
quantity	decimal	Fraction digits: 5 Max size: 100000000 Min size: -100000000	No*	*This field is required if distribution is set to EInvoiceB2B Optional quantity with up to 5 decimals
unit	string	UNECERec20	No*	This field is required if distribution is set to EInvoiceB2B Optional unit of quantity according to UNECERec20 code list: C62* - Used for unit-less count (pcs) KGM - Kilogram GRM - Gram AD - Byte 2P - Kilobyte 4L - Megabyte E34 - Gigabyte E35 - Terabyte SEC - Seconds MIN - Minutes DAY - Day WEE - Week MON - Month ANN - Year
unitPrice	decimal	Fraction digits: 5 Max size: 100000000 Min size: 0	No*	*This field is required if distribution is set to EInvoiceB2B Optional unitprice with up to 5 decimals. Inclusive or exclusive of vat dependent of setting of the boolean attribute Invoicespecification.InclVat
vatCategoryCode	string		No	Optional VatCategoryCode according to UN/CEFACT code list 5305, D.16B AE - VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee E - Exempt from tax: Code specifying that taxes are not applicable S - Standard rate: Code specifying the standard rate Z - Zero rated goods: Code specifying that the goods are at a zero rate G - Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged O - Services outside scope of tax: Code specifying that taxes are not applicable to the services K - VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area
vatRate	decimal	Fraction digits: 2 Max size: 100.00 Min size: 0.00	No	Optional valid VatRate
invoiceVatSpecifications	object		Yes	Is specified once per distinct combination of VatCategoryCode and VatRate. Each combination must match sum of corresponding InvoiceLines
vatSubTotal	list		Yes	VatSubTotal is specified once per combination of VatCategoryCode and VatRate
taxableAmount	decimal	Fraction digits: 2 Min size: -100000000 Max size: 100000000	Yes
vatAmount	decimal	Fraction digits: 2 Min size: -100000000 Max size: 100000000	Yes
vatRate	decimal	percentage min: 0.00 max: 100.00	Yes	vatRate in percentage
vatCategoryCode	string		Yes	Valid values: AE - VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee E - Exempt from tax: Code specifying that taxes are not applicable S - Standard rate: Code specifying the standard rate Z - Zero rated goods: Code specifying that the goods are at a zero rate G - Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged O - Services outside scope of tax: Code specifying that taxes are not applicable to the services K - VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area
taxCurrencyVatSpecification	object		No	Used if seller tax currency is other than invoice currency
vatSubTotal	list	required 1-10 items	Yes	VatSubTotal is specified once per combination of VatCategoryCode and VatRate
taxableAmount	decimal	amount	Yes
vatAmount	decimal	amount	Yes
vatRate	decimal	percentage min: 0.00 max: 100.00	Yes	vatRate in percentage
vatCategoryCode	string		Yes	Valid values: AE - VAT Reverse Charge: Code specifying that the standard VAT rate is levied from the invoicee E - Exempt from tax: Code specifying that taxes are not applicable S - Standard rate: Code specifying the standard rate Z - Zero rated goods: Code specifying that the goods are at a zero rate G - Free export item, tax not charged: Code specifying that the item is free export and taxes are not charged O - Services outside scope of tax: Code specifying that taxes are not applicable to the services K - VAT exempt for EEA intra-community supply of goods and services. A tax category code indicating the item is VAT exempt due to an intra-community supply in the European Economic Area
taxCurrencyCode	string		Yes	The tax currency code of the seller
exchangeRate	decimal	Fraction digits: 5 Min size: 0.00001	Yes	ExchangeRate used to calculate vat in seller tax currency
taxReduction	object		No	Taxreduction used for Reversed Tax and ROT/RUT
taxReductionDescription	string	Maxlength: 250	Yes
taxReductionAmount	decimal	Fraction digits: 2 Min size: 0,01 Max size: 100000000	Yes

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

Problem type (code)	Httpstatus	Description
validation	400	occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
invoice-not-found	404

Ledger and Factoring

3. Invoice-service

Introduction

Invoices

Example of a new debit invoice

Example of a new credit invoice

Get single "create-invoice" request

Invoice resource properties

legalMonetaryTotal

referenceInfo

invoiceSpecification

Problems

Example

Problem types