PayEx Developer Portal - card-transaction

1

(% class="jumbotron" %)

2

(((

3

(% class="container" %)

(((

Integrate to **PayEx Ledger Card transaction API **

)))

)))

(% class="lead" %)

The card transaction api contains functions that are used in payment scenarios: online, in-store and offline. Before transactions can be created an account must exists with associated cards.

13

14

[[image:1583697961121-375.png||height="352" width="428"]]

----

= Changelog =

2020-05-19

PointOfSale property added to the resources **purchase, cash-withdrawal** and **reversal**

22

23

2020-05-14

24

Changed instructions of extracting AcquireBatchId from RKHA file

25

26

2020-05-07

27

Added CardAuthenticationMethod and Channel to Purchase resource (offlineinfo)

28

29

2020-04-15

30

Added CardAuthenticationMethod and Channel to Authorizations resource

31

32

2020-03-06

33

Cancellations resource added, cancels the authorization when posted

== Summary ==

(% class="box successmessage" %)

39

(((

40

The card transaction api is used for making card payments against credit-accounts, it uses card terminology. All card transactions ends up on a credit-account that maintains all balances. [[Complete mapping of the card-transactions to the account>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HMappingcard-transactiontocredit-account]].

41

)))

42

43

The card transactions has two major concepts Authorizations and Financial Transactions.

44

45

46

===== **Authorizations** =====

47

48

Validates if payments can be done, account has sufficient funds etc..The authorizations will end up as reservations on the credit-account. Authorization will in most cases end up in financial transaction, a "Purchase".

49

50

Authorizations and Cancellations are the only real-time transactions, they take place instantly on at the point of sale (POS) (eg. cache register or online payment).

51

52

53

===== **Financial transactions** =====

54

55

The financial transactions are the actual monetary transactions. There are three different type of financial transactions: Purchase, Cache-Withdrawals and Reversals. Each financial transaction can be reversed using reversals.

56

57

58

====== //Transaction flow// ======

59

60

Most transactions follow the flow where a authorization is initially made and is later followed by a financial transaction, however there are cases with financial transactions without corresponding authorizations. The typical scenario is when a POS-Terminal loses connection with the internet. To prevent an all-stand-still at the point of sales, the cards can contain an offline-limit.The offline-limit restricts maximum amount of a purchase that can be made unauthorized. (% class="small" %)The offline-limit (if such exist) is regulated in the agreement between the card-issuer and the consumer.

61

62

===

63

Route description ===

64

65

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

66

67

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.

68

//api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**/resource2/**{resource2Id}**/resource3/**{resource3Id}**//

69

70

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

71

|=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description

72

|(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be credit-account

73

|(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx

74

|(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1

75

|(% style="width:604px" %)resource2Id|(% style="width:2790px" %)identifier of resource2, subresource to resource1

76

|(% style="width:604px" %)resource3Id|(% style="width:2790px" %)identifier of resource3, subresource to resource2

77

78

(% class="wikigeneratedid" %)

79

Routes that occurs in examples of this documentation will use the following identifiers

80

81

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

82

|=(% style="width: 488px;" %)Resource|=(% style="width: 2271px;" %)Identifier

83

|(% style="width:488px" %)LedgerNumber|(% style="width:2271px" %)XXX

84

|(% style="width:488px" %)AuthorizationId|(% style="width:2271px" %)YYY

85

|(% style="width:488px" %)SourcePurchaseTransactionId|(% style="width:2271px" %)PPP

86

|(% style="width:488px" %)SourceCashWithdrawalTransactionId|(% style="width:2271px" %)WWW

87

|(% style="width:488px" %)SourceReversalTransactionId|(% style="width:2271px" %)RRR

88

89

=== Authorizations ===

90

91

(% class="wikigeneratedid" %)

92

An authorization is done as the first step in using an account as payment. A successful authorization leads to a reservation on the account, the account is identified through the **cardToken.** The authorization is not a financial transaction, to make the financial transaction a Purchase (or other type of transaction) must be posted on the authorization.

93

94

==== Post authorizations ====

95

96

97

POST /ledger/card-transaction/v1/XXX/authorizations HTTP/1.1

98

Host: -

99

Authorization: Bearer <Token>

100

Content-Type: application/json

101

102

{

103

"sourceAuthorizationTransactionId": "789",

104

"sellerNumber": "654",

105

"cardToken": "5646735165",

106

"type": "Purchase|Reversal|CashWithdrawal",

107

"pointOfSale": "Testshop",

108

"authorizationAmount": 300.0,

109

"currency": "SEK",

110

"cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",

111

"channel": "POS|UnattendedPOS|Ecom "

}

HTTP/1.1 201 CREATED

Content-Type: application/json

119

120

{

121

"authorizationId": "YYY",

122

"@id": "/ledger/card-transaction/v1/XXX/authorizations/YYY",

"parentHREF": "/",

"operations": []

}

====

Get authorizations ====

130

131

132

GET /ledger/card-transaction/v1/XXX/authorizations/YYY HTTP/1.1

133

Host: -

134

Authorization: Bearer <Token>

135

Content-Type: application/json

==== ====

HTTP/1.1 200 OK

Content-Type: application/json

143

144

{

145

"sourceAuthorizationTransactionId": "789",

146

"authorizationId": 123,

147

"sellerNumber": "654",

148

"cardToken": "546415646315",

149

"type": "Purchase|Reversal|CashWithdrawal",

150

"pointOfSale": "Testshop",

151

"validToDate": "2019-11-28",

152

"authorizationAmount": 300.0,

153

"remainingAmount" : 150.0,

154

"currency": "SEK",

155

"cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",

156

"channel": "POS|UnattendedPOS|Ecom ",

157

"@id": "/ledger/card-transaction/v1/XXX/authorizations/NNN",

158

"purchases": "/ledger/card-transaction/v1/XXX/purchases?authorizationId=123",

159

"cash-withdrawals": "/ledger/card-transaction/v1/XXX/cash-withdrawals?authorizationId=123",

160

"reversals": "/ledger/card-transaction/v1/XXX/reversals?authorizationId=123",

"parentHREF": "/",

"operations": []

}

==== Resource properties authorizations ====

168

169

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

170

|=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 118px;" %)Format|=(% style="width: 586px;" %)Description

171

|(% style="width:215px" %)@id |(% style="width:114px" %)string|(% style="width:118px" %)Uri |(% style="width:586px" %)

172

|(% style="width:215px" %)sourceAuthorizationTransactionId|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Unique identifier of the specific authorization, generated by source (typically the integrating system)

173

Used for [[idempotency>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/#HPropertiesusedforidempotency]]

174

|(% style="width:215px" %)authorizationId|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 6|(% style="width:586px" %)Unique identifier of the authorization, generated by PayEx. Should be stored and must be set when transactions is to be created (except for purchases in offline mode)

175

|(% style="width:215px" %)sellerNumber|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 15|(% style="width:586px" %)Identifier of the current seller/merchant

176

|(% style="width:215px" %)cardToken|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)Identifier of the card. The aurhotization is made on the account that the card is linked to

177

|(% style="width:215px" %)type|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)(((

178

type of authorization

* Purchase

* Reversal

* CashWithdrawal

)))

|(% style="width:215px" %)pointOfSale|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Name of the location/point/shop of sale, will be returned in reservation resource

185

|(% style="width:215px" %)validToDate|(% style="width:114px" %)date|(% style="width:118px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:586px" %)Purchase can not be executed after this date

186

|(% style="width:215px" %)authorizeAmount|(% style="width:114px" %)decimal|(% style="width:118px" %)Amount|(% style="width:586px" %)Original authorized amount

187

|(% style="width:215px" %)remainingAmount|(% style="width:114px" %)decimal|(% style="width:118px" %)Amount|(% style="width:586px" %)Amount left on the authorization that can be Purchased

188

|(% style="width:215px" %)currency|(% style="width:114px" %)string|(% style="width:118px" %)[[ISO 4217>>url:https://sv.wikipedia.org/wiki/ISO_4217]]|(% style="width:586px" %)

189

|(% style="width:215px" %)purchases|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)

190

|(% style="width:215px" %)cash-withdrawals|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)

191

|(% style="width:215px" %)reversals|(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)

192

|(% style="width:215px" %)cardAuthenticationMethod|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)(((

193

(((

194

Method of authentication (optional)

195

196

* ChipPin //(Normal transaction in store / terminal)//

197

* ChipSign// (Transaction made in a store / terminal where the buyer shows his identification and gives his signature)//

198

* PanCvcExpr// (E-com transaction. Transaction made online by entering the cards pan, cvc and expiredate)//

* RecurringToken

* MagStripePin

)))

)))

|(% style="width:215px" %)channel|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)(((

204

(((

205

Type of channel (optional)

* POS

* UnattendedPOS

* Ecom

)))

)))

----

== Cancellations ==

The authorization must be cancelled if the seller aborts the process (for any reason) after a successful call to authorizations has been made.

218

This is done by sending a post request to the cancellation URL that was provided in the response of the actual authorization call.

219

220

==== Post cancellations ====

221

222

223

POST /ledger/card-transaction/v1/XXX/authorizations/YYY/cancellations HTTP/1.1

224

Host: -

225

Authorization: Bearer <Token>

226

Content-Type: application/json

227

228

{

229

"cancellationDate" : "2019-11-20"

}

==== Resource properties cancellations ====

236

237

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

238

|=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 118px;" %)Format|=(% style="width: 586px;" %)Description

239

|(% style="width:215px" %)@id |(% style="width:114px" %)string|(% style="width:118px" %)Uri|(% style="width:586px" %)

240

|(% style="width:215px" %)cancellationDate|(% style="width:114px" %)date|(% style="width:118px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:586px" %) Date when the cancellation was made

----

== Purchases ==

==== Post purchases ====

247

248

249

POST /ledger/card-transaction/v1/XXX/purchases HTTP/1.1

250

Host: -

251

Authorization: Bearer <Token>

252

Content-Type: application/json

253

254

{

255

"authorizationId" : "AUTH71",

256

"sourcePurchaseTransactionId" : "534313",

257

"sellerReceiptId": "58743597125",

258

"additionalReferences":{

259

"acquirerBatchId": "200206885010",

260

"acquirerTransactionId" : "534313"

261

},

262

"amount": 200.0,

263

"date": "2019-11-28",

264

"pointOfSale": "Testshop",

265

"offlineInfo" : {

266

"pointOfSale": "Testshop",

267

"cardToken": "5646735165",

268

"sellerNumber": "654",

269

"currency": "SEK",

270

"cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",

271

"channel": "POS|UnattendedPOS|Ecom "

}

}

==== Get purchases ====

277

278

279

GET /ledger/card-transaction/v1/XXX/purchases/PPP HTTP/1.1

280

Host: -

281

Authorization: Bearer <Token>

282

Content-Type: application/json

==== List purchases ====

287

288

289

GET /ledger/card-transaction/v1/XXX/purchases HTTP/1.1

290

Host: -

291

Authorization: Bearer <Token>

292

Content-Type: application/json

==== Resource purchases ====

HTTP/1.1 201 CREATED

Content-Type: application/json

301

302

{

303

"description": "stora butiken test, köpref. 12345689",

304

"authorizationId" : "AUTH71",

305

"sourcePurchaseTransactionId" : "534313",

306

"sellerReceiptId": "58743597125",

307

"additionalReferences":{

308

"acquirerBatchId": "200206885010",

309

"acquirerTransactionId" : "534313"

310

},

311

"amount": 200.0,

312

"date": "2019-11-28",

313

"pointOfSale": "Testshop",

314

"offlineInfo" : {

315

"pointOfSale": "Testshop",

316

"cardToken": "5646735165",

317

"sellerNumber": "654",

318

"currency": "SEK",

319

"cardAuthenticationMethod": "ChipPin|ChipSign|PanCvcExpr|RecurringToken|MagStripePin",

320

"channel": "POS|UnattendedPOS|Ecom "

321

},

322

"corrections": "/ledger/card-transaction/v1/XXX/purchases/YYY/corrections",

323

"@id": "/ledger/card-transaction/v1/XXX/purchases/YYY",

324

"operations": [

325

{

326

"rel": "create-correction",

327

"method": "post",

328

"href": "/ledger/card-transaction/v1/XXX/authorizations/NNN/purchases/YYY/corrections"

}

]

}

==== Resource properties purchases ====

335

336

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

337

|=(% style="width: 337px;" %)Property|=(% style="width: 121px;" %)Data type|=(% style="width: 164px;" %)Format|=(% style="width: 1156px;" %)Description

338

|(% style="width:337px" %)@id |(% style="width:121px" %)string|(% style="width:164px" %)Uri|(% style="width:1156px" %)

339

|(% style="width:337px" %)description|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 200|(% style="width:1156px" %)Describes the current Purchase (derives from info sent in the authorization), may be printed on the bill, output only

340

|(% style="width:337px" %)authorizationId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 6|(% style="width:1156px" %)The id of the authorization from which this purchase originated from (not required if the purchase was made offline)

341

|(% style="width:337px" %)(((

342

(% style="background-color:transparent" %)sourcePurchaseTransactionId

343

)))|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Unique identifier of the Purchase transaction

344

Used for [[idempotency>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/#HPropertiesusedforidempotency]]

345

|(% style="width:337px" %)(((

346

additionalReferences.acquirerBatchId

347

)))|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Used for reconciling acquirer transactions. See [[RKHA21>>||anchor="HRKHA21format"]] section on this page for more information

348

|(% style="width:337px" %)additionalReferences.acquirerTransactionId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Unique acquirer identifier of the transaction. Equals field "BABS reference number" position 18-28 in the RKHAS400 Original transaction

349

|(% style="width:337px" %)sellerReceiptId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Equals field ”Retrieval reference number” position 333-344 in the RKHAS400 Original transaction

350

|(% style="width:337px" %)amount|(% style="width:121px" %)decimal|(% style="width:164px" %) |(% style="width:1156px" %)

351

|(% style="width:337px" %)date|(% style="width:121px" %)date|(% style="width:164px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1156px" %)valuedate of the transaction

352

|(% style="width:215px" %)pointOfSale|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Name of the location/point/shop of sale. This new property will replace the below property, however both should be set in an transition period.

353

|(% style="width:337px" %)offlineInfo.pointOfSale|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Name of the location/point/shop of sale, will be returned in reservation resource. This property is to be removed after the above property (PointOfSale) has been fully implemented in all systems (VAS/PxR), but should be set as before until then.

354

|(% style="width:337px" %)offlineInfo.cardToken|(% style="width:121px" %)string|(% style="width:164px" %) |(% style="width:1156px" %)Identifier of the card. The purchase will be made on the account that the card is linked to

355

|(% style="width:337px" %)offlineInfo.sellerNumber|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 15|(% style="width:1156px" %)Identifier of the current seller/merchant

356

|(% style="width:337px" %)offlineInfo.currency|(% style="width:121px" %)string|(% style="width:164px" %)[[ISO 4217>>url:https://sv.wikipedia.org/wiki/ISO_4217]]|(% style="width:1156px" %)

357

|(% style="width:215px" %)offlineInfo.cardAuthenticationMethod|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)(((

358

(((

359

Method of authentication (optional)

360

361

* ChipPin //(Normal transaction in store / terminal)//

362

* ChipSign// (Transaction made in a store / terminal where the buyer shows his identification and gives his signature)//

363

* PanCvcExpr// (E-com transaction. Transaction made online by entering the cards pan, cvc and expiredate)//

* RecurringToken

* MagStripePin

)))

)))

|(% style="width:215px" %)offlineInfo.channel|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)(((

369

(((

370

Type of channel (optional)

* POS

* UnattendedPOS

* Ecom

)))

)))

|(% style="width:337px" %)corrections|(% style="width:121px" %)string|(% style="width:164px" %)Uri|(% style="width:1156px" %)

378

|(% style="width:337px" %)withdrawalAmount|(% style="width:121px" %)decimal?|(% style="width:164px" %) |(% style="width:1156px" %)

----

== Cash-withdrawals ==

383

384

==== Post cash-withdrawals ====

385

386

387

POST /ledger/card-transaction/v1/XXX/cash-withdrawals HTTP/1.1

388

Host: -

389

Authorization: Bearer <Token>

390

Content-Type: application/json

391

392

{

393

"authorizationId" : "AUTH71",

394

"sourceCashWithdrawalTransactionId" : "534313",

395

"sellerReceiptId": "54313546",

396

"additionalReferences":{

397

"acquirerBatchId": "fdsfsdfsd",

398

"acquirerTransactionId" : "534313"

399

},

400

"amount": 200.0,

401

"date": "2019-11-28",

402

"pointOfSale": "Testshop"

}

==== Get cash-withdrawals ====

407

408

409

GET /ledger/card-transaction/v1/XXX/cash-withdrawals/WWW HTTP/1.1

410

Host: -

411

Authorization: Bearer <Token>

412

Content-Type: application/json

==== List cash-withdrawals ====

417

418

419

GET /ledger/card-transaction/v1/XXX/cash-withdrawals HTTP/1.1

420

Host: -

421

Authorization: Bearer <Token>

422

Content-Type: application/json

==== Resource cash-withdrawals ====

HTTP/1.1 201 CREATED

Content-Type: application/json

431

432

{

433

"description": "stora butiken test, köpref. 12345689",

434

"authorizationId" : "AUTH71",

435

"sourceCashWithdrawalTransactionId" : "534313",

436

"sellerReceiptId": "541687421",

437

"additionalReferences":{

438

"acquirerBatchId": "200206885020",

439

"acquirerTransactionId" : "534313"

440

},

441

"amount": 200.0,

442

"date": "2019-11-28",

443

"pointOfSale": "Testshop",

444

"corrections": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY/corrections",

445

"@id": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY",

446

"operations": [

447

{

448

"rel": "create-correction",

449

"method": "post",

450

"href": "/ledger/card-transaction/v1/XXX/cash-withdrawals/YYY/corrections"

}

]

}

==== Resource properties cash-withdrawals ====

457

458

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

459

|=(% style="width: 337px;" %)Property|=(% style="width: 121px;" %)Data type|=(% style="width: 164px;" %)Format|=(% style="width: 1156px;" %)Description

460

|(% style="width:337px" %)@id |(% style="width:121px" %)string|(% style="width:164px" %)Uri|(% style="width:1156px" %)

461

|(% style="width:337px" %)description|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 200|(% style="width:1156px" %)Describes the current cash-withdrawals (derives from info sent in the authorization), may be printed on the bill, output only

462

|(% style="width:337px" %)authorizationId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 6|(% style="width:1156px" %)The id of the authorization from which this cash-withdrawal transaction originated from

463

|(% style="width:337px" %)(((

464

(% style="background-color:transparent" %)sourceCashWithdrawalTransactionId

465

)))|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Unique identifier of the cash-withdrawal transaction. Used for [[idempotency>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/#HPropertiesusedforidempotency]]

466

|(% style="width:337px" %)(((

467

additionalReferences.acquirerBatchId

468

)))|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Used for reconciling acquirer transactions. See [[RKHA21>>||anchor="HRKHA21format"]] section on this page for more information

469

|(% style="width:337px" %)additionalReferences.acquirerTransactionId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Unique acquirer identifier of the transaction.

470

|(% style="width:337px" %)sellerReceiptId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)

471

|(% style="width:337px" %)amount|(% style="width:121px" %)decimal|(% style="width:164px" %) |(% style="width:1156px" %)

472

|(% style="width:337px" %)date|(% style="width:121px" %)date|(% style="width:164px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1156px" %)valuedate of the transaction

473

|(% style="width:215px" %)pointOfSale|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Name of the location/point/shop of sale

474

|(% style="width:337px" %)corrections|(% style="width:121px" %)string|(% style="width:164px" %)Uri|(% style="width:1156px" %)

----

=== Reversals ===

Used to refund a purchase for any reason

481

482

==== Create reversals ====

483

484

Execute post towards this resource to add the amount on the card (account) specified in the authorization

485

486

487

POST /ledger/card-transaction/v1/XXX/reversals HTTP/1.1

488

Host: -

489

Authorization: Bearer <Token>

490

Content-Type: application/json

491

492

{

493

"authorizationId" : "AUTH71",

494

"sellerReceiptId": "12345689",

495

"additionalReferences":{

496

"acquirerBatchId": "200206885020",

497

"acquirerTransactionId" : "534313"

498

},

499

"sourceReversalTransactionId" : "534312",

500

"amount": 200.0,

501

"date": "2019-11-28",

502

"pointOfSale": "Testshop"

}

==== Get reversals ====

507

508

509

GET /ledger/card-transaction/v1/XXX/reversals/RRR HTTP/1.1

510

Host: -

511

Authorization: Bearer <Token>

512

Content-Type: application/json

==== List reversals ====

517

518

519

GET /ledger/card-transaction/v1/XXX/reversals HTTP/1.1

520

Host: -

521

Authorization: Bearer <Token>

522

Content-Type: application/json

==== Resource reversals ====

HTTP/1.1 200 OK

Content-Type: application/json

531

532

{

533

"authorizationId" : "AUTH71",

534

"sellerReceiptId": "12345689",

535

"additionalReferences":{

536

"acquirerBatchId": "200206885020",

537

"acquirerTransactionId" : "534313"

538

},

539

"sourceReversalTransactionId" : "534312",

540

"amount": 200.0,

541

"date": "2019-11-28",

542

"pointOfSale": "Testshop",

543

"@id" : "/ledger/card-transaction/v1/XXX/reversals/YYY",

544

"operations" : [

545

{

546

"rel": "create-correction",

547

"method": "post",

548

"href": "/ledger/card-transaction/v1/XXX/reversals/YYY/corrections"

}

]

}

==== Resource reversals properties ====

555

556

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

557

|=(% style="width: 215px;" %)Property|=(% style="width: 114px;" %)Data type|=(% style="width: 118px;" %)Format|=(% style="width: 586px;" %)Description

558

|(% style="width:215px" %)@id |(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: |(% style="width:586px" %)

559

|(% style="width:337px" %)authorizationId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 6|(% style="width:1156px" %)The id of the authorization from which this reversal originated from

560

|(% style="width:337px" %)sellerReceiptId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Equals field ”Retrieval reference number” position 333-344 in the RKHAS400 Original transaction

561

|(% style="width:337px" %)(((

562

additionalReferences.acquirerBatchId

563

)))|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Used for reconciling acquirer transactions. See [[RKHA21>>||anchor="HRKHA21format"]] section on this page for more information

564

|(% style="width:337px" %)additionalReferences.acquirerTransactionId|(% style="width:121px" %)string|(% style="width:164px" %)Maxlength: 50|(% style="width:1156px" %)Unique acquirer identifier of the transaction. Equals field "BABS reference number" position 18-28 in the RKHAS400 Original transaction

565

|(% style="width:215px" %)sourceReversalTransactionId|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Unique identifier of the Reversal transaction. Used for [[idempotency>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/#HPropertiesusedforidempotency]]

566

|(% style="width:215px" %)amount|(% style="width:114px" %)decimal|(% style="width:118px" %) |(% style="width:586px" %)

567

|(% style="width:337px" %)date|(% style="width:121px" %)date|(% style="width:164px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1156px" %)valuedate of the transaction

568

|(% style="width:215px" %)pointOfSale|(% style="width:114px" %)string|(% style="width:118px" %)Maxlength: 50|(% style="width:586px" %)Name of the location/point/shop of sale.

=== Corrections ===

Each type of transactions can be corrected by making a POST call against its correction resource

573

574

==== Create purchase corrections ====

575

576

577

POST /ledger/card-transaction/v1/XXX/purchases/PPP/corrections HTTP/1.1

578

Host: -

579

Authorization: Bearer <Token>

580

Content-Type: application/json

581

582

{

583

"additionalReferences":{

584

"acquirerBatchId": "200206885020",

585

"acquirerTransactionId" : "534313"

586

},

587

"sourceCorrectionTransactionId" : "534313",

"amount": 200.0,

"date": "2019-11-28"

}

==== Create cash-withdrawal corrections ====

594

595

596

POST /ledger/card-transaction/v1/XXX/cash-withdrawals/WWW/corrections HTTP/1.1

597

Host: -

598

Authorization: Bearer <Token>

599

Content-Type: application/json

600

601

{

602

"additionalReferences":{

603

"acquirerBatchId": "200206885020",

604

"acquirerTransactionId" : "534313"

605

},

606

"sourceCorrectionTransactionId" : "534313",

"amount": 200.0,

"date": "2019-11-28"

}

==== Create reversal corrections ====

613

614

615

POST /ledger/card-transaction/v1/XXX/reversals/RRR/corrections HTTP/1.1

616

Host: -

617

Authorization: Bearer <Token>

618

Content-Type: application/json

619

620

{

621

"additionalReferences":{

622

"acquirerBatchId": "200206885020",

623

"acquirerTransactionId" : "534313"

624

},

625

"sourceCorrectionTransactionId" : "534313",

"amount": 200.0,

"date": "2019-11-28"

}

==== Corrections resource properties ====

632

633

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

634

|=(% style="width: 215px;" %)(((

635

Property

636

)))|=(% style="width: 114px;" %)(((

637

Data type

638

)))|=(% style="width: 118px;" %)(((

639

Format

640

)))|=(% style="width: 586px;" %)(((

641

Description

642

)))

643

|(% style="width:215px" %)(((

644

@id

645

)))|(% style="width:114px" %)(((

646

string

647

)))|(% style="width:118px" %)(((

648

Maxlength:

649

)))|(% style="width:586px" %)(((

650

651

)))

652

|(% style="width:337px" %)(((

653

additionalReferences.acquirerBatchId

654

)))|(% style="width:121px" %)(((

655

string

656

)))|(% style="width:164px" %)(((

657

Maxlength: 50

658

)))|(% style="width:1156px" %)(((

659

Used for reconciling acquirer transactions. See [[RKHA21>>||anchor="HRKHA21format"]] section on this page for more information

660

)))

661

|(% style="width:337px" %)(((

662

additionalReferences.acquirerTransactionId

663

)))|(% style="width:121px" %)(((

664

string

665

)))|(% style="width:164px" %)(((

666

Maxlength: 50

667

)))|(% style="width:1156px" %)(((

668

Unique acquirer identifier of the transaction.

669

)))

670

|(% style="width:215px" %)(((

671

sourceCorrectionTransactionId

672

)))|(% style="width:114px" %)(((

673

string

674

)))|(% style="width:118px" %)(((

675

Maxlength: 50

676

)))|(% style="width:586px" %)(((

677

Unique identifier of the correction transaction. Used for [[idempotency>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/#HPropertiesusedforidempotency]]

678

)))

679

|(% style="width:215px" %)(((

680

amount

681

)))|(% style="width:114px" %)(((

682

decimal

683

)))|(% style="width:118px" %)(((

684

685

)))|(% style="width:586px" %)(((

686

687

)))

688

|(% style="width:337px" %)date|(% style="width:121px" %)date|(% style="width:164px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|(% style="width:1156px" %)valuedate of the transaction

== ==

= Mapping card-transaction to credit-account =

693

694

|=(% style="width: 233px;" %)Card Transaction Api (this api)|=(% style="width: 134px;" %)Type|=(% style="width: 256px;" %)Credit Account Api|=(% style="width: 1043px;" %)Description

695

|(% style="width:233px" %)[[../authorizations>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HAuthorizations]]|(% style="width:134px" %)(% class="small" %)Authorization|(% style="width:256px" %)[[../reservations>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HReservations]]|(% style="width:1043px" %)(% class="small" %)Successful authorizations will end up as reservations in the credit-account api. The credit account/accounts api will also include a property with the total reservation amount that has not yet received a corresponding financial transaction in [[the "(% class="small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small small" %)##reservedAmount##" property>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HAccounts]](%%).

696

|(% style="width:233px" %)[[../authorization/../cancellations>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HCancellations]]|(% style="width:134px" %)(% class="small" %)Authorization|(% style="width:256px" %)n/a|(% style="width:1043px" %)(% class="small" %)Cancellations are used to free up authorizations/reservations, if the consumer of the api know that a financial transaction will not occur. Authorizations automatically times-out after a configurable time.

697

|(% style="width:233px" %)[[../purchases>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HPurchases]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)(((

698

[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "purchase"**##

699

)))|(% style="width:1043px" %)(% class="small" %)Purchase is the financial clearing-transaction describing a purchase

700

|(% style="width:233px" %)[[../purchases/../corrections>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HCorrections]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)(((

701

[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "credit"**##

702

)))|(% style="width:1043px" %)(% class="small" %)A correction of a purchase transaction,

703

|(% style="width:233px" %)[[../cash-withdrawals>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HCash-withdrawals]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)(((

704

[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "purchase"**##

705

)))|(% style="width:1043px" %)(% class="small" %)Cash-withdrawal is the financial clearing transaction describing a cash-withdrawal at point of sales.(%%) (% class="small" %)//Requires special agreement.//

706

|(% style="width:233px" %)[[../cash-withdrawals/../corrections>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HCorrections]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)(((

707

[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "credit"**##

708

)))|(% style="width:1043px" %)(% class="small" %)A correction of a cash-withdrawal transaction.

709

|(% style="width:233px" %)[[../reversals>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HReversals]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)(((

710

[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "credit"**##

711

)))|(% style="width:1043px" %)(% class="small" %)Reversal is the financial clearing-transaction describing a deposit/return at point of sale

712

|(% style="width:233px" %)[[../reversals/../corrections>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/card-transaction/#HCorrections]]|(% style="width:134px" %)(% class="small" %)Financial Transaction|(% style="width:256px" %)[[../transactions>>https://developer.payex.com/xwiki/wiki/developer/view/Main/credit-account/api/credit-account/#HTransactions]] (% class="small" %)##**"type" : "purchase"**##|(% style="width:1043px" %)(% class="small" %)A correction of a reversal transaction.

713

714

//Complete specification of credit-account-api can be found [[here>>doc:Main.credit-account.api.credit-account.WebHome]].//

715

716

(% class="box infomessage" %)

717

(((

718

Financial card-transactions will end up on the account-statement/bill, along with other financial transactions associated to the account.

719

Financial card-transactions of type purchase that do not have a corresponding authorization are usually subject to liability shift, meaning that if the transaction I disputed by the consumer the financial risk is held by the merchants.

720

Financial card-transactions are batch processed in clearing files and do not occur in real time.

)))

== ==

== RKHA21 format ==

If the original source for the transactions towards purchases/cash-withdrawals/reversals/corrections is the RKHA21 file the below rules should be used to set the AcquirerBatchId.

728

729

AcquirerBatchId = [Processing date][Sender][**1:st** character of Cycle]

730

731

For the example values in the table below the AcquirerBatchId will be "**20020688502**".

732

733

**RKHA21 file header row description**

734

735

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

736

|=(% style="width: 113px;" %)(((

737

Position

738

)))|=(% style="width: 226px;" %)(((

739

Field

740

)))|=(% style="width: 118px;" %)(((

741

Format

742

)))|=(% style="width: 586px;" %)(((

743

Description

744

)))|=(% style="width: 586px;" %)(((

745

Example

746

)))

747

|(% style="width:113px" %)(((

748

1

749

)))|(% style="width:226px" %)(((

750

Transaction code

751

)))|(% style="width:118px" %)(((

752

2 N

753

)))|(% style="width:586px" %)(((

754

01

755

)))|(% style="width:586px" %)(((

756

757

)))

758

|(% style="width:113px" %)(((

759

3

760

)))|(% style="width:226px" %)(((

761

Processing date

762

)))|(% style="width:118px" %)(((

763

6 N

764

)))|(% style="width:586px" %)(((

765

YYMMDD

766

)))|(% style="width:586px" %)(((

767

200206

768

)))

769

|(% style="width:113px" %)(((

770

9

771

)))|(% style="width:226px" %)(((

772

Sender

773

)))|(% style="width:118px" %)(((

774

4 N

775

)))|(% style="width:586px" %)(((

776

"8850" (Babs)

777

)))|(% style="width:586px" %)(((

778

8850

779

)))

780

|(% style="width:113px" %)(((

781

13

782

)))|(% style="width:226px" %)(((

783

Cycle

784

)))|(% style="width:118px" %)(((

785

2 AN

786

)))|(% style="width:586px" %)(((

787

10/20

788

)))|(% style="width:586px" %)(((

789

20

790

)))

791

|(% style="width:113px" %)(((

792

15

793

)))|(% style="width:226px" %)(((

794

Filler

795

)))|(% style="width:118px" %)(((

796

26 AN

797

)))|(% style="width:586px" %)(((

798

Space characters

799

)))|(% style="width:586px" %)(((

800

801

)))

802

|(% style="width:113px" %)(((

803

41

804

)))|(% style="width:226px" %)(((

805

Vers.nr/serial number

806

)))|(% style="width:118px" %)(((

807

6 N

808

)))|(% style="width:586px" %)(((

809

File serial number

810

)))|(% style="width:586px" %)(((

811

812

)))

813

|(% style="width:113px" %)(((

814

47

815

)))|(% style="width:226px" %)(((

816

Transaction entry

817

)))|(% style="width:118px" %)(((

818

1 AN

819

)))|(% style="width:586px" %)(((

820

821

)))|(% style="width:586px" %)(((

822

823

)))

824

|(% style="width:113px" %)(((

825

48

826

)))|(% style="width:226px" %)(((

827

Filler

828

)))|(% style="width:118px" %)(((

829

333 AN

830

)))|(% style="width:586px" %)(((

831

Space characters

832

)))|(% style="width:586px" %)(((

)))

(% class="box successmessage" %)

837

(((

838

The **rkha **format actually has a 28 character filler at position 13 by default, but for "Babs" the first two positions in this filler are redefined to be "cycle" (position 13 and 14), which leaves the Filler to be 26 characters instead of 28.

)))

== Problems ==

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.

844

The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.

845

Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

=== Example ===

HTTP/1.1 400 Error

Content-Type: application/problem+json

852

853

{

854

"Type" : "ledger.card-transaction.validation",

855

"Title" : "A validation error occurred",

856

"Status" : 400,

857

"Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",

858

"Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",

859

"Problems" : [

860

{

861

"amount" : "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"

}

]

}

=== Problem types ===

868

869

(% class="box infomessage" %)

870

(((

871

Note, each problem typecode is preceded by "ledger.card-transaction." in this API, e.g. the error "validation" in the table below will appear as typecode "ledger.card-transaction.validation".

872

)))

873

874

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

875

|=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description

876

|(% style="width:537px" %)validation|(% style="width:172px" %)400|(% style="width:796px" %)occurs if any of the inputvalidation fails

877

|(% style="width:537px" %)card-token-not-found|(% style="width:172px" %)400|(% style="width:796px" %)Occurs on post towards "authorizations" when no card could be found according to the specified cardToken.

878

|(% style="width:537px" %)seller-no-not-registered|(% style="width:172px" %)501|(% style="width:796px" %)

879

|(% style="width:537px" %)currency-not-supported|(% style="width:172px" %)422|(% style="width:796px" %)

880

|(% style="width:537px" %)company-not-configured|(% style="width:172px" %)501|(% style="width:796px" %)

881

|(% style="width:537px" %)duplicate-authorization|(% style="width:172px" %)409|(% style="width:796px" %)occurs if specified SourceAuthorizationTransactionId hase already has been used on another authorization

882

|(% style="width:537px" %)duplicate-transaction-reference|(% style="width:172px" %)409|(% style="width:796px" %)occurs if any of the references that is required to be unique already has been used on another transaction of the same type

883

|(% style="width:537px" %)insufficient-funds|(% style="width:172px" %)409|(% style="width:796px" %)occurs if there is not enough funds in the account. Depending on the type of account, the reason may be that there is not enough prepaid funds or that the total debt (including the new authorization) exceeds the creditlimit of the account

884

|(% style="width:537px" %)authorization-not-found|(% style="width:172px" %)422|(% style="width:796px" %)occurs when trying to execute purchase (or other transaction) on authorization that does not exists

885

|(% style="width:537px" %)authorization-has-been-used|(% style="width:172px" %)409|(% style="width:796px" %)the referenced authorization has already been used (captured)

886

|(% style="width:537px" %)authorization-not-active|(% style="width:172px" %)409|(% style="width:796px" %)transaction cannot be executed toward the specified authorization since it is not active

887

|(% style="width:537px" %)authorization-expired|(% style="width:172px" %)422|(% style="width:796px" %)transaction cannot be executed toward the specified authorization since it has expired

888

|(% style="width:537px" %)cancel-authorization-prohibited|(% style="width:172px" %)422|(% style="width:796px" %)cancellation cannot be made on the specified authorization (for any reason)

889

|(% style="width:537px" %)authorization-type-invalid|(% style="width:172px" %)409|(% style="width:796px" %)Occurs when trying to execute transaction on authorization of an another type (i.e. purchase transaction towards authorization of type reversal)

890

|(% style="width:537px" %)account-blocked|(% style="width:172px" %)409|(% style="width:796px" %)Occurs when trying to execute transaction on an account with a claim level blocked for new purchases.

Wiki source code of card-transaction