forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpaysafecash-apiary.apib
617 lines (454 loc) · 35.8 KB
/
paysafecash-apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
FORMAT: 1A9
HOST: http://polls.apiblueprint.org/paysafecash/v1
# Integrating the paysafe cash REST API
# Technical introduction
This section provides a technical introduction of paysafe cash. Paysafe cash is based on the paysafecard REST API.
## About the API
The paysafecard REST API follows <a href="http://en.wikipedia.org/wiki/Representational_state_transfer" target="_blank">*RESTful*</a> design principles making it easy to understand and integrate the API.
Representational State Transfer (REST) is a software architecture style, consisting of guidelines for creating scalable web services.
RESTful systems typically communicate over the Hypertext Transfer Protocol with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) used by web browsers to retrieve web pages and send data to remote servers.
It facilitates solid and universally accepted foundations like [*http basic authentication*](http://en.wikipedia.org/wiki/Basic_access_authentication), [*http verbs*](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods), [*JSON*](http://en.wikipedia.org/wiki/JSON) and [*CORS*](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
## Versioning
Every time there is backwards-incompatible change to the API, a new major version will be released. This major version is part of the URL path.
The current major version is *v1*. Unless informed by our technical support department that we are dropping support for a particular API version, you do not need to switch API versions.
## Prerequisites
You can only connect to the paysafe cash system if the following prerequisites are fulfilled:
- API key for request authentification provided by paysafecard.
- Authorisation of the payment server IP address (if a 403 error is received when trying to access the service, it is likely that the IP address is not yet allowed to access).
- Content-type: Please make sure that the content type in the HTTP header, when submitting requests, is set to **Content-Type: application/json**
- Character encoding needs to be in UTF-8
## API key authentication
Every request to the paysafecard API is authenticated using an API key.
- The value of the **API key needs to be base64 encoded** when transmitted in the HTTP header!
- Set the key as the username. [*HTTP basic authentication*](http://en.wikipedia.org/wiki/Basic_access_authentication)
- Your API key may only be used from your backend systems.
- *Please note: Your API key must be kept secured - never expose the API key to anybody!*
Below is an example of how the API key is supposed to be set.
```
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
```
## Test Environment and Endpoints
- paysafecard provides the ‘paysafe cash test system’, a test environment for integration of new business partners.
Every new business partner needs to integrate the payment platform first on the test system.
Once the integration on your system is finished a UAT(UserAcceptanceTest) needs to be done in order to ensure a seemless integration flow.
- The endpoint for the *test environment* is: https://apitest.paysafecard.com/v1/
- The endpoint for the *production environment* is: https://api.paysafecard.com/v1/
## HTTP status codes
| Code | Short Description | Description |
| --- | --- | --- |
| 200 | OK | Everything is OK.|
| 201 | Created | New object was successfully created.|
| 400 | Bad Request | Missing parameter.|
| 401 | Unauthorized | Invalid or expired API key.|
| 404 | Not Found | Not found. This is also returned when you try to retrieve a payment that does not exist.|
| 500 | Internal Server Error | This indicates a general technical error on paysafecard's end.|
| 501 | Not Implemented | Version feature not implemented.|
| 502 | Bad Gateway | Invalid response from upstream system.|
| 503 | Service Unavailable | Server overloaded.|
| 504 | Gateway Timeout | Timeout from upstream system.|
*Below is an example of an error response:*
```
400 Bad Request
{
"code": "invalid_request_parameter"
"message": ""must contain 1-10 digits, followed by a decimal separator '.' followed by 2 digits",
"number": 10028,
"param": "amount"
}
```
*Please note: A list of all the common error codes can be found below at the end of each service section.*
# Customer product introduction
This section provides an overview of the paysafe cash customer products relevant in the context of the paysafecard REST API.
## paysafe cash
paysafe cash gives customers the possibility to purchase products online without a bank account or credit card. The customers can go to a point of sales and pay the products they ordered online with cash.
To be able to use paysafe cash, an account is required. The customers can sign up for this online.
After the customers chose a product and are redirected to the paysafe cash bar code application, they can login with said user and get a bar code in return. With this bar code, they can pay at the point of sales.
If the transaction fails for some reason, the money will be on the customers account, and the customer can pay with the left amount again for other products.
# Payment flow with paysafe cash
This area provides information about the paysafe cash payment flow from a business partner's point of view.
## Functional payment flow
The functional payment flow works as follows:
1. The customer selects paysafe cash as the preferred payment option in your webshop.
2. You initiate a payment with the correct amount, currency and other parameters.
3. You re-direct the customer to paysafe cash's hosted bar code application, where the customer has 30 minutes to login and generate a bar code.
4. The customer has a pre-defined time frame (default 72 hours) to take the bar code and go to a point of sales. After the cash payment, the money will be assigned to the transaction and therefore it is ready to be debited.
5. paysafecard sends a notification to the notification URL.
6. You capture the payment (additional information can be found in the section "Capturing a payment" below).
7. You complete the transaction in your database and ship the purchased product to the customer.
## Bar code application details
paysafe cash customers are, by default, redirected to the hosted bar code application from paysafecard, where they login to get a bar code. With this bar code, they can complete the transaction at a point of sales.
Please make sure that the hosted payment page size is correctly set in your webshop.
### Integration on desktop devices
The paysafe cash bar code application should be displayed as a redirect in the same window, on a new browser tab or a new browser window.
Always allow vertical scrolling or dynamic sizing.
### Integration on mobile devices
paysafe cash bar code application is optimised automatically for mobile devices.
# Group Payment Process
1. The customer selects the payment method paysafe cash.
1. Initiate Payment: Send POST request`initiate Payment`.
* 2.1. If the response gives back http20x, redirect the customer to the payment panel.
* 2.2. If the response gives back http40x or htp50x, show an error message to the customer.
Inititate Payment error message: "Transaction could not be intitiated due to connection problems. If the problem persists, please contact our (businessparter)support."
1. Redirection to the bar code application`auth_url`: The customer reaches the bar code application.
1. Login(by customer): The customer logs in to retrieve the bar code
* 4.1. If the customer cancels the transaction on the payment panel, please show the following error message: "Transaction aborted by user" on your failureURL
1. Customer goes to Point of Sales and pays the transaction with cash
1. Payment notification delivery: Since the transaction is paid, the amount assigned to the transaction(transaction status "AUTHORIZED"), we send a notification to your`notification_url`.
1. `notification_url` handling: You perform the GET request`Retrieve payment details`to check the state of the transaction.
* 7.1. If the GET request `retrieve payment details` gets back the according status "AUTHORIZED", perform the POST request `capture Payment`.
* 7.2. If the response of`capture payment`is http20X and the status is "SUCCESS", make a user account top up.
1. As soon capture payment was successful, the transaction is completed. Mark it in your system as finished and ship the purchase
# Group Payment Information
The following section provides additional information about the payment process:
## Payment status
|Value |Description |
|--- |--- |
|`INITIATED` |The initial state of a payment after it has been successfully created. |
|`REDIRECTED`|The customer has been redirected to the bar code application to generate a bar code.|
|`AUTHORIZED`|The customer has paid the transaction amount at a point of sales.|
|`SUCCESS`|The payment has been completed successfully.|
|`CANCELED_MERCHANT`|You, as the business partner, have cancelled the payment.|
|`CANCELED_CUSTOMER`|The customer has cancelled the payment.|
|`EXPIRED`|The customer has not logged in to the bar code application in 30 minutes after the transaction has been created, the customer has not paid the transaction in the predefined time frame (default 72 hours) or you, the business partner, have not captured the authorized amount during the disposition time window.|
## Bar code timeout
As soon a transaction is successuflly created and the customer logs in at the bar code application and generates a bar code, the **bar code timeout** starts. This is the time frame in which the customer is able to go to a point of sales and pay the transaction amount.
This time window is set per default to 72 hours.
## Disposition time window
Once a payment is in the state `AUTHORIZED`, you have to capture the customer's payment within a certain time period (disposition time).
The disposition time window is configurable per MID.
If this time window is exceeded, the payment will automatically expire and the amount will be available again on the customer’s account.
*Please note: All payments which have not been authorized by the customer or which have not been captured by you during the disposition time window, will be set to `EXPIRED`. These jobs are only active in the paysafecard production environment.*
## Payment notification
The payment notification is used to notify the business partner about the status of the transaction. The payment notification is sent as soon money is assigned to the transaction, so when the transaction can be captured.
In case of technical errors (e.g. socket timeout), or application errors (e.g. HTTP 500 response), the payment notification is resubmitted at a regular interval until one of the following criteria is fulfilled:
- The payment notification is successfully delivered (i.e. HTTP 200 response from payment server).
- The maximum number of retry attempts has been reached (currently configured at 5 retries).
- The transaction is completed successfully.
## Status before expiration
`status_before_expiration` can be used to hold the status of the payment before it transitions to `EXPIRED`.
This is useful to distinguish cases where a successfully authorized payment has not been captured from cases where a customer did not authorize the payment at all.
The possible values are "AUTHORIZED", "INITIATE" and "REDIRECTED".
# Group Payment API Calls
## Initiating a payment [/payments]
Upon successful execution of this request, the `status` of the payment transitions to `INITIATED`.
Using the optional HEADER-Parameter `Correlation-ID` you can set a part of the parameter `id` on your own.
+ Attributes (PaymentRequest)
### Initiating a payment [POST]
The next step is to redirect the customer to the `auth_url`, which is returned as part of the response.
As soon as the customer has authorized the payment, its state will transition to `AUTHORIZED` and the customer will be redirected to the `success_url` you specified when creating the payment.
In addition to redirecting the customer back to your site, we will call the `notification_url` you specified. See more details in the section "Payment notification".
Now you are ready to perform the final step, capturing the payment.
+ Request (application/json)
+ Headers
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
+ Attributes (PaymentRequest)
+ Response 201 (application/json)
{
"object": "PAYMENT",
"id": "pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
"created": 1430137532383,
"updated": 1430137532383,
"amount": 0.01,
"currency": "EUR",
"status": "INITIATED",
"redirect": {
"success_url": "http://ok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
"failure_url": "http://nok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR",
"auth_url": "https://dv.customer.paysafecard.com/psccustomer/GetCustomerPanelServlet?mid=1000000007&mtid=pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR&amount=0.01¤cy=EUR"
},
"customer": {
"id": "ICuCsrKUmg3pCpTyFNNrPR6K5k36P8Sv"
},
"notification_url": "http://ok.com/pay_1000000007_Hukab77YIXzKUYMdgPDBQ986ihNUQChu_EUR"
}
## Capturing a payment [/payments/{id}/capture]
```
POST /payments/{id}/capture
```
| Parameter | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| `id` | string | required | pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR | id from Step 1 |
### Capturing a payment [POST]
+ Parameters
+ id: pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR (required) - Id from the initiate payment call.
+ Request (application/json)
+ Headers
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
+ Response 200 (application/json)
{
"object":"PAYMENT",
"id":"pay_1000000007_k3JfFMcpLPXGMk1mOdkbmRARdr5kKQeI_EUR",
"created":1430205127021,
"updated":1430206011382,
"amount":0.01,
"currency":"EUR",
"status":"SUCCESS",
"type":"PAYSAFECARD",
"customer":{
"id":"a4ssjAMiHia58AJ7wi4cHBgsFOTmTvCv"},
"notification_url":"http://ok.com",
"card_details":[{
"serial":"1453591278",
"currency":"EUR",
"amount":0.01,
"type":"00002",
"country":"AT"}]
}
### Retrieving payment details [/payments/{id}]
```
GET /payments/{id}
```
| Parameter | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| `id` | string | required | pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR | id from Step 1 |
+ Parameters
+ id (required, string, `pay_9000001500_t7krk6idmLIzz6uUUv3AhU6dIay7ah75_EUR`) ... id from Step 1.
### Retrieving payment details [GET]
+ Request (application/json)
+ Headers
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
+ Response 200 (application/json)
+ Attributes (PaymentResponse)
# Group Payment API response objects
|Parameter|Description|Cases|
|---|---|---|
|`object`|Identifies the object. For a payment, the value returned is PAYMENT.|Always|
|`id`|Unique identifier for a payment.|Always|
|`created`|Unix timestamp specifying when this object was created.|Always|
|`updated`|Unix timestamp specifying when this object was last updated.|Always|
|`amount`|The payment amount.|Always|
|`currency`|Currency of this payment.|Always|
|`status`|Please scroll up to the section "Payment status" for a list of all possible payment states.|Always|
|`status_before_expiration`|Holds the status of the payment before it transitioned to `EXPIRED`. This is useful to distinguish cases where a successfully authorized payment has not been captured from cases where a customer did not authorize the payment at all.|Optional. Only returned when the payment is in status `EXPIRED`.|
|`type`|Always set to PAYSAFECARD.|Always|
|`redirect[success_url]`|URL to redirect if customer clicks on "Back to Shop". Should redirect to Homepage/Shopping basket. Shopping basket should be emptied as soon the customer is redirected to the bar code application.|Always|
|`redirect[failure_url]`|URL to redirect after customer/you as merchant cancels the transaction.|Always|
|`notification_url`|Notification URL we will contact after authorization has been successfully completed.|Always|
|`customer[id]`| ID provided by you, which identifies the customer.|Always|
|`customer[ip]`|IPv4 address of the customer.|After customer has been re-directed to paysafecards payment panel.|
|`card_details[serial]`|The serial number of the card that has been used to authorize the payment.|After cards have been assigned.|
|`card_details[currency]`|The currency of the card.|After cards have been assigned.|
|`card_details[amount]`|The amount that has been deducted from the card for this payment.|After cards have been assigned.|
|`card_details[type]`|The type of card.|After cards have been assigned.|
|`card_details[country]`|The country where this card was issued.|After cards have been assigned.|
# Group Payment Error Codes
|Code |Number (optional) |HTTP Status |Description |
|--- |--- |--- |--- |
|`general_technical_error` |10007 |500 |General technical error.|
|`invalid_api_key` |10008 |401 |Authentication failed due to missing or invalid API key. Your key needs to be set to the HTTP auth username.|
|`invalid_request_parameter` |10028 |400 |One of the request parameters failed validation. The `message` and `param` fields contain more detailed information.|
|`duplicate_transaction_id` |2001 |400 |Transaction already exists.|
|`payment_invalid_state` |2017 |400 |The payment is in an invalid state, e.g. you tried to capture a payment that is in state `INITIATED` instead of `AUTHORIZED`.|
|`Merchant with Id XXXXXXXXXX is not active.` |3001 |400 |Merchant is not active.|
|`Merchant with Id XXXXXXXXXX is not allowed to perform this debit any more`|3007 |400 |Debit attempt after expiry of dispo time window.|
|`submerchant_not_found` |3014 |400 |The `submerchant_id` specified by you has not been configured.|
Other errors can be communicated to the customer as “general technical error”. In general when one of these
errors occur the business partner should contact paysafecard immediately via [email protected] if the account is not live.
For live accounts, [email protected] should be contacted.
#Group Customer Data Takeover
There is the possibility that the business partner sends the customer data (full name, DoB, full list of parameters below) to paysafecard, so the registration form is prefilled.
This has the purpose to make the registration of the customer easier. If the business partner wants to use that feature, it has to be pointed out clearly to the customer that the data is shared with paysafecard.
The customer data exchange happens at the redirection of the customer to the bar code application.
+ Customer has to be informed of the data exchange
+ Makes it easier for the customer to register at paysafecard
+ Business partner sends the data in the redirection
Instead of the normal redirect (GET request), the business partner has to perform a POST request with a hidden form including the customer's data.
**Important**: paysafecard does not store this data. It is solely used to make the registration easier. The data is only accessible for 10 minutes and is dropped afterwards.
####Parameters for the form containing customer data
|Field|Value|Max length|
|---|---|---|
|salutation|string 'mr or 'mrs'|3|
|firstName|string|40|
|lastName|string|40|
|birthDate|date format pattern "dd/MM/yyyy" <ul><li>dd: day with leading zero</li><li>MM: month with leading zero</li><li>yyyy: 4 digit year</li></ul>||
|phoneNumer|string including international calling code, e.g. +4471001234567891|30|
|email|string|70|
|street|string|35|
|city|string|40|
|postalCode|string|10|
##Steps to create the hidden object and perform the redirect
###Create a JS object with the customer's data
var customerData = { <br />
salutation: "mr", <br />
firstName: "John", <br />
lastName: "Doe", <br />
birthDate: "01/02/1970", <br />
phoneNumber: "+4471001234567891", <br />
email: "[email protected]" <br />
street: "76 Regent Street", <br />
city: "London", <br />
postalCode: "W1B 5RN" <br />
};
###Create a hidden form containing the customer's data
var form = document.createElement("form"); <br />
form.id = "psc_post_form_id"; <br />
form.style.display = "none"; <br />
form.style.width = "0"; <br />
form.style.height = "0"; <br />
form.method = "post"; <br />
for (var i in customerData) { <br />
var parameter = document.createElement ("input"); <br />
parameter.name = i; <br />
parameter.value = customerData[i]; <br />
form.appendChild(parameter); } <br />
document.body.appendChild(form);
###Set target, URL with payment parameters and execute the form submit
form.target = ''; // '' *-> redirect; '_blank' -> new tab; '{iframe_id}'* <br />
form.action = "https://customer.test.at.paysafecard.com/psccustomer/GetCustomerPanelServlet" <br />
+"?mid=merchantID" <br />
+"&mtid=merchantTransactionId1&amount=3.00" <br />
+"¤cy=EUR"; <br />
form.submit();
# Group Refund Process
The refund feature provides business partners to fully or partially refund a previously paid transaction back into the
customer‘s my paysafecard account.
A refund will always be issued in the currency of the original payment transaction.
Refunding a payment is possible up to 45 days after the initial payment.
- Prerequisites
- The business partner needs to have the merchant refund REST functions implemented on the website or back-end system.
- The business partner needs to be fully integrated and refund needs to be enabled at paysafecard’s side.
- The customer needs to be registered with my paysafecard in order to receive a refund.
- A refund transaction always refers to a previous underlying payment, because of this reason it is required that a
payment has been processed before the refund can be processed.
- Validation and refund
In order to make sure that the requested refund can continue, the business partner has to precheck
the likeliness of the upcoming refund to be successful, there are certain conditions why a refund might be
refused. The validation is performed by providing `capture=false` during a refund request.
As soon as the validation was successful the business partner can initiate the refund to the paysafecard customer,
paysafecard will top-up the requested refund amount in the customer’s my paysafecard account.
- Settlement
All successfull refunds will be deducted from the payments (netting) on the montly invoice that paysafecard
sends its business partners.
# Group Refund API Calls
## Validating/Capturing a Refund [/payments/{id}/refunds]
```
POST /payments/{id}/refunds
```
| Parameter | Type [validation] | Required | Example | Description |
| --- | --- | --- | --- | --- |
| `type` | string<br/>[PAYSAFECARD] | required | paysafecard | Must be set to PAYSAFECARD.|
| `capture` | boolean<br/>[true,false] | required | true or false |
| `amount` | float or integer<br/>[max length: 11 digits before, optionally 2 digits after decimal point] | required | 10.00 | The precision needs to be two digits after the colon.|
| `currency` | string<br/> [max. length: 3, all uppercase] | required | EUR | ISO 4217 (3 letter ISO currency code) |
| `customer[email]` | string<br/> [valid email address] | optional<br/>one of email, phone_number, account_id | [email protected] | Needs to be the email that the customer used to register for myPaysafecard. |
### Validating a new Refund [POST]
+ Parameters
+ id: `pay_9000001500_Bo2Phc1X2Gtg6Nu7WtqHZrjA2At3qdkj_EUR` (required) - Id of a prevalidated or captured payout
+ Request (application/json)
+ Headers
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
+ Attributes (RefundValidationRequest)
+ Response 201 (application/json)
+ Attributes (RefundResponse)
## Capturing a pre validated Refund [/payments/{paymentid}/refunds/{refundid}/capture]
| Parameter | Type | Required | Example | Description |
| --- | --- | --- | --- | --- |
| `id` | string | required | ref_1000000007_2838fhsd6dashsdkfsd_EUR | id from Step 1
### Capturing a pre validated Refund [POST]
+ Parameters
+ paymentid: `pay_9000001500_Bo2Phc1X2Gtg6Nu7WtqHZrjA2At3qdkj_EUR` (required) - Id of a prevalidated or captured payout
+ refundid: `ref_9000001500_MfnRV7RG19RgpqHACDpQDX16oRJHFWxs_EUR`
+ Request (application/json)
+ Headers
Authorization: Basic cHNjX0R4dThqSnI1LVdPYXhLWnpjOXdyMUtNLXd1Y3dZMXg=
+ Attributes (RefundCaptureRequest)
+ Response 201 (application/json)
+ Attributes (RefundResponse)
# Group Refund Error Codes
|Code |Number (optional) |HTTP Status |Description |
|--- |--- |--- |--- |
|`PRODUCT_NOT_AVAILABLE` |3100 |404 |Product not available.|
|`DUPLICATE_ORDER_REQUEST` |3103 |400 |Duplicate order request.|
|`FACEVALUE_FORMAT_ERROR` |3106 |400 |Invalid facevalue format.|
|`MISSING_PARAMETER` |3150 |400 |Missing paramenter.|
|`INVALID_CURRENCY` |3151 |400 |Invalid currency.|
|`MERCHANT_NOT_ALLOWED_FOR_PAYOUT` |3161 |400 |Merchant not allowed to perform this Action.|
|`CUSTOMER_NOT_FOUND` |3162 |404 |No customer account found by provided credentials.|
|`INVALID_PARAMETER` |3163 |400 |Invalid paramater.|
|`duplicate_payout_request` |3164 |400 |Transaction already exists.|
|`INVALID_AMOUNT` |3165 |400 |Invalid amount.|
|`CUSTOMER_LIMIT_EXCEEDED` |3167 |400 |Customer limit exceeded.|
|`KYC_INVALID_FOR_PAYOUT_CUSTOMER` |3168 |400 |Feature not activated in this country for this kyc Level.|
|`payout_id_collision` |3169 |400 |Payout id collides with existing disposition id|
|`topup_limit_exceeded` |3170 |400 |Top-up limit exceeded.|
|`payout_amount_below_minimum` |3171 |400 |Payout amount is below minimum payout amount of the merchant.|
|`MERCHANT_REFUND_EXCEEDS_ORIGINAL_TRANSACTION` |3179 |400 |Merchant refund exceeds original transaction.|
|`MERCHANT_REFUND_ORIGINAL_TRANSACTION_INVALID_STATE` |3180 |400 |Original Transaction of Merchant Refund is in invalid state.|
|`MERCHANT_REFUND_CLIENT_ID_NOT_MATCHING` |3181 |400 |Merchant Client Id not matching with original Payment.|
|`NO_UNLOAD_MERCHANT_CONFIGURED` |3182 |400 |merchant client Id missing.|
|`MERCHANT_REFUND_MISSING_TRANSACTION` |3184 |404 |No original Transaction found.|
|`merchant_refund_customer_credentials_missing` |3185 |404 |my paysafecard account not found on original transaction and no additional credentials provided.|
|`customer_inactive` |3193 |400 |Customer not active.|
|`customer_yearly_payout_limit_reached` |3194 |400 |Customer yearly payout limit exceeded.|
|`customer_details_mismatchd` |3195 |400 |Customer details from request don't match with database.|
|`max_amount_of_payout_merchants_reached` |3198 |400 |There is already the maximum number of pay-out merchant clients assigned to this account.|
|`payout_blocked` |3199 |400 |Payout blocked due to security reasons.|
Other errors can be communicated to the customer as “general technical error”. In general when one of these
errors occur, the business partner should contact paysafecard immediately via [email protected] if the account is not live.
For live accounts, [email protected] should be contacted.
# Data Structures
## TypedObject (object)
+ type: PAYSAFECARD (required, fixed) - Type of the product, must be set to PAYSAFECARD.
## PaymentRequest (TypedObject)
+ amount: 0.01 (number, required) - Payment amount, precision must be 2 digits after the colon.
`10.00`
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ redirect (Redirect, required) - URLs to redirect after successful or failed authorization. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ `notification_url`: https://notification.com/{payment_id} (required)- Notification URL we will contact after the authorization has been successfully completed. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ customer: "id":"3ncrypt3d3m41l" "min_age":"18" "kyc_level":"SIMPLE" "country_restriction":"DE" (object, required) - Only the id is mandatory. It's value uniquely identifies the customer and is provided by you. If any personal data (e.g. customer's user name, email address, etc.) is used here, it has to be encrypted or hashed for security reasons. min_age: Valid for my paysafecard payments. For additional information about my paysafecard, please see the section "my paysafecard". Restricts payments to my paysafecard customers only, who are equal to or older than the specified age. Please note: This means that it is required that the customer has a registered my paysafecard account to make the payment. kyc_level: Valid values: SIMPLE or FULL. These values refer to the KYC level of the customer's my paysafecard account. Depending on the country, my paysafecard accounts are offered with SIMPLE and/or FULL customer identification. country_restriction: DE (optional) - ISO 3166-1 alpha-2 two-letter country code used to restrict payments to residents of a particular country.
+ id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation (required)
+ `min_age`: (optional) - Valid for my paysafecard payments. For additional information about my paysafecard, please see the section "my paysafecard". Restricts payments to my paysafecard customers only, who are equal to or older than the specified age. Please note: This means that it is required that the customer has a registered my paysafecard account to make the payment.
+ `kyc_level`: (optional) - Valid values SIMPLE or FULL. These values refer to the KYC level of the customer's my paysafecard account. Depending on the country, my paysafecard accounts are offered with SIMPLE and/or FULL customer identification.
+ `country_restriction`: (optional) - ISO 3166-1 alpha-2 two-letter country code used to restrict payments to residents of a particular country.
+ submerchant_id: 1 - ReportingCriterion (optional) - Also called ‘reporting criteria’, offers the possibility to classify sub-merchants. Agreement with paysafecard needed - not agreed values lead to a failed payment.
+ shop_id: `shop1` (optional) - Identification of the shop which is the originator of the request. This is most likely used by payment service providers who act as a proxy for other payment methods as well.
## PaymentResponse (TypedObject)
+ id: pay_1000000007_k3JfFMcpLPXGMk1mOdkbmRARdr5kKQeI_EUR - The unique id of this payment
+ created: 1430317131908 (number)
+ updated: 1430317131908 (number)
+ amount: 0.01 (number)
+ currency: EUR (required) - ISO 4217 (3 letter ISO currency code).
+ status: SUCCESS
+ redirect (Redirect)
+ `notification_url`: https://notification.com/{payment_id} (required)- Notification URL we will contact after the authorization has been successfully completed. The placeholder {payment_id} in the URL is replaced with the actual ID of this payment.
+ customer (CustomerResponseFull)
+ card_details (array[CardDetails])
## CardDetails (object)
+ serial: 1453591278
+ currency: EUR
+ amount: 0.01
+ type: 00002
+ country: AT
## CustomerResponseFull (object)
+ id
+ account_id
+ first_name: xApuEWppcYCptzoRnykkNuKznx
+ last_name: DbHILeEKPCRTCFuGbHKByYtbCm
+ email: [email protected] - the customer identifier
+ age
+ kyc_level
+ currency
## Redirect (object)
+ `success_url`: https://ok.com/{payment_id}
+ `failure_url`: https://nok.com/{payment_id}
## RefundRequest (TypedObject)
+ amount: 00.01 (number, required)
+ currency: EUR (required)
+ customer (object, required)
+ id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation (required)
+ email: [email protected] (required)
## RefundValidationRequest (RefundRequest)
+ capture: false (boolean, required)
## RefundCaptureRequest (RefundRequest)
+ capture: true (boolean, required)
## RefundResponse (object)
+ object: refund - Type of object, always refund
+ id: ref_1000000007_2838fhsd6dashsdkfsd_EUR
+ created: 1430137532383 (number)
+ updated: 1430137532383 (number)
+ currency: EUR
+ amount: 10.00
+ customer (object)
+ id: merchantclientid5HzDvoZSodKDJ7X7VQKrtestAutomation
+ email: [email protected]
+ status : SUCCESSFULEUpdated