> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Settlement files (legacy)
This endpoint is deprecated. Paybyrd continues to support implementations using this endpoint for an indefinite period. However, we recommend using the [FinanceHub Settlement files](/manage-payments/settlements/settlement-files) endpoint instead.
Settlement files are CSV reports generated by Paybyrd that summarize the financial transactions included in a given settlement period. Each file records the amounts, fees, and references needed to reconcile payouts.
Settlement files serve as official records of financial transactions for a given period. They support reconciliation, compliance monitoring, and financial accountability.
You access settlement files through the Settlement API, which returns a list of files for a given time period.
## Authentication
The API authentication needs to be done with a `x-api-key` header, and it will be provided by Paybyrd.
## Retrieving the settlement file
To retrieve the list of files for a period, send a `GET` request to:
`https://settlements.paybyrd.com/api/v1/files?createdFrom={startDateTime}&createdTo={endDateTime}`
## Response content structure
Each item in the response list has the following structure:
| Field | Type | Description |
| --------- | ----------------- | ------------------------------------------------------------------- |
| groupId | String (UUID) | Customer-defined group or organization hierarchy. |
| id | String (UUID) | Unique identifier of the settlement file. |
| checksum | String | MD5 hash of the file contents, represented as a hexadecimal string. |
| createdAt | String (ISO 8601) | UTC timestamp when the file was generated. |
| url | String (URL) | URL to download the settlement file. |
## Usage recommendations
Paybyrd normally generates one file per day. However, there may be situations where more than one file is generated for the same day, in which case these files are complementary and must be fully processed to obtain all settlement information.
To receive settlements consistently on a daily basis, make requests with sequential date periods. For example, an automated system could make one request per day, using the `createdTo` value from the previous request as the `createdFrom` value for the next.
## Retrieving a list of settlement files for a specific day
To retrieve files for a specific day, set the period to cover the full day: from `00:00:00` to `23:59:59`, as shown in the example below.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/files?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-18T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "8a5d4f748b9795d4e5b562ef9ed9f12dc5c2444cb7852ce9f29b8c7a97dfa18c",
"createdAt": "2022-12-28T17:04:46Z",
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "e8be2832-83fe-46a6-88ce-eb7069305209",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-11-18T16_49_58Z_PaybyrdSettlement.csv?..."
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement file not found."
}
}
```
## Retrieving a list of settlement files (period filtering)
When filtering by period, days with no settlement file are omitted from the results. Use `from` and `to` as query parameters for period filtering.
```bash theme={null}
curl --location --request GET 'https://settlements.paybyrd.com/api/v1/files?from=2022-12-13T00:00:00&to=2022-12-16T23:59:59' \
--header 'x-api-key: '
```
```json theme={null}
// Success (HTTP Status Code: 200)
{
"data": [
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "059dc3a0-b8cb-40b3-8bbf-e76b7328e634",
"checksum": "302c4ad6e635ef0c6a289be55ba86662734c7e6fe04e48fceb4042bc1b8b702e",
"createdAt": "2022-12-13T11:23:58Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-13T11_29_58Z_PaybyrdSettlement.csv?..."
},
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "8d620102-0ff0-4f5c-aff4-44905072da2b",
"checksum": "8a5d4f748b9795d4e5b562ef9ed9f12dc5c2444cb7852ce9f29b8c7a97dfa18c",
"createdAt": "2022-12-14T17:55:10Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-14T17_55_10Z_PaybyrdSettlement.csv?..."
},
{
"groupId": "07b52763-6268-4ad5-82de-2b6db4bc0aad",
"id": "71c2088c-ad9b-4cea-abe7-1f2396f935ed",
"checksum": "604b0f937855d941df7b19ef51c42575572ead9ca2ee399eb17d2e3c1fc80bf9",
"createdAt": "2022-12-16T19:12:55Z",
"url": "https://paybyrd-settlements.blob.core.windows.net/files/07b52763-6268-4ad5-82de-2b6db4bc0aad/2022-12-16T19_12_16Z_PaybyrdSettlement.csv?..."
}
]
}
```
```json theme={null}
// Not Found (HTTP Status Code: 404)
{
"error": {
"code": "BYRD901",
"message": "Settlement files not found."
}
}
```
```json theme={null}
// Bad Request (HTTP Status Code: 400)
{
"error": {
"code": "BYRD900",
"message": "Invalid settlement filter date (createdAt)."
}
}
```
```json theme={null}
// Unexpected errors (HTTP Status Code: 500)
{
"error": {
"code": "BYRD999",
"message": "Internal server error."
}
}
```
## File specification
The file is created in CSV format using `|` (pipe) as a separator. The filename follows this pattern: `yyyy-MM-ddThh-mm-ssZ-PaybyrdSettlement.csv`
Example: `2022-11-18T16-49-58Z-PaybyrdSettlement.csv`
## Billing events
Depending on the contractual agreement, acquirers can charge billing events at the settlement. In those cases, a special line is sent in the settlement file to inform the merchant about charges made at the payout. These rows have `SETTLEMENT_TYPE` set to `"B"` and only the following fields are populated:
`PAYMENT_REFERENCE`, `GROUP_ID`, `IBAN`, `SWIFT`, `SETTLEMENT_AMOUNT`, `SETTLEMENT_TOTAL_FEE_AMOUNT` (always zero), `SETTLEMENT_CURRENCY`, `ACQUIRER_PERCENTAGE_FEE` (always zero), `ACQUIRER_FEE` (always zero), `SETTLEMENT_TYPE`, `BILLING_DESCRIPTION`
## Field specifications
| Field name | Type | Format | Description |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PAYMENT\_REFERENCE | String(12) | Alphanumeric | Unique number assigned to every "Fund Event" (ACH Payment/Withdrawal, Wire Transfer, Invoice) |
| ACQUIRER\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction in the Acquirer. |
| ACQUIRER\_UNIQUE\_TRANSACTION\_REFERENCE | String(72) | \*\*\* | The identifier of the transaction lifetime in the Acquirer. If a transaction has an event fund, this ID will always be the same as the ID of the transaction that was processed. This can be translated by the Acquirer common ID, like ARN. |
| PAYBYRD\_TRANSACTION\_REFERENCE | String(36) | \*\*\* | The identifier of the transaction at Paybyrd. |
| STORE\_LEGAL\_NAME | String(200) | \*\*\* | Doing Business As (DBA) Name |
| GROUP\_ID | Long | Numeric | Customer-defined group or organization hierarchy assigned with DBA/MID locations |
| MERCHANT\_ID | Long | Numeric | Customer-defined subgroup or organization hierarchy assigned with DBA/MID locations |
| STORE\_ID | Long | Numeric | Customer Facing Merchant Identification Number |
| ORDER\_ID | String(36) | GUID | A unique reference number generated by Paybyrd to initiate transactions by HPP |
| IBAN | String(34) | \*\*\* | International Bank Account Number of the Customer to which the Fund Event is directed |
| SWIFT | String(11) | \*\*\* | SWIFT (Society for Worldwide Interbank Financial Telecommunications) code of the bank of the Customer to which the Fund Event is directed |
| SETTLEMENT\_AMOUNT | Long | ISO amount | Transaction amount in the settlement currency |
| SETTLEMENT\_TOTAL\_FEE\_AMOUNT | Long | Precision 6 digits | Total Commission amount |
| TRANSACTION\_TYPE | Char(2) | "P" = Payment, "PA" = Pre-Auth, "R" = Refund, "A" = Adjustment, "C" = Chargeback, "CR" = Chargeback reversal | Detailed record tag identifying |
| SETTLEMENT\_CURRENCY | Char(3) | \*\*\* | The ISO currency assigned to the Fund Event |
| SETTLEMENT\_DATE | Date | yyyy-MM-dd | The calendar day the transaction was batched and electronically deposited |
| SETTLEMENT\_EXCHANGE\_RATE | Long | Precision 2 digits | Exchange Rate |
| SETTLEMENT\_PAYMENT\_DATE | Date | yyyy-MM-dd | Date the Acquirer system created and transmitted the Fund Event |
| INTERCHANGE\_AMOUNT | Long | Precision 6 digits | Interchange amount |
| TRANSACTION\_CARD\_BRAND | String(15) | Visa, Maestro, Mastercard, DinersClub, UnionPay | High-level scheme tag |
| TRANSACTION\_AUTHORIZATION\_CODE | Int | \*\*\* | The six-digit "APPROVED" reference associated with the purchase transaction |
| TRANSACTION\_CURRENCY | String(3) | \*\*\* | Cardholder Currency Code |
| TRANSACTION\_AMOUNT | Long | ISO amount | The transaction amount |
| TRANSACTION\_DATE | DateTime | yyyy-MM-dd hh:mm:ss | The calendar date time the transaction was processed in UTC |
| TRANSACTION\_CARD\_TYPE | String(20) | Consumer, Commercial | Card scheme defined type of card used in the transaction payment record |
| TRANSACTION\_MASKED\_CARD\_NUMBER | String(19) | 679128\*\*\*\*\*4259 | The masked number of the cardholder account. This field length can vary by 16 to 19 (for Amex cards). |
| TRANSACTION\_CARD\_USAGE | String(25) | Credit, Debit | The payment method of the transaction |
| ACQUIRER\_PERCENTAGE\_FEE | Long | Precision 3 digits | Acquirer fee (in %) |
| ACQUIRER\_FEE | Long | Precision 6 digits | Acquirer fee (in amount) |
| CHARGEBACK\_CONTROL\_NUMBER | String(50) | \*\*\* | The "Case ID" of the cardholder's chargeback action transaction |
| ORDER\_REF | String(100) | \*\*\* | The Order Reference |
| TICKET\_NUMBER | String(100) | \*\*\* | Flight Ticket Number |
| SCHEME\_FEES | Long | Precision 6 digits | Card scheme fees |
| TRANSACTION\_MARKET\_ID | String(36) | \*\*\* | An identification of the Market sent by the client when the Transaction is processed |
| TRANSACTION\_APPLICATION\_ID | String(36) | Alphanumeric | The application Id that generated the transaction |
| TRANSACTION\_INITIATED\_FROM | String(4) | Alphanumeric | The source font of the transaction (ECOM / POS) |
| AIRPORT\_CODE | String(3) | Alphanumeric | The Airport Code where the POS is installed |
| TRANSACTION\_POS\_SERIAL\_NUMBER | String(20) | Alphanumeric | The Serial Number of POS that processes the Transaction |
| SETTLEMENT\_TYPE | Char(1) | "T" = Transaction, "B" = Billing | Specifies the type of the settlement |
| BILLING\_DESCRIPTION | String(100) | \*\*\* | A value containing a description of the charge of the billing made at the Payout moment. This field is filled only when SETTLEMENT\_TYPE is set as "B". |