forked from Paysafecard-DEV/api-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
paysafecardsettlementreportapi-apiary.apib
232 lines (169 loc) · 18.9 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
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
FORMAT: 1A
HOST: https://api.paysafecard.com/v3/reports/
# paysafecard Settlement Report API
# Technical introduction
This document describes the Settlement Report API for business partners of paysafecard.
## About the API
The Settlement Report API can be accessed over HTTPS and informs about all successfully debited transactions (paysafecard and Paysafecash), payouts and refunds.
The data can be filtered by various criteria and the reports are shown as text-file in csv format (Comma-Separated Values).
## 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 *v5*.
Unless informed by our technical support department that we are dropping support for a particular API version, the business partners do not need to switch API versions.
<a name="change_log"></a>
## Change Log
`2021.08.10`
Two parameters return 5 decimals instead of 2 decimals:
- "FeeAmount"
- FeeAmount before the change: `2.98`
- FeeAmount after the change: `2.98123`
- "NetAmount"
- NetAmount before the change: `15.98`
- NetAmount after the change: `15.98123`
`2021.01.26`
### New major version - v5
- Added two new report header parameters ("PaymentInstrument" and "PaymentInstrumentSubtype") to identify giftcard payments
- This version also contains report header parameters "DistributorReferenceId" and "MerchantReferenceId"(See section [Settlement Report with Partner Data](#report_with_partner_data))
`2020.05.06`
### New major version - v4
- Added two new report header parameters ("DistributorReferenceId" and "MerchantReferenceId") to support Partner data in the report
- See section [Settlement Report with Partner Data](#report_with_partner_data) for a full explanation of the new parameters and an example request
`2019.10.09`
The search parameters below were replaced:
- "merchant_client_id" is now "customer_id"
- "reporting_criteria" is now "submerchant_id"
### New major version - v3
- Renamed the report header parameter "PercentageOfCommission" to "FeeAmount"
- "FeeAmount" now displays the fee amount value of a transaction
`2018-04-11`
Added two new search parameters:
- customer_psc_id
- transaction_id
`2017-06-13`
Added two new options for the search parameter "transaction_type"
- Valid values are now PAYMENT, REFUND, PAYOUT
### New major version - v2
- Added two new report paramaters to accommodate refund and payout transactions: "CustomerPscId" and "OriginalTransactionID"
`2016-10-03`
- Increased the maximum allowed search for the date filter from 3 to 12 months
## Prerequisites
A connection to the API is successful if the following prerequisites are fulfilled:
- API key for request authentification provided by paysafecard per request
- 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
- The internet connection (e.g. through firewall) must allow secured HTTP connections (HTTPS)
Connect to our services only via respective FQDNs
Do not cache DNS resolutions of paysafecard FQDNs in your infrastructure (Client servers, Resolvers etc.). The DNS resolutions should expire as soon as the TTL is reached.
In case your application is based on Java, please check your TTL setup on JVM, the DNS caching behavior needs to be adjusted to:
networkaddress.cache.ttl=60 (TTL 60 seconds). Please note that, this parameter needs to be persisted in the JVM security config
If your application is based on any other framework that caches DNS resolution, please make sure to set the DNS TTL to no more than 60 seconds or rely on the TTL set by our DNS records
Honoring DNS changes will make sure that you connect always to our active system.
## 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 must to be set.
```
Authorization: Basic cHNjX2NSc09keTI2eDI1MGhPLWp4V0VpeUt2YmhudWJsNHA=
Content-Type: application/json
Accept: text/csv
```
## Endpoint
- https://api.paysafecard.com/v3/reports/
## Limits
- file download: maximum 200.000 downloadable lines
- maximum allowed search with date filter: 12 months at once
## Reconciliation
In the report, only successfully debited transactions (paysafecard and Paysafecash), payouts and refunds are listed. I.e. all transactions settled by paysafecard.
This means that the data for the present day will only be available to be retrieved via the Settlement Report API, on the next day.
In order to reconcile the invoice sent by paysafecard with the report from this Settlement Report API, just use the stated invoice number from the invoice as a search filter.
## Settlement Report [/settlement?from={from}&to={to}&mid={mid}&submerchant_id={submerchant_id}&customer_id={customer_id}&invoice_number={invoice_number}&transaction_type={transaction_type}&include_header={include_header}&customer_psc_id={customer_psc_id}&transaction_id={transaction_id}]
### Retrieve Settlement Report [GET]
+ Parameter
+ from: `2016-09-01` (string, required) - The start date of the transactions to be retrieved in the format `yyyy-mm-dd`. <br></br>
+ to: `2016-09-20` (string, required) - The end date of the transactions to be retrieved in the format `yyyy-mm-dd`. <br></br> Regardless of the date from/to, the default time values are 00:00 to 23:59. <br></br> Maximum allowed search: 12 months at once. <br></br>
+ `mid`: 1000000007 (array, optional) - The Merchant ID is the unique alphanumeric merchant identifier and defines the transaction currency. <br></br> If a MID is not specified, all transactions for all MIDs assigned to the API key in use will be retrieved.<br></br>
+ `submerchant_id`: RC1 (string, optional) - The sub merchant Id, also known as reporting criteria. If a submerchant Id is not specified, all transactions for all submerchant Ids assigned to the MID will be retrieved. <br></br>
+ `customer_id`: encryt3d3m4il (string, optional) - The customer Id is the end customer unique identifier. All transactions done by the same customer must have the same customer Id. <br></br> This parameter is provided by the business partner at the start of each transaction.<br></br>
+ `invoice_number`: INV1 (string, optional) - The invoice number is the 10-digit number of a created invoice. With this parameter, specific transactions by using an invoice number can be retrieved. <br></br> The result will display all invoice related transactions. <br></br>
+ `transaction_type`: PAYMENT (string, optional) - Only transactions of the specified type are returned. Valid values are PAYMENT, REFUND, PAYOUT. <br></br> This parameter can be used multiple times in a request to include more than one transaction type in the result and defaults to PAYMENT. <br></br>
+ `include_header`: true (boolean, optional) - If the report should include a header with the csv field names. <br></br>
+ `customer_psc_id`: 243900150947 (string, optional) - If a single my paysafecard customer needs to be searched, this parameter can be used. Only numeric values are possible. <br></br>
+ `transaction_id`: pay_1000000007_kUrTDMbIkxA6bC3PLV8r6n853IxdWs0x_EUR (string, optional) - A transaction unique identifier. If a single transaction needs to be searched, this parameter can be used. <br></br>
+ Request
+ Headers
Authorization: Basic cHNjX2NSc09keTI2eDI1MGhPLWp4V0VpeUt2YmhudWJsNHA=
Content-Type: application/json
Accept: text/csv
+ Response 200 (text/csv)
"MID","TransactionID","DebitNr","ReportingCriteria","MerchantClientID","Currency","GrossAmount","FeeAmount","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 Response CSV Header
| Parameter Name | Info | Format |
|-------------------------------|-----------------------|---------|
| `MID` | The Merchant ID is the unique alphanumeric merchant identifier and defines the transaction currency. If a mid was not specified during the API request, all transactions for all MIDs assigned to the API key in use will be shown.|default value of 10-digits |
| `TransactionID` | The Transaction ID is the transaction unique identifier. If there are any refunds related to the original payment, they will also be displayed in the results.|For transactions using the REST API, the following schemes apply: payment: pay\_MID\_corID\_CUR<br> payout: out\_MID\_corID\_CUR<br> refund: ref\_MID\_corID\_CUR |
| `DebitNr` | Parameter no longer in use. Default value always 1. |1 |
| `ReportingCriteria` | The Reporting Criteria (or submerchant Id) is an optional parameter that offers the possibility to classify transactions and differentiate between several web shops of one contracting business partner. |arbitrary - the setup of RCs must be agreed with paysafecard |
| `MerchantClientID` | The Merchant Client ID (or customer Id) is the end customer unique identifier. All transactions done by the same customer must have the same Merchant Client ID. This parameter is provided by the business partner at the start of each transaction. |arbitrary - Uniqueness mandatory|
| `Currency` | This is the Currency in which the transaction was started. |ISO 4217|
| `GrossAmount` | The Gross Amount is the full amount of the transaction. |digit representation - Ending on two decimal places|
| `FeeAmount` | The Fee Amount is the fee value deducted from the transaction.|. followed by decimal places, default value: .00000|
| `PercentageOfTax` | The Tax stands for the value charged only to EU business partners that have a contract with paysafecard and do not have a valid VAT number. |. followed by decimal places, default value:.000 |
| `DebitAmount` | The Debit Amount is the amount that was debited from the customer’s paysafecard PIN or account. |digit representation - Ending on two decimal places |
| `ExchangeRate` | The Exchange Rate parameter will be filled with a value different than 1, in the case where the business partner currency and the paysafecard PIN currency are not the same, and a conversion is needed.|depending on conversion - digit representation with decimal places |
| `InvoiceNumber` | The Invoice Number is the 10-digit number of a created invoice. The parameter values will be empty if the invoice has not yet been created.|digit representation |
| `VoucherNumber` | The Voucher Number is the number that is given to all transactions of one day, per country. |digit representation |
| `DebitTimestamp` | The Debit Timestamp is the time when the transaction was closed. |yyyy-mm-dd hh:mm:ss.ms|
| `InitialAmount` | The Initial Amount is the amount in which the transaction was created. |digit representation - Ending on two decimal places|
| `DispositionAmount` | The Disposition Amount is the amount that has not been debited yet from the transaction. Parameter no longer in use |n/a - default value: .00 |
| `NetAmount` | The Net Amount is the transaction amount after paysafecard fees have been deducted. |digit representation - Ending on five decimal places.|
| `CreationTimestamp` | The Creation Timestamp Disposition is the time when the transaction was created.|yyyy-mm-dd hh:mm:ss.ms|
| `ShopID` | The Shop ID is the parameter that identifies the web shop from which the transaction was created. This is an optional parameter and it is sent by the business partner when creating the transaction.|digit representation |
| `ClientIpCountry` | The Country IP is the country code where the paysafecard PIN was used. Note: This information is derived from our systems and although carefully provided, we do not assume any liability on the correctness of the data shared for country.|2-digit ISO 3166-1 |
| `CardOrigin` | The PIN Origin is the country code where the paysafecard PIN was sold.| 2-digit ISO 3166-1|
| `BusinessType` | The Transaction Type stands for the specific transaction type: Payment (I), Paysafecash (L), Payout (P) or Refund (R).|one letter representation |
| `CustomerPscId` | The Customer PSC ID is the my paysafecard ID of the customer. In the reports this field has a value only if the customer has used a my paysafecard account for the transaction. If the customer used a paysafecard PIN, the field values will be empty.|unique - Only my paysafecard transactions|
| `OriginalTransactionID` | The Original transaction id field is filled only when the transaction type is a Refund (R), and it represents the Transaction ID (TID) of the original payment.|see Transaction ID - Only transactions of type Refund(R)|
| `PaymentInstrument` | The payment method used. |"paysafecard", "Paysafecash", "giftcard", "pagoefectivo", "safetypay"|
| `PaymentInstrumentSubtype` | Only filled if "giftcard" or "safetypay" was used. | "cvspharmacy","dollargeneral","circlek","openbuckscard","online","cash"|
# Group Settlement Report with Partner Data
<a name="report_with_partner_data"></a>
The v4 of the API includes two new parameters ("DistributorReferenceId" and "MerchantReferenceId") to support Partner data in the report, as well as some changes to the values usually provided by the API for some parameters.
All parameter changes and the description are listed below:
| Parameter Name | Info | Format |
|-------------------------------|-----------------------|---------|
| `FeeAmount` | The Fee Amount will not be calculated in a first phase, thus this field will show "0". | digit representation - 0.0000
| `InvoiceNumber` | The Invoice Number does not apply in this case, thus it is filled with "9999999999". |digit representation - 9999999999
| `VoucherNumber` | The Voucher Number does not apply in this case, thus it is filled with "9999999999". |digit representation - 9999999999
| `NetAmount` | The Net Amount will not be calculated in a first phase, so the gross amount is displayed. |digit representation - Ending on five decimal places|
| `DistributorReferenceId` | The Distributor Reference Id shows the transaction id of the Partner system. <br> In the US this is the equivalent to the "Cashtie_Reference_Number". |digit representation - 74694276301
| `MerchantReferenceId` | Placeholder only - The Merchant Reference Id will be empty.
## Settlement Report [/settlement?from={from}&to={to}&mid={mid}&submerchant_id={submerchant_id}&include_header={include_header}]
### Retrieve Settlement Report [GET]
+ Parameter
+ from: `2020-05-06` (string, required) - The start date of the transactions to be retrieved in the format `yyyy-mm-dd`. <br></br>
+ to: `2020-12-07` (string, required) - The end date of the transactions to be retrieved in the format `yyyy-mm-dd`. <br></br> Regardless of the date from/to, the default time values are 00:00 to 23:59. <br></br> Maximum allowed search: 12 months at once. <br></br>
+ `mid`: 1000000007 (array, optional) - The Merchant ID is the unique alphanumeric merchant identifier and defines the transaction currency. <br></br> If a MID is not specified, all transactions for all MIDs assigned to the API key in use will be retrieved.<br></br>
+ `submerchant_id`: RC1 (string, optional) - The sub merchant Id, also known as reporting criteria. If a submerchant Id is not specified, all transactions for all submerchant Ids assigned to the MID will be retrieved. <br></br>
+ `include_header`: true (boolean, optional) - If the report should include a header with the csv field names. <br></br>
+ Request
+ Headers
Authorization: Basic cHNjX2NSc09keTI2eDI1MGhPLWp4V0VpeUt2YmhudWJsNHA=
Content-Type: application/json
Accept: text/csv
+ Response 200 (text/csv)
"MID","TransactionID","DebitNr","ReportingCriteria","MerchantClientID","Currency","GrossAmount","FeeAmount","PercentageOfTax","DebitAmount","ExchangeRate","InvoiceNumber","VoucherNumber","DebitTimestamp","InitialAmount","DispositionAmount","NetAmount","CreationTimestamp","ShopID","ClientIpCountry","CardOrigin","BusinessType","CustomerPscId","OriginalTransactionID","DistributorReferenceId","MerchantReferenceId"
"1000000007","pay_1000000007_fCt2qmo78RtPnsU3bdpOHgmFyCsUiaji_USD","1","RC1","cXTLq3xJEtPGlGtASumFKeUt38UfrmDB","USD","10.05",".00000",".000","10.05","1.05170","9999999999","9999999999","2020-05-05 22:10:20.019","10.05",".00","10.05000","2020-05-05 21:51:19.388","","","US","L","","","74694276301",""
# 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.|