The Settlement API is intended to return to the consumer the list of settlement files belonging to a given period.

The "Refunds Before Clearing" file is a supplementary document to the settlement file, designed to record transactions that have been refunded before the clearing process by the acquirer. The creation of this file aims to provide more accurate control over transactions that did not incur fees or other charges due to refunding before clearing.

Authentication

The API authentication needs to be done with a x-api-key header, and it will be provided by Paybyrd.

Retrieving the refunds before clearing file

To retrieve the file list available in the period, simply execute the "GET" method to the endpoint: https://settlements.paybyrd.com/api/v1/authorization-files?createdFrom={startDateTime}&createdTo={endDateTime}.

The structure of each item of the list of archives available in the period is shown below:

Response content structure

FieldName	Type	Format	Description
GroupId	Long	Numeric	Customer-defined group or organization hierarchy assigned with DBA/MID locations
Id	String(36)	GUID	The identifier of the SettlementFile in the Paybyrd
Checksum	String	-------	A MD5 hash made using the bytes of the file. It is shown as a hexadecimal string of the resulting bytes of the hash
CreatedAt	Date	yyyy-MM-ddThh:mm:ssZ	The UTC date the File was generated
Url	String	-------	The URL to download the SettlementFil

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.

If a daily, consistent receive of all settlements is needed, is recommended to make requests in a manner that created date periods are sequential. For example, one automated system could request refunds before clearing on a daily basis making one request per day, using the "createdTo" parameter of the last request as the "createdFrom" for the actual request.

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

To retrieve the files for a specific day, you must make the request using the period for the all day, from 00:00 to 23:59, like the example below.

Curl for a specific day

curl --location --request GET 'https://settlements.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>'

Below is an example of the expected response, with two hypothetical scenarios. In the first one, a least one file exists, and in the second one doesn't exists any file:

Success Response Example

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

Fail Response Example

{
    "error": {
        "code": "BYRD901",
        "message": "Settlement file not found."
    }
}

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

For period filtering, if a file doesn't exist for one specific day, it will not be listed in the result. As in the following example, in a hypothetical scenario when the date 2022-12-15 doesn't have a file:

Curl with filter by period

curl --location --request GET 'https://settlements.paybyrd.com/api/v1/authorizations-paybyrd?from=2023-11-01T00:00:00&to=2023-11-27T23:59:59' \
--header 'x-api-key: <your_api_key>'

Below is an example of all the expected response scenarios:

Success Response Example

{
    "data": [
        {
            "checksum": "d41d8cd98f00b204e9800998ecf8427e",
            "createdAt": "2023-11-26T01:00:00Z",
            "groupId": 2678,
            "id": "6788c708-ae07-42a1-bc05-1c93903572b1",
            "url": "https://settlementv2storage.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://settlementv2storage.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://settlementv2storage.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://settlementv2storage.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://settlementv2storage.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://settlementv2storage.blob.core.windows.net/authorizations-paybyrd/2678/2023-11-24T01-00-02-0590721%2B0-PaybyrdAuthorizations.csv?..."
        }
    ],
    "code": "BYRD200"
}

Fail Response Examples

{
    "error": {
        "code": "BYRD901",
        "message": "Settlement files not found.",
    }
}

{
    "error": {
        "code": "BYRD900",
        "message": "Invalid settlement filter date (createdAt).",
    }
}

{
    "error": {
        "code": "BYRD999",
        "message": "Internal server error."
    }
}

File Specification

The file will be created in a CSV format using "|" (pipe) as a separator with a name using this pattern: yyyy-MM-ddThh-mm-ssZ-PaybyrdSettlement.csv

Example:

2022-11-18T16-49-58Z-PaybyrdSettlement.csv

Field specifications

FieldName	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" = PreAuth "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. This field length can vary by 16 to 19 (for Amex cards).
TRANSACTION_CARD_USAGE	String(25)	Credit, Debit	The payment method of 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 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 process the Transaction