Integrate to PayEx contract financing API

Changelog

2022-03-31
initial draft version

2022-05-05
Added status to the Contract resource

2025-06-17

Added AccountProfile to POST Contract

introduced new resource authorization

Introduction

The contract-financing API is used to handle the financed contracts between PayEx and the Lessor. Before the end customer can be offered a financed operational lease, the contract value has to be approved by PayEx.

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 resource3Id, to operate on this resource you must also include the ids of its parent resources in the route.
api.payex.com/ledger/{subDomain}/v1/{ledgerNumber}/resource1/{resource1Id}

Route segment	Description
subDomain	In this part of the API it is contract-financing
ledgerNumber	The ledger identifier/number that you will receive from PayEx at setup
resource1Id	Identifier of resource1

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

Resource	Identifier
ledgerNumber	XXX = ledgerNumber
contracts	NNN = contractId

1. Contracts

View a specific contract based on contractId

1.1 Get specific Contract

Request

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Get a created Contract

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"contractEndDate": "2027-02-17",
"unBilledAmount": 4700.00,
"status": "Open",
"operations": [
    {
     "rel": "add-authorization",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/23456/authorizations"
    }
  ],
"authorizations": "/ledger/contract-financing/v1/xxx/contracts/23456/authorizations",
"contractId": 23456,
"customerNo": "ABC123",
"nationalConsumerIdentifier": {
   "value": "19101010-1010",
   "countryCode": "SE"
  },
"contractDescription": "Leasing product name",
"duration": "12",
"monthlyAmount": 400.00,
"currency": "SEK",
"accountProfile": "ProfileName",
"@id": "/ledger/contract-financing/v1/xxx/contracts/23456"
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	contract-id-not-found	Occurs if the contract was not found
404	not-found	Invalid authentication status for requested method

1.2 Create Contract

Creating a contract involves PayEx credit checking the end customer. If approved, the contract is created and can be activated when the lease is started and the regret period is passed.

Request

POST /ledger/contract-financing/v1/{ownerNo}/contracts HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"contractId": 23456,
"customerNo": "ABC123",
"nationalConsumerIdentifier": {
   "value": "19101010-1010",
   "countryCode": "SE"
  },
"contractDescription": "Leasing product name",
"authorizationAmount": 4800.00,
"duration": "12",
"monthlyAmount": 400.00,
"currency": "SEK",
"accountProfile": "ProfileName",
"authorizationId": 2345678
}

Request object specification

Property	Data type	Format	Required	Description
contractId	number	Type: int32 Max: 4294967295 Min: 0	Yes	Unique identifier of each contract in the ledger. Must be a non-negative integer (unsigned int).
customerNo	string	Pattern: ^[a-zA-Z0-9\-]*$	No	The identifier of the customer, 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. Use only alphanumeric characters
nationalConsumerIdentifier	object		Yes
value	string		Yes	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string		Yes	The country code for the identifier value property, empty strings are not allowed, ISO 3166-1 alpha-2
contractDescription	string	Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$	Yes	Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
authorizationAmount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Yes	Originally authorized contract value
duration	string		No	No. of months the contract is expected to last, maybe required depending on configuration
monthlyAmount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	No	Regular monthly amount to be billed/payed, maybe required depending on configuration
currency	string	SEK NOK DKK EUR	Yes
accountProfile	string	Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$	No	Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement
authorizationId	number	Type: int64 Min: 0	Yes	Unique id for the reservation

Creates a Contract

Response

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

{
"unBilledAmount": 4800.00,
"status": "Open",
"operations": [
    {
     "rel": "add-authorization",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/23456/authorizations"
    }
  ],
"authorizations": "/ledger/contract-financing/v1/xxx/contracts/23456/authorizations",
"contractId": 23456,
"customerNo": "ABC123",
"nationalConsumerIdentifier": {
   "value": "19101010-1010",
   "countryCode": "SE"
  },
"contractDescription": "Leasing product name",
"duration": "12",
"monthlyAmount": 400.00,
"currency": "SEK",
"accountProfile": "ProfileName",
"authorizationId": 2345678,
"@id": "/ledger/contract-financing/v1/xxx/contracts/23456"
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	credit-check-rejected	Credit check or extend of credit check was rejected
422	authorization-id-invalid	Occurs if the used authorizationId isn't valid, might already exist
422	duplicate-contract-id	Occurs if the used contractId is a duplicate
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
contractId	number	Type: int32 Max: 4294967295 Min: 0	Unique identifier of each contract in the ledger
customerNo	string	Pattern: ^[a-zA-Z0-9\-]*$	The identifier of the customer, 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. Use only alphanumeric characters
nationalConsumerIdentifier	object
value	string		The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Visit developer.payex.com for information about supported national identifier format
countryCode	string		The country code for the identifier value property, empty strings are not allowed, ISO 3166-1 alpha-2
contractDescription	string	Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$	Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
duration	string		No. of months the contract is expected to last, maybe required depending on configuration
monthlyAmount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Regular monthly amount to be billed/payed
currency	string	SEK NOK DKK EUR
accountProfile	string		AccountProfile for account. If empty, default will be used
contractEndDate	string	Type: date	The end date of the contract
unBilledAmount	number	Type: double	Remaining non billed/invoiced contract value
status	string		Billing account status
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response
authorizations	dynamic

2. Authorizations

Get all authorizations based on contractId

2.1 Get list of Authorizations

Request

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Lists all authorizations

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"items": [
    {
     "activatedAmount": 0,
     "creditedAmount": 0,
     "status": "Open",
     "validToDate": "2029-10-01",
     "operations": [
        {
         "rel": "activate",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/activate"
        },
        {
         "rel": "cancel",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/cancel"
        },
        {
         "rel": "credit",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/credit"
        }
      ],
     "authorizationId": 2345678,
     "amount": 1200,
     "currency": "SEK",
     "@id": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678"
    },
    {
     "activatedAmount": 0,
     "creditedAmount": 0,
     "status": "Open",
     "validToDate": "2029-12-01",
     "operations": [
        {
         "rel": "activate",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345679/activate"
        },
        {
         "rel": "cancel",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345679/cancel"
        },
        {
         "rel": "credit",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345679/credit"
        }
      ],
     "authorizationId": 2345679,
     "amount": 2400,
     "currency": "SEK",
     "@id": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345679"
    }
  ],
"navigation": {
   "@id": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations"
  }
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	contract-id-not-found	Occurs if the contract was not found
500	fatal	Unexpected error, logs may give details about the problem

Get a specific authorization based on contractId and authorizationId

2.2 Get specific Authorization

Request

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response of one authorization

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"activatedAmount": 0,
"creditedAmount": 0,
"status": "Open",
"validToDate": "2029-10-01",
"operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/activate"
    },
    {
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/cancel"
    },
    {
     "rel": "credit",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/credit"
    }
  ],
"authorizationId": 2345678,
"amount": 1200,
"currency": "SEK",
"@id": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678"
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	contract-id-not-found	Occurs if the contract was not found
422	authorization-id-invalid	Occurs if the authorizationId is not valid
500	fatal	Unexpected error, logs may give details about the problem

2.3 Create Authorization

Creating an authorization involves PayEx credit checking the end customer. If approved, the authorization is created and can be activated when the lease is started and the regret period is passed.

Request

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"authorizationId": 2345678,
"amount": 1200,
"currency": "SEK"
}

Request object specification

Property	Data type	Format	Required	Description
authorizationId	number	Type: int64 Min: 0	Yes	Unique identifier of each contract in the ledger
amount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Yes	Authorization amount
currency	string	SEK NOK DKK EUR	Yes

Response of one authorization

Response

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

{
"activatedAmount": 0,
"creditedAmount": 0,
"status": "Open",
"validToDate": "2029-10-01",
"operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/activate"
    },
    {
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/cancel"
    },
    {
     "rel": "credit",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678/credit"
    }
  ],
"authorizationId": 2345678,
"amount": 1200,
"currency": "SEK",
"@id": "/ledger/contract-financing/v1/xxx/contracts/nnn/authorizations/2345678"
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	operation-not-allowed	Occurs if the operation is not allowed
422	contract-id-not-found	Occurs if the contract was not found
422	currency-validation	Occurs if the given currency in the request not matches the currency of the contract
422	authorization-id-invalid	Occurs if the authorizationId is not valid
500	fatal	Unexpected error, logs may give details about the problem

Response object specification

Property	Data type	Format	Description
@id	string		Uri identifier of the current resource
authorizationId	number	Type: int64 Min: 0	Unique identifier of each contract in the ledger
amount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Authorization amount
currency	string	SEK NOK DKK EUR
activatedAmount	number	Type: double	Total activated contracted value
creditedAmount	number	Type: double	Total credited contract value
status	string		Authorization status
validToDate	string	Type: date	The authorization is valid for activation until this date
operations	array		List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response

3. Activate

3.1 Create Activate

Activates the contract when the lease is started and regret period has passed. Initiates the clearing/settlement process of the contracted amount. The operation is exposed by the parent authorization if available.

Request

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId}/activate HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"transactionId": "123548776",
"contractEndDate": "2027-02-17",
"amount": 4700,
"currency": "SEK"
}

Request object specification

Property	Data type	Format	Required	Description
transactionId	string	Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$	Yes	Unique identifier of all types of transactions (contract/activate/credit)in the ledger
contractEndDate	string	Type: date	Yes	The end date of the contract
amount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Yes	Activate amount
currency	string	SEK NOK DKK EUR	Yes

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	invalid-amount	Amount is higher than available amount
422	invalid-authorization-status	Occurs if the authorization has another status than what's allowed for the operation
422	contract-not-found	Occurs if the used contractId isn't a match
422	authorization-id-invalid	Occurs if the authorizationId is not valid
500	fatal	Unexpected error, logs may give details about the problem

4. Cancel

4.1 Create Cancel

Cancels the contract and the reserved amount on the end customer. The operation is exposed by the parent authorization if available.

Request

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId}/cancel HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
}

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	invalid-authorization-status	Occurs if the contract has another status than what's allowed for the operation
422	authorization-id-invalid	Occurs if the authorizationId is not valid
422	contract-not-found	Occurs if the authorization does not match the contract
500	fatal	Unexpected error, logs may give details about the problem

5. Credit

5.1 Create Credit

Credits the unbilled contract amount and initiates clearing and settlement of the credited amount. The operation is exposed by the parent authorization if available.

Request

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId}/credit HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"transactionId": "1235487767",
"amount": 120.22,
"currency": "SEK"
}

Request object specification

Property	Data type	Format	Required	Description
transactionId	string	Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$	Yes	Unique identifier of all types of transactions (contract/activate/credit)in the ledger
amount	number	Type: double Pattern: ^\d+.\d{0,2}$ Max: 100000000 Min: 0	Yes	Amount to credit the contract
currency	string	SEK NOK DKK EUR	Yes

Response

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

{
}

Possible problems

Http status	Problem type	Description
400	validation	Occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
422	invalid-authentication-state	Invalid authentication status for requested method
422	invalid-amount	Credited amount is higher than available amount
422	currency-not-configured	Currency is invalid
422	authorization-id-invalid	Occurs if the authorizationId is not valid
422	contract-not-found	Occurs if the authorization does not match the contract
500	fatal	Unexpected error, logs may give details about the problem

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

Ledger and Factoring

../contract-financing

Changelog

Introduction

1. Contracts

1.1 Get specific Contract

1.2 Create Contract

2. Authorizations

2.1 Get list of Authorizations

2.2 Get specific Authorization

2.3 Create Authorization

3. Activate

3.1 Create Activate

4. Cancel

4.1 Create Cancel

5. Credit

5.1 Create Credit

Problems

Example