Wiki source code of bnpl-payment-order

Last modified by Thomas Hedström on 2024/11/01 08:12
Hide last authors
Thomas Hedström 4.1 1 (% id="HChangelog" %)
2 = Changelog =
Thomas Hedström 2.1 3
4
Thomas Hedström 6.1 5 2024-10-30 - Init documenation
Thomas Hedström 4.1 6 \\\\
7
8 (% id="HIntroduction" %)
9 = Introduction =
10
11
Thomas Hedström 11.1 12 The bnpl-payment-order API handles payment flows for multiple buy-now-pay-later services, where the customer themselves are available to choose between preferred payment method from a set of preconfigured payment options.
Thomas Hedström 4.1 13
14
Thomas Hedström 10.1 15 [[image:1730445122347-474.png||height="435" width="467"]]
16
Thomas Hedström 4.1 17 ==
18 ~1. Bnpl-payment-orders ==
19
20
Thomas Hedström 2.1 21 Get the specified payment order
22
23 ==== 1.1 Get specific Bnpl-payment-order ====
24
25 {{code language="http" title="**Request**"}}
26 GET /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId} HTTP/1.1
27 Host: -
28 Authorization: Bearer<Token>
29 Content-Type: application/json
30
31 {{/code}}
32
33 Payment order that has been authorized and with full RemainingAmount left
34
35 {{code language="http" title="**Response**"}}
36 HTTP/1.1 200 OK
37 Content-Type: application/json
38
39 {
40 "paymentOrderId": 1234567890,
41 "status": "Authorized",
42 "authorizationAmount": 1000.00,
43 "remainingAmount": 1000.00,
44 "currency": "SEK",
45 "sellerAuthorizationId": "1234567890",
46 "customer": {
47 "nationalConsumerIdentifier": {
48 "value": "YYYYMMDD-XXXX",
49 "countryCode": "SE"
50 },
51 "email": "example@payex.com",
Thomas Hedström 7.1 52 "msisdn": "+46701234567"
Thomas Hedström 2.1 53 },
54 "pointOfSale": "My Web Shop",
55 "mcc": "1234",
56 "restrictToProfiles": [
57 {
58 "profileName": "BA_PartPayment",
59 "subProfiles": [
60 {
61 "subProfileName": "InstallmentAccount_3"
62 }
63 ]
64 }
65 ],
66 "operations": [
67 {
68 "rel": "add-reversal",
69 "method": "POST",
70 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"
71 },
72 {
73 "rel": "redirect",
74 "method": "POST",
75 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"
76 },
77 {
78 "rel": "cancel-authorize",
79 "method": "POST",
80 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"
81 },
82 {
83 "rel": "add-capture",
84 "method": "POST",
85 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"
86 }
87 ]
88 }
89 {{/code}}
90
91
92
93 **Possible problems**
94
95 (% class="table-bordered table-striped" %)
96 |=Http status |=Problem type |=Description
97 |400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
98 |404 |not-found |the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist
99 |500 |fatal |an unexpected error has occurred
100
101 ==== 1.2 Create Bnpl-payment-order ====
102
103 Create a payment order to begin authorization process
104
105 {{code language="http" title="**Request**"}}
106 POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders HTTP/1.1
107 Host: -
108 Authorization: Bearer<Token>
109 Content-Type: application/json
110
111 {
112 "authorizationAmount": 1000.00,
113 "currency": "SEK",
114 "sellerAuthorizationId": "1234567890",
115 "customer": {
116 "nationalConsumerIdentifier": {
117 "value": "YYYYMMDD-XXXX",
118 "countryCode": "SE"
119 },
120 "email": "example@payex.com",
Thomas Hedström 7.1 121 "msisdn": "+46701234567"
Thomas Hedström 2.1 122 },
123 "pointOfSale": "My Web Shop",
124 "mcc": "1234",
125 "restrictToProfiles": [
126 {
127 "profileName": "BA_PartPayment",
128 "subProfiles": [
129 {
130 "subProfileName": "InstallmentAccount_3"
131 }
132 ]
133 }
134 ]
135 }
136 {{/code}}
137
138
139 **Request object specification**
140
141 (% class="table-bordered table-striped" %)
142 |=Property |=Data type|=Format|=Required|=Description
143 |authorizationAmount |number |Type: double
144 Max: 100000000
145 Min: 0 |Yes |The authorization amount, can't have more than 2 decimal places
146 |currency |string |(((
147 * SEK
148 * NOK
149 * DKK
150 * EUR
Thomas Hedström 3.1 151 )))|Yes |
Thomas Hedström 2.1 152 |sellerAuthorizationId |string | |Yes |The seller's unique identifier of the authorize/payment order
153 |=customer |object | |Yes |
154 |= nationalConsumerIdentifier |object | |Yes |
155 | value |string | |No |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
156 | countryCode |string |Pattern: SE~|NO~|DK~|FI |No |The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ~[~[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]
157 | email |string | |Yes |Email to the customer
158 | msisdn |string | |Yes |Phone number to the customer
159 |pointOfSale |string | |Yes |Trade name of the point of sale. Will be displayed to end customer.
160 |mcc |string | |Yes |Merchant Category Code
161 |=restrictToProfiles |array | |No |
162 | profileName |string | |Yes |Profile identifier
163 |= subProfiles |array | |No |
164 | subProfileName |string | |Yes |Sub profile identifier
165
166 Newly created payment order with restricted account profiles
167
168 {{code language="http" title="**Response**"}}
169 HTTP/1.1 201 Created
170 Content-Type: application/json
171
172 {
173 "paymentOrderId": 1234567890,
174 "status": "Created",
175 "authorizationAmount": 1000.00,
176 "remainingAmount": 0,
177 "currency": "SEK",
178 "sellerAuthorizationId": "1234567890",
179 "customer": {
180 "nationalConsumerIdentifier": {
181 "value": "YYYYMMDD-XXXX",
182 "countryCode": "SE"
183 },
184 "email": "example@payex.com",
185 "msisdn": "\u002B46701234567"
186 },
187 "pointOfSale": "My Web Shop",
188 "mcc": "1234",
189 "restrictToProfiles": [
190 {
191 "profileName": "BA_PartPayment",
192 "subProfiles": [
193 {
194 "subProfileName": "InstallmentAccount_3"
195 }
196 ]
197 }
198 ],
199 "operations": [
200 {
201 "rel": "add-reversal",
202 "method": "POST",
203 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"
204 },
205 {
206 "rel": "redirect",
207 "method": "POST",
208 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"
209 },
210 {
211 "rel": "cancel-authorize",
212 "method": "POST",
213 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"
214 },
215 {
216 "rel": "add-capture",
217 "method": "POST",
218 "href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"
219 }
220 ],
221 "@id": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890"
222 }
223 {{/code}}
224
225
226 **Possible problems**
227
228 (% class="table-bordered table-striped" %)
229 |=Http status |=Problem type |=Description
230 |400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
231 |404 |not-found |the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist
232 |500 |fatal |an unexpected error has occurred
233
234 **Response object specification**
235
236 (% class="table-bordered table-striped" %)
237 |=Property |=Data type|=Format|=Description
238 |authorizationAmount |number |Type: double
239 Max: 100000000
240 Min: 0 |The authorization amount, can't have more than 2 decimal places
241 |currency |string |(((
242 * SEK
243 * NOK
244 * DKK
245 * EUR
Thomas Hedström 3.1 246 )))|
Thomas Hedström 2.1 247 |sellerAuthorizationId |string | |The seller's unique identifier of the authorize/payment order
248 |=customer |object | |
249 |= nationalConsumerIdentifier |object | |
250 | 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
251 | countryCode |string |Pattern: SE~|NO~|DK~|FI |The country code for the identifier value property. Valid values are 'SE', 'NO', 'DK', 'FI'. ~[~[ISO 3166-1 alpha-2>>url:https://sv.wikipedia.org/wiki/ISO_3166]]
252 | email |string | |Email to the customer
253 | msisdn |string | |Phone number to the customer
254 |pointOfSale |string | |Trade name of the point of sale. Will be displayed to end customer.
255 |mcc |string | |Merchant Category Code
256 |=restrictToProfiles |array | |
257 | profileName |string | |Profile identifier
258 |= subProfiles |array | |
259 | subProfileName |string | |Sub profile identifier
260 |paymentOrderId |number |Type: int64 |PaymentOrderId aka ExternalReservationId
261 |status |string |(((
262 * Created
263 * Rejected
264 * Canceled
265 * Failed
266 * Authorized
Thomas Hedström 3.1 267 )))|
Thomas Hedström 2.1 268 |remainingAmount |number |Type: double |Remaining amount of the authorize. If amount is zero then the authorize has already been fully used, cancelled or the payment order has not been authorized yet
269 |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]]
270 |@id |string | |Uri identifier of the current resource
Thomas Hedström 3.1 271
Thomas Hedström 2.1 272 == 2. Cancel-authorize ==
273
274
275 ==== 2.1 Create Cancel-authorize ====
276
277 This operation is for removing any remaining amount of an already completed authorization. Already captured amount is unaffected.
278
279 {{code language="http" title="**Request**"}}
280 POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/cancel-authorize HTTP/1.1
281 Host: -
282 Authorization: Bearer<Token>
283 Content-Type: application/json
284
285 {
286 }
287 {{/code}}
288
289
290
291 {{code language="http" title="**Response**"}}
292 HTTP/1.1 204 NO CONTENT
293 Content-Type: application/json
294
295 {}
296 {{/code}}
297
298
299 **Possible problems**
300
301 (% class="table-bordered table-striped" %)
302 |=Http status |=Problem type |=Description
303 |404 |not-found |the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist
304 |500 |fatal |an unexpected error has occurred
305
306 == 3. Captures ==
307
308
309 ==== 3.1 Create Capture ====
310
311 Perform a capture to solidify the purchase for this payment order. Multiple captures can be done for one payment order as long as we have RemainingAmount left on the order.
312
313 {{code language="http" title="**Request**"}}
314 POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/captures HTTP/1.1
315 Host: -
316 Authorization: Bearer<Token>
317 Content-Type: application/json
318
319 {
320 "amount": 1000.00,
321 "currency": "SEK",
322 "orderLines": [
323 {
324 "itemDescription": "Phone",
325 "amount": 1000.00
326 }
327 ],
328 "sellerTransactionId": "1234567",
329 "receiptReference": "Example-receipt-Phone"
330 }
331 {{/code}}
332
333
334 **Request object specification**
335
336 (% class="table-bordered table-striped" %)
337 |=Property |=Data type|=Format|=Required|=Description
338 |amount |number |Type: double
339 Max: 100000000
340 Min: 0 |Yes |The total amount
341 |currency |string |(((
342 * SEK
343 * NOK
344 * DKK
345 * EUR
Thomas Hedström 3.1 346 )))|Yes |
Thomas Hedström 2.1 347 |=orderLines |array | |Yes |
Thomas Hedström 3.1 348 | itemDescription |string |Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Yes |Name or description of an individual item in the capture
Thomas Hedström 2.1 349 | amount |number |Type: double
350 Max: 100000000
351 Min: 0 |Yes |Price of an individual item in the capture
Thomas Hedström 3.1 352 |sellerTransactionId |string | |Yes |
353 |receiptReference |string |Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ |Yes |A receipt reference meaningful for the consumer
Thomas Hedström 2.1 354
355 Capture example with one item in the order line
356
357 {{code language="http" title="**Response**"}}
358 HTTP/1.1 201 Created
359 Content-Type: application/json
360
361 {
362 "captureId": 1234,
363 "amount": 1000.00,
364 "currency": "SEK",
365 "orderLines": [
366 {
367 "itemDescription": "Phone",
368 "amount": 1000.00
369 }
370 ],
371 "sellerTransactionId": "Example-seller-123",
Thomas Hedström 3.1 372 "receiptReference": "1234567",
373 "@id": "https://example.com/capture/1234"
Thomas Hedström 2.1 374 }
375 {{/code}}
376
377
378 **Possible problems**
379
380 (% class="table-bordered table-striped" %)
381 |=Http status |=Problem type |=Description
382 |400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
383 |404 |not-found |the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist
384 |500 |fatal |an unexpected error has occurred
385
386 **Response object specification**
387
388 (% class="table-bordered table-striped" %)
389 |=Property |=Data type|=Format|=Description
390 |amount |number |Type: double
391 Max: 100000000
392 Min: 0 |The total amount
393 |currency |string |(((
394 * SEK
395 * NOK
396 * DKK
397 * EUR
Thomas Hedström 3.1 398 )))|
Thomas Hedström 2.1 399 |=orderLines |array | |
Thomas Hedström 3.1 400 | itemDescription |string |Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Name or description of an individual item in the capture
Thomas Hedström 2.1 401 | amount |number |Type: double
402 Max: 100000000
403 Min: 0 |Price of an individual item in the capture
Thomas Hedström 3.1 404 |sellerTransactionId |string | |
405 |receiptReference |string |Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ |A receipt reference meaningful for the consumer
406 |captureId |number |Type: int64 |
Thomas Hedström 8.1 407 |@id |string |Uri identifier of the current resource|
Thomas Hedström 3.1 408
Thomas Hedström 2.1 409 == 4. Reversals ==
410
411
412 ==== 4.1 Create Reversal ====
413
414 Can only reverse captures from this payment order
415
416 {{code language="http" title="**Request**"}}
417 POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/reversals HTTP/1.1
418 Host: -
419 Authorization: Bearer<Token>
420 Content-Type: application/json
421
422 {
423 "amount": 1000.00,
424 "currency": "SEK",
425 "sellerTransactionId": "123"
426 }
427 {{/code}}
428
429
430 **Request object specification**
431
432 (% class="table-bordered table-striped" %)
433 |=Property |=Data type|=Format|=Required|=Description
434 |amount |number |Type: double
435 Max: 100000000
436 Min: 0 |Yes |The total amount to reverse
437 |currency |string |(((
438 * SEK
439 * NOK
440 * DKK
441 * EUR
Thomas Hedström 3.1 442 )))|Yes |
443 |sellerTransactionId |string | |Yes |
Thomas Hedström 2.1 444
445 Reversal of 1000SEK
446
447 {{code language="http" title="**Response**"}}
448 HTTP/1.1 201 Created
449 Content-Type: application/json
450
451 {
452 "reversalId": "12345678",
453 "amount": 1000.00,
454 "currency": "SEK",
455 "sellerTransactionId": "123455679"
456 }
457 {{/code}}
458
459
460 **Possible problems**
461
462 (% class="table-bordered table-striped" %)
463 |=Http status |=Problem type |=Description
464 |400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
465 |404 |not-found |the targeted resource was not found, cause could be both that it's not accessible with provided information/credentials or that the resource doesn't exist
466 |500 |fatal |an unexpected error has occurred
467
468 **Response object specification**
469
470 (% class="table-bordered table-striped" %)
471 |=Property |=Data type|=Format|=Description
472 |amount |number |Type: double
473 Max: 100000000
474 Min: 0 |The total amount to reverse
475 |currency |string |(((
476 * SEK
477 * NOK
478 * DKK
479 * EUR
Thomas Hedström 3.1 480 )))|
481 |sellerTransactionId |string | |
Thomas Hedström 2.1 482 |reversalId |string | |Identifier of the reversal
Thomas Hedström 3.1 483 |uri |string | |
484
Thomas Hedström 2.1 485 == 5. Redirect ==
486
487
Thomas Hedström 5.1 488 ==== 5.1 Redirect ====
Thomas Hedström 2.1 489
490 While payee is progressing the authorization implementor should start poll the parent resource BnplPaymentOrder for updates
491
492 {{code language="http" title="**Request**"}}
493 POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/redirect HTTP/1.1
494 Host: -
495 Authorization: Bearer<Token>
496 Content-Type: application/json
497
498 {
Thomas Hedström 3.1 499 "returnUrl": "https://www.landing-page-for-user-after-payment-order.com",
Thomas Hedström 2.1 500 "redirectOptions": {
501 "languageCode": "SV"
502 }
503 }
504 {{/code}}
505
506
507 **Request object specification**
508
509 (% class="table-bordered table-striped" %)
510 |=Property |=Data type|=Format|=Required|=Description
511 |returnUrl |string | |Yes |Url to return the end user to after process is completed or cancelled
Thomas Hedström 3.1 512 |=redirectOptions |object | |Yes |
Thomas Hedström 2.1 513 | languageCode |string |(((
514 * EN
515 * SV
516 * NO
517 * DA
Thomas Hedström 3.1 518 )))|Yes |
Thomas Hedström 2.1 519
520 Example response containing redirect info for the chosen payment method
521
522 {{code language="http" title="**Response**"}}
523 HTTP/1.1 200 OK
524 Content-Type: application/json
525
526 {
Thomas Hedström 3.1 527 "redirectUrl": "https://www.open-chosen-payment-method-example.com",
Thomas Hedström 2.1 528 }
529 {{/code}}
530
531
532 **Possible problems**
533
534 (% class="table-bordered table-striped" %)
535 |=Http status |=Problem type |=Description
536 |409 |invalid-payment-method |unable to redirect before choosing a payment method
537 |400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation
538
539 **Response object specification**
540
541 (% class="table-bordered table-striped" %)
542 |=Property |=Data type|=Format|=Description
Thomas Hedström 3.1 543 |redirectUrl |string | |Url to redirect the user to the bnpl page for the user to continue the process
Thomas Hedström 2.1 544
545 {{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}