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

Customer

The customer resource is located under ledger/customer/v1/ apiThe 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",
   "msisdn" : "+91485918841",
   "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",
   "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=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

Important to note!
  • Standard length of CustomerNo in Norway and Denmark is 7 characters (numeric only).
  • Only use numeric characters for CustomerNo in Sweden, in order to use AutoGiro (Direct Debit).

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.

PropertyRequiredComment *
customerNoYes*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.
nationalIdentifierNo*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.regNoYes 
   nationalIdentifier.countryCodeYes 
vatNoNo*Required if reverse tax is used
legalEntityNo 
nameYes 
emailAddressNo 
msisdnNo 
eDIAddressInfoNo 
   eDIAddressInfo.vanNo

 

   eDIAddressInfo.interChangeRecipientNo 
   eDIAddressInfo.BuyerIdYes 
legalAddressYes 
   addresseeYes 
   streetAddressNo 
   coAddressNo 
   cityYes 
   zipCodeYes 
   countryCodeYes 
billingAddressNo 
   addresseeYes 
   streetAddressNo 
   coAddressNo 
   cityYes 
   zipCodeYes 
   countryCodeYes 
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
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
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

PropertyData typeFormatDescription
@id string Uri of the specific customer
customerNostringMinLength: 1
MaxLength: 15*
numeric, 1-9 
The unique identifier of the customer
MaxLength may differ depending on configuration
KID (Norway)
nationalIdentifierobject  
   nationalIdentifier.regNostringCountry specificSweden: YYYYMMDD-NNNC
Norway: DDMMYYNNNNN
   nationalIdentifier.countryCodestringISO 3166-1 alpha-2 
vatNostringMinLength: 7
MaxLength: 17
Regex pattern:
[A-Z]{2}.*
Customer VAT registration number. Mandatory if reverse tax is used. Must conform to country specific algorithm
legalEntitystring valid values:
"consumer"
"business"
namestringMaxlength: 72
Regex?
Full name of end-customer
emailAddressstringMaxlength: 254
Regex pattern: [^@]+@[^\.]+\..+
 
msisdnstringMaxlength: 15
Minlength: 5
+NNNN
 "Mobile Subscriber Integrated Services Digital Network Number", ie. Cellphone number
Countrycode is always required as the example below
+46720000000
eDIAddressInfoobject EDI addressing info
   eDIAddressInfo.vanstringMaxlength: 255

Buyer VAN identifier (OperatorId)

   eDIAddressInfo.interChangeRecipientstringMaxlength: 13Routing address. EAN
   eDIAddressInfo.BuyerIdstringMaxlength: 13NAD_BY/Buyerparty. EAN/Corporate identity number
legalAddressuri reference to the customers legal address
billingAddressuri 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.

PropertyRequired
addresseeYes
streetAddressNo
coAddressNo
cityYes
zipCodeYes
countryCodeYes

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

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

PropertyData typeFormatDescription
addresseestringMaxlength: 72Fullname
streetAddressstringMaxlength: 35 
coAddressstringMaxlength: 35Care of (C/O) name. This is optional.
citystringMaxlength: 30 
zipCodestringMaxlength: 9ZipCode without whitespaces
countryCodestringISO 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

PropertyRequired
addresseeYes
streetAddressNo
coAddressNo
cityYes
zipCodeYes
countryCodeYes
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.

PropertyRequired
addresseeYes
streetAddressNo
coAddressNo
cityYes
zipCodeYes
countryCodeYes
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

PropertyData typeFormatDescription
addresseestringMaxlength: 72Fullname
streetAddressstringMaxlength: 35 
coAddressstringMaxlength: 35Care of (C/O) name. This is optional.
citystringMaxlength: 30 
zipCodestringMaxlength: 9ZipCode without whitespaces
countryCodestringISO 3166-1 alpha-2 

Generate customer

The generate consumer customer by reg no resource is located under ledger/customer/v1/ apiIt 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.

PropertyRequired
customerNoNo
nationalIdentifier.regNoYes
nationalIdentifier.countryCodeYes
emailAddressNo
msisdnNo
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

PropertyData typeFormatDescription
@id stringMaxlength: Uri of the specific customer
customerNostringMaxlength: 15 
nationalIdentifier.regNostringCountry specificSweden: YYYYMMDD-NNNC
Norway: DDMMYYNNNNN
nationalIdentifier.countryCodestringISO 3166-1 alpha-2 
emailAddressstringMaxlength: 254
Regex pattern: [^@]+@[^\.]+\..+
 
msisdnstringMaxlength: 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/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." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.customer.validation".

Problem type (code)HttpstatusDescription
validation400occurs if any of the inputvalidation fails, it is described in the problem which parameter that failed the validation
forbidden403occurs if access to method is not allowed.
customer-does-not-exists404specified customer number does not exists
legal-address-does-not-exists404legal address does not exists for the specified customer
billing-address-does-not-exists404billing address does not exists for the specified customer
Created by Fredrik Nilsson on 2021/06/29 16:23