> ## Documentation Index > Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://beta.paybyrd.com/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. ```bash theme={null} 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}' ``` ```json theme={null} // 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?..." } ] } ``` ```json theme={null} // 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. ```bash theme={null} 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}' ``` ```json theme={null} // 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?..." } ] } ``` ```json theme={null} // 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 } } ``` ```json theme={null} // Bad Request (HTTP Status Code: 400) { "error": { "code": "BYRD900", "message": "Invalid settlement filter date (createdAt)." } } ``` ```json theme={null} // 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 |