Changes for page bnpl-payment-order

Last modified by Thomas Hedström on 2024/11/01 08:12
From empty
To version 11.1
edited by Thomas Hedström
on 2024/11/01 08:12
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +bnpl-payment-order
Parent
... ... @@ -1,0 +1,1 @@
1 +Main.credit-account.api.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +xwiki:XWiki.djr
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Tags
... ... @@ -1,0 +1,1 @@
1 +px-custom-page-content
Content
... ... @@ -1,0 +1,545 @@
1 +(% id="HChangelog" %)
2 += Changelog =
3 +
4 +
5 + 2024-10-30 - Init documenation
6 +\\\\
7 +
8 +(% id="HIntroduction" %)
9 += Introduction =
10 +
11 +
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.
13 +
14 +
15 +[[image:1730445122347-474.png||height="435" width="467"]]
16 +
17 +==
18 +~1. Bnpl-payment-orders ==
19 +
20 +
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",
52 + "msisdn": "+46701234567"
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",
121 + "msisdn": "+46701234567"
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
151 +)))|Yes |
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
246 +)))|
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
267 +)))|
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
271 +
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
346 +)))|Yes |
347 +|=orderLines |array | |Yes |
348 +| itemDescription |string |Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Yes |Name or description of an individual item in the capture
349 +| amount |number |Type: double
350 +Max: 100000000
351 +Min: 0 |Yes |Price of an individual item in the capture
352 +|sellerTransactionId |string | |Yes |
353 +|receiptReference |string |Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ |Yes |A receipt reference meaningful for the consumer
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",
372 + "receiptReference": "1234567",
373 + "@id": "https://example.com/capture/1234"
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
398 +)))|
399 +|=orderLines |array | |
400 +| itemDescription |string |Pattern: ^[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Name or description of an individual item in the capture
401 +| amount |number |Type: double
402 +Max: 100000000
403 +Min: 0 |Price of an individual item in the capture
404 +|sellerTransactionId |string | |
405 +|receiptReference |string |Pattern: ^[a-zA-Z0-9#_:@.\-]{1,}$ |A receipt reference meaningful for the consumer
406 +|captureId |number |Type: int64 |
407 +|@id |string |Uri identifier of the current resource|
408 +
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
442 +)))|Yes |
443 +|sellerTransactionId |string | |Yes |
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
480 +)))|
481 +|sellerTransactionId |string | |
482 +|reversalId |string | |Identifier of the reversal
483 +|uri |string | |
484 +
485 +== 5. Redirect ==
486 +
487 +
488 +==== 5.1 Redirect ====
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 +{
499 + "returnUrl": "https://www.landing-page-for-user-after-payment-order.com",
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
512 +|=redirectOptions |object | |Yes |
513 +| languageCode |string |(((
514 +* EN
515 +* SV
516 +* NO
517 +* DA
518 +)))|Yes |
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 +{
527 + "redirectUrl": "https://www.open-chosen-payment-method-example.com",
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
543 +|redirectUrl |string | |Url to redirect the user to the bnpl page for the user to continue the process
544 +
545 +{{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}
1730445122347-474.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.djr
Size
... ... @@ -1,0 +1,1 @@
1 +6.6 KB
Content