Last modified by Rasmus Enekvist on 2025/03/24 12:55
From empty
To version 12.1
edited by Rasmus Enekvist
on 2025/02/04 11:20
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +contract-financing-working
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.Invoicing.Contract Financing.Technical-reference.API.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +xwiki:XWiki.rae
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Tags
... ... @@ -1,0 +1,1 @@
1 +px-custom-page-content
Content
... ... @@ -1,0 +1,426 @@
1 +(% class="jumbotron" %)
2 +(((
3 +(% class="container" %)
4 +(((
5 +Draft:
6 +Integrate to **PayEx contract financing API **
7 +)))
8 +)))
9 +
10 += Changelog =
11 +
12 +2022-03-31
13 +initial draft version
14 +
15 +2022-05-05
16 +Added status to the Contract resource
17 +
18 +2025-02-04
19 +
20 +Added AccountProfile to POST Contract
21 +
22 +introduced new operation Extend
23 +
24 +(% id="HRoutesegments" %)
25 += Introduction =
26 +
27 +(% class="lead" %)
28 +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
51 +
52 +== Contracts ==
53 +
54 +=== Create contract ===
55 +
56 +(% class="wikigeneratedid" id="HCreatingacontractinvolvesPayExcreditcheckingtheendcustomer.Ifapproved2Cthecontractiscreatedandcanbeactivatedwhentheleaseisstartedandtheregretperiodispassed." %)
57 +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.
58 +
59 +
60 +{{code language="http" title="**Request**"}}
61 +POST /ledger/contract-financing/v1/XXX/contracts HTTP/1.1
62 +Host: -
63 +Authorization: Bearer<Token>
64 +Content-Type: application/json
65 +
66 +{
67 + "customerNo": "ABC123",
68 + "nationalConsumerIdentifier": {
69 + "value": "19101010-1010",
70 + "countryCode": "SE"
71 + },
72 + "contractId": 23456,
73 + "contractDescription": "Leasing product name",
74 + "accountProfile": "Leasing12Months",
75 + "reservationAmount": 4800.00,
76 + "duration": "12",
77 + "monthlyAmount": 400.00,
78 + "currency": "SEK"
79 +}
80 +{{/code}}
81 +
82 +**Request properties requirements**
83 +
84 +(% class="table-bordered table-striped" style="width:810px" %)
85 +|=(% style="width: 292px;" %)Property |=(% style="width: 159px;" %)Required|=(% style="width: 461px;" %)Comment
86 +|=(% style="width: 292px;" %)customerNo|(% style="width:159px" %)Yes*|(% style="width:461px" %)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.//
87 +|=(% style="width: 292px;" %)nationalConsumerIdentifier |(% style="width:159px" %)Yes |(% style="width:461px" %)
88 +|(% style="width:292px" %) value |(% style="width:159px" %)Yes |(% style="width:461px" %)The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer.
89 +Sweden: YYYYMMDD-NNNC
90 +Norway: DDMMYYNNNNN
91 +|(% style="width:292px" %) countryCode |(% style="width:159px" %)Yes |(% style="width:461px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]
92 +|(% style="width:292px" %)contractId|(% style="width:159px" %)Yes |(% style="width:461px" %)Unique identifier of each contract in the ledger
93 +|(% style="width:292px" %)contractDescription|(% style="width:159px" %)Yes |(% style="width:461px" %)Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
94 +|(% style="width:292px" %)accountProfile|(% style="width:159px" %)No~*~*|(% style="width:461px" %)Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.
95 +|(% style="width:292px" %)reservationAmount|(% style="width:159px" %)Yes|(% style="width:461px" %)Total contract value
96 +|(% style="width:292px" %)duration |(% style="width:159px" %)Yes~*~*|(% style="width:461px" %)No. of months the contract is expected to last. may be optional depending on agreement.
97 +|(% style="width:292px" %)monthlyAmount|(% style="width:159px" %)Yes~*~* |(% style="width:461px" %)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.
98 +|(% style="width:292px" %)currency |(% style="width:159px" %)Yes |(% style="width:461px" %)(((
99 +Currency of the contract, must be equal to agreed currency
100 +
101 +* SEK
102 +* NOK
103 +* DKK
104 +* EUR
105 +)))
106 +
107 +~** Maybe inverted depending on configurations agreed with PayEx.
108 +
109 +{{code language="http" title="**Response**"}}
110 +HTTP/1.1 201 CREATED
111 +Content-Type: application/json
112 +
113 +{
114 + "customerNo": "ABC123",
115 + "nationalConsumerIdentifier": {
116 + "value": "19101010-1010",
117 + "countryCode": "SE"
118 + },
119 + "contractId": 23456,
120 + "contractDescription": "Leasing product name",
121 + "accountProfile": "Leasing12Months",
122 + "reservationAmount": 4800.00,
123 + "duration": "12",
124 + "monthlyAmount": 400.00,
125 + "currency": "SEK",
126 + "unBilledAmount": 0.00,
127 + "activatedAmount": 0,
128 + "reservationValidToDate": "2022-03-01",
129 + "status": "Open"
130 + "operations": [
131 + {
132 + "rel": "activate",
133 + "method": "POST",
134 + "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/activate"
135 + },
136 + {
137 + "rel": "cancel",
138 + "method": "POST",
139 + "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/cancel"
140 + }
141 + ]
142 +}
143 +{{/code}}
144 +
145 +===== Get specific contract =====
146 +
147 +{{code language="http" title="**Request**"}}
148 +GET /ledger/contract-financing/v1/XXX/contracts/YYY HTTP/1.1
149 +Host: -
150 +Authorization: Bearer<Token>
151 +Content-Type: application/json
152 +
153 +
154 +{{/code}}
155 +
156 +{{code language="http" title="**Response**"}}
157 +HTTP/1.1 200 OK
158 +Content-Type: application/json
159 +
160 +{
161 + "customerNo": "ABC123",
162 + "nationalConsumerIdentifier": {
163 + "value": "19101010-1010",
164 + "countryCode": "SE"
165 + },
166 + "contractId": 23456,
167 + "contractDescription": "Leasing product name",
168 + "accountProfile": "Leasing12Months",
169 + "contractEndDate": "2022-02-17",
170 + "reservationAmount": 4800.00,
171 + "activatedAmount": 4800.00,
172 + "creditedAmount": 0.00,
173 + "duration": "12",
174 + "monthlyAmount": 400.00,
175 + "currency": "SEK",
176 + "unBilledAmount": 4800.00,
177 + "reservationValidToDate": "2022-03-01",
178 + "accountStatus": "Open"
179 + "operations": [
180 + {
181 + "rel": "activate",
182 + "method": "POST",
183 + "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/activate"
184 + },
185 +{
186 + "rel": "credit",
187 + "method": "POST",
188 + "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/credit"
189 + },
190 +{
191 + "rel": "cancel",
192 + "method": "POST",
193 + "href": "/ledger/contract-financing/v1/xxx/contracts/8c535338-d92c-49e7-90bf-304dbf38e0bd/cancel"
194 + }
195 + ]
196 +}
197 +{{/code}}
198 +
199 +
200 +**contract properties**
201 +
202 +(% class="table-bordered table-striped" %)
203 +|=(% style="width: 305px;" %)Property |=(% style="width: 187px;" %)Data type|=(% style="width: 138px;" %)Format|=(% style="width: 1042px;" %)Description
204 +|=(% style="width: 292px;" %)customerNo |(% style="width:159px" %)string|(% style="width:461px" %)Maxlength: 15|(% style="width:1042px" %)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.//
205 +|=(% style="width: 292px;" %)nationalConsumerIdentifier |(% style="width:159px" %) |(% style="width:461px" %) |(% style="width:1042px" %)National identifier details
206 +|(% style="width:292px" %) value |(% style="width:159px" %)string |(% style="width:461px" %)Country specific|(% style="width:1042px" %)The identifier - SSN, Personnummer, CPR, d-nummer, temporary identification number etc. Uniquely identifies the consumer.
207 +Sweden: YYYYMMDD-NNNC
208 +Norway: DDMMYYNNNNN
209 +|(% style="width:292px" %) countryCode |(% style="width:159px" %)string|(% style="width:461px" %)[[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]|(% style="width:1042px" %)The country code for the identifier value property
210 +|(% style="width:292px" %)contractId|(% style="width:159px" %)integer(uint)|(% style="width:461px" %)Numeric, maxValue(4294967295)|(% style="width:1042px" %)Unique identifier of each contract in the ledger
211 +|(% style="width:292px" %)contractDescription|(% style="width:159px" %)string|(% style="width:461px" %)Maxlength: 50|(% style="width:1042px" %)Textual name/description of the leased product. Used on the invoice/bill sent to the end customer
212 +|(% style="width:292px" %)accountProfile|(% style="width:159px" %)string|(% style="width:461px" %)Maxlength: 50|(% style="width:1042px" %)Describes a set of behaviours on the contract, values are agreed with PayEx, may be optional depending on agreement.
213 +|(% style="width:292px" %)contractEndDate|(% style="width:159px" %)date(nullable)|(% style="width:461px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1042px" %)The end date of the contract
214 +|(% style="width:292px" %)reservationAmount|(% style="width:159px" %)decimal|(% style="width:461px" %)Fraction digits: 2
215 +Max size: 100000000
216 +Min size: 0.01|(% style="width:1042px" %)(((
217 +Originally reserved contract value
218 +)))
219 +|(% style="width:292px" %)activatedAmount|(% style="width:159px" %)decimal|(% style="width:461px" %)Fraction digits: 2
220 +Max size: 100000000
221 +Min size: 0.00|(% style="width:1042px" %)Total activated contracted value
222 +|(% style="width:292px" %)creditedAmount|(% style="width:159px" %)decimal|(% style="width:461px" %)Fraction digits: 2
223 +Max size: 100000000
224 +Min size: 0.00|(% style="width:1042px" %)Total credited contract value
225 +|(% style="width:292px" %)duration |(% style="width:159px" %)string|(% style="width:461px" %)(((
226 +12,
227 +
228 +24,
229 +
230 +36
231 +)))|(% style="width:1042px" %)No. of months the contract is expected to last
232 +|(% style="width:292px" %)monthlyAmount|(% style="width:159px" %)decimal|(% style="width:461px" %)Fraction digits: 2
233 +Max size: 100000000
234 +Min size: 0.01|(% style="width:1042px" %)Regular monthly amount to be billed/payed
235 +|(% style="width:292px" %)currency |(% style="width:159px" %)string|(% style="width:461px" %)(((
236 +
237 +)))|(% style="width:1042px" %)(((
238 +Currency of the contract, must be equal to agreed currency
239 +
240 +* SEK
241 +* NOK
242 +* DKK
243 +* EUR
244 +)))
245 +|(% style="width:305px" %)unBilledAmount|(% style="width:187px" %)decimal|(% style="width:138px" %)Fraction digits: 2
246 +Max size: 100000000
247 +Min size: 0.00|(% style="width:1042px" %)remaining non billed/invoiced contract value
248 +|(% style="width:305px" %)accountStatus|(% style="width:187px" %)string|(% style="width:138px" %)(((
249 +Open,
250 +
251 +Closed
252 +)))|(% style="width:1042px" %)
253 +|(% style="width:305px" %)reservationValidToDate|(% style="width:187px" %)date|(% style="width:138px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1042px" %)The contract is valid for activation until this date
254 +
255 +=== Activate ===
256 +
257 +
258 +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.
259 +
260 +{{code language="http" title="**Request**"}}
261 +POST /ledger/contract-financing/v1/XXX/contracts/NNN/activate HTTP/1.1
262 +Host: -
263 +Authorization: Bearer<Token>
264 +Content-Type: application/json
265 +
266 +{
267 + "transactionId": "123456",
268 + "contractEndDate": "2023-03-25"
269 +}
270 +{{/code}}
271 +
272 +**Request properties requirements**
273 +
274 +(% class="table-bordered table-striped" %)
275 +|=(% style="width: 333px;" %)Property |=(% style="width: 1338px;" %)Required
276 +|(% style="width:333px" %)transactionId|(% style="width:1338px" %)Yes
277 +|(% style="width:333px" %)contractEndDate|(% style="width:1338px" %)Yes
278 +
279 +{{code language="http" title="**Response**"}}
280 +HTTP/1.1 204 No Content
281 +Content-Type: application/json
282 +
283 +{{/code}}
284 +
285 +**Properties**
286 +
287 +(% class="table-bordered table-striped" %)
288 +|=Property |=Data type|=Format|=Description
289 +|transactionId|string|Maxlength: 50|Unique identifier of all types of transactions (activate/credit/offcontract) in the ledger. Use only alphanumeric characters and/or underscore.
290 +\\Please note that offcontract (in CustomerBilling file) transactionIds must be unique, within the same range.
291 +|contractEndDate|date|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|The end date of the contract
292 +
293 +=== Credit ===
294 +
295 +
296 +Credits the unbilled contract amount and initiates clearing and settlement of the credited amount. The operation is exposed by the parent contract if available.
297 +
298 +{{code language="http" title="**Request**"}}
299 +POST /ledger/contract-financing/v1/XXX/contracts/NNN/credit HTTP/1.1
300 +Host: -
301 +Authorization: Bearer<Token>
302 +Content-Type: application/json
303 +
304 +{
305 + "transactionId": "123456",
306 + "amount": 100.00,
307 + "currency": "SEK"
308 +}
309 +{{/code}}
310 +
311 +**Request properties requirements**
312 +
313 +(% class="table-bordered table-striped" %)
314 +|=(% style="width: 333px;" %)Property |=(% style="width: 1338px;" %)Required
315 +|(% style="width:333px" %)transactionId|(% style="width:1338px" %)Yes
316 +|(% style="width:333px" %)amount|(% style="width:1338px" %)Yes
317 +|(% style="width:333px" %)currency|(% style="width:1338px" %)Yes
318 +
319 +{{code language="http" title="**Response**"}}
320 +HTTP/1.1 204 No Content
321 +Content-Type: application/json
322 +
323 +{{/code}}
324 +
325 +**Properties**
326 +
327 +(% class="table-bordered table-striped" %)
328 +|=Property |=Data type|=Format|=Description
329 +|transactionId|string|Maxlength: 50|Unique identifier of all types of transactions (activate/credit)in the ledger. Use only alphanumeric characters and/or underscore
330 +|amount|decimal|Fraction digits: 2
331 +Max size: 100000000
332 +Min size: 0.00|amount to credit the contract
333 +|currency|string| |Same currency as used when creating the contract
334 +
335 +=== ===
336 +
337 +=== Extend ===
338 +
339 +
340 +Extend the contract amount. The operation is exposed by the parent contract if available.
341 +
342 +{{code language="http" title="**Request**"}}
343 +POST /ledger/contract-financing/v1/XXX/contracts/NNN/extend HTTP/1.1
344 +Host: -
345 +Authorization: Bearer<Token>
346 +Content-Type: application/json
347 +
348 +{
349 + "transactionId": "123456",
350 + "amount": 100.00,
351 + "currency": "SEK"
352 +}
353 +{{/code}}
354 +
355 +**Request properties requirements**
356 +
357 +(% class="table-bordered table-striped" %)
358 +|=(% style="width: 333px;" %)Property |=(% style="width: 1338px;" %)Required
359 +|(% style="width:333px" %)transactionId|(% style="width:1338px" %)Yes
360 +|(% style="width:333px" %)amount|(% style="width:1338px" %)Yes
361 +|(% style="width:333px" %)currency|(% style="width:1338px" %)Yes
362 +
363 +{{code language="http" title="**Response**"}}
364 +HTTP/1.1 204 No Content
365 +Content-Type: application/json
366 +
367 +{{/code}}
368 +
369 +**Properties**
370 +
371 +(% class="table-bordered table-striped" %)
372 +|=Property |=Data type|=Format|=Description
373 +|transactionId|string|Maxlength: 50|Unique identifier of all types of transactions (activate/credit,extend)in the ledger. Use only alphanumeric characters and/or underscore
374 +|amount|decimal|Fraction digits: 2
375 +Max size: 100000000
376 +Min size: 0.00|amount to extend the contract with
377 +|currency|string| |Same currency as used when creating the contract
378 +
379 +=== ===
380 +
381 +=== Cancel ===
382 +
383 +
384 +Cancels the contract and the reserved amount on the end customer. The operation is exposed by the parent contract if available.
385 +
386 +{{code language="http" title="**Request**"}}
387 +POST /ledger/contract-financing/v1/XXX/contracts/NNN/cancel HTTP/1.1
388 +Host: -
389 +Authorization: Bearer<Token>
390 +Content-Type: application/json
391 +{{/code}}
392 +
393 +
394 +{{code language="http" title="**Response**"}}
395 +HTTP/1.1 204 No Content
396 +Content-Type: application/json
397 +
398 +
399 +{{/code}}
400 +
401 +== Problem types ==
402 +
403 +(% class="box infomessage" %)
404 +(((
405 +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".
406 +)))
407 +
408 +(% class="table-bordered table-striped" %)
409 +|=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
410 +|(% style="width:537px" %)validation|(% style="width:172px" %)400|(% style="width:796px" %)occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
411 +|(% style="width:537px" %)not-found|(% style="width:172px" %)404|(% style="width:796px" %)requested resource not found
412 +|(% style="width:537px" %)contract-id-invalid|(% style="width:172px" %)404|(% style="width:796px" %)requested resource not found
413 +|(% style="width:537px" %)conflict|(% style="width:172px" %)409|(% style="width:796px" %)state of resource is un valid for any further progress
414 +|(% style="width:537px" %)claimant-mismatch|(% style="width:172px" %)409|(% style="width:796px" %)mismatch between claimant (in url) used in new request vs. when authenticaiton resource was made,
415 +|(% style="width:537px" %)authentication-is-no-longer-valid|(% style="width:172px" %)422|(% style="width:796px" %)the limited time of the authentication has passed
416 +|(% style="width:537px" %)transactionId-not-unique|(% style="width:172px" %)422|(% style="width:796px" %)Duplicate external transaction reference
417 +|(% style="width:537px" %)credit-check-rejected|(% style="width:172px" %)422|(% style="width:796px" %)credit check or extend of credit check was rejected
418 +|(% style="width:537px" %)currency-invalid|(% style="width:172px" %)422|(% style="width:796px" %)the currency is not valid
419 +|(% style="width:537px" %)invalid-regno-exception|(% style="width:172px" %)409|(% style="width:796px" %)the regno did not pass validation. regex or checksum was wrong
420 +|(% style="width:537px" %)seller-not-registerd|(% style="width:172px" %)422|(% style="width:796px" %)company seller is not registered
421 +|(% style="width:537px" %)contract-no-longer-valid|(% style="width:172px" %)422|(% style="width:796px" %)contract reservation has expired
422 +|(% style="width:537px" %)transactionId-not-unique|(% style="width:172px" %)422|(% style="width:796px" %)transaction with same id already exist
423 +|(% style="width:537px" %)contract-id-invalid|(% style="width:172px" %)422|(% style="width:796px" %)contract id is not valid or existing contractid already exist
424 +|(% style="width:537px" %)invalid-contract-status|(% style="width:172px" %)422|(% style="width:796px" %)contract has invalid status
425 +|(% style="width:537px" %)fatal|(% style="width:172px" %)500|(% style="width:796px" %)Unexpected error, logs maybe can tell more in detail what the problem is
426 +|(% style="width:537px" %)not-implemented|(% style="width:172px" %)501|(% style="width:796px" %)the requested method is not implemented fully by code or not configured for the resource, body will tell which.
ContractFinancing.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.rae
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content