> ## Documentation Index > Fetch the complete documentation index at: https://developers.stablepay.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Payments > Returns a list of payments. ## OpenAPI ````yaml GET /v1/payments openapi: 3.0.3 info: title: Stablepay Money API description: > The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank transfers. version: 0.5.0 contact: name: Stablepay Engineering email: hello@stablepay.io servers: - url: https://api.stablepay.ai description: Production security: - BearerAuth: [] tags: - name: Health description: Service liveness check. - name: FX description: Live FX rate conversion between USDC and local fiat currencies. - name: Payments description: Submit and track stablecoin-to-fiat payout requests. - name: Balances description: >- Live on-chain USDC and native token balances for the tenant's custody wallets. - name: Analytics description: >- Pre-aggregated payment analytics — volume, success rates, corridor breakdowns, and daily time series. - name: Reversals description: Reversals of succeeded payouts. - name: Customers description: | KYC API for DeFi wallets. Onboard and verify your end-users, then link their wallet addresses so verified identity travels with their on-chain activity. - name: Webhooks description: Register endpoints and manage outbound event delivery. - name: Admin description: >- Ops-only endpoints for tenant management and payment operations. Requires an admin-scoped API key. paths: /v1/payments: get: tags: - Payments summary: List payments description: | Returns a list of payments. operationId: listPayments parameters: - name: from in: query required: false schema: type: string description: | Only payments created at or after this time. example: '2026-10-11' - name: to in: query required: false schema: type: string description: | Only payments created before this time. example: '2026-10-12' - name: limit in: query required: false schema: type: integer default: 20 maximum: 100 description: Number of payments to return. example: 20 - name: offset in: query required: false schema: type: integer default: 0 description: Number of payments to skip. example: 0 - name: reference in: query required: false schema: type: string description: Exact match on your own reference. example: issuer_payment_001 - name: direction in: query required: false schema: type: string enum: - money_in - money_out description: Filter by payment direction. example: money_out responses: '200': description: Paginated list of payments. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/PaymentResponse' total: type: integer description: >- Total payments matching the filters, ignoring limit and offset. example: 42 limit: type: integer description: Limit applied to this response. example: 20 offset: type: integer description: Offset applied to this response. example: 0 required: - data - total - limit - offset example: data: - id: ABC_NG01M2IEFDNF4INFQD41O3R status: succeeded direction: money_out paymentMethod: BANK sourceCurrency: USDC amountStablecoin: '0.787' fiatAmount: '1000' destinationCurrency: NGN providerRef: AbCd2fv3ovnefe2 reference: issuer_payment_001 errorCode: null failureReason: null customerMessage: null depositInstruction: null redirectUrl: null paymentCode: BANK createdAt: '2026-05-06T10:31:00.000Z' updatedAt: '2026-05-06T10:31:45.000Z' total: 42 limit: 20 offset: 0 '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: > Validation error — direction is not money_in or money_out, from or to is not a valid ISO 8601 date, or from is not earlier than to. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: direction: summary: Unknown direction value: statusCode: 422 message: >- direction must be 'money_in' or 'money_out'. Received: outbound badDate: summary: Malformed from or to value: statusCode: 422 message: >- from must be an ISO 8601 date (2026-10-11) or date-time with offset (2026-10-11T00:00:00Z). Received: 11-10-2026 range: summary: from is not earlier than to value: statusCode: 422 message: from must be earlier than to. components: schemas: PaymentResponse: type: object properties: id: type: string description: Prefixed ULID for this payment. example: pay_01HV8KZMRJPQR9S7T3XABCDEF status: $ref: '#/components/schemas/PaymentStatus' direction: $ref: '#/components/schemas/Direction' paymentMethod: $ref: '#/components/schemas/PaymentMethod' sourceCurrency: $ref: '#/components/schemas/CurrencyIn' amountStablecoin: type: string description: Total stablecoin amount charged. example: '10.500' fiatAmount: type: string description: Fiat amount the recipient receives. example: '1350' destinationCurrency: $ref: '#/components/schemas/CurrencyOut' providerRef: type: string nullable: true description: Provider's transaction ID. Null until the provider accepts. example: CC4SOjQu8UUarKaOGZy9 reference: type: string nullable: true description: >- Caller's own reference code (e.g. "csh-txn-20260506-001"). Stored as supplied in the payment request. example: csh-txn-20260506-001 errorCode: type: string nullable: true description: >- Machine-readable failure code (e.g. `insufficient_funds` or `invalid_account`). Null unless `status` is `failed`. example: null failureReason: type: string nullable: true description: >- Human-readable description of why the payment failed. Null unless `status` is `failed`. example: null customerMessage: type: string nullable: true description: Human-readable status message safe to surface to the end customer. example: null depositInstruction: allOf: - $ref: '#/components/schemas/DepositInstruction' nullable: true description: | Money-in only. Bank account the customer must transfer fiat into to complete a bank payin. redirectUrl: type: string nullable: true description: > Hosted checkout URL the customer must be redirected to complete the payment. Present for payment methods that require a redirect (e.g. OPAY deeplink payins); null otherwise. example: null paymentCode: type: string nullable: true description: The paymentCode supplied on the request, echoed back. example: null createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - status - direction - paymentMethod - sourceCurrency - amountStablecoin - fiatAmount - destinationCurrency - providerRef - reference - errorCode - failureReason - customerMessage - redirectUrl - paymentCode - createdAt - updatedAt ErrorResponse: type: object properties: statusCode: type: integer example: 400 code: type: string description: Machine-readable error code. example: validation_error message: type: string description: Human-readable error message. example: fiatAmount must be a positive number. required: - statusCode - message PaymentStatus: type: string description: | Current state of the payment in the state machine. `initiated` → `provider_accepted` → `succeeded` | `failed` | `refunded` Direction: type: string enum: - money_in - money_out description: | money_out: issuer sends stablecoin → recipient receives fiat. money_in: customer pays fiat → issuer receives stablecoin. PaymentMethod: type: string enum: - BANK - MOMO - PAYBILL - TILL description: The supported payment method used to deliver funds to the recipient. CurrencyIn: type: string enum: - USDC - USDT description: Stablecoin sent onchain for payment settlement. CurrencyOut: type: string enum: - CDF - GHS - KES - NGN - TZS - UGX - XAF - XOF - ZAR - ZMW description: Fiat currency received by the recipient. DepositInstruction: type: object description: | Bank details the customer must transfer fiat into to complete a bank money-in. properties: type: type: string enum: - fiat example: fiat bankName: type: string example: Access Bank bankCode: type: string nullable: true example: '000014' accountName: type: string example: Stablepay Defi accountNumber: type: string example: '0123456789' expiresAt: type: string format: date-time nullable: true description: >- After this time the deposit account expires and the payment must be re-initiated. reference: type: string nullable: true example: csh-txn-20260506-001 required: - type - bankName - accountName - accountNumber securitySchemes: BearerAuth: type: http scheme: bearer description: | Stablepay API key. Include as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.