Changes for page bnpl-payment-order

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