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

==

18

~1. Bnpl-payment-orders ==

19

20

21

Get the specified payment order

22

23

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

24

25

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

Payment order that has been authorized and with full RemainingAmount left

HTTP/1.1 200 OK

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"

}

]

}

],

"operations": [

{

"rel": "add-reversal",

69

"method": "POST",

70

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

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"

}

]

}

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

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"

}

]

}

]

}

**Request object specification**

140

141

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

142

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

* SEK

* NOK

* DKK

* EUR

)))|Yes |

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

|mcc |string | |Yes |Merchant Category Code

Newly created payment order with restricted account profiles

HTTP/1.1 201 Created

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"

}

]

}

],

"operations": [

{

"rel": "add-reversal",

202

"method": "POST",

203

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

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"

}

**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 |(((

* SEK

* NOK

* DKK

* EUR

)))|

|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

|status |string |(((

* Created

* Rejected

* Canceled

* Failed

* Authorized

)))|

|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

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

{

}

HTTP/1.1 204 NO CONTENT

293

Content-Type: application/json

{}

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

== 3. Captures ==

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

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

{

"amount": 1000.00,

"currency": "SEK",

"orderLines": [

{

"itemDescription": "Phone",

"amount": 1000.00

}

],

"sellerTransactionId": "1234567",

329

"receiptReference": "Example-receipt-Phone"

}

**Request object specification**

335

336

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

337

338

|amount |number |Type: double

339

Max: 100000000

340

Min: 0 |Yes |The total amount

341

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

| amount |number |Type: double

350

Max: 100000000

351

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

352

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

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

372

"receiptReference": "1234567",

373

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

}

**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 |(((

* SEK

* NOK

* DKK

* EUR

)))|

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

== 4. Reversals ==

==== 4.1 Create Reversal ====

413

414

Can only reverse captures from this payment order

415

416

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

{

"amount": 1000.00,

"currency": "SEK",

"sellerTransactionId": "123"

}

**Request object specification**

431

432

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

433

434

|amount |number |Type: double

435

Max: 100000000

436

Min: 0 |Yes |The total amount to reverse

437

|currency |string |(((

* SEK

* NOK

* DKK

* EUR

)))|Yes |

Reversal of 1000SEK

HTTP/1.1 201 Created

Content-Type: application/json

450

451

{

452

"reversalId": "12345678",

453

"amount": 1000.00,

454

"currency": "SEK",

455

"sellerTransactionId": "123455679"

}

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