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