{ "openapi": "3.0.0", "info": { "title": "x-gateway-external-api", "contact": {} }, "servers": [ { "url": "https://api.xgateway.tech/api/v2" } ], "paths": { "/transactions/export": { "post": { "operationId": "ExportTransactionsAsync", "responses": { "200": { "description": "CSV file exported successfully" } }, "description": "Exports transactions to CSV format based on provided filters.\r\n\r\nThis endpoint generates a CSV export of transactions with the following logic:\r\n- **Increment**: Transactions where both created_at AND updated_at fall within the specified period\r\n- **Carry-over**: Transactions where created_at < period_start AND updated_at falls within the period.\r\n\r\nThe export is limited to 50,000 records to ensure optimal performance.\r\n\r\nThis endpoint allows filtering transactions with various filters including:\r\n- Transaction ID - UUID of the transaction.\r\n- Order ID - Merchant's order identifier.\r\n- Transaction hashes - Array of blockchain transaction hashes.\r\n- Customer IDs - Array of customer IDs (UUIDs) for filtering (not included in export).\r\n- Date ranges - ISO 8601 datetime format (e.g., '2024-01-01T00:00:00.000Z').\r\n- Networks - Blockchain networks (ethereum, bitcoin, tron, polygon, bnb_smart_chain, solana, bahamut).\r\n- Accounts - List of account IDs (UUIDs).\r\n- Statuses - Transaction statuses (confirmed, created, failed, misdirected, on_hold_review, processing, automatically_approved, automatically_rejected, manually_approved, manually_rejected).\r\n- Transaction types - Types of transactions (deposit, withdrawal, correction_up, correction_down, merchant_deposit, settlement).\r\n\r\nThe CSV includes the following fields:\r\n- id, order_id, created_at, updated_at\r\n- type, status, merchant_id, invoice_id, account_id\r\n- amount_original_currency, original_currency\r\n- transaction_amount, transaction_currency\r\n- rolling_reserve, rolling_reserve_unlock_date\r\n- processing_fee, technical_fee\r\n- balance_before, balance_after, balance_currency.\r\n\r\nAll amount fields are exported as strings with a prefix (') to preserve precision in Excel/CSV viewers.\r\n\r\nAll date/time parameters must be in ISO 8601 format with timezone. Examples:\r\n- UTC: '2024-01-01T00:00:00.000Z' or '2024-01-01T00:00:00Z'\r\n- Dubai time (UTC+4): '2024-01-01T04:00:00+04:00'\r\n- New York time (UTC-5): '2024-01-01T07:00:00-05:00'.\r\n\r\nInput dates with any timezone are properly handled - they are converted to UTC for database queries.\r\nThe dates in the CSV export will be converted to the timezone specified in the 'tz' parameter.\r\n\r\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header.", "tags": [ "Transactions" ], "security": [ { "api_key": [] } ], "parameters": [ { "description": "IANA timezone identifier for date formatting in the export.\r\nAll dates in the CSV will be converted to this timezone.\n- Timezone for date conversion in the export. Accepts IANA timezone identifiers.", "in": "query", "name": "tz", "required": false, "schema": { "default": "UTC", "type": "string" } } ], "requestBody": { "description": "Export filters for transactions.\n- The export filters including required date range.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionExportBody", "description": "Export filters for transactions.\n- The export filters including required date range." } } } } } } }, "components": { "schemas": { "Network": { "type": "string", "enum": [ "bahamut", "bitcoin", "bnb_smart_chain", "ethereum", "polygon", "solana", "tron" ], "description": "Represents supported cryptocurrency networks in the payment processing system.\r\n\r\nUsed to specify which blockchain network a cryptocurrency transaction relates to.\r\n\r\nEach network supports its own native cryptocurrency (e.g. BTC, ETH, TRX).\r\n\r\nTransactions must be processed differently based on network since each cryptocurrency functions\r\nindependently. Records of transactions and account balances are also maintained separately by\r\nnetwork." }, "AllowedNetwork": { "$ref": "#/components/schemas/Network", "description": "Type representing allowed network values." }, "NewTransactionStatus": { "description": "Enum representing the statuses of a transaction during its lifecycle.\r\nProvides clear indications of the state of a transaction, helping to track\r\nand manage its progress or resolution.", "enum": [ "CONFIRMED", "CREATED", "FAILED", "PROCESSING", "HOLD" ], "type": "string" }, "SearchableTransactionStatus": { "$ref": "#/components/schemas/NewTransactionStatus" }, "TransactionType.Chargeback": { "enum": [ "chargeback" ], "type": "string" }, "TransactionType.CorrectionDown": { "enum": [ "correction_down" ], "type": "string" }, "TransactionType.CorrectionUp": { "enum": [ "correction_up" ], "type": "string" }, "TransactionType.Deposit": { "enum": [ "deposit" ], "type": "string" }, "TransactionType.MerchantDeposit": { "enum": [ "merchant_deposit" ], "type": "string" }, "TransactionType.Settlement": { "enum": [ "settlement" ], "type": "string" }, "TransactionType.Withdrawal": { "enum": [ "withdrawal" ], "type": "string" }, "SearchableTransactionType": { "anyOf": [ { "$ref": "#/components/schemas/TransactionType.Chargeback" }, { "$ref": "#/components/schemas/TransactionType.CorrectionDown" }, { "$ref": "#/components/schemas/TransactionType.CorrectionUp" }, { "$ref": "#/components/schemas/TransactionType.Deposit" }, { "$ref": "#/components/schemas/TransactionType.MerchantDeposit" }, { "$ref": "#/components/schemas/TransactionType.Settlement" }, { "$ref": "#/components/schemas/TransactionType.Withdrawal" } ] }, "TransactionExportBody": { "description": "TSOA-compatible interface for the export request body.\r\nExtends the service layer's filter interface to maintain consistency.", "properties": { "transactionIds": { "items": { "type": "string" }, "type": "array", "description": "Filter by transaction UUIDs.", "example": [ "550e8400-e29b-41d4-a716-446655440000", "123e4567-e89b-12d3-a456-426655440000" ] }, "orderIds": { "items": { "type": "string" }, "type": "array", "description": "Filter by merchant's order IDs.", "example": [ "ORDER-123456", "ORDER-789012" ] }, "hashes": { "items": { "type": "string" }, "type": "array", "description": "Filter by blockchain transaction hashes.", "example": [ "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] }, "blockHashes": { "items": { "type": "string" }, "type": "array", "description": "Filter by blockchain block hashes.", "example": [ "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" ] }, "recipients": { "items": { "type": "string" }, "type": "array", "description": "Filter by transaction recipients.", "example": [ "0x1234567890123456789012345678901234567890", "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" ] }, "customerIds": { "items": { "type": "string" }, "type": "array", "description": "Filter by customer IDs (must be valid UUIDs).", "example": [ "550e8400-e29b-41d4-a716-446655440000", "123e4567-e89b-12d3-a456-426655440000" ] }, "fromUpdatedAt": { "type": "string", "description": "REQUIRED: Start date/time for filtering by the updated_at field.\r\nMust be in ISO 8601 format with timezone.\r\nThe timezone in the input is properly handled - all dates are converted to UTC for database queries.", "example": "2024-01-01T00:00:00.000Z" }, "toUpdatedAt": { "type": "string", "description": "REQUIRED: End date/time for filtering by the updated_at field.\r\nMust be in ISO 8601 format with timezone.\r\nThe timezone in the input is properly handled - all dates are converted to UTC for database queries.", "example": "2024-12-31T23:59:59.999Z" }, "networks": { "items": { "$ref": "#/components/schemas/AllowedNetwork" }, "type": "array", "description": "Filter by blockchain networks.\r\nAllowed values: ethereum, bitcoin, tron, polygon, bnb_smart_chain, solana, bahamut.", "example": [ "ethereum", "polygon" ] }, "accounts": { "items": { "type": "string" }, "type": "array", "description": "Filter by account IDs (must be valid UUIDs).", "example": [ "550e8400-e29b-41d4-a716-446655440000", "123e4567-e89b-12d3-a456-426655440000" ] }, "statuses": { "items": { "$ref": "#/components/schemas/SearchableTransactionStatus" }, "type": "array", "description": "Filter by transaction statuses.\r\nAllowed values: confirmed, created, failed, misdirected, on_hold_review, processing, automatically_approved, automatically_rejected, manually_approved, manually_rejected.", "example": [ "confirmed", "failed" ] }, "transactionTypes": { "items": { "$ref": "#/components/schemas/SearchableTransactionType" }, "type": "array", "description": "Filter by transaction types.\r\nAllowed values: deposit, withdrawal, correction_up, correction_down, merchant_deposit, settlement.", "example": [ "deposit", "withdrawal" ] } }, "required": [ "fromUpdatedAt", "toUpdatedAt" ], "type": "object", "additionalProperties": false } }, "securitySchemes": { "api_key": { "in": "header", "name": "x-api-key", "type": "apiKey" } } } }