Main.Invoicing.invoice-service.invoice-service-apis.Technical reference.2\. Customer - 2. Customer

Page of - last modified by Lukas Fletcher on 2024/05/15 18:02

2. Customer

Lukas Fletcher

2024/05/15 18:02

Table of Contents

Introduction

Changelog

Customer

Surpluses

Active-Disbursement-Orders

Legal-address

Billing-address

Consent

Find customer

Generate customer

Problems

Example

Problem types

Integrate to PayEx Customer API

Introduction

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

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource2Id, to operate on this resource you must also include the ids of its parentresources in the route.
lf-api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}

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

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

Resource	Identifier
LedgerNumber	XXX
Customer	NNN (CustomerNo)

Changelog

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

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

2024-04-26

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

2024-05-15

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

Customer

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

Get a specific customer

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : "9999",
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
},
"vatNo" : "SE101010101001",
"legalEntity" : "consumer|business",
"name" : "Britt-Marie Axelstopp",
"emailAddress" : "britt@axelstopp.com",
"protectedIdentity": false,
"preferredLanguageCode": "SV",
"legalStatus": "active",
"msisdn" : "+91485918841",
"activeConsents": [
"Betalingsservice",
"Avtalegiro"
],
"eDIAddressInfo" : {
"VAN": "ABCXYZ",
"InterChangeRecipient": "Recipient_ID1",
"BuyerId": "123465"
},
"legalAddress" : "/ledger/customer/v1/XXX/customers/9999/legal-address",
"billingAddress" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
"surpluses": "/ledger/customer/v1/XXX/customers/9999/surpluses",
"operations" :
[
{
"rel" : "add-billing-address",
"href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
"method" : "POST"
}
]
}

Get a specific customer using $expand

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

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

Request

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

Response

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

Create new customer

Important to note!

Standard length of customerNo in Norway and Denmark is 7 characters (numeric only).

Only use numeric characters and not with a leading zero for customerNo in Sweden, in order to use AutoGiro (Direct Debit).

Dependency to legalEntity:

Late fee will be added instead of reminder fee or collection claim fee when legalEntity is set to "business" (if specially contracted with PayEx and configured in ledger).

SSN (regNo) for private individuals will not be displayed in ledger reports due to GDPR. regNO will only be displayed when legalEntity is set till "business".

When invoice/claim is distributed by e-mail: If legalEntity is set to "consumer" the e-mail message will only include a link to PayEx Invoice Portal where the invoice/claim is available, otherwise a copy of the invoice/claim will be added in the e-mail message as a pdf-file.

Finland only: Different claim processes will be used depending on "consumer" or "business".

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

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

Examples

Standard create customer

Request

POST /ledger/customer/v1/XXX/customers HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"customerNo" : "9999",
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
},
"vatNo" : "SE101010101001",
"legalEntity" : "consumer|business",
"name" : "Britt-Marie Axelstopp",
"emailAddress" : "britt@axelstopp.com",
"msisdn" : "+91485918841",
"eDIAddressInfo" : {
"VAN": "ABCXYZ",
"InterChangeRecipient": "Recipient_ID1",
"BuyerId": "123456"
},
"legalAddress" : {
"addressee" : "Britt-Marie Axelstopp",
"streetAddress" : "The street 18",
"coAddress" : "c/o Jansson",
"city" : "STOCKHOLM",
"zipCode" : "15961",
"countryCode" : "SE"
},
"distributionType": "postal",
"taxIdentificationNumber" : "123456789"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json
{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Create customer with billing-address

Request

POST /ledger/customer/v1/XXX/customers HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"customerNo" : "9999",
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
},
"vatNo" : "SE101010101001",
"legalEntity" : "consumer|business",
"name" : "Britt-Marie Axelstopp",
"emailAddress" : "britt@axelstopp.com",
"msisdn" : "+91485918841",
"eDIAddressInfo" : {
"VAN": "ABCXYZ",
"InterChangeRecipient": "Recipient_ID1",
"BuyerId": "123456"
},
"legalAddress" : {
"addressee" : "Britt-Marie Axelstopp",
"streetAddress" : "The street 18",
"coAddress" : "c/o Jansson",
"city" : "STOCKHOLM",
"zipCode" : "15961",
"countryCode" : "SE"
},
"billingAddress" : {
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "SE"
}
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json
{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Update customer

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

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

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

Examples

Update all properties

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"emailAddress" : "britt@axelstopp.com",
"protectedIdentity": false,
"preferredLanguageCode": "SV",
"legalStatus": "active",
"msisdn" : "+91485918841",
"eDIAddressInfo" : {
"VAN": "ABCXYZ",
"InterChangeRecipient": "Recipient_ID1",
"BuyerId": "123456"
},
"distributionType": "postal",
"taxIdentificationNumber" : "987654321"
}

Update only emailAddress

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"emailAddress" : "britt@axelstopp.com"
}

Update emailAddress and delete msisdn

Request

PATCH /ledger/customer/v1/XXX/customers/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"emailAddress" : "britt@axelstopp.com",
"msisdn" : null
}

Customer resource properties

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

Operations

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

add-billing-address

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

Surpluses

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

Get specified Surplus information

Request

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

Response

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

Get list of Surpluses Information

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"surplusId": "123",
"balance": 10.00,
"currency": "SEK",
"date": "2023-01-01T00:00:00",
"status": "open",
"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
"operations": [],
"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/123"
},
{
"surplusId": "456",
"balance": 20.00,
"currency": "SEK",
"date": "2023-01-02T00:00:00",
"status": "pending-disbursement",
"account": "/ledger/account/v1/XXX/accounts/BBB",
"operations": [],
"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/456"
},
{
"surplusId": "789",
"balance": 30.00,
"currency": "SEK",
"date": "2023-01-03T00:00:00",
"status": "pending-regulate",
"invoice": "/ledger/invoice/v1/XXX/invoices/AAA",
"operations": [],
"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/789"
}
],
"navigation": {
"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses",
"first": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0",
"previous": "/ledger/customer/v1/XXX/customers/NNN/surpluses?skip=0"
}
}

Surpluses resource properties

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

Active-Disbursement-Orders

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

Get active disbursement orders

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"operations": [],
"swedishBankAccount": {
"accountNo": "3300-1010101010",
"accountType": "BKSE"
}
}
],
"navigation": {
"@id": "/ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders"
}
}

Operations

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

add-disbursement-orders

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

request properties

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

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

Examples

Create disbursement with swedish bank account

Request

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"SwedishBankAccount" : {
"AccountNo":"944-1049000",
"AccountType":"BGSE"
}
}

Create a disbursement order with a norwegian bankaccount

Request

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

Create a disbursement order with an international bankaccount

Request

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"international" : {
"iban" : "123456",
"bic" : "SWED..."
}
}

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

Request

POST /ledger/customer/v1/XXX/customers/NNN/surpluses/YYY/active-disbursement-orders HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"swedishSus" : {
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
},
"address" : {
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"coAddress" : null,
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "se",
}
}
}

Legal-address

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

Get the legal address of the customer

Request

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

Response

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

Operations

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

Update (replace)

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

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

Example

Request

PUT /ledger/customer/v1/XXX/customers/NNN/legal-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "SE"
}

update-legal-address-from-population-register

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

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

Request

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

Legal-address resource properties

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

Billing-address

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

Get the billing address of the customer

Request

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

Response

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

Add a billing-address

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

Request

POST /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "SE"
}

Operations

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

Update (replace)

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

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

Request

PUT /ledger/customer/v1/XXX/customers/NNN/billing-address HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"addressee" : "Kalle Axelstopp",
"streetAddress" : "Axelgatan 18",
"city" : "STOCKHOLM",
"zipCode" : "16872",
"countryCode" : "SE"
}

Delete

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

Request

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

Billing-address resource properties

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

Consent

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

Get the underlying consent resources of the customer

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"recurringCard": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card",
"recurringCardRedirectRegistration": "/ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration"
}

Consent resource properties

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

Recurring-card

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

Get customer active Recurring Card Consent

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"cardToken": "2eb28854-07ec-4e88-b672-7c61cc54b461",
"consentExpiryDate": "04-2035",
"instrumentDisplayName": "551000******1232",
"cardExpiryDate": "04/2035"
}

Delete customer active Recurring Card Consent

Request

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

Response

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

Recurring-card resource properties

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

Recurring-card-redirect-registration

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

Start a Recurring Card registration

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

Request

POST /ledger/customer/v1/XXX/customers/NNN/consent/recurring-card-redirect-registration HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"completeUrl": "https://www.google.com/search?q=cancelurl",
"cancelUrl": "https://www.google.com/search?q=completeurl",
"language": "en-US"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
"status": "Initialized",
"@id": "/ledger/customer/v1/xxx/customers/yyy/consent/recurring-card-redirect-registration"
}

Get Recurring Card Redirect Registration

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"redirectUrl": "https://ecom.externalintegration.payex.com/checkout/abc123",
"status": "Initialized"
}

Recurring-card-redirect-registration resource properties

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

Find customer

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

Property	Required
nationalIdentifier.regNo	Yes
nationalIdentifier.countryCode	Yes

Request

POST /ledger/customer/v1/XXX/find-customer HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
}
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Find customer resource properties

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

Generate customer

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

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

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

Request

POST /ledger/customer/v1/XXX/generate-consumer-customer-by-reg-no HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json
{
"nationalIdentifier": {
"regNo" : "YYYYMMDD-NNNN",
"countryCode" : "SE"
},
"emailAddress" : "britt@axelstopp.com",
"msisdn" : "+91485918841",
"customerNo" : "9999"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json
{
"@id" : "/ledger/customer/v1/XXX/customers/9999",
"customerNo" : " 9999"
}

Generate customer resource properties

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

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

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

Example

Response

HTTP/1.1 400 Error
Content-Type: application/problem+json
{
"Type" : "ledger/{domain}/v1/problems/validation",
"Title" : "A validation error occurred",
"Status" : 400,
"Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
"Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
"Problems" :
{
"amount" : [
"Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
]
}
}

Problem types

Note, each problem typecode is preceded by "ledger/customer/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/customer/v1/problems/validation".

Problem type (code)	Httpstatus	Description
validation	400	occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
forbidden	403	occurs if access to method is not allowed.
not-found	404	specified resource not found
customer-not-found	404	specified customer number does not exists
legal-address-does-not-exists	404	legal address does not exists for the specified customer
billing-address-does-not-exists	404	billing address does not exists for the specified customer