Settlement Report API
The Settlement Report includes a list of all successful settled transactions (deposits, payouts, refunds). It can be accessed in the Merchant Service Center and via the Settlement Report API.
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 for the Settlement Report API is v7. You can find details on the version in our change log. 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.
Endpoint
Settlement Report API: https://api.paysafecard.com/v7/reports/
This integration can not be tested on our test environment.
Request headers
Set the Accept header to text/csv.
Limits
- The file download has a maximum of 200.000 downloadable lines
- The maximum allowed search with date filter is 12 months
- There is a timeout of 60 seconds after which the request is aborted. If that happens, please try to reduce the time frame in the date filter.
Reconciliation
In the report, only successfully debited transactions, payouts and refunds are listed. 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, you can use the stated invoice number from the invoice as a search filter.
Settlement Report request paramater filters
You can filter the results by adding request parameters. For example, you can show only results from a specific MID with the filter mid.
| Parameter Name | Info | Format |
|---|---|---|
from | start date | String |
to | end date | String |
mid | MID | Array |
submerchant_id | Reporting Criterion (RC) reporting_criteria before v4 | String |
customer_id | Merchant Client ID (MCID) merchant_client_id before v4 | String |
invoice_number | Invoice number | String |
transaction_type | v3 Payment, Payout, Refund | String |
include_header | Should the CSV include the header line | Boolean |
customer_psc_id | v3 customer PaysafeCard account ID | String |
transaction_id | v3 Transaction ID (MTID) | String |
payment_instrument | v6 Payment instrument (paysafecard, safetypay, pagoefectivo, giftcard) | String |
transaction_reference | v7 Identification of the transaction, representing the last 16 digits of the barcode number. | String |
barcode_number | v7 Barcode number. | String |
Settlement Report response CSV headers
| Parameter Name | Info | Format (+ example) |
|---|---|---|
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 payout: out_MID_corID_CUR 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. US PaysafeCash: this will show 0 | . followed by decimal places, default value: .00000 |
TotalFeeAmount | v6 Replaces FeeAmount. | . followed by decimal places, default value: .00000 |
PercentageFeeAmount | v6 Part of the TotalFeeAmount that was calculated as percentage of the amount. | . followed by decimal places, default value: .00000 |
FixedFeeAmount | v6 Part of the TotalFeeAmount that was calculated as fixed fee. | . 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 partner currency is different than EUR and will represent the exchange rate between the former and latter. | 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. US PaysafeCash: this will show 9999999999 | digit representation |
VoucherNumber | The Voucher Number is the number that is given to all transactions of one day, per country. US PaysafeCash: this will show 9999999999 | 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. US PaysafeCash: this will show the gross amount | 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 | v2 The Customer PSC ID is the PaysafeCard account ID of the customer. In the reports this field has a value only if the customer has used a PaysafeCard account for the transaction. If the customer used a PaysafeCard PIN, the field values will be empty. | unique - Only PaysafeCard account transactions |
OriginalTransactionID | v2 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) |
DistributorReferenceId | v4 The Distributor Reference Id shows the transaction id of the Partner system. In the US this is the equivalent to the "Cashtie_Reference_Number". | digit representation - 74694276301 |
MerchantReferenceId | v4 Used for correlation ID or Openbucks reference IDs. | string |
PaymentInstrument | v5 The payment method used. | "paysafecard", "Paysafecash", "giftcard", "pagoefectivo", "safetypay" |
PaymentInstrumentSubtype | v5 Only filled if "giftcard" or "safetypay" was used. | "cvspharmacy","dollargeneral","circlek","openbuckscard","online","cash" |
BankID | v6 Only filled if the transaction was made with SafetyPay. | 4 digit code. See our bank ID list |
retailerFriendlyName | v7 US PaysafeCash Retailer brand name, serving as public alias reference for the payment points at the particular retailer | String - 7 Eleven |
retailerLocationNumber | v7 US PaysafeCash Location number of the address of the payment point | String - 19835 |
retailerAddress1 | v7 US PaysafeCash Address of the payment point | String - 16A Main street |
retailerAddress2 | v7 US PaysafeCash Additional address information for the payment point | String - Downtown |
retailerCity | v7 US PaysafeCash City of the payment point | String - Fresno |
retailerCounty | v7 US PaysafeCash County of the payment point | String - Fresno |
retailerState | v7 US PaysafeCash State of the payment point | String - CA |
retailerZipCode | v7 US PaysafeCash ZIP code of the payment point | String - 93727-3508 |
retailerCountry | v7 US PaysafeCash Country of the payment point | String - USA |
totalPaymentAmount | v7 US PaysafeCash The amount that the end-user paid at the payment point, including POS surcharge fee (if any) | String - 67.50 |
convenienceFee | v7 US PaysafeCash POS surcharge fee, convenience fee calculated on top to the disposition amount | BigDecimal - 2.50 |
billerRemittanceTotal | v7 US PaysafeCash The amount that is settled to the merchant/aggregator/integrator | BigDecimal - 64.35 |
invoiceDate | v7 US PaysafeCash Date of issuance of the invoice that is settled | Date - 2023/05/29 |
billerId | v7 US PaysafeCash Identification of the merchant/aggregator/integrator | String - 1100003062 |
billerName | v7 US PaysafeCash Name of the merchant/aggregator/integrator | String - Skrill USA Inc Wallet |
paymentNumber | v7 US PaysafeCash Identification of the settlement transfer | String - 2357534 |
paymentTime | v7 US PaysafeCash The time when the barcode was paid | yyyy-mm-dd hh:mm:ss.ms |
transactionType | v7 US PaysafeCash Type of transaction | String - Payment |
transactionRefernce | v7 US PaysafeCash Barcode number excluding EAN | Number - 639981000248297895 |
Change Log
2026.05.26
Added new open balances endpoint information.
2026.01.22
Added new report parameter "transactionType" & "transactionReference" for US PaysafeCash transactions (v7 only).
2025.03.18
Added new report parameter "paymentTime" for US PaysafeCash transactions (v7 only).
2024.08.05
Merchant reference ID is now populated by correlation ID as well.
2023.08.10
New major version - v7
- Added new report parameters "retailerFriendlyName", "retailerLocationNumber", "retailerAddress1", "retailerAddress2", "retailerCity", "retailerCounty", "retailerState", "retailerZipCode", "retailerCountry", "totalPaymentAmount", "convenienceFee", "billerRemittanceTotal", "invoiceDate", "billerId", "billerName" and "paymentNumber" for US PaysafeCash transactions.
- Added new request parameters (filters) "transaction_reference" and "barcode_number" to search for US PaysafeCash transactions.
2022.04.05
New major version - v6
- Renamed "FeeAmount" to "TotalFeeAmount"
- Added new report parameters "PercentageFeeAmount" and "FixedFeeAmount" to identify how the fees are calculated
- Added new report parameter "BankID" to further identify SafetyPay transactions
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 Settlement Report response CSV headers.
2020.05.06
New major version - v4
- Added two new report header parameters ("DistributorReferenceId" and "MerchantReferenceId") to support Partner data in the report
- See Settlement Report response CSV headers for these parameters.
2019.10.09
New major version - v3
- Renamed the report header parameter "PercentageOfCommission" to "FeeAmount"
- "FeeAmount" now displays the fee amount value of a transaction
The search parameters below were replaced:
- "merchant_client_id" is now "customer_id"
- "reporting_criteria" is now "submerchant_id"
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
2016-10-03
New major version - v2
- Increased the maximum allowed search for the date filter from 3 to 12 months
- Added two new report paramaters to accommodate refund and payout transactions: "CustomerPscId" and "OriginalTransactionID"