Introduction

This guide describes the requirements for server-to-server communication between an external client and PayEx ledger APIs.

Terms

• Mutual TLS (mTLS): Defined as "two or more entities verify the others' legality before any data or information is transmitted"
• Ingress: Exposes HTTPS routes from the outside to ledger APIs.
• LedgerNo: A ledger is represented by an ledger number. The term company number\companyNo is also used.
• Client: Initiates a request. This request will always refer to a specific ledger.
• Client certificate: A x509-certificate issued by PayEx to secure the ingress to ledger APIs as part of a mTLS setup.
• TenantOwnerNo: A tenant owner number represents one or many ledgers as a group. Can in it self also represent a ledger (i.e if a client issues requests for a small number of ledgers, there is no need to use a separate "TenantOwnerNo"). Client certificates are always issued to a specific "TenantOwnerNo",
• Reference token: Sometimes also called opaque tokens are just a references to a stored token. Reference-tokens are issued by PayEx to gain access to ledger APIs. Tokens are always issued to a specific "LedgerNo" and the ledger number in the request-url must match the ledger number in the token used to make the request.
• Credentials: A combination of client certificate and access token in a request.

Environments and urls

PayEx ledger offers two environments

• https://api.sandbox.payex.com/ledger
  This is our sandbox for testing APIs and workflows

• https://lf-api.payex.com/ledger
  This is our production environment

Each environment will require a specific set of credentials. Certificates and tokens used for the sandbox-environment cannot be used for production and vice versa.

TLS (Transport Layer Security) 1.2 is required for both endpoints

Client certificates

Both https://api.sandbox.payex.com/ledger and https://lf-api.payex.com/ledger are secured by mutual TLS and requires a client certificate. Each request must include the client certificate and will be validated to allow access to the APIs.

Lifetime

PayEx will issue these certificates and they are typically valid for two years.

Scope

• One certificate per client and environment

Client certificates are bound to the ingress for each environment. A client can server one or many ledgers using the same client certificate.

Formats

One zip-file containing

• pfx: PKCS#12 archive containing client certificate, signing certificate and private key
• key: Private key, encrypted pem-format
• crt: Client certificate and signing certificate, pem-format

Pfx and crt\key contains the same certificate\key information using different formats.

Zip-file:

Access tokens

Ledger APIs are protected by token based authentication. An authorization header containing an access token for a specific ledger must be included in each request.

Example

Lifetime

PayEx will issue these tokens and they will be in the form of reference tokens. A reference token is typically valid for 5000 days  (~13years) but this may change when new tokens are issued.

Scope

• Each access token gives access to exactly one ledger in a specific environment.

Example:

A company managing 10 ledgers in production and 1 ledger in sandbox will be issued a total of 11 access tokens

10 production-tokens intended for https://lf-api.payex.com/ledger

1 sandbox-token intended for https://api.sandbox.payex.com/ledger

Testing credentials

Both sandbox and production environment offers an url for testing credentials

• https://api.sandbox.payex.com/ledger/connection-test
• https://lf-api.payex.com/ledger/connection-test

Example using curl (on linux)

• -v: Verbose
• key: Private key as an encrypted pem-file
• pass: Password for "key"
• cert: Certificate as pem-file
• -H "Authorization: Token in an authorization header

A successful connection-test will include information about what ledger the token is issued to and when the credentials will expire. Credentials should be renewed well before expiration.

Problems

Some of the problems that might occur

• The client certificate is missing, revoked or invalid:

• The supplied token is invalid or the authorize-header is incorrect:

• The client certificate is valid but token does not have a cnf-claim:
  The token may have been incorrectly issued without a "proof of possession"-requirement. If that is the case, a new token must be issued with the correct requirements.

• LedgerNo in token does not match ledger number in request-url:
  The client may represent the ledger numbers used in both token and request-url but if the two does not match, the request will fail. In the example below, a token issued for "838383" is used to access ledger "838384"

Exchanging the secrets

Both the certificates and the tokens are sensitive information that must only be managed by those individuals with a business need for it. It is a Class 2 information class with an Extended security level.

The basic principles are:

• The certificates are distributed to the integrator through a specific Team area in Microsoft Teams, where the specific dedicated technical contact at the integrator is invited.
• The tokens are distributed through e-mail or through the same Team channel as the certificates.
• Password to access the certificates are sent via encrypted e-mail to the explicitly stated technical contact with sensitivity levels set to Confidential.

N.B. The technical contact must be agreed in advance before set-up. To access a Team area within PayEx, name and e-mail address to the technical contact are needed, including the domain of the integrator (i.e. payex.com for PayEx employees)

Removal of certificates and tokens

As soon as the integrator confirmes fetching the certificates and tokens and have successfully completed a connection test the certificates and tokens will be removed from the Teams area.

Any issues should render the creation of a new certificate or token (i.e. no re-distribution of already "delivered" certificates should exist).

HTTP Headers

PayEx supports some HTTP headers for tracking that are used for troubleshooting purposes. It is not a requirement to use any of these http headers but it is highly recommended to implement at least "X-Request-ID" as a minimum for any future troubleshooting and support. The value of those headers is preferably a uniquely generated GUID and is set by the caller.

X-Request-ID

This HTTP header uniquely identifies every HTTP request, and is set by the caller on all requests passed to PayEx.

X-Correlation-ID

As an option for improved troubleshooting PayEx also supports the header "X-Correalation-ID". This HTTP header is a uniquely generated value (on the caller side) that is set on all requests that is part of an operation or event chain that consists of multiple requests. The value is thus unique per operation or event chain rather than for each request.

Example request