Wiki source code of card-transaction
Last modified by David Persson on 2024/02/21 07:48
1 | (% class="jumbotron" %) |
2 | ((( |
3 | (% class="container" %) |
4 | ((( |
5 | |
6 | |
7 | Integrate to **PayEx Ledger Card transaction API ** |
8 | ))) |
9 | ))) |
10 | |
11 | (% class="lead" %) |
12 | 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"]] |
15 | |
16 | ---- |
17 | |
18 | = Changelog = |
19 | |
20 | 2020-05-19 |
21 | 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 |
34 | |
35 | |
36 | == Summary == |
37 | |
38 | (% 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 | {{code language="http" title="**Request**"}} |
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Ā " |
112 | } |
113 | {{/code}} |
114 | |
115 | |
116 | {{code language="http" title="**Response**"}} |
117 | HTTP/1.1 201 CREATED |
118 | Content-Type: application/json |
119 | |
120 | { |
121 | "authorizationId": "YYY", |
122 | "@id": "/ledger/card-transaction/v1/XXX/authorizations/YYY", |
123 | "parentHREF": "/", |
124 | "operations": [] |
125 | } |
126 | {{/code}} |
127 | |
128 | ==== |
129 | Get authorizations ==== |
130 | |
131 | {{code language="http" title="**Request**"}} |
132 | GET /ledger/card-transaction/v1/XXX/authorizations/YYY HTTP/1.1 |
133 | Host: - |
134 | Authorization: Bearer <Token> |
135 | Content-Type: application/json |
136 | {{/code}} |
137 | |
138 | ==== ==== |
139 | |
140 | {{code language="http" title="**Response**"}} |
141 | HTTP/1.1 200 OK |
142 | 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", |
161 | "parentHREF": "/", |
162 | "operations": [] |
163 | } |
164 | {{/code}} |
165 | |
166 | |
167 | ==== 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 |
179 | |
180 | * Purchase |
181 | * Reversal |
182 | * CashWithdrawal |
183 | ))) |
184 | |(% 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)// |
199 | * RecurringToken |
200 | * MagStripePin |
201 | ))) |
202 | ))) |
203 | |(% style="width:215px" %)channel|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)((( |
204 | ((( |
205 | Type of channel (optional) |
206 | |
207 | * POS |
208 | * UnattendedPOS |
209 | * Ecom |
210 | ))) |
211 | ))) |
212 | |
213 | ---- |
214 | |
215 | == Cancellations == |
216 | |
217 | 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 | {{code language="http" title="**Request**"}} |
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" |
230 | } |
231 | {{/code}} |
232 | |
233 | |
234 | |
235 | ==== 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 |
241 | |
242 | ---- |
243 | |
244 | == Purchases == |
245 | |
246 | ==== Post purchases ==== |
247 | |
248 | {{code language="http" title="**Request**"}} |
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Ā " |
272 | } |
273 | } |
274 | {{/code}} |
275 | |
276 | ==== Get purchases ==== |
277 | |
278 | {{code language="http" title="**Request**"}} |
279 | GET /ledger/card-transaction/v1/XXX/purchases/PPP HTTP/1.1 |
280 | Host: - |
281 | Authorization: Bearer <Token> |
282 | Content-Type: application/json |
283 | |
284 | {{/code}} |
285 | |
286 | ==== List purchases ==== |
287 | |
288 | {{code language="http" title="**Request**"}} |
289 | GET /ledger/card-transaction/v1/XXX/purchases HTTP/1.1 |
290 | Host: - |
291 | Authorization: Bearer <Token> |
292 | Content-Type: application/json |
293 | |
294 | {{/code}} |
295 | |
296 | ==== Resource purchases ==== |
297 | |
298 | {{code language="http" title="**Response**"}} |
299 | HTTP/1.1 201 CREATED |
300 | 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" |
329 | } |
330 | ] |
331 | } |
332 | {{/code}} |
333 | |
334 | ==== 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)// |
364 | * RecurringToken |
365 | * MagStripePin |
366 | ))) |
367 | ))) |
368 | |(% style="width:215px" %)offlineInfo.channel|(% style="width:114px" %)string|(% style="width:118px" %) |(% style="width:586px" %)((( |
369 | ((( |
370 | Type of channel (optional) |
371 | |
372 | * POS |
373 | * UnattendedPOS |
374 | * Ecom |
375 | ))) |
376 | ))) |
377 | |(% 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" %) |
379 | |
380 | ---- |
381 | |
382 | == Cash-withdrawals == |
383 | |
384 | ==== Post cash-withdrawals ==== |
385 | |
386 | {{code language="http" title="**Request**"}} |
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" |
403 | } |
404 | {{/code}} |
405 | |
406 | ==== Get cash-withdrawals ==== |
407 | |
408 | {{code language="http" title="**Request**"}} |
409 | GET /ledger/card-transaction/v1/XXX/cash-withdrawals/WWW HTTP/1.1 |
410 | Host: - |
411 | Authorization: Bearer <Token> |
412 | Content-Type: application/json |
413 | |
414 | {{/code}} |
415 | |
416 | ==== List cash-withdrawals ==== |
417 | |
418 | {{code language="http" title="**Request**"}} |
419 | GET /ledger/card-transaction/v1/XXX/cash-withdrawals HTTP/1.1 |
420 | Host: - |
421 | Authorization: Bearer <Token> |
422 | Content-Type: application/json |
423 | |
424 | {{/code}} |
425 | |
426 | ==== Resource cash-withdrawals ==== |
427 | |
428 | {{code language="http" title="**Response**"}} |
429 | HTTP/1.1 201 CREATED |
430 | 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" |
451 | } |
452 | ] |
453 | } |
454 | {{/code}} |
455 | |
456 | ==== 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" %) |
475 | |
476 | ---- |
477 | |
478 | === Reversals === |
479 | |
480 | 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 | {{code language="http" title="**Request**"}} |
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" |
503 | } |
504 | {{/code}} |
505 | |
506 | ==== Get reversals ==== |
507 | |
508 | {{code language="http" title="**Request**"}} |
509 | GET /ledger/card-transaction/v1/XXX/reversals/RRR HTTP/1.1 |
510 | Host: - |
511 | Authorization: Bearer <Token> |
512 | Content-Type: application/json |
513 | |
514 | {{/code}} |
515 | |
516 | ==== List reversals ==== |
517 | |
518 | {{code language="http" title="**Request**"}} |
519 | GET /ledger/card-transaction/v1/XXX/reversals HTTP/1.1 |
520 | Host: - |
521 | Authorization: Bearer <Token> |
522 | Content-Type: application/json |
523 | |
524 | {{/code}} |
525 | |
526 | ==== Resource reversals ==== |
527 | |
528 | {{code language="http" title="**Response**"}} |
529 | HTTP/1.1 200 OK |
530 | 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" |
549 | } |
550 | ] |
551 | } |
552 | {{/code}} |
553 | |
554 | ==== 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. |
569 | |
570 | === Corrections === |
571 | |
572 | Each type of transactions can be corrected by making a POST call against its correction resource |
573 | |
574 | ==== Create purchase corrections ==== |
575 | |
576 | {{code language="http" title="**Request**"}} |
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", |
588 | "amount": 200.0, |
589 | "date": "2019-11-28" |
590 | } |
591 | {{/code}} |
592 | |
593 | ==== Create cash-withdrawal corrections ==== |
594 | |
595 | {{code language="http" title="**Request**"}} |
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", |
607 | "amount": 200.0, |
608 | "date": "2019-11-28" |
609 | } |
610 | {{/code}} |
611 | |
612 | ==== Create reversal corrections ==== |
613 | |
614 | {{code language="http" title="**Request**"}} |
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", |
626 | "amount": 200.0, |
627 | "date": "2019-11-28" |
628 | } |
629 | {{/code}} |
630 | |
631 | ==== 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 |
689 | |
690 | == == |
691 | |
692 | = 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. |
721 | ))) |
722 | |
723 | == == |
724 | |
725 | == RKHA21 format == |
726 | |
727 | 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" %)((( |
833 | |
834 | ))) |
835 | |
836 | (% 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. |
839 | ))) |
840 | |
841 | == Problems == |
842 | |
843 | 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. |
846 | |
847 | === Example === |
848 | |
849 | {{code language="http" title="**Response**"}} |
850 | HTTP/1.1 400 Error |
851 | 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]" |
862 | } |
863 | ] |
864 | } |
865 | {{/code}} |
866 | |
867 | === 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. |