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}?SellerNo={SellerNo} 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": "+46701234567"

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"

}

]

}

**Query paramters**

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

101

|=Name |=Required |=Description

|SellerNo |False |

**Possible problems**

106

107

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

108

|=Http status |=Problem type |=Description

109

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

110

|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

111

|500 |fatal |an unexpected error has occurred

112

113

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

114

115

Create a payment order to begin authorization process

116

117

118

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

119

Host: -

120

Authorization: Bearer<Token>

121

Content-Type: application/json

122

123

{

124

"authorizationAmount": 1000.00,

125

"currency": "SEK",

126

"sellerAuthorizationId": "1234567890",

127

"customer": {

128

"nationalConsumerIdentifier": {

129

"value": "YYYYMMDD-XXXX",

130

"countryCode": "SE"

131

},

132

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

133

"msisdn": "+46701234567"

134

},

135

"pointOfSale": "My Web Shop",

136

"mcc": "1234",

137

"restrictToProfiles": [

138

{

139

"profileName": "BA_PartPayment",

140

"subProfiles": [

141

{

142

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"instore": false

}

**Request object specification**

153

154

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

155

156

|authorizationAmount |number |Type: double

157

Max: 100000000

158

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

159

|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

166

167

168

| 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

169

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

170

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

171

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

172

173

|mcc |string | |No |Merchant Category Code

Newly created payment order with restricted account profiles

HTTP/1.1 201 Created

Content-Type: application/json

185

186

{

187

"paymentOrderId": 1234567890,

188

"status": "Created",

189

"authorizationAmount": 1000.00,

190

"remainingAmount": 0,

191

"currency": "SEK",

192

"sellerAuthorizationId": "1234567890",

193

"customer": {

194

"nationalConsumerIdentifier": {

195

"value": "YYYYMMDD-XXXX",

196

"countryCode": "SE"

197

},

198

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

199

"msisdn": "+46701234567"

200

},

201

"pointOfSale": "My Web Shop",

202

"mcc": "1234",

203

"restrictToProfiles": [

204

{

205

"profileName": "BA_PartPayment",

206

"subProfiles": [

207

{

208

"subProfileName": "InstallmentAccount_3"

}

]

}

],

"instore": false,

"operations": [

{

"rel": "add-reversal",

217

"method": "POST",

218

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

224

},

225

{

226

"rel": "cancel-authorize",

227

"method": "POST",

228

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

229

},

230

{

231

"rel": "add-capture",

232

"method": "POST",

233

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

234

}

235

],

236

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

}

**Possible problems**

242

243

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

244

|=Http status |=Problem type |=Description

245

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

246

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

247

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

248

|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

249

|500 |fatal |an unexpected error has occurred

250

251

252

**Response object specification**

253

254

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

255

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

256

|authorizationAmount |number |Type: double

257

Max: 100000000

258

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

259

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

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

266

|=customer |object | |

267

|= nationalConsumerIdentifier |object | |

268

| 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

269

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

270

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

271

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

272

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

273

|mcc |string | |Merchant Category Code

274

|=restrictToProfiles |array | |

275

| profileName |string | |Profile identifier

276

|= subProfiles |array | |

277

| subProfileName |string | |Sub profile identifier

278

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

279

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

|status |string |(((

* Created

* Rejected

* Canceled

* Authorized

* Failed

)))|

|remainingAmount |number |Type: double

288

Max: 100000000

289

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

290

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

291

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

292

293

== 2. Cancel-authorize ==

294

295

296

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

297

298

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

299

300

301

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

302

Host: -

303

Authorization: Bearer<Token>

304

Content-Type: application/json

{

}

HTTP/1.1 204 NO CONTENT

314

Content-Type: application/json

{}

**Possible problems**

321

322

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

323

|=Http status |=Problem type |=Description

324

|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

325

|500 |fatal |an unexpected error has occurred

== 3. Captures ==

==== 3.1 Create Capture ====

331

332

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.

333

334

335

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

336

Host: -

337

Authorization: Bearer<Token>

338

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"orderLines": [

{

"itemDescription": "Phone",

"amount": 1000.00

}

],

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

350

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

356

357

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

358

359

|amount |number |Type: double

360

Max: 100000000

361

Min: 0 |Yes |The total amount

362

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

| amount |number |Type: double

371

Max: 100000000

372

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

373

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

374

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

375

376

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

393

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

394

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

}

**Possible problems**

400

401

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

402

|=Http status |=Problem type |=Description

403

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

404

|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

405

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

406

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

407

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

408

|500 |fatal |an unexpected error has occurred

409

410

411

**Response object specification**

412

413

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

414

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

415

|amount |number |Type: double

416

Max: 100000000

417

Min: 0 |The total amount

418

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

|=orderLines |array | |

425

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

426

| amount |number |Type: double

427

Max: 100000000

428

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

429

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

430

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

431

|captureId |number |Type: int64

432

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

433

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

== 4. Reversals ==

==== 4.1 Create Reversal ====

439

440

Can only reverse captures from this payment order

441

442

443

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

444

Host: -

445

Authorization: Bearer<Token>

446

Content-Type: application/json

{

"amount": 1000.00,

"currency": "SEK",

"sellerTransactionId": "123455679",

452

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

458

459

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

460

461

|amount |number |Type: double

462

Max: 100000000

463

Min: 0 |Yes |The total amount to reverse

464

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

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

471

|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

478

479

{

480

"reversalId": "12345678",

481

"amount": 1000.00,

482

"currency": "SEK",

483

"sellerTransactionId": "123455679",

484

"receiptReference": "Example-receipt-Phone"

}

**Possible problems**

490

491

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

492

|=Http status |=Problem type |=Description

493

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

494

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

495

|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

496

|500 |fatal |an unexpected error has occurred

497

498

499

**Response object specification**

500

501

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

502

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

503

|amount |number |Type: double

504

Max: 100000000

505

Min: 0 |The total amount to reverse

506

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|

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

513

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

514

|reversalId |string | |Identifier of the reversal

515

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

== 5. Redirect ==

==== 5.1 Create Redirect ====

521

522

While payee is progressing the authorization implementor should start poll the parent resource BnplPaymentOrder for updates

523

524

525

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

526

Host: -

527

Authorization: Bearer<Token>

528

Content-Type: application/json

529

530

{

531

"returnUrl": "https://www.back-to-my-web-shop.com",

"redirectOptions": {

"languageCode": "SV"

}

}

**Request object specification**

540

541

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

| languageCode |string |(((

* EN

* SV

* NO

* DA

)))|Yes |

Example response containing redirect info for the chosen payment method

HTTP/1.1 200 OK

Content-Type: application/json

557

558

{

559

"redirectUrl": "https://www.open-chosen-payment-method-example.com"

}

**Possible problems**

565

566

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

567

|=Http status |=Problem type |=Description

568

|500 |fatal |an unexpected error has occurred

569

|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

570

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

571

|409 |invalid-state |Invalid state of payment order for redirect

572

573

574

**Response object specification**

575

576

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

577