Draft:
Integrate to PayEx contract financing API

Changelog

2022-03-31
initial draft version

2022-05-05
Added status to the Contract resource

2025-02-04

Added AccountProfile to POST Contract

introduced new operation Extend

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

Contracts

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/XXX/contracts HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

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

Request properties requirements

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.
nationalConsumerIdentifier	Yes
value	Yes	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Sweden: YYYYMMDD-NNNC Norway: DDMMYYNNNNN
countryCode	Yes	ISO 3166-1 alpha-2
contractId	Yes	Unique identifier of each contract in the ledger
contractDescription	Yes	Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
accountProfile	Yes**	Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.
reservationAmount	Yes	Total contract value
duration	Yes**	No. of months the contract is expected to last. may be optional depending on agreement.
monthlyAmount	Yes**	Regular monthly amount to be billed/payed. (monthlyAmount * duration) must equal reservationAmount. Decimal places must be zero Ex(123.00). may be optional depending on agreement.
currency	Yes	Currency of the contract, must be equal to agreed currency SEK NOK DKK EUR

Response

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

{
"customerNo": "ABC123",
"nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
  },
"contractId": 23456,
"contractDescription": "Leasing product name",
"accountProfile": "Leasing12Months",
"reservationAmount": 4800.00,
"duration": "12",
"monthlyAmount": 400.00,
"currency": "SEK",
"unBilledAmount": 0.00,
"activatedAmount": 0,
"reservationValidToDate": "2022-03-01",
"status": "Open"
"operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/activate"
    },
    {
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/cancel"
    }
  ]
}

Get specific contract

Request

GET /ledger/contract-financing/v1/XXX/contracts/YYY HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

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

{
"customerNo": "ABC123",
"nationalConsumerIdentifier": {
     "value": "19101010-1010",
     "countryCode": "SE"
  },
"contractId": 23456,
"contractDescription": "Leasing product name",
"accountProfile": "Leasing12Months",
"contractEndDate": "2022-02-17",
"reservationAmount": 4800.00,
"activatedAmount": 4800.00,
"creditedAmount": 0.00,
"duration": "12",
"monthlyAmount": 400.00,
"currency": "SEK",
"unBilledAmount": 4800.00,
"reservationValidToDate": "2022-03-01",
"accountStatus": "Open"
"operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/activate"
    },
{
     "rel": "credit",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/credit"
    },
{
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/cancel"
    }
  ]
}

contract properties

Property	Data type	Format	Description
customerNo	string	Maxlength: 15	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.
nationalConsumerIdentifier			National identifier details
value	string	Country specific	The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer. Sweden: YYYYMMDD-NNNC Norway: DDMMYYNNNNN
countryCode	string	ISO 3166-1 alpha-2	The country code for the identifier value property
contractId	integer(uint)	Numeric, maxValue(4294967295)	Unique identifier of each contract in the ledger
contractDescription	string	Maxlength: 50	Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
accountProfile	string	Maxlength: 50	Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.
contractEndDate	date(nullable)	ISO 8601	The end date of the contract
reservationAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.01	Originally reserved contract value
activatedAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.00	Total activated contracted value
creditedAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.00	Total credited contract value
duration	string	12, 24, 36	No. of months the contract is expected to last
monthlyAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.01	Regular monthly amount to be billed/payed
currency	string		Currency of the contract, must be equal to agreed currency SEK NOK DKK EUR
unBilledAmount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.00	remaining non billed/invoiced contract value
accountStatus	string	Open, Closed
reservationValidToDate	date	ISO 8601	The contract is valid for activation until this date

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 contract if available.

Request

POST /ledger/contract-financing/v1/XXX/contracts/NNN/activate HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"transactionId": "123456",
"contractEndDate": "2023-03-25"
}

Request properties requirements

Property	Required
transactionId	Yes
contractEndDate	Yes

Response

HTTP/1.1 204 No Content
Content-Type: application/json

Properties

Property	Data type	Format	Description
transactionId	string	Maxlength: 50	Unique identifier of all types of transactions (activate/credit/offcontract) in the ledger. Use only alphanumeric characters and/or underscore. Please note that offcontract (in CustomerBilling file) transactionIds must be unique, within the same range.
contractEndDate	date	ISO 8601	The end date of the contract

Credit

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

Request

POST /ledger/contract-financing/v1/XXX/contracts/NNN/credit HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"transactionId": "123456",
"amount": 100.00,
"currency": "SEK"
}

Request properties requirements

Property	Required
transactionId	Yes
amount	Yes
currency	Yes

Response

HTTP/1.1 204 No Content
Content-Type: application/json

Properties

Property	Data type	Format	Description
transactionId	string	Maxlength: 50	Unique identifier of all types of transactions (activate/credit)in the ledger. Use only alphanumeric characters and/or underscore
amount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.00	amount to credit the contract
currency	string		Same currency as used when creating the contract

Extend

Extend the contract amount. The operation is exposed by the parent contract if available.

Request

POST /ledger/contract-financing/v1/XXX/contracts/NNN/extend HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

{
"transactionId": "123456",
"amount": 100.00,
"currency": "SEK"
}

Request properties requirements

Property	Required
transactionId	Yes
amount	Yes
currency	Yes

Response

HTTP/1.1 204 No Content
Content-Type: application/json

Properties

Property	Data type	Format	Description
transactionId	string	Maxlength: 50	Unique identifier of all types of transactions (activate/credit,extend)in the ledger. Use only alphanumeric characters and/or underscore
amount	decimal	Fraction digits: 2 Max size: 100000000 Min size: 0.00	amount to extend the contract with
currency	string		Same currency as used when creating the contract

Cancel

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

Request

POST /ledger/contract-financing/v1/XXX/contracts/NNN/cancel HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Response

HTTP/1.1 204 No Content
Content-Type: application/json

Problem types

Note, each problem typecode is preceded by "ledger.contract-financing." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.contract-financing.validation".

Problem type (code)	Httpstatus	Description
validation	400	occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
not-found	404	requested resource not found
contract-id-invalid	404	requested resource not found
conflict	409	state of resource is un valid for any further progress
claimant-mismatch	409	mismatch between claimant (in url) used in new request vs. when authenticaiton resource was made,
authentication-is-no-longer-valid	422	the limited time of the authentication has passed
transactionId-not-unique	422	Duplicate external transaction reference
credit-check-rejected	422	credit check or extend of credit check was rejected
currency-invalid	422	the currency is not valid
invalid-regno-exception	409	the regno did not pass validation. regex or checksum was wrong
seller-not-registerd	422	company seller is not registered
contract-no-longer-valid	422	contract reservation has expired
transactionId-not-unique	422	transaction with same id already exist
contract-id-invalid	422	contract id is not valid or existing contractid already exist
invalid-contract-status	422	contract has invalid status
fatal	500	Unexpected error, logs maybe can tell more in detail what the problem is
not-implemented	501	the requested method is not implemented fully by code or not configured for the resource, body will tell which.

Ledger and Factoring

contract-financing-working

Changelog

Introduction

Contracts

Create contract

Get specific contract

Activate

Credit

Extend

Cancel

Problem types