PayEx Developer Portal - bnpl-payment-order

1

(% id="HChangelog" %)

2

= Changelog =

3

4

5

2024-10-30 - Init documenation

6

\\\\

7

8

(% id="HIntroduction" %)

= Introduction =

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

== 1. Bnpl-payment-orders ==

18

19

20

Get the specified payment order

21

22

==== 1.1 Get specific Bnpl-payment-order ====

23

24

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

Payment order that has been authorized and with full RemainingAmount left

HTTP/1.1 200 OK

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": "\u002B46701234567"

52

},

53

"pointOfSale": "My Web Shop",

54

"mcc": "1234",

55

"restrictToProfiles": [

56

{

57

"profileName": "BA_PartPayment",

58

"subProfiles": [

59

{

60

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"operations": [

{

"rel": "add-reversal",

68

"method": "POST",

69

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"

},

{

"rel": "redirect",

"method": "POST",

"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

"rel": "add-reversal",

88

"method": "POST",

89

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"

},

{

"rel": "redirect",

"method": "POST",

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"

95

},

96

{

97

"rel": "cancel-authorize",

98

"method": "POST",

99

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"

100

},

101

{

102

"rel": "add-capture",

103

"method": "POST",

104

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"

}

]

}

**Possible problems**

113

114

(% class="table-bordered table-striped" %)

115

|=Http status |=Problem type |=Description

116

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

117

|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

118

|500 |fatal |an unexpected error has occurred

119

120

121

==== 1.2 Create Bnpl-payment-order ====

122

123

Create a payment order to begin authorization process

124

125

126

POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders HTTP/1.1

127

Host: -

128

Authorization: Bearer<Token>

129

Content-Type: application/json

130

131

{

132

"authorizationAmount": 1000.00,

133

"currency": "SEK",

134

"sellerAuthorizationId": "1234567890",

135

"customer": {

136

"nationalConsumerIdentifier": {

137

"value": "YYYYMMDD-XXXX",

138

"countryCode": "SE"

139

},

140

"email": "example@payex.com",

141

"msisdn": "\u002B46701234567"

142

},

143

"pointOfSale": "My Web Shop",

144

"mcc": "1234",

145

"restrictToProfiles": [

146

{

147

"profileName": "BA_PartPayment",

148

"subProfiles": [

149

{

150

"subProfileName": "InstallmentAccount_3"

}

]

}

]

}

**Request object specification**

160

161

(% class="table-bordered table-striped" %)

162

163

|authorizationAmount |number |Type: double

164

Max: 100000000

165

Min: 0 |Yes |The authorization amount, can't have more than 2 decimal places

166

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

))) |Yes |

|sellerAuthorizationId |string |Pattern: ^~[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ |Yes |The seller's unique identifier of the authorize/payment order

173

174

175

| value |string | |Yes |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

176

| countryCode |string |Pattern: SE~|NO~|DK~|FI |Yes |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]]

177

| email |string |Pattern: ^~[^;\xA0\xD0\─@<>\p{Cc}]+@(?!\.)(?!.*\.\.)(?:~[^;\xA0\xD0\─@<>\p{Cc}]+\.~[^;\xA0\xD0\─@<>\p{Cc}]+~|\~[~[A-Fa-f\d\:]+\])(?<!\.)$ |Yes |Email to the customer

178

| msisdn |string |Pattern: ^~[+]{1}\d{4,14}$ |No |Phone number to the customer

179

180

|mcc |string | |Yes |Merchant Category Code

Newly created payment order with restricted account profiles

HTTP/1.1 201 Created

Content-Type: application/json

192

193

{

194

"paymentOrderId": 1234567890,

195

"status": "Created",

196

"authorizationAmount": 1000.00,

197

"remainingAmount": 0,

198

"currency": "SEK",

199

"sellerAuthorizationId": "1234567890",

200

"customer": {

201

"nationalConsumerIdentifier": {

202

"value": "YYYYMMDD-XXXX",

203

"countryCode": "SE"

204

},

205

"email": "example@payex.com",

206

"msisdn": "\u002B46701234567"

207

},

208

"pointOfSale": "My Web Shop",

209

"mcc": "1234",

210

"restrictToProfiles": [

211

{

212

"profileName": "BA_PartPayment",

213

"subProfiles": [

214

{

215

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"operations": [

{

"rel": "add-reversal",

223

"method": "POST",

224

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"

},

{

"rel": "redirect",

"method": "POST",

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"

230

},

231

{

232

"rel": "cancel-authorize",

233

"method": "POST",

234

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"

235

},

236

{

237

"rel": "add-capture",

238

"method": "POST",

239

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"

240

},

241

{

242

"rel": "add-reversal",

243

"method": "POST",

244

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/reversals"

},

{

"rel": "redirect",

"method": "POST",

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/redirect"

250

},

251

{

252

"rel": "cancel-authorize",

253

"method": "POST",

254

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/cancel-authorize"

255

},

256

{

257

"rel": "add-capture",

258

"method": "POST",

259

"href": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890/captures"

260

}

261

],

262

"@id": "/ledger/bnpl-payment-order/v1/xxx/bnpl-payment-orders/1234567890"

}

**Possible problems**

268

269

(% class="table-bordered table-striped" %)

270

|=Http status |=Problem type |=Description

271

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

272

|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

273

|500 |fatal |an unexpected error has occurred

**Response object specification**

278

279

(% class="table-bordered table-striped" %)

280

|=Property |=Data type|=Format|=Description

281

|authorizationAmount |number |Type: double

282

Max: 100000000

283

Min: 0 |The authorization amount, can't have more than 2 decimal places

284

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

))) |

|sellerAuthorizationId |string |Pattern: ^~[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ |The seller's unique identifier of the authorize/payment order

291

|=customer |object | |

292

|= nationalConsumerIdentifier |object | |

293

| 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

294

| 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]]

295

| email |string |Pattern: ^~[^;\xA0\xD0\─@<>\p{Cc}]+@(?!\.)(?!.*\.\.)(?:~[^;\xA0\xD0\─@<>\p{Cc}]+\.~[^;\xA0\xD0\─@<>\p{Cc}]+~|\~[~[A-Fa-f\d\:]+\])(?<!\.)$ |Email to the customer

296

| msisdn |string |Pattern: ^~[+]{1}\d{4,14}$ |Phone number to the customer

297

|pointOfSale |string |Pattern: ^~[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Trade name of the point of sale. Will be displayed to end customer.

298

|mcc |string | |Merchant Category Code

299

|=restrictToProfiles |array | |

300

| profileName |string | |Profile identifier

301

|= subProfiles |array | |

302

| subProfileName |string | |Sub profile identifier

303

|paymentOrderId |number |Type: int64 |PaymentOrderId aka ExternalReservationId

|status |string |(((

* Created

* Rejected

* Canceled

* Failed

* Authorized

))) |

|remainingAmount |number |Type: double

312

Max: 100000000

313

Min: 0 |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

314

|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]]

315

|@id |string | |Uri identifier of the current resource

316

== 2. Cancel-authorize ==

317

318

319

==== 2.1 Create Cancel-authorize ====

320

321

This operation is for removing any remaining amount of an already completed authorization. Already captured amount is unaffected.

322

323

324

POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/cancel-authorize HTTP/1.1

325

Host: -

326

Authorization: Bearer<Token>

327

Content-Type: application/json

{

}

HTTP/1.1 204 NO CONTENT

337

Content-Type: application/json

{}

**Possible problems**

344

345

(% class="table-bordered table-striped" %)

346

|=Http status |=Problem type |=Description

347

|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

348

|500 |fatal |an unexpected error has occurred

== 3. Captures ==

==== 3.1 Create Capture ====

355

356

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.

357

358

359

POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/captures HTTP/1.1

360

Host: -

361

Authorization: Bearer<Token>

362

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"orderLines": [

{

"itemDescription": "Phone",

"amount": 1000.00

}

],

"sellerTransactionId": "1234567",

374

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

380

381

(% class="table-bordered table-striped" %)

382

383

|amount |number |Type: double

384

Max: 100000000

385

Min: 0 |Yes |The total amount

386

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

))) |Yes |

| amount |number |Type: double

395

Max: 100000000

396

Min: 0 |Yes |Price of an individual item in the capture

397

|sellerTransactionId |string |Pattern: ^~[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ |Yes |The seller's unique identifier of the capture

398

|receiptReference |string |Pattern: ^~[a-zA-Z0-9#_:@.\-]{1,}$ |Yes |A receipt reference meaningful for the consumer

399

400

401

Capture example with one item in the order line

HTTP/1.1 201 Created

Content-Type: application/json

{

"captureId": 1234,

"amount": 1000.00,

"currency": "SEK",

"orderLines": [

{

"itemDescription": "Phone",

"amount": 1000.00

}

],

"sellerTransactionId": "Example-seller-123",

418

"receiptReference": "1234567",

419

"@id": "https://example.com/capture/1234"

}

**Possible problems**

425

426

(% class="table-bordered table-striped" %)

427

|=Http status |=Problem type |=Description

428

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

429

|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

430

|409 |currency-not-supported |Currency for this capture is invalid for this payment order, make sure it match with currency specified at order creation

431

|422 |corrupt-resource |Performed action may or may not have been completed but result was corrupted or incomplete. Read details for more information.

432

|500 |fatal |an unexpected error has occurred

**Response object specification**

437

438

(% class="table-bordered table-striped" %)

439

|=Property |=Data type|=Format|=Description

440

|amount |number |Type: double

441

Max: 100000000

442

Min: 0 |The total amount

443

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

))) |

|=orderLines |array | |

450

| itemDescription |string |Pattern: ^~[\u0020-\u003A \u003C-\u007E \u00A0-\u00FF \u2019]*$ |Name or description of an individual item in the capture

451

| amount |number |Type: double

452

Max: 100000000

453

Min: 0 |Price of an individual item in the capture

454

|sellerTransactionId |string |Pattern: ^~[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ |The seller's unique identifier of the capture

455

|receiptReference |string |Pattern: ^~[a-zA-Z0-9#_:@.\-]{1,}$ |A receipt reference meaningful for the consumer

456

|captureId |number |Type: int64

457

Pattern: ^~[a-zA-Z0-9\-]{1,}$ |Identifier of the capture

458

|@id |string | |Uri identifier of the current resource

== 4. Reversals ==

==== 4.1 Create Reversal ====

463

464

Can only reverse captures from this payment order

465

466

467

POST /ledger/bnpl-payment-order/v1/{ownerNo}/bnpl-payment-orders/{paymentOrderId}/reversals HTTP/1.1

468

Host: -

469

Authorization: Bearer<Token>

470

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"sellerTransactionId": "123"

}

**Request object specification**

481

482

(% class="table-bordered table-striped" %)

483

484

|amount |number |Type: double

485

Max: 100000000

486

Min: 0 |Yes |The total amount to reverse

487

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

))) |Yes |

|sellerTransactionId |string |Pattern: ^~[a-zA-Z0-9#_:@.\-åäöÅÄÖ]{1,}$ |Yes |The sellers unique identifier of the reversal

Reversal of 1000SEK

HTTP/1.1 201 Created

Content-Type: application/json

501

502

{

503

"reversalId": "12345678",

504

"amount": 1000.00,

505

"currency": "SEK",

506

"sellerTransactionId": "123455679"

}

**Possible problems**

512

513

(% class="table-bordered table-striped" %)

514

|=Http status |=Problem type |=Description

515

|400 |validation |occurs if any of the input validation fails, it is described in the problem which parameter that failed the validation

516

|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

517

|500 |fatal |an unexpected error has occurred

**Response object specification**

522

523

(% class="table-bordered table-striped" %)

524

|=Property |=Data type|=Format|=Description