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)

Swagger

Swagger.json-2026-09-15

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

2026-01-27
Added new possible value for to ActiveConsents - PharmaciesSE

2026-07-08
Added new secontion for Trusted Seller Group Consents

2026-08-19
Added resource Affordability-Questions. Planned release 2026-09-22

2026-09-15
Added flowcharts for recuring cards

Recuring card flowcharts

Flowcharts describing how to register, view and delete recuring card

1. Register new card

2. Get card info

3. Delete card

API specification

1. Customers

Get a customer from ledger using customer number as identifier

1.1 Get specific Customer

Request

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

Get customer

Response

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

{
"customerNo": "YYY",
"nationalIdentifier": {
   "regNo": "YYYYMMDD-NNNN",
   "countryCode": "SE"
  },
"vatNo": "SE101010101001",
"legalEntity": "consumer",
"name": "Test Testsson",
"emailAddress": "Test@test.se",
"protectedIdentity": false,
"preferredLanguageCode": "SV",
"legalStatus": "active",
"msisdn": "+467040000000",
"activeConsents": [
   "Betalingsservice",
   "Avtalegiro",
   "RecurringCard"
  ],
"ediAddressInfo": {
   "van": "ABCXYZ",
   "interChangeRecipient": "Recipient_ID1",
   "buyerId": "123465"
  },
"surpluses": "/ledger/customer/v1/xxx/customers/yyy/surpluses",
"legalAddress": "/ledger/customer/v1/xxx/customers/yyy/legal-address",
"billingAddress": "/ledger/customer/v1/xxx/customers/yyy/billing-address",
"consent": "/ledger/customer/v1/xxx/customers/yyy/consent",
"operations": [
    {
     "rel": "partial-update-customer",
     "method": "PATCH",
     "href": "/ledger/customer/v1/xxx/customers/yyy"
    },
    {
     "rel": "add-billing-address",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/billing-address"
    },
    {
     "rel": "update-kyc-answers",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/update-kyc-answers"
    }
  ],
"taxIdentificationNumber": "1234567890"
}

1.2 Create Customer

Create a new customer in ledger

Request

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

{
"customerNo": "YYY",
"ediAddressInfo": {
   "van": "ABCXYZ",
   "interChangeRecipient": "Recipient_ID1",
   "buyerId": "123465"
  },
"emailAddress": "Test@test.se",
"legalAddress": {
   "addressee": "Test Testsson",
   "streetAddress": "Test street 1",
   "zipCode": "60000",
   "city": "Test town",
   "coAddress": "Co address",
   "countryCode": "SE"
  },
"legalEntity": "consumer",
"msisdn": "+467040000000",
"name": "Test Testsson",
"nationalIdentifier": {
   "regNo": "YYYYMMDD-NNNN",
   "countryCode": "SE"
  },
"protectedIdentity": false,
"preferredLanguageCode": "SV",
"vatNo": "SE101010101001",
"taxIdentificationNumber": "1234567890"
}

Request object specification

Property	Data type	Format	Required	Description
customerNo	string		No	Unique customer number assigned to the customer in the source system.
ediAddressInfo	object		No
van	string		No	Value Added Network identifier used for EDI communications.
interChangeRecipient	string		No	Recipient identifier for EDI interchanges.
buyerId	string		No	Identifier assigned to the buying organization or customer
emailAddress	string		No	Primary email address for electronic communication with the customer.
legalAddress	object		No
addressee	string		No	Name of the individual, organization, or department that receives mail at the address.
streetAddress	string		No	Street name and number of the address.
zipCode	string		No	Postal or ZIP code of the address.
city	string		No	City or locality of the address.
coAddress	string		No	Care-of (c/o) address information or additional address line.
countryCode	string		No	Two-letter ISO country code of the address.
billingAddress	object		No
legalEntity	string		No	Customer classification. Supported values: consumer for private individuals and business for organizations or companies.
msisdn	string		No	Mobile Station International Subscriber Directory Number (MSISDN), typically a mobile phone number in international format.
name	string		No	Customer's full name or business name.
nationalIdentifier	object		No
regNo	string		Yes
countryCode	string	Pattern: ^[A-Z]{2}$	Yes
protectedIdentity	boolean		Yes	Indicates whether the customer has a protected/confidential identity according to national regulations.
preferredLanguageCode	string		No	Preferred language code used for communication with the customer.
vatNo	string		No	Value Added Tax (VAT) registration number.
distributionType	string		No	Preferred method for distribution of invoices, orders, or other business documents.
taxIdentificationNumber	string		No	Tax identification number assigned by the relevant tax authority.

Create a customer response

Response

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

{
"customerNo": "YYY",
"@id": "/ledger/customer/v1/xxx/customers/yyy"
}

1.3 Update Customer

Update customer info

Request

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

Response

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

{
}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.
400	invalid-reg-no	Validation error when accessing resource . Please refer to the problems property for additional details.
400	invalid-phone-no	Validation error when accessing resource . Please refer to the problems property for additional details.
422	customer-already-exists	The requested resource '' could not be processed. Customer Already Exists
400	email-address-invalid	Validation error when accessing resource . Please refer to the problems property for additional details.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
customerNo	string		Unique customer number assigned to the customer in the source system.
nationalIdentifier	object
regNo	string
countryCode	string	Pattern: ^[A-Z]{2}$
vatNo	string		Value Added Tax (VAT) registration number.
legalEntity	string		Customer classification. Supported values: consumer for private individuals and business for organizations or companies.
name	string		Customer's full name or business name.
emailAddress	string		Primary email address for electronic communication with the customer.
protectedIdentity	boolean		Indicates whether the customer has a protected/confidential identity according to national regulations.
preferredLanguageCode	string		Preferred language code used for communication with the customer.
legalStatus	string		Indicates the legal status of the individual (for example, Active or Deceased).
msisdn	string		Mobile Station International Subscriber Directory Number (MSISDN), typically a mobile phone number in international format.
activeConsents	array
	string
ediAddressInfo	object
van	string		Value Added Network identifier used for EDI communications.
interChangeRecipient	string		Recipient identifier for EDI interchanges.
buyerId	string		Identifier assigned to the buying organization or customer
surpluses	dynamic
legalAddress	dynamic
billingAddress	dynamic
consent	dynamic
distributionType	string		Preferred method for distribution of invoices, orders, or other business documents.
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]]
taxIdentificationNumber	string		Tax identification number assigned by the relevant tax authority.

2. Surpluses

List all available surpluses on the customer

2.1 Get list of Surpluses

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/surpluses HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get surpluses list

Response

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

{
"items": [
    {
     "surplusId": "123",
     "balance": 10,
     "currency": "SEK",
     "date": "2026-09-13T00:00:00+02:00",
     "status": "open",
     "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
     "activeDisbursementOrders": "/ledger/customer/v1/xxx/customers/yyy/surpluses/123/active-disbursement-orders",
     "operations": [
        {
         "rel": "active-disbursement-orders",
         "method": "POST",
         "href": "/ledger/customer/v1/xxx/customers/yyy/surpluses/123/active-disbursement-orders"
        }
      ],
     "@id": "/ledger/customer/v1/xxx/customers/yyy/surpluses/123"
    },
    {
     "surplusId": "456",
     "balance": 20,
     "currency": "SEK",
     "date": "2026-09-11T00:00:00+02:00",
     "status": "pending-disbursement",
     "account": "/ledger/account/v1/XXX/accounts/BBB",
     "activeDisbursementOrders": "/ledger/customer/v1/xxx/customers/yyy/surpluses/456/active-disbursement-orders",
     "operations": [
        {
         "rel": "active-disbursement-orders",
         "method": "POST",
         "href": "/ledger/customer/v1/xxx/customers/yyy/surpluses/456/active-disbursement-orders"
        }
      ],
     "@id": "/ledger/customer/v1/xxx/customers/yyy/surpluses/456"
    },
    {
     "surplusId": "789",
     "balance": 30,
     "currency": "SEK",
     "date": "2026-09-04T00:00:00+02:00",
     "status": "pending-regulate",
     "invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
     "activeDisbursementOrders": "/ledger/customer/v1/xxx/customers/yyy/surpluses/789/active-disbursement-orders",
     "operations": [
        {
         "rel": "active-disbursement-orders",
         "method": "POST",
         "href": "/ledger/customer/v1/xxx/customers/yyy/surpluses/789/active-disbursement-orders"
        }
      ],
     "@id": "/ledger/customer/v1/xxx/customers/yyy/surpluses/789"
    }
  ],
"navigation": {
   "@id": "/ledger/customer/v1/xxx/customers/yyy/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.

2.2 Get specific Surpluse

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/surpluses/{surplusId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get single surplus

Response

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

{
"surplusId": "YYY",
"balance": 10,
"currency": "SEK",
"date": "2026-09-13T00:00:00+02:00",
"status": "open",
"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
"account": "/ledger/account/v1/XXX/accounts/BBB",
"activeDisbursementOrders": "/ledger/customer/v1/xxx/customers/yyy/surpluses/yyy/active-disbursement-orders",
"operations": [
    {
     "rel": "active-disbursement-orders",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/surpluses/yyy/active-disbursement-orders"
    }
  ],
"@id": "/ledger/customer/v1/XXX/customers/AAA/surpluses/YYY"
}

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
surplusId	string
balance	number	Type: double
currency	string
date	string	Type: date-time
status	string
invoice	string
account	string
activeDisbursementOrders	dynamic
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]]

3. Active-disbursement-orders

list active surpluse disbursement orders pending disbursement batch is run.

3.1 Get list of Active-disbursement-orders

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/surpluses/{surplusId}/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get customer billing-address

Response

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

{
"items": [
    {
     "operations": [],
     "swedishBankAccount": {
       "accountNo": "1234567890",
       "accountType": "BGSE"
      }
    }
  ],
"navigation": {
   "@id": "/ledger/customer/v1/xxx/customers/yyy/surpluses/zzz/active-disbursement-orders"
  }
}

3.2 Create Active-disbursement-order

Add a disbursement order. Disburses all available funds on surplus account, when disbursement batch is run

Request

POST /ledger/customer/v1/{ownerNo}/customers/{customerNo}/surpluses/{surplusId}/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"swedishBankAccount": {
   "accountNo": "NNN",
   "accountType": "BGSE | PGSE | BKSE | PKSE"
  }
}

Request object specification

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

Response

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

{
}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.

Response object specification

Property	Data type	Format	Description
items	array
@id	string		Uri identifier of the current resource
activeDisbursementOrdersId	string
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]]
norwegianBankAccount	object
accountNo	string
swedishBankAccount	object
accountNo	string
accountType	string
international	object
iban	string
bic	string
swedishSus	object
nationalIdentifier	object
regNo	string
countryCode	string
address	object
addressee	string
streetAddress	string
city	string
zipCode	string
countryCode	string
coAddress	string
navigation	object
@id	string	Type: uri	The current result view.
first	string	Type: uri	Link to the first results.
previous	string	Type: uri	Link to the previous results.
next	string	Type: uri	Link to the next results.

4. Legal-address

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

4.1 Get list of Legal-address

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/legal-address HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get customer legal-address

Response

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

{
"addressee": "Test Testsson",
"streetAddress": "Test street 1",
"zipCode": "60000",
"city": "Test town",
"coAddress": "Co address",
"countryCode": "SE",
"operations": [
    {
     "rel": "update-legal-address",
     "method": "PUT",
     "href": "/ledger/customer/v1/xxx/customers/yyy/legal-address"
    },
    {
     "rel": "update-legal-address-from-population-register",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/legal-address/update-legal-address-from-population-register"
    }
  ]
}

4.2 Replace Legal-address

this "PUT" operation will replace the existing legal-address with the address specified in the request body.

Request

PUT /ledger/customer/v1/{ownerNo}/customers/{customerNo}/legal-address HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"addressee": "Test Testsson",
"streetAddress": "Test street 1",
"zipCode": "60000",
"city": "Test town",
"coAddress": "Co address",
"countryCode": "SE"
}

Request object specification

Property	Data type	Required
addressee	string	No
streetAddress	string	No
zipCode	string	No
city	string	No
coAddress	string	No
countryCode	string	No

Response

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

{
}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
addressee	string
streetAddress	string
zipCode	string
city	string
coAddress	string
countryCode	string
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]]

5. Update-legal-address-from-population-register

5.1 Create Update-legal-address-from-population-register

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

Request

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

{
}

Response

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

{}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.

6. Billing-address

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

6.1 Get list of Billing-address

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/billing-address HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get customer billing-address

Response

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

{
"addressee": "Test Testsson",
"streetAddress": "Test street 1",
"zipCode": "60000",
"city": "Test town",
"coAddress": "Co address",
"countryCode": "SE",
"operations": [
    {
     "rel": "update-billing-address",
     "method": "PUT",
     "href": "/ledger/customer/v1/xxx/customers/yyy/billing-address"
    },
    {
     "rel": "delete-billing-address",
     "method": "DELETE",
     "href": "/ledger/customer/v1/xxx/customers/yyy/billing-address"
    }
  ]
}

6.2 Create Billing-address

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

Request

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

{
"addressee": "Test Testsson",
"streetAddress": "Test street 1",
"zipCode": "60000",
"city": "Test town",
"coAddress": "Co address",
"countryCode": "SE"
}

Request object specification

Property	Data type	Required
addressee	string	No
streetAddress	string	No
zipCode	string	No
city	string	No
coAddress	string	No
countryCode	string	No

Response

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

{
}

6.3 Replace Billing-address

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

Request

PUT /ledger/customer/v1/{ownerNo}/customers/{customerNo}/billing-address HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"addressee": "Test Testsson",
"streetAddress": "Test street 1",
"zipCode": "60000",
"city": "Test town",
"coAddress": "Co address",
"countryCode": "SE"
}

Request object specification

Property	Data type	Required
addressee	string	No
streetAddress	string	No
zipCode	string	No
city	string	No
coAddress	string	No
countryCode	string	No

Response

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

{
}

6.4 Delete Billing-address

Use this operation to delete the billing address.

Request

DELETE /ledger/customer/v1/{ownerNo}/customers/{customerNo}/billing-address HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

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

{
}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
addressee	string
streetAddress	string
zipCode	string
city	string
coAddress	string
countryCode	string
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]]

Underlying resources that display information or enable registration of a customer's consent.

7.1 Get list of Consent

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get customer consent

Response

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

{
"recurringCard": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card",
"recurringCardRedirectRegistration": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration",
"trustedSellerGroups": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups",
"availableTrustedSellerGroupConsents": [],
"operations": [
    {
     "rel": "add-trusted-seller-group",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups"
    },
    {
     "rel": "add-recurring-card-redirect-registration",
     "method": "POST",
     "href": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration"
    }
  ]
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
recurringCard	dynamic
recurringCardRedirectRegistration	dynamic
trustedSellerGroups	dynamic
availableTrustedSellerGroupConsents	array
	string
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]]

8. Trusted-seller-groups

Get details about the customer's active Consent.

8.1 Get list of Trusted-seller-groups

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/trusted-seller-groups HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get consent list

Response

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

{
"items": [
    {
     "consentType": "ccccc1",
     "operations": [
        {
         "rel": "delete-trusted-seller-group",
         "method": "DELETE",
         "href": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/ccccc1"
        }
      ],
     "@id": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/ccccc1"
    },
    {
     "consentType": "ccccc2",
     "operations": [
        {
         "rel": "delete-trusted-seller-group",
         "method": "DELETE",
         "href": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/ccccc2"
        }
      ],
     "@id": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/ccccc2"
    }
  ],
"navigation": {
   "@id": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups"
  }
}

Get details about the customer's active Consent.

8.2 Get specific Trusted-seller-group

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/trusted-seller-groups/{consentType} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get single consent

Response

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

{
"consentType": "ccccc",
"operations": [
    {
     "rel": "delete-trusted-seller-group",
     "method": "DELETE",
     "href": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/ccccc"
    }
  ]
}

8.3 Create Trusted-seller-group

Save a pdf Consent document as a Base64 string for specific CustomerNo and ConsentType.

Request

POST /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/trusted-seller-groups HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"consentType": "PharmaciesSE",
"applicationDocument": {
   "content": "JVBERi0xLjQKJ...",
   "fileType": "pdf"
  }
}

Request object specification

Property	Data type	Format	Required	Description
consentType	string		Yes	Name of the Consent Type
applicationDocument	object		Yes
content	string		Yes	A base64 encoded string representing the content of the document.
fileType	string	Pattern: (?i)^(pdf\|txt\|json\|xml)$	Yes	The file type of the document. Supported file types are: pdf, txt, json and xml. The validation is case insensitive.

Save a consent document

Response

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

{
"consentType": "cccc",
"operations": [
    {
     "rel": "delete-trusted-seller-group",
     "method": "DELETE",
     "href": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/cccc"
    }
  ],
"@id": "/ledger/customer/v1/xxx/customers/yyy/consent/trusted-seller-groups/cccc"
}

8.4 Delete Trusted-seller-group

Delete a active consent from customer.

Request

DELETE /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/trusted-seller-groups/{consentType} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 204 NO CONTENT
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 requested resource is not found.
409	conflict	Occurs if the requested resource already exists.
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
consentType	string
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]]

9. Recurring-card

Get details about the customer's active Recurring Card Consent.

9.1 Get list of Recurring-card

Request

GET /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/recurring-card HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get customer active Recurring Card Consent.

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",
"cardBrand": "Visa",
"operations": [
    {
     "rel": "delete-recurring-card",
     "method": "DELETE",
     "href": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card"
    }
  ]
}

9.2 Delete Recurring-card

Delete the customer's active Recurring Card Consent.

Request

DELETE /ledger/customer/v1/{ownerNo}/customers/{customerNo}/consent/recurring-card HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

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

{
}

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
cardToken	string	Unique token representing the card for which the recurring card consent has been granted.
consentExpiryDate	string	Expiration date of the recurring card consent. After this date, the consent is no longer valid and must be renewed.
instrumentDisplayName	string	Masked representation of the payment card associated with the consent, displayed in a customer-friendly format.
cardExpiryDate	string	Expiration date of the payment card associated with the recurring card consent.
cardBrand	string	Brand of the payment card, for example Visa or Mastercard.
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]]

10. Recurring-card-redirect-registration

Get details about the customer's ongoing Recurring Card registration.

10.1 Get list of Recurring-card-redirect-registration

Request

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

Customer's ongoing Recurring Card Registration.

Response

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

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

10.2 Create Recurring-card-redirect-registration

Initializes the customer's Recurring Card registration with redirect to SwedbankPay.

Request

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

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

Request object specification

Property	Data type	Format	Required	Description
completeUrl	string	Type: uri	Yes	URL to which the customer is redirected after successfully completing the recurring card registration process.
cancelUrl	string	Type: uri	Yes	URL to which the customer is redirected if the recurring card registration process is cancelled or abandoned.
language	string		Yes	Language and regional settings for the recurring card registration page. Allowed values are: sv-SE, da-DK, en-US, fi-FI, nb-NO.

Customer's ongoing Recurring Card Registration.

Response

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

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

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
redirectUrl	string	URL where the customer should be redirected to complete the recurring card registration process.
status	string	Current state of the recurring card registration process. Possible values are: (Initialized\|Completed\|Aborted\|Failed)
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]]

11. Update-kyc-answers

11.1 Create Update-kyc-answer

When exposed on customer resources operations list it's a indication previous KYC answers up for renewal. Able to 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 201 CREATED
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 not found or if KYC is not configured on this ledger.
409	company-kyc-questions-not-configured	Occurs if ledger is not currently configured for KYC
500	fatal	Unexpected error, logs may give details about the problem

12. Find-customer

12.1 Create Find-customer

It is used to find customer with nationalIdentifier.

Request

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

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

Request object specification

Property	Data type	Required
nationalIdentifier	object	No
regNo	string	Yes
countryCode	string	No

Find customer with nationalIdentifier, regno and countrycode, returns CustomerNo = YYY

Response

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

{
"customerNo": "YYY"
}

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.
400	validation	Validation error when accessing resource . Please refer to the problems property for additional details.
400	invalid-reg-no	Validation error when accessing resource . Please refer to the problems property for additional details.
404	customer-does-not-exists	The requested resource '' was not found.
404	customer-not-found	The requested resource '' was not found.

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
customerNo	string

13. Kyc-questions

Get KYC questions from ledger using company number as identifier

13.1 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": []
}

Query parameters

Name	Required	Description
language	False	format ISO639-1, if not supported or none given request defaults to language code 'en'(English)

Possible problems

Http status	Problem type	Description
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.
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.

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
kycQuestions	array
questionCode	string	The code definition of the question
questionText	string	The translated text of the question
answer	object
type	string	The type of the expected answer: single \| multi \| text
required	boolean	If the answer is required
textValidationRegEx	string	The regex the answer should match
possibleAnswers	array
answerCode	string	The code definition of the answer
answerText	string	The translated text of the answer
subQuestions	array
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]]

14. Affordability-questions

Get affordability questions from ledger using company number as identifier

14.1 Get list of Affordability-questions

Request

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

Get CompanyInstance affordability questions if configured. It's expected that not all credit assessment levels are configured for every company.

Response

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

{
"creditAssessmentLevel1": [
    {
     "questionCode": "yearly_revenue",
     "questionText": "What is your yearly revenue?",
     "answer": {
       "type": "single",
       "required": true,
       "possibleAnswers": [
          {
           "answerCode": "interval1",
           "answerText": "0-500 000 SEK"
          },
          {
           "answerCode": "interval2",
           "answerText": "500 001-1 000 000 SEK"
          }
        ]
      }
    }
  ],
"creditAssessmentLevel2": [
    {
     "questionCode": "number_of_employees",
     "questionText": "How many employees does the company have?",
     "answer": {
       "type": "single",
       "required": true,
       "possibleAnswers": [
          {
           "answerCode": "interval1",
           "answerText": "1-10"
          },
          {
           "answerCode": "interval2",
           "answerText": "11-50"
          }
        ]
      }
    }
  ],
"operations": []
}

Query parameters

Name	Required	Description
language	False	format ISO639-1, if not supported or none given request defaults to language code 'en'(English)

Possible problems

Http status	Problem type	Description
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.
400	general-validation-error	Validation error when accessing resource . Please refer to the problems property for additional details.

Response object specification

Property	Data type	Description
@id	string	Uri identifier of the current resource
creditAssessmentLevel1	array
questionCode	string	The code definition of the question
questionText	string	The translated text of the question
answer	object
type	string	The type of the expected answer: single \| multi \| text
required	boolean	If the answer is required
textValidationRegEx	string	The regex the answer should match
possibleAnswers	array
answerCode	string	The code definition of the answer
answerText	string	The translated text of the answer
subQuestions	array
creditAssessmentLevel2	array
creditAssessmentLevel3	array
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

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

credit-account

customer

Introduction

Swagger

Changelog

Recuring card flowcharts

1. Register new card

2. Get card info

3. Delete card

API specification

1. Customers

1.1 Get specific Customer

1.2 Create Customer

1.3 Update Customer

2. Surpluses

2.1 Get list of Surpluses

2.2 Get specific Surpluse

3. Active-disbursement-orders

3.1 Get list of Active-disbursement-orders

3.2 Create Active-disbursement-order

4. Legal-address

4.1 Get list of Legal-address

4.2 Replace Legal-address

5. Update-legal-address-from-population-register

5.1 Create Update-legal-address-from-population-register

6. Billing-address

6.1 Get list of Billing-address

6.2 Create Billing-address

6.3 Replace Billing-address

6.4 Delete Billing-address

7. Consent

7.1 Get list of Consent

8. Trusted-seller-groups

8.1 Get list of Trusted-seller-groups

8.2 Get specific Trusted-seller-group

8.3 Create Trusted-seller-group

8.4 Delete Trusted-seller-group

9. Recurring-card

9.1 Get list of Recurring-card

9.2 Delete Recurring-card

10. Recurring-card-redirect-registration

10.1 Get list of Recurring-card-redirect-registration

10.2 Create Recurring-card-redirect-registration

11. Update-kyc-answers

11.1 Create Update-kyc-answer

12. Find-customer

12.1 Create Find-customer

13. Kyc-questions

13.1 Get list of Kyc-questions

14. Affordability-questions

14.1 Get list of Affordability-questions

Problems

Example