PayEx Developer Portal

Integrate to PayEx Customer API

Introduction

This api is used to create/read customers or change properties related to the customer.

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

Route segment	Description
Subdomain	In this part of the API it will be customer
LedgerNumber	The ledger identifier/number at PayEx
resource1Id	Identifier of resource1
resource2Id	identifier of resource2, subresource to resource1

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

Resource	Identifier
LedgerNumber	XXX
Customer	NNN (CustomerNo)

Changelog

2023-01-17
Added surpluses property to the Customer resource with planned release 2024-01-23

2023-11-27
Added new resource Surpluses & added a general 404 not-found to problems list.

2024-04-26

Added TaxIdentificationNumber to the Customer resource with planned release 2024-05-28

2024-05-15

Added Consent and underlying resources with planned release 2024-05-28. Updated Introduction API overview visual.

2025-02-14

Added operation Update-Kyc-Answers and updates to the Customer resource Operations list to reflect that. Planned release 2025-03-04

Added resource Kyc-Questions. Planned release 2025-03-04

Customer

The customer resource is located under ledger/customer/v1/ api. The customer- and its sub-resources are used to create, read and modify information related to customers.

Get a specific customer

Request

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

Response

Get a specific customer using $expand

if the entire customer model is needed, you can expand property references to other resources, in this example to get the customer model including the addresses on a single call.

Performance is affected when expand is used as more resources are retrieved. Only use $expand if you always need the referenced properties, otherwise it should be retrevied on demand.

Request

GET /ledger/customer/v1/XXX/customers/NNN?$expand=legaladdress,billingaddress HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "@id" : "/ledger/customer/v1/XXX/customers/9999",
   "customerNo" : "9999",
   "nationalIdentifier": {
     "regNo" : "YYYYMMDD-NNNN",
     "countryCode" : "SE"
    },
   "vatNo" : "SE101010101001",
   "legalEntity" : "consumer|business",
   "name" : "Britt-Marie Axelstopp",
   "emailAddress" : "britt@axelstopp.com",
   "protectedIdentity": false,
   "preferredLanguageCode": "SV",
   "legalStatus": "active",
   "msisdn" : "+91485918841",
   "activeConsents": [
       "Betalingsservice",
       "Avtalegiro"
    ],
   "eDIAddressInfo" : {
     "VAN": "ABCXYZ",
     "InterChangeRecipient": "Recipient_ID1",
     "BuyerId": "123456"
    },
   "legalAddress" : {
       "addressee" : "Britt-Marie Axelstopp",
       "streetAddress" : "The street 18",
       "coAddress" : "c/o Jansson",
       "city" : "STOCKHOLM",
       "zipCode" : "15961",
       "countryCode" : "SE",
       "operations" :
            [
                {
                   "rel" : "update",
                   "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
                   "method" : "PUT"
                },
                            {
                   "rel" : "update-legal-address-from-population-register",
                   "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
                   "method" : "POST"
                }
            ]
    },
   "billingAddress" : {
       "addressee" : "Kalle Axelstopp",
       "streetAddress" : "Axelgatan 18",
       "city" : "STOCKHOLM",
       "zipCode" : "16872",
       "countryCode" : "se",
       "operations" :
            [
                {
                   "rel" : "update",
                   "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
                   "method" : "PUT"
                },
                {
                   "rel" : "delete",
                   "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
                   "method" : "DELETE"
                }
            ]
    },
   "surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",
   "operations" :
    [
        {
           "rel" : "add-billing-address",
           "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
           "method" : "POST"
        }
    ]
}

Create new customer

Important to note!

Standard length of customerNo in Norway and Denmark is 7 characters (numeric only).
Only use numeric characters and not with a leading zero for customerNo in Sweden, in order to use AutoGiro (Direct Debit).
Dependency to legalEntity:
- Late fee will be added instead of reminder fee or collection claim fee when legalEntity is set to "business" (if specially contracted with PayEx and configured in ledger).
- SSN (regNo) for private individuals will not be displayed in ledger reports due to GDPR. regNO will only be displayed when legalEntity is set till "business".
- When invoice/claim is distributed by e-mail: If legalEntity is set to "consumer" the e-mail message will only include a link to PayEx Invoice Portal where the invoice/claim is available, otherwise a copy of the invoice/claim will be added in the e-mail message as a pdf-file.
- Finland only: Different claim processes will be used depending on "consumer" or "business".

A new customer is created by making a POST call to the API.
See below table of properties that is supported when creating a new customer. The table below also reflects what properties you can expect when retreiving a customer through a "GET" request.

Property	Required	Comment *
customerNo	Yes*	Normally required, exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case CustomerNo must not be set in request.
nationalIdentifier	No*	Normally optional, exception is when the configuration on the ledger is set for payex to generate customer numbers, in that case nationalIdentifier is required.
nationalIdentifier.regNo	Yes
nationalIdentifier.countryCode	Yes
vatNo	No*	Required if reverse tax is used
legalEntity	No
name	Yes
preferredLanguageCode	No
emailAddress	No
msisdn	No
protectedIdentity	No
distributionType	No
taxIdentificationNumber	No
eDIAddressInfo	No
eDIAddressInfo.van	No*	This field is required for distribution method EInvoiceB2B (EDI) to be used
eDIAddressInfo.interChangeRecipient	No
eDIAddressInfo.BuyerId	Yes
legalAddress	Yes
addressee	Yes
streetAddress	No
coAddress	No
city	Yes
zipCode	Yes
countryCode	Yes
billingAddress	No
addressee	Yes
streetAddress	No
coAddress	No
city	Yes
zipCode	Yes
countryCode	Yes

Examples

Standard create customer

Request

POST /ledger/customer/v1/XXX/customers HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "customerNo" : "9999",
   "nationalIdentifier": {
     "regNo" : "YYYYMMDD-NNNN",
     "countryCode" : "SE"
    },
   "vatNo" : "SE101010101001",
   "legalEntity" : "consumer|business",
   "name" : "Britt-Marie Axelstopp",
   "emailAddress" : "britt@axelstopp.com",
   "msisdn" : "+91485918841",
   "eDIAddressInfo" : {
     "VAN": "ABCXYZ",
     "InterChangeRecipient": "Recipient_ID1",
     "BuyerId": "123456"
    },
   "legalAddress" : {
       "addressee" : "Britt-Marie Axelstopp",
       "streetAddress" : "The street 18",
       "coAddress" : "c/o Jansson",
       "city" : "STOCKHOLM",
       "zipCode" : "15961",
       "countryCode" : "SE"
    },
   "distributionType": "postal",
   "taxIdentificationNumber" : "123456789"
}

Response

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

{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Create customer with billing-address

Request

POST /ledger/customer/v1/XXX/customers HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "customerNo" : "9999",
   "nationalIdentifier": {
     "regNo" : "YYYYMMDD-NNNN",
     "countryCode" : "SE"
    },
   "vatNo" : "SE101010101001",
   "legalEntity" : "consumer|business",
   "name" : "Britt-Marie Axelstopp",
   "emailAddress" : "britt@axelstopp.com",
   "msisdn" : "+91485918841",
   "eDIAddressInfo" : {
     "VAN": "ABCXYZ",
     "InterChangeRecipient": "Recipient_ID1",
     "BuyerId": "123456"
    },
   "legalAddress" : {
       "addressee" : "Britt-Marie Axelstopp",
       "streetAddress" : "The street 18",
       "coAddress" : "c/o Jansson",
       "city" : "STOCKHOLM",
       "zipCode" : "15961",
       "countryCode" : "SE"
    },
   "billingAddress" : {
       "addressee" : "Kalle Axelstopp",
       "streetAddress" : "Axelgatan 18",
       "city" : "STOCKHOLM",
       "zipCode" : "16872",
       "countryCode" : "SE"
    }
}

Response

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

{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Update customer

Some properties of the customer can be updated through this API. Properties will only be updated if included in the request. To delete a property, for example, the property must be included in the request and have the value set to null (see examples below).

The following customer properties is possible to update through a patch call

Property
emailAddress
legalStatus
preferredLanguageCode
protectedIdentity
msisdn
distributionType
taxIdentificationNumber
eDIAddressInfo
eDIAddressInfo.van
eDIAddressInfo.interChangeRecipient
eDIAddressInfo.BuyerId

Examples

Update all properties

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "emailAddress" : "britt@axelstopp.com",
   "protectedIdentity": false,
   "preferredLanguageCode": "SV",
   "legalStatus": "active",
   "msisdn" : "+91485918841",
   "eDIAddressInfo" : {
     "VAN": "ABCXYZ",
     "InterChangeRecipient": "Recipient_ID1",
     "BuyerId": "123456"
    },
   "distributionType": "postal",
   "taxIdentificationNumber" : "987654321"
}

Update only emailAddress

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"emailAddress" : "britt@axelstopp.com"
}

Update emailAddress and delete msisdn

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"emailAddress" : "britt@axelstopp.com",
"msisdn" : null
}

Remove EDIAddressInfo on a customer

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"eDIAddressInfo" : null
}

Customer resource properties

Property	Data type	Format	Description
@id	string		Uri of the specific customer
customerNo	string	MinLength: 1 MaxLength: 15* numeric, 1-9	The unique identifier of the customer MaxLength may differ depending on configuration KID (Norway)
nationalIdentifier	object
nationalIdentifier.regNo	string	Country specific	Sweden: YYYYMMDD-NNNC Norway: DDMMYYNNNNN
nationalIdentifier.countryCode	string	ISO 3166-1 alpha-2
vatNo	string	MinLength: 7 MaxLength: 17 Regex pattern: [A-Z]{2}.*	Customer VAT registration number. Mandatory if reverse tax is used. Must conform to country specific algorithm
legalEntity	string		Valid values: "consumer" "business"
name	string	Maxlength: 72 Regex?	Full name of end-customer
emailAddress	string	Maxlength: 254 Regex pattern: [^@]+@[^\.]+\..+
protectedIdentity	bool		Set to true if the customer has protected identity Postal distribution will be handled by "Skatteverket". Only supported in Sweden
preferredLanguageCode	string		Valid values: SV NO DA FI EN
legalStatus	string		Valid values: active deceased
msisdn	string	Maxlength: 15 Minlength: 5 +NNNN	"Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number Countrycode is always required as the example below +46720000000
distributionType	string		Sets distribution type. Allowed values are: postal noDistribution
taxIdentificationNumber	string	Maxlength: 20 Minlength: 1	Is an identification number used by the Internal Revenue Service (IRS) in the administration of tax laws
activeConsents	object		List of strings with possible values: Autogiro Avtalegiro Betalingsservice RecurringCard RecurringInvoiceToken EInvoice Kivra EBoks
eDIAddressInfo	object		EDI addressing info
eDIAddressInfo.van	string	Maxlength: 255	Buyer VAN identifier (OperatorId)
eDIAddressInfo.interChangeRecipient	string	Maxlength: 13	Routing address. EAN
eDIAddressInfo.BuyerId	string	Maxlength: 13	NAD_BY/Buyerparty. EAN/Corporate identity number
legalAddress	uri		reference to the customers legal address
billingAddress	uri		reference to the customer billing address
surpluses	uri		reference to the customer surpluses

Operations

Depending on the current permissions the following operations is supported on the customer resource

add-billing-address

Method: POST
This operation will be available if no billing-address exists on the customer, see billing-address resource for more details

Update-kyc-answers

Create Update-kyc-answer

When exposed on customer resources operations list it's a indication previous KYC answers up for renewal. Able update KYC with this operation even if current aren't expired but won't be suggested on the customer resource

Request

POST /ledger/customer/v1/{ownerNo}/customers/{customerNo}/update-kyc-answers HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"answers": [
    {
     "questionCode": "taxable_outside_sweden",
     "answerCode": "no"
    },
    {
     "questionCode": "multiple_citizenship",
     "answerCode": "yes"
    },
    {
     "questionCode": "citizen_ship_country_codes",
     "answerCode": "SWE"
    },
    {
     "questionCode": "citizen_ship_country_codes",
     "answerCode": "NOR"
    }
  ]
}

Request object specification

Property	Data type	Required	Description
answers	array	Yes
questionCode	string	Yes	The code definition of the question
answerCode	string	Yes	The code definition of the answer

Response

HTTP/1.1 204 NoContent
Content-Type: application/json
{}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if the validation of the request fails, it is described in the problem why the input is invalid.
404	not-found	Occurs if the customer found or if kyc is not configured on this ledger.
409	kyc-configuration	Occurs if ledger is not currently configured for KYC
500	fatal	Unexpected error, logs may give details about the problem

Surpluses

A surplus is the remaining value from a payment that was greater than the current debt, also referred as an 'overpayment'. Each instance of an overpayment will create a new surplus. A surplus will often have a connection to an account or invoice based of where the payment was placed but surpluses without connection to an account or invoice also exist. Surpluses can be used to settle upcoming debt or be disbursed.

Get specified Surplus information

Request

GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
  "surplusId": "YYY",
  "balance": 10.00,
  "currency": "SEK",
  "date": "2023-01-01T00:00:00",
  "status": "open",
  "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
  "account": "/ledger/account/v1/XXX/accounts/BBB",
  "operations": [],
  "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY"

Get list of Surpluses Information

Request

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

Response

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

{
   "items": [
        {
         "surplusId": "123",
         "balance": 10.00,
         "currency": "SEK",
         "date": "2023-01-01T00:00:00",
         "status": "open",
         "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
         "operations": [],
         "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/123"

        },
        {
         "surplusId": "456",
         "balance": 20.00,
         "currency": "SEK",
         "date": "2023-01-02T00:00:00",
         "status": "pending-disbursement",
         "account": "/ledger/account/v1/XXX/accounts/BBB",
         "operations": [],
         "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/456"

        },
        {
         "surplusId": "789",
         "balance": 30.00,
         "currency": "SEK",
         "date": "2023-01-03T00:00:00",
         "status": "pending-regulate",
         "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
         "operations": [],
         "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/789"

        }
    ],
   "navigation": {
       "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses",
       "first": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0",
       "previous": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0"
    }
}

Surpluses resource properties

Property	Data type	Format	Description
@id	string	Maxlength:	Uri of the specific surplus
surplusId	string	Maxlength: 50	Value is not considered case sensitive
balance	string		Amount value for the surplus, always a positive value
currency	string	ISO 4217
date	date	yyyy-MM-ddTHH:mm:ss	Surplus creation date
status	string		Expected statuses: open \| pending-disbursement \| pending-regulate After a surplus has been depleted it will no longer be returned from the API
invoice	string		Relative Uri to the connected source of the surplus through the Invoice API. A surplus can have a connection to an account or invoice but not both.
account	string		Relative Uri to the connected source of the surplus through the Account API. A surplus can have a connection to an account or invoice but not both.

Active-Disbursement-Orders

This shows if current surplus has been ordered to disburse the surplus to the end customer.

Get active disbursement orders

Request

GET /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/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": [
        {
           "operations": [],
           "swedishBankAccount": {
               "accountNo": "3300-1010101010",
               "accountType": "BKSE"
            }
        }
    ],
   "navigation": {
       "@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders"
    }
}

Operations

Depending on the current permissions the following operations is supported on the surplus resource

add-disbursement-orders

Method: POST
This operation will be available if agreed with payex.

request properties

Property	Data type	Required
norwegianBankAccount	object	No*
accountNo	string	Yes
swedishBankAccount	object	No*
clearingNo	string	Yes
accountNo	string	Yes
international	object	No*
iban	string	Yes
bic	string	Yes
swedishSus	object	No*
nationalIdentifier	object	Yes
regNo	string	Yes
countryCode	string	Yes
address	object	Yes
addressee	string	Yes
streetAddress	string	No
coAddress	string	No
city	string	Yes
zipCode	string	Yes
countryCode	string	Yes

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

Examples

Create disbursement with swedish bank account

Request

Create a disbursement order with a norwegian bankaccount

Request

Create a disbursement order with an international bankaccount

Request

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

Request

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "swedishSus" : {
       "nationalIdentifier": {
           "regNo" : "YYYYMMDD-NNNN",
           "countryCode" : "SE"
        },
       "address" : {
           "addressee" : "Kalle Axelstopp",
           "streetAddress" : "Axelgatan 18",
           "coAddress" : null,
           "city" : "STOCKHOLM",
           "zipCode" : "16872",
           "countryCode" : "se",
        }
    }
}

Legal-address

The legal address is where claims is normally sent to. It is required for a customer to have a legal address registered

Get the legal address of the customer

Request

GET /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "addressee" : "Britt-Marie Axelstopp",
   "streetAddress" : "The street 18",
   "coAddress" : "c/o Jansson",
   "city" : "STOCKHOLM",
   "zipCode" : "15961",
   "countryCode" : "SE",
   "operations" :
        [
            {
               "rel" : "update",
               "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
               "method" : "PUT"
            },
                        {
               "rel" : "update-legal-address-from-population-register",
               "href" : "/ledger/customer/v1/XXX/customers/9999/legal-address/update-legal-address-from-population-register",
               "method" : "POST"
            }
        ]
}

Operations

Depending on the current permissions the following operations is supported on the legal address resource

Update (replace)

Method: PUT
Use this operation to update the address, this "PUT" operation will replace the existing billing-address with the address specified in the request body.

Property	Required
addressee	Yes
streetAddress	No
coAddress	No
city	Yes
zipCode	Yes
countryCode	Yes

Example

Request

PUT /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
       "addressee" : "Kalle Axelstopp",
       "streetAddress" : "Axelgatan 18",
       "city" : "STOCKHOLM",
       "zipCode" : "16872",
       "countryCode" : "SE"
}

update-legal-address-from-population-register

Method: POST
Execution of this operation will result in an attempt to retrieve (and replace) the customer's legal address from the population registry.

Access to this operation is not normally granted, unless otherwise agreed.

Request

POST /ledger/customer/v1/XXX/customers/NNN/legal-address/update-legal-address-from-population-register HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
}

Legal-address resource properties

Property	Data type	Format	Description
addressee	string	Maxlength: 72	Fullname
streetAddress	string	Maxlength: 72
coAddress	string	Maxlength: 72	Care of (C/O) name. This is optional.
city	string	Maxlength: 27
zipCode	string	Maxlength: 9	ZipCode without whitespaces
countryCode	string	ISO 3166-1 alpha-2

Billing-address

The billing address is where invoices/bills/letters etc. is normally sent to.This address is optional

Get the billing address of the customer

Request

GET /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
   "addressee" : "Kalle Axelstopp",
   "streetAddress" : "Axelgatan 18",
   "coAddress" : "c/o Jansson",
   "city" : "STOCKHOLM",
   "zipCode" : "16872",
   "countryCode" : "SE",
   "operations" :
        [
            {
               "rel" : "update",
               "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
               "method" : "PUT"
            },
            {
               "rel" : "delete",
               "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
               "method" : "DELETE"
            }
        ]
}

Add a billing-address

Property	Required
addressee	Yes
streetAddress	No
coAddress	No
city	Yes
zipCode	Yes
countryCode	Yes

Request

POST /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
       "addressee" : "Kalle Axelstopp",
       "streetAddress" : "Axelgatan 18",
       "city" : "STOCKHOLM",
       "zipCode" : "16872",
       "countryCode" : "SE"
}

Operations

Depending on the current permissions the following operations is supported on the billing address resource

Update (replace)

Method: PUT
Use this operation to update the address, the "PUT" body of the request should be accoring to the properties of the resource.

Property	Required
addressee	Yes
streetAddress	No
coAddress	No
city	Yes
zipCode	Yes
countryCode	Yes

Request

PUT /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
       "addressee" : "Kalle Axelstopp",
       "streetAddress" : "Axelgatan 18",
       "city" : "STOCKHOLM",
       "zipCode" : "16872",
       "countryCode" : "SE"
}

Delete

Method: DELETE
Use this operation to delete the billing address.

Request

DELETE /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
}

Billing-address resource properties

Property	Data type	Format	Description
addressee	string	Maxlength: 72	Fullname
streetAddress	string	Maxlength: 72
coAddress	string	Maxlength: 72	Care of (C/O) name. This is optional.
city	string	Maxlength: 27
zipCode	string	Maxlength: 9	ZipCode without whitespaces
countryCode	string	ISO 3166-1 alpha-2

Consent

The consent resource is used to get the underlying resources that display information or enable registration of a customer's consent.

Get the underlying consent resources of the customer

Request

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

Response

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

{
"recurringCard": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card",
"recurringCardRedirectRegistration": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration"
}

Consent resource properties

Property	Data type	Format	Description
recurringCard	string	Path	Endpoint to resource
recurringCardRedirectRegistration	string	Path	Endpoint to resource

Recurring-card

This resource provides details about the customer's active Recurring Card Consent and the ability to remove it.

Get customer active Recurring Card Consent

Request

GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Response

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

{
"cardToken": "2eb28854-07ec-4e88-b672-7c61cc54b461",
"consentExpiryDate": "04-2035",
"instrumentDisplayName": "551000******1232",
"cardExpiryDate": "04/2035"
}

Delete customer active Recurring Card Consent

Request

DELETE /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NoContent
Content-Type: application/json

{
}

Recurring-card resource properties

Property	Data type	Format	Description
cardToken	string	Guid	Card Token Id
consentExpiryDate	string	Date (MM-yyyy)	Expiry date of the consent
instrumentDisplayName	string	Masked number	Masked card number used in the presentation layer
cardExpiryDate	string	Date (MM/yyyy)	Expiry date of the card

Recurring-card-redirect-registration

Initializes the customer's Recurring Card registration with redirect to SwedbankPay. The resource should be inquired until the status reaches an end status. Only one registration can be active at a time.

Start a Recurring Card registration

Property	Required	Comment
completeUrl	Yes	Redirect Url to be used if the user completes the card verification process.
cancelUrl	Yes	Redirect Url to be used if the user cancels the card verification process.
language	Yes	A language specified in the ISO 639-1 language code and with two letter country codes in the format "xx-YY". The following pairs are available: "en-US", "sv-SE", "nb-NO", "da-DK" and "fi-FI".

Request

POST /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
"completeUrl": "https://www.google.com/search?q=cancelurl",
"cancelUrl": "https://www.google.com/search?q=completeurl",
"language": "en-US"
}

Response

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

{
"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
"status": "Initialized",
"@id": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration"
}

Get Recurring Card Redirect Registration

Request

GET /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
}

Response

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

{
"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
"status": "Initialized"
}

Recurring-card-redirect-registration resource properties

Property	Data type	Format	Description
redirectUrl	string	Url	The redirect url to a flow that confirms the validity of card information without reserving or charging any amount.
status	string		Status of the card validity verification process. One of the following: "Initialized", "Completed", "Aborted" or "Failed".

Find customer

The find customer resource is located under ledger/customer/v1/ api. It is used to find customer with nationalIdentifier.

Property	Required
nationalIdentifier.regNo	Yes
nationalIdentifier.countryCode	Yes

Request

POST /ledger/customer/v1/XXX/find-customer HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "nationalIdentifier": {
     "regNo" : "YYYYMMDD-NNNN",
     "countryCode" : "SE"
    }
}

Response

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

{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Find customer resource properties

Property	Data type	Format	Description
@id	string	Maxlength:	Uri of the specific customer
customerNo	string	Maxlength: 15
nationalIdentifier.regNo	string	Country specific	Sweden: YYYYMMDD-NNNC Norway: DDMMYYNNNNN
nationalIdentifier.countryCode	string	ISO 3166-1 alpha-2

Generate customer

The generate consumer customer by reg no resource is located under ledger/customer/v1/ api. It is used to genarate a customer with a nationalIdentifier. It will retreive an legal address from the population register and create a consumer customer.

Access to this operation is not normally granted, unless otherwise agreed.

Property	Required
customerNo	No
nationalIdentifier.regNo	Yes
nationalIdentifier.countryCode	Yes
emailAddress	No
msisdn	No

Request

POST /ledger/customer/v1/XXX/generate-consumer-customer-by-reg-no HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "nationalIdentifier": {
     "regNo" : "YYYYMMDD-NNNN",
     "countryCode" : "SE"
    },
   "emailAddress" : "britt@axelstopp.com",
   "msisdn" : "+91485918841",
   "customerNo" : "9999"
}

Response

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

{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Generate customer resource properties

Property	Data type	Format	Description
@id	string	Maxlength:	Uri of the specific customer
customerNo	string	Maxlength: 15
nationalIdentifier.regNo	string	Country specific	Sweden: YYYYMMDD-NNNC Norway: DDMMYYNNNNN
nationalIdentifier.countryCode	string	ISO 3166-1 alpha-2
emailAddress	string	Maxlength: 254 Regex pattern: [^@]+@[^\.]+\..+
msisdn	string	Maxlength: 15	"Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number +46720000000

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

Kys-Questions

The Kys-Questions resource is located under ledger/customer/v1/ api. Get the company Know-your-customer(KYC) questions and possible answers, if company no configured questions then it returns Http Status 404

This endpoint has an optional query parameter Language, used to set desired translations for the questions by Language Code(ISO 639-1). If not set or if language code is not supported then translations defaults to EN(English).
Just as the questions, accepted languages differs by configurations, if you are missing a translation please contact our support.

Example: /ledger/customer/v1/{ledgerNo}/Kyc-Questions?language=sv

Get KYC questions from ledger using company number as identifier

Get list of Kyc-questions

Request

GET /ledger/customer/v1/{ownerNo}/kyc-questions?language={language} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get CompanyInstance KYC questions if configured or a 404 company-kyc-questions-not-configured response if not

Response

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

{
"kycQuestions": [
    {
     "questionText": "What is your current employment?",
     "answer": {
       "type": "single",
       "required": true,
       "possibleAnswers": [
          {
           "answerCode": "selfemployed",
           "answerText": "Own business"
          },
          {
           "answerCode": "private_employee",
           "answerText": "Private employee"
          },
          {
           "answerCode": "goverment_employee",
           "answerText": "Government employee"
          }
        ]
      },
     "questionCode": "employment"
    },
    {
     "questionText": "What is your yearly income",
     "answer": {
       "type": "single",
       "required": true,
       "possibleAnswers": [
          {
           "answerCode": "incomeinterval1",
           "answerText": "0-100 000 SEK"
          },
          {
           "answerCode": "incomeinterval2",
           "answerText": "100 001-200 000 SEK"
          },
          {
           "answerCode": "incomeinterval3",
           "answerText": "200 001-300 000 SEK"
          },
          {
           "answerCode": "incomeinterval4",
           "answerText": "Over 300 001 SEK"
          }
        ]
      },
     "questionCode": "income"
    }
  ],
"operations": []
}

Possible problems

Http status	Problem type	Description
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
404	company-kyc-questions-not-configured	The requested resource '' was not found.
500	internal-server-error	The requested resource '' could not be processed. Please contact support.
500	handled-exception	The requested resource '' could not be processed. Please contact support.
500	unhandled-exception	The requested resource '' could not be processed. Please contact support.

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
kycQuestions	array of question's
question.questionCode	string	The code definition of the question. Use this value when creating an answer request for /customers/{customerNo}/update-kyc-answers
question.questionText	string	The translated text of the question
answer	object
type	string	The type of the expected answer: single \| one answer only multi \| possible multiple answer text \| free text answer
required	boolean	If the answer is required
textValidationRegEx	string	The regex the answer should match, not all answers has a defined RegEx.
possibleAnswers	array of possibleAwnser's
possibleAwnser.answerCode	string	The code definition of the answer. Use this value when creating an answer request for /customers/{customerNo}/update-kyc-answers
possibleAwnser.answerText	string	The translated text of the answer
subQuestions	array of question's	Is recursive structure of kycQuestions but limited to depth of 1, meaning a sub question can't have sub questions.
operations	array	List of operations that is possible to perform on the current resource, read more about the [[hypermedia part of the response>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/ledger-api-general-docs/restful-pattern-guideline/#HHyper-mediaresponse]]

Problems

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Response

Problem types

Note, each problem typecode is preceded by "ledger/customer/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/customer/v1/problems/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
forbidden	403	occurs if access to method is not allowed.
not-found	404	specified resource not found
customer-not-found	404	specified customer number does not exists
legal-address-does-not-exists	404	legal address does not exists for the specified customer
billing-address-does-not-exists	404	billing address does not exists for the specified customer

Ledger and Factoring

2. Customer

Introduction

Changelog

Customer

Get a specific customer

Get a specific customer using $expand

Create new customer

Important to note!

Examples

Update customer

Examples

Customer resource properties

Operations

add-billing-address

Update-kyc-answers

Create Update-kyc-answer

Surpluses

Get specified Surplus information

Get list of Surpluses Information

Surpluses resource properties

Active-Disbursement-Orders

Get active disbursement orders

Operations

add-disbursement-orders

request properties

Legal-address

Get the legal address of the customer

Operations

Update (replace)

update-legal-address-from-population-register

Legal-address resource properties

Billing-address

Get the billing address of the customer

Add a billing-address

Operations

Update (replace)

Delete

Billing-address resource properties

Consent

Get the underlying consent resources of the customer

Consent resource properties

Recurring-card

Get customer active Recurring Card Consent

Delete customer active Recurring Card Consent

Recurring-card resource properties

Recurring-card-redirect-registration

Start a Recurring Card registration

Get Recurring Card Redirect Registration

Recurring-card-redirect-registration resource properties

Find customer

Find customer resource properties

Generate customer

Generate customer resource properties

Problems

Example

Kys-Questions

Get list of Kyc-questions

Problems

Example

Problem types