Ledger and Factoring

2. Customer

Integrate to PayEx Customer API 

Introduction

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

1612164561442-820.png

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 segmentDescription
SubdomainIn this part of the API it will be customer
LedgerNumberThe ledger identifier/number at PayEx
resource1IdIdentifier of resource1
resource2Ididentifier of resource2, subresource to resource1

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

ResourceIdentifier
LedgerNumberXXX
CustomerNNN (CustomerNo)

Swagger

Swagger.json-2026-06-26

Changelog

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

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

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

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": "\u002B467040000000",
 "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"
}

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. 

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

Request object specification

Property Data typeFormatRequiredDescription
customerNo string  No  
ediAddressInfo object   No  
   van string  No  
   interChangeRecipient string  No  
   buyerId string  No  
emailAddress string  No  
legalAddress object   No  
   addressee string  No  
   streetAddress string  No  
   zipCode string  No  
   city string  No  
   coAddress string  No  
   countryCode string  No  
billingAddress object   No  
legalEntity string  No  
msisdn string  No  
name string  No  
nationalIdentifier object   No  
   regNo string  Yes  
   countryCode string Pattern: ^[A-Z]{2}$ Yes  
protectedIdentity boolean  Yes  
preferredLanguageCode string  No  
vatNo string  No  
distributionType string  No  
taxIdentificationNumber string  No  

Create a customer response

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

{
 "customerNo": "YYY",
 "@id": "/ledger/customer/v1/xxx/customers/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. 
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 

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
customerNo string   
nationalIdentifier object    
   regNo string   
   countryCode string Pattern: ^[A-Z]{2}$  
vatNo string   
legalEntity string   
name string   
emailAddress string   
protectedIdentity boolean   
preferredLanguageCode string   
legalStatus string   
msisdn string   
activeConsents array    
    string   
ediAddressInfo object    
   van string   
   interChangeRecipient string   
   buyerId string   
surpluses dynamic    
legalAddress dynamic    
billingAddress dynamic    
consent dynamic    
distributionType 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]]
taxIdentificationNumber string   

2. Kyc-questions

Get KYC questions from ledger using company number as identifier

2.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 paramters

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 typeFormatDescription
@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]]

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

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. 

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

{
}

Response object specification

Property Data typeFormatDescription
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. Surpluses

List all available surpluses on the customer

4.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-07-05T00:00:00\u002B02: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-07-03T00:00:00\u002B02: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-06-26T00:00:00\u002B02: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. 

4.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-07-05T00:00:00\u002B02: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 typeFormatDescription
@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]]

5. Trusted-seller-groups

Get details about the customer's active Consent.

5.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"
  }
}

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 

Get details about the customer's active Consent.

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

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 

5.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 typeFormatRequiredDescription
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"
}

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 typeFormatDescription
@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]]

6. Legal-address

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

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

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 typeFormatDescription
@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]]

7. Update-kyc-answers

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

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. 

9. Billing-address

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

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

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. 

9.2 Create Billing-addre

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

{
}

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 typeFormatDescription
@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]]

10. Consent

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

10.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 typeFormatDescription
@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]]

11. Find-customer

11.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 typeFormatRequiredDescription
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 typeFormatDescription
@id string  Uri identifier of the current resource
customerNo string   

12. Recurring-card

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

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

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
cardToken string   
consentExpiryDate string   
instrumentDisplayName string   
cardExpiryDate string   
cardBrand 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]]

13. Recurring-card-redirect-registration

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

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

13.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=cancelurl",
 "cancelUrl": "https://www.google.com/search?q=completeurl",
 "language": "en-US"
}

Request object specification

Property Data typeFormatRequiredDescription
completeUrl string Type: uri Yes  
cancelUrl string Type: uri Yes  
language string  Yes  

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 typeFormatDescription
@id string  Uri identifier of the current resource
redirectUrl string   
status 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]]

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]"
         ]
      }
}
Created by David Persson on 2024/01/10 12:28