PayEx Developer Portal - contract-financing-working

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.

29

30

== [[image:ContractFinancing.png||alt="1645795304707-487.png"]] ==

31

32

33

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

34

35

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.

36

//api.payex.com/ledger/**{subDomain}**/v1/**{ledgerNumber}**/resource1/**{resource1Id}**//

37

38

(% class="table-bordered table-striped" %)

39

|=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description

40

|(% style="width:604px" %)subDomain|(% style="width:2790px" %)In this part of the API it is contract-financing

41

|(% style="width:604px" %)ledgerNumber|(% style="width:2790px" %)The ledger identifier/number that you will receive from PayEx at setup

42

|(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1

43

44

(% class="wikigeneratedid" %)

45

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

46

47

(% class="table-bordered table-striped" %)

48

|=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier

49

|(% style="width:488px" %)ledgerNumber|(% style="width:2271px" %)XXX = ledgerNumber

50

|(% style="width:488px" %)contracts|(% style="width:2271px" %)NNN = contractId

== 1. Contracts ==

View a specific contract based on contractId

56

57

==== 1.1 Get specific Contract ====

58

59

60

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId} HTTP/1.1

61

Host: -

62

Authorization: Bearer<Token>

63

Content-Type: application/json

Get a created Contract

HTTP/1.1 200 OK

Content-Type: application/json

72

73

{

74

"unBilledAmount": 4700.00,

75

"status": "Open",

76

"contractEndDate": "2023-02-17",

77

"authorizations": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations",

78

"customerNo": "ABC123",

79

"nationalConsumerIdentifier": {

80

"value": "19101010-1010",

"countryCode": "SE"

},

"contractId": 23456,

"contractDescription": "Leasing product name",

85

"duration": "12",

86

"monthlyAmount": 400.00,

87

"currency": "SEK",

88

"accountProfile": "ContractFinancing-12",

89

"operations": [

90

{

91

"rel": "add-authorization",

92

"method": "POST",

93

"href": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations"

}

]

}

**Possible problems**

102

103

(% class="table-bordered table-striped" %)

104

|=Http status |=Problem type |=Description

105

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

106

|422 |invalid-authentication-state |invalid authentication status for requested method

107

|404 |not-found |invalid authentication status for requested method

108

|404 |authorization-id-invalid |The requested resource was not found!

109

|404 |invalid-authentication-state |The requested resource was not found!

110

|500 |not-found |The requested resource was not found!

111

112

==== 1.2 Create Contract ====

113

114

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.

115

116

117

POST /ledger/contract-financing/v1/{ownerNo}/contracts HTTP/1.1

118

Host: -

119

Authorization: Bearer<Token>

120

Content-Type: application/json

121

122

{

123

"authorizationId": 55923,

124

"authorizationAmount": 4800.00,

125

"customerNo": "ABC123",

126

"nationalConsumerIdentifier": {

127

"value": "19101010-1010",

"countryCode": "SE"

},

"contractId": 23456,

"contractDescription": "Leasing product name",

132

"duration": "12",

133

"monthlyAmount": 400.00,

134

"currency": "SEK",

135

"accountProfile": "ContractFinancing-12"

}

**Request object specification**

141

142

(% class="table-bordered table-striped" %)

143

144

|authorizationId |number |Type: int64

145

Min: 0 |Yes |Unique identifier of each authorization in the ledger

146

|authorizationAmount |number |Type: double

147

Pattern: ^\d+.\d{0,2}$

148

Max: 100000000

149

Min: 0 |Yes |Originally authorized contract value

150

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

151

Use only alphanumeric characters

152

153

| 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

154

| countryCode |string | |Yes |The country code for the identifier value property, empty strings are not allowed, [[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]

155

|contractId |number |Type: int32

156

Max: 4294967295

157

Min: 0 |Yes |Unique identifier of each contract in the ledger

158

|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

159

160

|monthlyAmount |number |Type: double

161

Pattern: ^\d+.\d{0,2}$

162

Max: 100000000

163

Min: 0 |No |Regular monthly amount to be billed/payed, maybe required depending on configuration

164

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

171

172

Get a created Contract

HTTP/1.1 201 Created

Content-Type: application/json

177

178

{

179

"unBilledAmount": 4800.00,

180

"status": "Open",

181

"authorizations": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations",

182

"customerNo": "ABC123",

183

"nationalConsumerIdentifier": {

184

"value": "19101010-1010",

"countryCode": "SE"

},

"contractId": 23456,

"contractDescription": "Leasing product name",

189

"duration": "12",

190

"monthlyAmount": 400.00,

191

"currency": "SEK",

192

"accountProfile": "ContractFinancing-12",

193

"@id": "/ledger/contract-financing/v1/yyy/contracts/23456",

194

"operations": [

195

{

196

"rel": "add-authorization",

197

"method": "POST",

198

"href": "/ledger/contract-financing/v1/yyy/contracts/23456/authorizations"

}

]

}

**Possible problems**

206

207

(% class="table-bordered table-striped" %)

208

|=Http status |=Problem type |=Description

209

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

210

|422 |invalid-authentication-state |invalid authentication status for requested method

211

|422 |credit-check-rejected |credit check or extend of credit check was rejected

212

|500 |fatal |Unexpected error, logs may give details about the problem

213

214

**Response object specification**

215

216

(% class="table-bordered table-striped" %)

217

|=Property |=(% style="width: 78px;" %)Data type|=(% style="width: 291px;" %)Format|=Description

218

|@id |(% style="width:78px" %)string |(% style="width:291px" %) |Uri identifier of the current resource

219

|unBilledAmount |(% style="width:78px" %)number |(% style="width:291px" %)Type: double |

220

|status |(% style="width:78px" %)string |(% style="width:291px" %)(((

* open

* closed

)))|account status

|contractEndDate |(% style="width:78px" %)string |(% style="width:291px" %)Type: date |Expected end date of the contract

225

|authorizations |(% style="width:78px" %)dynamic |(% style="width:291px" %) |

226

|operations |(% style="width:78px" %)array |(% style="width:291px" %) |List of operations that is possible to perform on the current resource, read more about the [[hypermedia part of the response>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/ledger-api-general-docs/restful-pattern-guideline/#HHyper-mediaresponse]]

227

|customerNo |(% style="width:78px" %)string |(% style="width:291px" %)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.

228

Use only alphanumeric characters

229

|=nationalConsumerIdentifier |(% style="width:78px" %)object |(% style="width:291px" %) |

230

| value |(% style="width:78px" %)string |(% style="width:291px" %) |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

231

| countryCode |(% style="width:78px" %)string |(% style="width:291px" %) |The country code for the identifier value property, empty strings are not allowed, [[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]

232

|contractId |(% style="width:78px" %)number |(% style="width:291px" %)Type: int32

233

Max: 4294967295

234

Min: 0 |Unique identifier of each contract in the ledger

235

|contractDescription |(% style="width:78px" %)string |(% style="width:291px" %)Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ |Textual name/description of the leased product. Used on the invoice/bill sent to the end customer

236

|duration |(% style="width:78px" %)string |(% style="width:291px" %) |No. of months the contract is expected to last, maybe required depending on configuration

237

|monthlyAmount |(% style="width:78px" %)number |(% style="width:291px" %)Type: double

238

Pattern: ^\d+.\d{0,2}$

239

Max: 100000000

240

Min: 0 |Regular monthly amount to be billed/payed, maybe required depending on configuration

241

|currency |(% style="width:78px" %)string |(% style="width:291px" %)(((

* SEK

* NOK

* DKK

* EUR

)))|

|accountProfile |(% style="width:78px" %)string |(% style="width:291px" %)Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ |Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.

248

249

== 2. Authorizations ==

250

251

252

Get authorization list.

253

254

==== 2.1 Get list of Authorizations ====

255

256

257

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations HTTP/1.1

258

Host: -

259

Authorization: Bearer<Token>

260

Content-Type: application/json

List of authorizations

HTTP/1.1 200 OK

Content-Type: application/json

{

"items": [

{

"activatedAmount": 50,

274

"creditedAmount": 10,

275

"validToDate": "2025-02-25",

276

"status": "Open",

277

"authorizationId": 11111,

278

"amount": 100,

279

"currency": "SEK",

280

"@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,

301

"creditedAmount": 100,

302

"validToDate": "2025-03-25",

303

"status": "Open",

304

"authorizationId": 22222,

305

"amount": 200,

306

"currency": "SEK",

307

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

335

336

==== 2.2 Get specific Authorization ====

337

338

339

GET /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId} HTTP/1.1

340

Host: -

341

Authorization: Bearer<Token>

342

Content-Type: application/json

Get a created autorization

HTTP/1.1 200 OK

Content-Type: application/json

351

352

{

353

"activatedAmount": 1000.00,

354

"creditedAmount": 500.00,

355

"validToDate": "2025-02-25",

356

"status": "Open",

357

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

383

384

(% class="table-bordered table-striped" %)

385

|=Http status |=Problem type |=Description

386

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

387

|422 |invalid-authentication-state |invalid authentication status for requested method

388

|404 |not-found |invalid authentication status for requested method

389

|404 |authorization-id-invalid |The requested resource was not found!

390

|404 |invalid-authorization-status |The requested resource was not found!

391

|500 |not-found |The requested resource was not found!

392

393

==== 2.3 Create Authorization ====

394

395

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.

396

397

398

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations HTTP/1.1

399

Host: -

400

Authorization: Bearer<Token>

401

Content-Type: application/json

402

403

{

404

"authorizationId": 55923,

"amount": 1400.00,

"currency": "SEK"

}

**Request object specification**

412

413

(% class="table-bordered table-striped" %)

414

415

|authorizationId |number |Type: int64

416

Min: 0 |Yes |Unique identifier of each authorization in the ledger

417

|amount |number |Type: double

418

Pattern: ^\d+.\d{0,2}$

419

Max: 100000000

420

Min: 0 |Yes |Originally authorized contract value

421

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

Get a created autorization

HTTP/1.1 201 Created

Content-Type: application/json

433

434

{

435

"activatedAmount": 1000.00,

436

"creditedAmount": 500.00,

437

"validToDate": "2025-02-25",

438

"status": "Open",

439

"authorizationId": 1425,

440

"amount": 3500.00,

441

"currency": "SEK",

442

"@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**

465

466

(% class="table-bordered table-striped" %)

467

|=Http status |=Problem type |=Description

468

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

469

|422 |invalid-authentication-state |invalid authentication status for requested method

470

|422 |credit-check-rejected |credit check or extend of credit check was rejected

471

|500 |fatal |Unexpected error, logs may give details about the problem

472

473

**Response object specification**

474

475

(% class="table-bordered table-striped" %)

476

|=Property |=Data type|=Format|=Description

477

|@id |string | |Uri identifier of the current resource

478

|authorizationId |number |Type: int64

479

Min: 0 |Unique identifier of each authorization in the ledger

480

|amount |number |Type: double

481

Pattern: ^\d+.\d{0,2}$

482

Max: 100000000

483

Min: 0 |Originally authorized contract value

484

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

|activatedAmount |number |Type: double |Total activated contracted value

491

|creditedAmount |number |Type: double |Total credited contract value

492

|validToDate |string |Type: date |The contract is valid for activation until this date

|status |string |(((

* open

* closed

* cancelled

)))|authorization status

498

|operations |array | |List of operations that is possible to perform on the current resource, read more about the [[hypermedia part of the response>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/ledger-api-general-docs/restful-pattern-guideline/#HHyper-mediaresponse]]

== 3. Activate ==

==== 3.1 Create Activate ====

504

505

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.

506

507

508

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId}/activate HTTP/1.1

509

Host: -

510

Authorization: Bearer<Token>

511

Content-Type: application/json

512

513

{

514

"transactionId": "123548776",

515

"contractEndDate": "2025-02-25",

"amount": 100.00,

"currency": "SEK"

}

**Request object specification**

523

524

(% class="table-bordered table-striped" %)

525

526

|transactionId |string |Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ |Yes |Unique identifier of all types of transactions (contract/activate/credit)in the ledger

527

528

|amount |number |Type: double

529

Max: 100000000

530

Min: 0 |Yes |Part of the authorization to activate

|currency|string|(((

* SEK

* NOK

* DKK

* EUR

)))|Yes|

HTTP/1.1 201 CREATED

Content-Type: application/json

{

}

**Possible problems**

548

549

(% class="table-bordered table-striped" %)

550

|=Http status |=Problem type |=Description

551

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

552

|422 |invalid-authentication-state |invalid authentication status for requested method

553

|422 |invalid-authorization-status |occurs if the contract has another status than what's allowed for the operation

554

|500 |fatal |Unexpected error, logs may give details about the problem

555

|404 |authorization-id-invalid |The requested resource was not found!

556

|404 |invalid-authorization-status |The requested resource was not found!

== 4. Credit ==

==== 4.1 Create Credit ====

562

563

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

564

565

566

POST /ledger/contract-financing/v1/{ownerNo}/contracts/{contractId}/authorizations/{authorizationId}/credit HTTP/1.1

567

Host: -

568

Authorization: Bearer<Token>

569

Content-Type: application/json

570

571

{

572

"transactionId": "1235487767",

"amount": 120.22,

"currency": "SEK"

}

**Request object specification**

580

581

(% class="table-bordered table-striped" %)

582

583

|transactionId |string |Pattern: ^[a-zA-Z0-9_:!"#<>=?\[\]@{}´ %-/À-ÖØ-öø-ú]*$ |Yes |Unique identifier of all types of transactions (contract/activate/credit)in the ledger

584

|amount |number |Type: double

585

Pattern: ^\d+.\d{0,2}$

586

Max: 100000000

587

Min: 0 |Yes |Amount to credit the contract

588

|currency |string |(((

589

* SEK