> ## Documentation Index > Fetch the complete documentation index at: https://docs.afriex.com/llms.txt > Use this file to discover all available pages before exploring further. # List Transactions > Retrieves a paginated list of transactions. Retrieve a paginated list of all transactions associated with your business. ## OpenAPI ````yaml GET /api/v1/transaction openapi: 3.1.0 info: title: Afriex Business API version: 1.0.8 description: >- Welcome to the Afriex Business API. This API allows you to manage customers, process payments, handle payouts, and receive real-time notifications via webhooks. For detailed guidance on authentication, pagination, error handling, and webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in the top bar. The guide provides a step-by-step instructions to help you integrate seamlessly. termsOfService: https://www.afriex.com/terms-and-condition contact: name: Afriex API Support email: eng@afriex.co url: https://docs.afriex.com license: name: Proprietary url: https://www.afriex.com/terms-and-condition servers: - url: https://sandbox.api.afriex.com description: Staging Base URL - url: https://api.afriex.com description: Production Base URL security: - ApiKey: [] tags: - name: Customers description: Create and manage your customers. - name: Payment Methods description: Register and resolve customer payout and collection methods. - name: Transactions description: Create and track deposits, withdrawals, and swaps. - name: Balance description: View and top up your business wallet balances. - name: Rates description: Fetch real-time exchange rates. - name: Checkout Sessions description: Create hosted checkout sessions. - name: Webhooks description: Webhook event payloads and sandbox webhook testing. - name: Media description: Generate presigned URLs for secure file uploads. paths: /api/v1/transaction: parameters: - $ref: '#/components/parameters/x-api-version' get: tags: - Transactions summary: Get transaction list description: Retrieves a paginated list of transactions. operationId: listTransactions parameters: - name: page in: query description: Zero-based page number for pagination. required: false schema: type: integer minimum: 0 default: 0 - name: limit in: query description: Number of items per page (max 100). required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - name: transactionId in: query description: >- Filter by the Afriex transaction ID (`transactionId`) returned when the transaction was created. required: false schema: type: string - name: reference in: query description: >- Filter by the merchant-supplied reference set in `meta.reference` at transaction creation. required: false schema: type: string - name: status in: query description: >- Filter by one or more transaction statuses. Use a comma-separated list for multiple values (e.g. `?status=PENDING,PROCESSING`). required: false schema: type: array items: type: string enum: - PENDING - PROCESSING - SUCCESS - FAILED - CANCELLED - REFUNDED - RETRY - UNKNOWN - SCHEDULED - CUSTOMER_ACTION_REQUIRED - REJECTED - IN_REVIEW - DISPUTED - DISPUTE_RESOLVED - DISPUTE_WON - DISPUTE_LOST - DISPUTE_EVIDENCE_SUBMITTED style: form explode: false - name: type in: query description: >- Filter by one or more transaction types. Use a comma-separated list for multiple values (e.g. `?type=DEPOSIT,WITHDRAW`). required: false schema: type: array items: type: string enum: - DEPOSIT - WITHDRAW - SWAP style: form explode: false - name: channel in: query description: >- Filter by one or more payment channels (source or destination). Use a comma-separated list for multiple values (e.g. `?channel=BANK_ACCOUNT,MOBILE_MONEY`). required: false schema: type: array items: type: string enum: - BANK_ACCOUNT - MOBILE_MONEY - CARD - CRYPTO - VIRTUAL_BANK_ACCOUNT - ACH_BANK_ACCOUNT - INTERAC - PAYBILL_TILL - RFP - UPI - VIRTUAL_CARD - SWIFT - WE_CHAT - ALIPAY - WALLET style: form explode: false - name: currency in: query description: >- Filter by one or more 3-letter ISO 4217 currency codes (source or destination). Use a comma-separated list for multiple values (e.g. `?currency=USD,NGN`). required: false schema: type: array items: type: string examples: - USD style: form explode: false - name: fromDate in: query description: >- Return only transactions created on or after this ISO 8601 date-time (e.g. `2025-01-01T00:00:00.000Z`). required: false schema: type: string format: date-time - name: toDate in: query description: >- Return only transactions created on or before this ISO 8601 date-time. Must be equal to or later than `fromDate`. required: false schema: type: string format: date-time responses: '200': description: List of transactions retrieved successfully. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Transaction' page: type: integer description: Current page number total: type: integer description: Total number of transactions matching the query examples: success: summary: Transaction list retrieved value: data: - status: SUCCESS type: SWAP channel: WALLET sourceAmount: '10' sourceCurrency: USD destinationAmount: '14101.041' destinationCurrency: NGN destinationId: '' customerId: 68e6717848e1f632e9686460 transactionId: 69d3c79531c0234586ad5ee0 meta: reference: ref-swap-minimal-002 idempotencyKey: idem-swap-minimal-002 createdAt: '2026-04-06T14:47:49.166Z' updatedAt: '2026-04-06T14:47:49.166Z' - status: PENDING type: WITHDRAW channel: BANK_ACCOUNT sourceAmount: '3.28847' sourceCurrency: USD destinationAmount: '5000' destinationCurrency: NGN destinationId: 690df3281c11eea59108fcaf customerId: 69528240ba52c13b669fb239 transactionId: 69d60071ab82306f11b03393 meta: reference: ref-withdraw-001 idempotencyKey: idem-withdraw-001 createdAt: '2026-04-08T07:14:57.444Z' updatedAt: '2026-04-08T07:14:57.444Z' total: 285 page: 0 '400': description: Invalid request parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: Validation error value: code: VALIDATION_ERROR error: 'Failed to parse request. Issues: ''page'' must be a number' details: {} '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: code: AUTHENTICATION_ERROR error: Authorization header is missing details: {} invalidApiKey: summary: Invalid API key value: code: AUTHENTICATION_ERROR error: Invalid authorization header details: {} '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serverError: summary: Unexpected server error value: code: INTERNAL_SERVER_ERROR error: It's not you, it's us, please reach out to support details: {} x-codeSamples: - lang: TypeScript label: Afriex SDK source: | const response = await afriex.transactions.list({ page: 0, limit: 20, status: ["PENDING", "PROCESSING"], currency: ["USD", "NGN"], fromDate: "2026-01-01T00:00:00.000Z", toDate: "2026-01-31T23:59:59.999Z", }); console.log(response.data); // Transaction[] components: parameters: x-api-version: name: x-api-version in: header required: false description: >- API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest stable. schema: type: string schemas: Transaction: type: object properties: transactionId: type: string description: The unique identifier for the transaction. customerId: type: string description: The unique identifier of the customer. sourceId: type: string description: The unique identifier of the source payment method. destinationId: type: string description: The unique identifier of the destination payment method. sourceAmount: type: string description: The souce transaction amount value sourceCurrency: type: string description: The currency code of the wallet charged. destinationAmount: type: string description: The destination transaction amount value destinationCurrency: type: string description: The description currency code. type: type: string enum: - DEPOSIT - WITHDRAW - SWAP description: The type of transaction. channel: type: string enum: - BANK_ACCOUNT - SWIFT - MOBILE_MONEY - UPI - INTERAC - WE_CHAT - CARD - CRYPTO - VIRTUAL_BANK_ACCOUNT - POOL_ACCOUNT - ACH_BANK_ACCOUNT - PAYBILL_TILL - RFP - VIRTUAL_CARD - ALIPAY - WALLET description: The payment channel of the transaction. status: type: string enum: - PENDING - PROCESSING - SUCCESS - FAILED - CANCELLED - REFUNDED - RETRY - UNKNOWN - SCHEDULED - CUSTOMER_ACTION_REQUIRED - REJECTED - IN_REVIEW - DISPUTED - DISPUTE_RESOLVED - DISPUTE_WON - DISPUTE_LOST - DISPUTE_EVIDENCE_SUBMITTED description: The current status of the transaction. merchantReference: type: string description: >- The merchant-supplied reference for the transaction (mirrors meta.reference from the create request). rate: type: string description: >- The realized source-to-destination exchange rate for the transaction, expressed as `1 sourceCurrency = rate destinationCurrency` (equal to destinationAmount / sourceAmount). fee: type: string description: >- The fee charged for this transaction, denominated in `sourceCurrency`. It is reported separately from `sourceAmount`. Omitted when no fee applied to the transaction. meta: type: object description: >- Transaction metadata. Echoes the metadata you attached on create and may include server-set state flags such as `otpRequired` and `failureReason`. properties: narration: type: string description: >- The narration you attached when creating the transaction, echoed back. An empty string when none was provided. otpRequired: type: boolean description: >- Returned on deposits that may need an extra authorization step. When `true`, the deposit is waiting for the customer to submit a one-time password; call `POST /transaction/{transactionId}/authorize` to complete it. failureReason: type: object description: >- Present only when `status` is `FAILED` or `REJECTED`. Carries a stable `AFX_*` code and a customer-safe message. Branch on `code` rather than the underlying rail so your integration stays stable across routing changes. required: - code - message - retryable properties: code: type: string description: >- Stable `AFX_*` failure code. Safe to switch on; the set grows over time but existing values do not change meaning. example: AFX_VELOCITY_LIMIT_EXCEEDED enum: - AFX_REQUEST_FAILED - AFX_SYSTEM_ERROR - AFX_SERVICE_UNAVAILABLE - AFX_INVALID_CURRENCY - AFX_INVALID_AMOUNT - AFX_INVALID_RECIPIENT - AFX_RECIPIENT_NOT_FOUND - AFX_BENEFICIARY_RESTRICTED - AFX_INVALID_SENDER - AFX_INVALID_REQUEST - AFX_VELOCITY_LIMIT_EXCEEDED - AFX_AMOUNT_LIMIT_EXCEEDED - AFX_PAYMENT_FAILED - AFX_COMPLIANCE_REJECTED - AFX_PROPOSAL_EXPIRED message: type: string description: >- Customer-safe short description of the failure. Suitable for display; do not parse — branch on `code` instead. retryable: type: boolean description: >- `true` when re-submitting the same request (or, for `AFX_PROPOSAL_EXPIRED`, starting a fresh proposal) may succeed. `false` when the caller must change the request before retrying. additionalProperties: true createdAt: type: string description: The date and time the transaction was created. updatedAt: type: string description: The date and time the transaction was last updated. ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. error: type: string description: Human-readable error message. details: $ref: '#/components/schemas/ErrorDetails' ErrorDetails: type: object properties: errorMessage: type: string description: Detailed/technical error message. friendlyMessage: type: string description: User-facing error message safe to display. data: type: object description: >- Optional caller-safe context for the error. On a customer-create uniqueness conflict (EMAIL_ALREADY_EXISTS / PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's id, so you can adopt it without a follow-up lookup. properties: customerId: type: string description: Id of the existing customer (on a create conflict). securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: >- Static business API key issued from the dashboard. A business can provision **multiple API keys**, each scoped to a configurable set of **permissions** (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Requests made with a key that does not include the permission required by the target endpoint will be rejected with a `403 Forbidden` response; an unrecognised, malformed or revoked key returns `401 Unauthorized`. Manage your keys and their permissions under **Developer → API keys** in the dashboard. ````