Ledger and Factoring

contract-financing-working

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

1645795304707-487.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 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 segmentDescription
subDomainIn this part of the API it is contract-financing
ledgerNumberThe ledger identifier/number  that you will receive from PayEx at setup
resource1IdIdentifier of resource1

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

ResourceIdentifier
ledgerNumberXXX = ledgerNumber
contractsNNN = 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

{
 "unBilledAmount": 4700.00,
 "status": "Open",
 "contractEndDate": "2023-02-17",
 "authorizations": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations",
 "customerNo": "ABC123",
 "nationalConsumerIdentifier": {
   "value": "19101010-1010",
   "countryCode": "SE"
  },
 "contractId": 23456,
 "contractDescription": "Leasing product name",
 "duration": "12",
 "monthlyAmount": 400.00,
 "currency": "SEK",
 "accountProfile": "ContractFinancing-12",
 "operations": [
    {
     "rel": "add-authorization",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/23456/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 
404 not-found invalid authentication status for requested method 
404 authorization-id-invalid The requested resource was not found! 
404 invalid-authentication-state The requested resource was not found! 
500 not-found The requested resource was not found! 

1.2 Create Contract

Creating a contract involves PayEx credit checking the end customer. If approved, the contract is created, the initial authorization is also 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

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

Request object specification

Property Data typeFormatRequiredDescription
authorizationId number Type: int64
Min: 0 		Yes Unique identifier of each authorization in the ledger
authorizationAmount number Type: double
Pattern: ^\d+.\d{0,2}$
Max: 100000000
Min: 0 		Yes Originally authorized contract value
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
contractId number Type: int32
Max: 4294967295
Min: 0 		Yes Unique identifier of each contract in the ledger
contractDescription string Pattern: ^[a-zA-Z0-9_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ Yes Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
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_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ No Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.

Get a created Contract

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

{
 "unBilledAmount": 4800.00,
 "status": "Open",
 "authorizations": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations",
 "customerNo": "ABC123",
 "nationalConsumerIdentifier": {
   "value": "19101010-1010",
   "countryCode": "SE"
  },
 "contractId": 23456,
 "contractDescription": "Leasing product name",
 "duration": "12",
 "monthlyAmount": 400.00,
 "currency": "SEK",
 "accountProfile": "ContractFinancing-12",
 "@id": "/ledger/contract-financing/v1/yyy/contracts/23456",
 "operations": [
    {
     "rel": "add-authorization",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/23456/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 credit-check-rejected credit check or extend of credit check was rejected 
500 fatal Unexpected error, logs may give details about the problem 

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
unBilledAmount number Type: double  
status string 
  • open
  • closed
account status
contractEndDate string Type: date Expected end date of the contract
authorizations dynamic    
operations array  List of operations that is possible to perform on the current resource, read more about the hypermedia part of the response
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
contractId number Type: int32
Max: 4294967295
Min: 0 		Unique identifier of each contract in the ledger
contractDescription string Pattern: ^[a-zA-Z0-9_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ 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, maybe required depending on configuration
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
 
accountProfile string Pattern: ^[a-zA-Z0-9_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.

2. Authorizations

Get authorization list.

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

List of authorizations

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

{
 "items": [
    {
     "activatedAmount": 50,
     "creditedAmount": 10,
     "validToDate": "2025-02-25",
     "status": "Open",
     "authorizationId": 11111,
     "amount": 100,
     "currency": "SEK",
     "@id": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/11111",
     "operations": [
        {
         "rel": "activate",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/11111/activate"
        },
        {
         "rel": "cancel",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/11111/cancel"
        },
        {
         "rel": "credit",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/11111/credit"
        }
      ]
    },
    {
     "activatedAmount": 150,
     "creditedAmount": 100,
     "validToDate": "2025-03-25",
     "status": "Open",
     "authorizationId": 22222,
     "amount": 200,
     "currency": "SEK",
     "@id": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/22222",
     "operations": [
        {
         "rel": "activate",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/22222/activate"
        },
        {
         "rel": "cancel",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/22222/cancel"
        },
        {
         "rel": "credit",
         "method": "POST",
         "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/22222/credit"
        }
      ]
    }
  ],
 "navigation": {
   "@id": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations"
  }
}

View a specific authorization based on 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

Get a created autorization

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

{
 "activatedAmount": 1000.00,
 "creditedAmount": 500.00,
 "validToDate": "2025-02-25",
 "status": "Open",
 "authorizationId": 1425,
 "amount": 3500.00,
 "currency": "SEK",
 "operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/activate"
    },
    {
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/cancel"
    },
    {
     "rel": "credit",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/credit"
    }
  ]
}

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 
404 not-found invalid authentication status for requested method 
404 authorization-id-invalid The requested resource was not found! 
404 invalid-authorization-status The requested resource was not found! 
500 not-found The requested resource was not found! 

2.3 Create Authorization

Creating a 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": 55923,
 "amount": 1400.00,
 "currency": "SEK"
}

Request object specification

Property Data typeFormatRequiredDescription
authorizationId number Type: int64
Min: 0 		Yes Unique identifier of each authorization in the ledger
amount number Type: double
Pattern: ^\d+.\d{0,2}$
Max: 100000000
Min: 0 		Yes Originally authorized contract value
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
Yes  

Get a created autorization

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

{
 "activatedAmount": 1000.00,
 "creditedAmount": 500.00,
 "validToDate": "2025-02-25",
 "status": "Open",
 "authorizationId": 1425,
 "amount": 3500.00,
 "currency": "SEK",
 "@id": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425",
 "operations": [
    {
     "rel": "activate",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/activate"
    },
    {
     "rel": "cancel",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/cancel"
    },
    {
     "rel": "credit",
     "method": "POST",
     "href": "/ledger/contract-financing/v1/yyy/contracts/ccc/authorizations/1425/credit"
    }
  ]
}

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 
500 fatal Unexpected error, logs may give details about the problem 

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
authorizationId number Type: int64
Min: 0 		Unique identifier of each authorization in the ledger
amount number Type: double
Pattern: ^\d+.\d{0,2}$
Max: 100000000
Min: 0 		Originally authorized contract value
currency string 
  • SEK
  • NOK
  • DKK
  • EUR
 
activatedAmount number Type: double Total activated contracted value
creditedAmount number Type: double Total credited contract value
validToDate string Type: date The contract is valid for activation until this date
status string 
  • open
  • closed
  • cancelled
authorization status
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 contract 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": "2025-02-25",
 "amount": 100.00,
 "currency": "SEK"
}

Request object specification

Property Data typeFormatRequiredDescription
transactionId string Pattern: ^[a-zA-Z0-9_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ 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
Max: 100000000
Min: 0 		Yes Part of the authorization to activate
currencystring
  • SEK
  • NOK
  • DKK
  • EUR
Yes 
Response
HTTP/1.1 201 CREATED
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 
500 fatal Unexpected error, logs may give details about the problem 
404 authorization-id-invalid The requested resource was not found! 
404 invalid-authorization-status The requested resource was not found! 

4. Credit

4.1 Create 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/{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 typeFormatRequiredDescription
transactionId string Pattern: ^[a-zA-Z0-9_:!&quot;#&lt;&gt;=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ 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 201 CREATED
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 used contractId isn't a match 
500 fatal Unexpected error, logs may give details about the problem 

5. Cancel

5.1 Create Cancel

Cancels the authorization, blocking any further activation. The operation is exposed by the parent contract 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 used contractId isn't a match 
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]"
         ]
      }
}
Created by Rasmus Enekvist on 2025/02/04 10:35