Main.Invoicing.invoice-service.invoice-service-apis.Technical reference.3\. Invoice-service - 3. Invoice-service 
Page of - last modified by David Persson on 2024/04/08 12:56 
3. Invoice-service 

David Persson

2024/04/08 12:56
Table of Contents
Introduction
Invoices
Example
Problem types

Integrate to 
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

Route segment | Description
Subdomain | In this part of the API it will be
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

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

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

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

{
      "invoice" : "..ledger/invoice/v1/XXX/invoices/NNN",
}
Get single "create-invoice" request

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

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

�	
�	
�	
�	
If no distribution is set, default distribution priority  order will apply.

currency | string | | Yes | Valid currency supported in Your accountsreceivable
| 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
| object | | No | Optional invoiceperiod. Used in EDI
startDate | date | ISO 8601 | Yes |
endDate | date | ISO 8601 | Yes |
| object | | No | Optional deliveryinformation of product/service invoiced. Also used in EDI
deliveryDate | date | ISO 8601 | No |
| 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

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

Optional quantity with up to 5 decimals

unit

string

UNECERec20

No*

Optional unit of quantity according to UNECERec20 code list:
�	
�	
�	
�	
�	
�	
�	
�	
�	
�	
�	
�	
�	
�

unitPrice

decimal

Fraction digits: 5
Max size: 100000000
Min size: 0

No*

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

vatRate

decimal

Fraction digits: 2
Max size: 100.00
Min size: 0.00

No

Optional valid VatRate

| 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:
�	-
�	- 
�	- 
�	 - 
�	 - 
�	 - 
�	 -

| object | | No | Used if seller tax currency is other than invoice currency
| 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:
�	-
�	- 
�	- 
�	 - 
�	 - 
�	 - 
�	 -

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

| 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

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 |