Refunds before clearing files

The Settlement API returns the list of settlement files for a given period. The Refunds Before Clearing file supplements the settlement file. It records transactions refunded before the acquirer’s clearing process — transactions that did not incur fees or other charges.

Authentication

Authenticate requests using an x-api-key header. You can find your API key in the Developer Keys page of the dashboard.

Retrieving the refunds before clearing file

To retrieve the list of files for a period, send a GET request to: https://financehub.paybyrd.com/api/v1/authorization-files?createdFrom={startDateTime}&createdTo={endDateTime} Optional query parameters: merchantId and storeId to filter results by merchant or store.

Response content 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 file.
url	String (URL)	URL to download the 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 refunds before clearing information. To receive all settlements consistently each day, 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 refunds before clearing files for a specific day

To retrieve files for a specific day, set the period from 00:00 to 23:59, as in the example below.

curl --location --request GET 'https://financehub.paybyrd.com/api/v1/authorization-files?createdFrom=2023-11-27T00:00:00&createdTo=2023-11-27T23:59:59' \
--header 'x-api-key: {your_api_key}'

// Success (HTTP Status Code: 200)
{
    "data": [
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-27T01:00:00Z",
            "groupId": 2678,
            "id": "34a815e7-40b3-4936-b689-70984ec7ad4e",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-27T01-00-00-8192727%2B0-PaybyrdAuthorizations.csv?..."
        }
    ]
}

// 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 refunds before clearing files (period filtering)

When filtering by period, days with no file are omitted from the results.

curl --location --request GET 'https://financehub.paybyrd.com/api/v1/authorization-files?createdFrom=2023-11-01T00:00:00&createdTo=2023-11-27T23:59:59' \
--header 'x-api-key: {your_api_key}'

// Success (HTTP Status Code: 200)
{
    "data": [
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-26T01:00:00Z",
            "groupId": 2678,
            "id": "6788c708-ae07-42a1-bc05-1c93903572b1",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-26T01-00-00-8689833%2B0-PaybyrdAuthorizations.csv?..."
        },
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-25T01:00:01Z",
            "groupId": 2678,
            "id": "dda7a84c-fc2f-4150-a5f1-3810d0e20154",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-25T01-00-01-1366726%2B0-PaybyrdAuthorizations.csv?..."
        },
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-22T01:00:04Z",
            "groupId": 2678,
            "id": "9fae07f8-55cd-4df7-99a7-664c7e35f82a",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-22T01-00-04-5510526%2B0-PaybyrdAuthorizations.csv?..."
        },
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-27T01:00:00Z",
            "groupId": 2678,
            "id": "34a815e7-40b3-4936-b689-70984ec7ad4e",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-27T01-00-00-8192727%2B0-PaybyrdAuthorizations.csv?..."
        },
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-23T01:00:00Z",
            "groupId": 2678,
            "id": "234ba4fb-1dca-49de-983e-e99c5504fd3b",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-23T01-00-00-7690997%2B0-PaybyrdAuthorizations.csv?..."
        },
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-24T01:00:02Z",
            "groupId": 2678,
            "id": "54cf4233-5e9d-4f73-ae4f-fd05084919f0",
            "url": "https://financehubstoragestg.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-24T01-00-02-0590721%2B0-PaybyrdAuthorizations.csv?..."
        }
    ]
}

// 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
ACQUIRER_TRANSACTION_REFERENCE	String(72)	***	The identifier of the transaction in the Acquirer
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
TRANSACTION_TYPE	Char(1)	“P” = Payment; “PA” = Pre-Auth; “R” = Refund	Detailed record tag identifying
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
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

​Authentication

​Retrieving the refunds before clearing file

​Response content structure

​Usage recommendations

​Retrieving a list of refunds before clearing files for a specific day

​Retrieving a list of refunds before clearing files (period filtering)

​File specification

​Field specifications