2. Customer

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}

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

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.

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

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.

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.

Examples

Standard create customer

Create customer with billing-address

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

Examples

Update all properties

Update only emailAddress

Update emailAddress and delete msisdn

Remove EDIAddressInfo on a customer

Customer resource properties

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

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

Get list of Surpluses Information

Surpluses resource properties

Active-Disbursement-Orders

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

Get 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

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

Examples

Create disbursement with swedish bank account

Create a disbursement order with a norwegian bankaccount

Create a disbursement order with an international bankaccount

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

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

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.

Example 

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.

Legal-address resource properties

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

Add a billing-address

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.

Delete

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

Billing-address resource properties

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

Consent resource properties

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

Delete customer active Recurring Card Consent

Recurring-card resource properties

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

Get Recurring Card Redirect Registration

Recurring-card-redirect-registration resource properties

Find customer

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

Find customer resource properties

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.

Generate customer resource properties

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

Problem types