Settlement files

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://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/SettlementFiles?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/SettlementFiles?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

Accept Payments

Manage Payments

Settlement files

Authentication

Retrieving the settlement file

Response content structure

Usage recommendations

Retrieving a list of settlement files for a specific day

Retrieving a list of settlement files (period filtering)

File specification

Field specifications

​Authentication

​Retrieving the settlement file

​Response content structure

​Usage recommendations

​Retrieving a list of settlement files for a specific day

​Retrieving a list of settlement files (period filtering)

​File specification

​Field specifications

Authentication

Retrieving the settlement file

Response content structure

Usage recommendations

Retrieving a list of settlement files for a specific day

Retrieving a list of settlement files (period filtering)

File specification

Field specifications