Settlement files are essential documentation that formalizes agreements and resolutions between disputing parties, serving as comprehensive records of the terms, conditions, and details negotiated. These files play a crucial role in legal recordkeeping, providing a clear reference point for enforcing agreements and preventing future disputes. They outline financial considerations, such as compensation and payment details, contributing to transparency and financial accountability. Settlement files are vital in dispute resolution, helping bring closure by encapsulating the final agreed-upon terms, and they serve as tools for compliance and performance monitoring. Additionally, these files may include clauses on confidentiality and non-disclosure, further solidifying the understanding between parties and facilitating a positive and constructive resolution process.

At Paybyrd, these files are made available through the Settlement API whose objective is to return to the consumer the list of settlement files belonging to a given 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 file list available in the period, simply execute the "GET" method to the endpoint: https://settlements.paybyrd.com/api/v1/files?createdFrom={startDateTime}&createdTo={endDateTime}.

Response content structure

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

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.

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 settlements 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 settlement 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/files?createdFrom=2022-11-18T00:00:00&createdTo=2022-11-18T23: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": "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?..."  
        }  
    ]  
}

Fail Response Example

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

Retrieving a list of settlement 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/files?from=2022-12-13T00:00:00&to=2022-12-16T23:59:59' \
--header 'x-api-key: <your_api_key>'

Below is an example of all the expected response scenarios:

Success Response Example

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

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

Billing events

Depending on the contractual agreement, Acquirers can charge billing events at the settlement. In those cases, a special line will be sent in the settlement file to inform the Merchant about charges being made at the Payout. Those charges are shown as Billing events. The field SETTLEMENT_TYPE will have its value set as "B", and none of the transaction fields will have any value, as this event is a direct charge made at the Payout moment. The field BILLING_DESCRIPTION will have a text explaining the type of the charge made.

Below are a list of the fields that should have a value in billing events. All the remaining fields should be empty.

• PAYMENT_REFERENCE
• GROUP_ID
• IBAN
• SWIFT
• SETTLEMENT_AMOUNT
• SETTLEMENT_TOTAL_FEE_AMOUNT (in this case, should always be zero)
• SETTLEMENT_CURRENCY
• ACQUIRER_PERCENTAGE_FEE (in this case, should always be zero)
• ACQUIRER_FEE (in this case, should always be zero)
• SETTLEMENT_TYPE (in this case, should be "B")
• BILLING_DESCRIPTION

Field specifications