PayEx Developer Portal

Integrate to PayEx Customer API

Introduction

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

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

The below route is an example of a route towards resource2Id, to operate on this resource you must also include the ids of its parentresources in the route.
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)

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.

Important to note!

Standard length of CustomerNo in Norway is 7 characters (numeric only).

Get a specific customer

Request

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

Response

Get a specific customer using $expand

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

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

Request

GET /ledger/customer/v1/XXX/customers/NNN?$expand=legal-address,billing-address 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",
   "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",
       "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"
                }
            ]
    },
   "operations" :
    [
        {
           "rel" : "add-billing-address",
           "href" : "/ledger/customer/v1/XXX/customers/9999/billing-address",
           "method" : "POST"
        }
    ]
}

Create new customer

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
emailAddress	No
msisdn	No
eDIAddressInfo	No
eDIAddressInfo.van	No
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"
    }
}

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

Response

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

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

Update customer

Some peroperties 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
msisdn
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",
   "msisdn" : "+91485918841",
   "eDIAddressInfo" : {
     "VAN": "ABCXYZ",
     "InterChangeRecipient": "Recipient_ID1",
     "BuyerId": "123456"
    },
}

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: [^@]+@[^\.]+\..+
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
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

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

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: 35
coAddress	string	Maxlength: 35	Care of (C/O) name. This is optional.
city	string	Maxlength: 30
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: 35
coAddress	string	Maxlength: 35	Care of (C/O) name. This is optional.
city	string	Maxlength: 30
zipCode	string	Maxlength: 9	ZipCode without whitespaces
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"
}

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.customer.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." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.customer.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.
customer-does-not-exists	404	specified customer number does not exists
legal-address-does-not-exists	404	legal address does not exists for the specified customer
billing-address-does-not-exists	404	billing address does not exists for the specified customer

Ledger and Factoring

2. Customer

Introduction

Customer

Important to note!

Get a specific customer

Get a specific customer using $expand

Create new customer

Examples

Update customer

Examples

Customer resource properties

Operations

add-billing-address

Legal-address

Get the legal address of the customer

Operations

Update (replace)

update-legal-address-from-population-register

Legal-address resource properties

Billing-address

Get the billing address of the customer

Add a billing-address

Operations

Update (replace)

Delete

Billing-address resource properties

Generate customer

Generate customer resource properties

Problems

Example

Problem types