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.
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://financehub.paybyrd.com/api/v1/SettlementFiles?createdFrom={startDateTime}&createdTo={endDateTime}
Optional query parameters: merchantId and storeId to filter results by merchant or store.
Response content structure
Each item in the response list has the following structure:
| Field | Type | Description |
|---|
| checksum | String | MD5 hash of the file contents, represented as a hexadecimal string. |
| createdAt | String (ISO 8601) | Timestamp when the file was generated. |
| groupId | Long | Customer-defined group or organization hierarchy. |
| merchantId | Long | Customer-defined merchant identifier. Optional. |
| storeId | Long | Customer-facing merchant identification number. Optional. |
| id | String (UUID) | Unique identifier of the settlement file. |
| 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.
curl --location --request GET 'https://financehub.paybyrd.com/api/v1/files?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-18T23:59:59' \
--header 'x-api-key: {your_api_key}'
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
}
]
}
// Not Found (HTTP Status Code: 404)
{
"data": {
"problemDetails": {
"type": "ApplicationNotFoundFail",
"title": "Settlement file not found with the specified period.",
"status": 404,
"instance": "not_found",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 404
}
}
Retrieving a list of settlement files (period filtering)
When filtering by period, days with no settlement file are omitted from the results.
curl --location --request GET 'https://financehub.paybyrd.com/api/v1/files?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-25T23:59:59' \
--header 'x-api-key: {your_api_key}'
// Success (HTTP Status Code: 200)
{
"data": [
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
},
{
"checksum": "ba421754061547e5d80153d3d2923be4",
"createdAt": "2026-05-26T13:11:02.390069-03:00",
"groupId": 1,
"merchantId": 1,
"id": "59188227-0811-4e30-8c57-b8dff2ab07e9",
"url": "https://financehubstoragestg.blob.core.windows.net/settlements-paybyrd/57/87/2026-05-26T16-11-00-4990180%2B0-PaybyrdSettlement.csv?sv=2025-07-05&se=2026-06-17T09%3A53%3A19Z&sr=b&sp=r&sig=MGQ7rFFMvIskJtcsefdvCh6lYnp6lqIrTbzN2n3rB48%3D"
}
]
}
// Not Found (HTTP Status Code: 404)
{
"data": {
"problemDetails": {
"type": "ApplicationNotFoundFail",
"title": "Settlement file not found with the specified period.",
"status": 404,
"instance": "not_found",
"extensions": {}
},
"contentType": "application/problem+json",
"statusCode": 404
}
}
// Bad Request (HTTP Status Code: 400)
{
"error": {
"code": "BYRD900",
"message": "Invalid settlement filter date (createdAt)."
}
}
// 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
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 |
| 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 |
| 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. Field length can vary from 16 to 19 digits (Amex cards). |
| TRANSACTION_CARD_USAGE | String(25) | Credit, Debit | The payment method of the transaction |
| 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 |
| 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 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 the POS that processed the Transaction |
