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 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.

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: <your_api_key>'

// 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?..."
        }
    ]
}

// 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.

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: <your_api_key>'

// 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?..."
        }
    ]
}

// Not Found (HTTP Status Code: 404)
{
    "error": {
        "code": "BYRD901",
        "message": "Settlement files not found."
    }
}

// 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

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”.

Accept Payments

Manage Payments

Settlement files (legacy)

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

Billing events

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

​Billing events

​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

Billing events

Field specifications