PayEx Developer Portal - bnpl-payment-order

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.

18

19

20

[[image:1730445122347-474.png||height="435" width="467"]]

21

22

== 1. Bnpl-payment-orders ==

23

24

25

Get the specified payment order

26

27

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

28

29

30

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

31

Host: -

32

Authorization: Bearer<Token>

33

Content-Type: application/json

Payment order that has been authorized and with full RemainingAmount left

HTTP/1.1 200 OK

Content-Type: application/json

42

43

{

44

"paymentOrderId": 1234567890,

45

"status": "Authorized",

46

"authorizationAmount": 1000.00,

47

"remainingAmount": 1000.00,

48

"currency": "SEK",

49

"sellerAuthorizationId": "1234567890",

50

"customer": {

51

"nationalConsumerIdentifier": {

52

"value": "YYYYMMDD-XXXX",

53

"countryCode": "SE"

54

},

55

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

56

"msisdn": "\u002B46701234567"

57

},

58

"pointOfSale": "My Web Shop",

59

"mcc": "1234",

60

"restrictToProfiles": [

61

{

62

"profileName": "BA_PartPayment",

63

"subProfiles": [

64

{

65

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"instore": false,

"operations": [

{

"rel": "add-reversal",

74

"method": "POST",

75

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

81

},

82

{

83

"rel": "cancel-authorize",

84

"method": "POST",

85

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

86

},

87

{

88

"rel": "add-capture",

89

"method": "POST",

90

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

91

},

92

{

93

"rel": "add-reversal",

94

"method": "POST",

95

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

101

},

102

{

103

"rel": "cancel-authorize",

104

"method": "POST",

105

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

106

},

107

{

108

"rel": "add-capture",

109

"method": "POST",

110

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

}

]

}

**Possible problems**

119

120

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

121

|=Http status |=Problem type |=Description

122

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

123

|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

124

|500 |fatal |an unexpected error has occurred

125

126

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

127

128

Create a payment order to begin authorization process

129

130

131

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

132

Host: -

133

Authorization: Bearer<Token>

134

Content-Type: application/json

135

136

{

137

"authorizationAmount": 1000.00,

138

"currency": "SEK",

139

"sellerAuthorizationId": "1234567890",

140

"customer": {

141

"nationalConsumerIdentifier": {

142

"value": "YYYYMMDD-XXXX",

143

"countryCode": "SE"

144

},

145

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

146

"msisdn": "\u002B46701234567"

147

},

148

"pointOfSale": "My Web Shop",

149

"mcc": "1234",

150

"restrictToProfiles": [

151

{

152

"profileName": "BA_PartPayment",

153

"subProfiles": [

154

{

155

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"instore": false

}

**Request object specification**

166

167

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

168

169

|authorizationAmount |number |Type: double

170

Max: 100000000

171

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

172

|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

179

180

181

| 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

182

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

183

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

184

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

185

186

|mcc |string | |No |Merchant Category Code

Newly created payment order with restricted account profiles

HTTP/1.1 201 Created

Content-Type: application/json

198

199

{

200

"paymentOrderId": 1234567890,

201

"status": "Created",

202

"authorizationAmount": 1000.00,

203

"remainingAmount": 0,

204

"currency": "SEK",

205

"sellerAuthorizationId": "1234567890",

206

"customer": {

207

"nationalConsumerIdentifier": {

208

"value": "YYYYMMDD-XXXX",

209

"countryCode": "SE"

210

},

211

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

212

"msisdn": "\u002B46701234567"

213

},

214

"pointOfSale": "My Web Shop",

215

"mcc": "1234",

216

"restrictToProfiles": [

217

{

218

"profileName": "BA_PartPayment",

219

"subProfiles": [

220

{

221

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"instore": false,

"operations": [

{

"rel": "add-reversal",

230

"method": "POST",

231

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

237

},

238

{

239

"rel": "cancel-authorize",

240

"method": "POST",

241

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

242

},

243

{

244

"rel": "add-capture",

245

"method": "POST",

246

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

247

},

248

{

249

"rel": "add-reversal",

250

"method": "POST",

251

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

257

},

258

{

259

"rel": "cancel-authorize",

260

"method": "POST",

261

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

262

},

263

{

264

"rel": "add-capture",

265

"method": "POST",

266

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

267

}

268

],

269

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

}

**Possible problems**

275

276

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

277

|=Http status |=Problem type |=Description

278

|409 |identifier-already-in-use |SellerAuthorizationId [xxxx] already exists. It is used for payment order with PaymentOrderId [yyyyy]

279

|409 |no-available-profiles |No profiles configured.

280

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

281

|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

282

|500 |fatal |an unexpected error has occurred

283

284

**Response object specification**

285

286

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

287

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

288

|authorizationAmount |number |Type: double

289

Max: 100000000

290

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

291

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

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

298

|=customer |object | |

299

|= nationalConsumerIdentifier |object | |

300

| 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

301

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

302

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

303

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

304

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

305

|mcc |string | |Merchant Category Code

306

|=restrictToProfiles |array | |

307

| profileName |string | |Profile identifier

308

|= subProfiles |array | |

309

| subProfileName |string | |Sub profile identifier

310

|instore |boolean | |This request is an Instore bnpl order

311

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

|status |string |(((

* Created

* Rejected

* Canceled

* Failed

* Authorized

)))|

|remainingAmount |number |Type: double

320

Max: 100000000

321

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

322

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

323

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

324

325

== 2. Cancel-authorize ==

326

327

328

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

329

330

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

331

332

333

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

334

Host: -

335

Authorization: Bearer<Token>

336

Content-Type: application/json

{

}

HTTP/1.1 204 NO CONTENT

346

Content-Type: application/json

{}

**Possible problems**

353

354

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

355

|=Http status |=Problem type |=Description

356

|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

357

|500 |fatal |an unexpected error has occurred

== 3. Captures ==

==== 3.1 Create Capture ====

363

364

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.

365

366

367

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

368

Host: -

369

Authorization: Bearer<Token>

370

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"orderLines": [

{

"itemDescription": "Phone",

"amount": 1000.00

}

],

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

382

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

388

389

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

390

391

|amount |number |Type: double

392

Max: 100000000

393

Min: 0 |Yes |The total amount

394

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

| amount |number |Type: double

403

Max: 100000000

404

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

405

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

406

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

407

408

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",

425

"receiptReference": "Example-receipt-Phone",

426

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

}

**Possible problems**

432

433

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

434

|=Http status |=Problem type |=Description

435

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

436

|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

437

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

438

|409 |identifier-already-in-use |SellerTransactionId [xxxx] already exists. It is used in the capture transaction with CaptureId [yyyy]

439

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

440

|500 |fatal |an unexpected error has occurred

441

442

**Response object specification**

443

444

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

445

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

446

|amount |number |Type: double

447

Max: 100000000

448

Min: 0 |The total amount

449

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

|=orderLines |array | |

456

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

457

| amount |number |Type: double

458

Max: 100000000

459

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

460

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

461

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

462

|captureId |number |Type: int64

463

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

464

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

== 4. Reversals ==

==== 4.1 Create Reversal ====

470

471

Can only reverse captures from this payment order

472

473

474

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

475

Host: -

476

Authorization: Bearer<Token>

477

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"sellerTransactionId": "123455679",

483

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

489

490

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

491

492

|amount |number |Type: double

493

Max: 100000000

494

Min: 0 |Yes |The total amount to reverse

495

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

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

502

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

Reversal of 1000SEK

HTTP/1.1 201 Created

Content-Type: application/json

509

510

{

511

"reversalId": "12345678",

512

"amount": 1000.00,

513

"currency": "SEK",

514

"sellerTransactionId": "123455679",

515

"receiptReference": "Example-receipt-Phone"

}

**Possible problems**

521

522

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

523

|=Http status |=Problem type |=Description

524

|409 |identifier-already-in-use |SellerTransactionId [xxxx] already exists. It is used in the capture transaction with ReversalId [yyyy]

525

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

526

|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

527

|500 |fatal |an unexpected error has occurred

528

529

**Response object specification**

530

531

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

532

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

533

|amount |number |Type: double