forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpaysafecardsettlementreportapi-apiary.apib
101 lines (73 loc) · 6.02 KB
/
paysafecardsettlementreportapi-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
FORMAT: 1A
HOST: https://api.paysafecard.com/v2/reports/
# paysafecard settlement report API
# Technical introduction
This section provides a technical introduction to the paysafecard settlement report API.
## About the API
This revue describes the settlement report API for business partners of paysafecard.
The settlement report informs about all successful debited transactions.
The data can be filtered by various criteria. The reports are shown as text-file in csvformat
(Comma-Separated Values).
The internet connection (e.g. through firewall) must allow secured HTTP connections
(HTTPS).
The necessary API KEY will be sent to the business partner upon request.
## 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 *v2*. 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 paysafecard 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**
- Accept: Please make sure that the accept header, when submitting requests, is set to **Accept: text/csv**
- 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 header key is supposed to be set.
```
Authorization: Basic cHNjX2NSc09keTI2eDI1MGhPLWp4V0VpeUt2YmhudWJsNHA=
Content-Type: application/json
Accept: text/csv
```
## Endpoint
- The endpoint for the *production environment* is: https://api.paysafecard.com/v2/reports/
## Generate settlement report
In the debit report only all successfully debited transactions are listed.
All transactions that are here listed have exclusively status SUCCESS.
In order to reconcile the settlement with the debit report, please use the stated
invoice number in the invoice as a search filter.
### NOTE THE FOLLOWING LIMITS:
You can only connect to paysafecard if the following prerequisites are fulfilled:
- file download: maximum 200.000 downloadable lines
- maximum allowed search with date filter: 12 months at once
## Settlement Report [/settlement?from={from}&to={to}&mid={mid}&reporting_criteria={reporting_criteria}&merchant_client_id={merchant_client_id}&invoice_number={invoice_number}&transaction_type={transaction_type}&include_header={include_header}]
### Retrieve Settlement Report [GET]
+ Parameter
+ from: `2016-09-01` (string, required) - The from date
+ to: `2016-09-20` (string, required) - The to date
+ `mid`: 1000000007 (array, optional) - If no mids are present, all mids that are bound to this account will be searched
+ `reporting_criteria`: RC1 (string, optional) - The reporting criteria
+ `merchant_client_id`: encryt3d3m4il (string, optional) - The customer id
+ `invoice_number`: INV1 (string, optional) - The invoice number. Required if from and to are missing
+ `transaction_type`: PAYMENT (string, optional) - Only transactions of the specified type are returned. Valid values are PAYMENT, REFUND, PAYOUT. This parameter can be used multiple times in a request to include more than one transaction type in the result. Defaults to PAYMENT
+ `include_header`: false (boolean, optional) - If the response should include a header with the csv field names
+ Request
+ Headers
Authorization: Basic cHNjX2NSc09keTI2eDI1MGhPLWp4V0VpeUt2YmhudWJsNHA=
Content-Type: application/json
Accept: text/csv
+ Response 200 (text/csv)
"MID","TransactionID","DebitNr","ReportingCriteria","MerchantClientID","Currency","GrossAmount","PercentageOfCommission","PercentageOfTax","DebitAmount","ExchangeRate","InvoiceNumber","VoucherNumber","DebitTimestamp","InitialAmount","DispositionAmount","NetAmount","CreationTimestamp","ShopID","ClientIpCountry","CardOrigin","BusinessType","CustomerPscId","OriginalTransactionID"
"1000613392","ref_1000613392_g4AkEi3ZBuG4AHpKeIhRyKoRs2j9CiD3_EUR","","","cXTLq3xJEtPGlGtASumFKeUt38UfrmDB","EUR","9.99","","","","","","","2017-05-16 13:54:57.751","","","","","","","AT","R","164585866073",""
# Group Settlement report 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.|
|`Merchant with Id XXXXXXXXXX is not active.` |3001 |400 |Merchant is not active.|
|`submerchant_not_found` |3014 |400 |The `submerchant_id` specified by you has not been configured.|