> ## Documentation Index > Fetch the complete documentation index at: https://docs.paycrest.io/llms.txt > Use this file to discover all available pages before exploring further. # List Orders ## OpenAPI ````yaml openapi-v2.yaml GET /sender/orders openapi: 3.0.3 info: title: Paycrest Aggregator API version: 1.0.0 description: > OpenAPI schema for the Paycrest Aggregator API. This covers sender, provider, and general endpoints. servers: - url: https://api.paycrest.io/v2 security: [] tags: - name: Sender description: Endpoints for senders to create and manage payment orders - name: Provider description: Endpoints for providers to manage and fulfill orders - name: General description: General protocol and utility endpoints paths: /sender/orders: get: tags: - Sender summary: List v2 payment orders parameters: - in: query name: page schema: type: integer default: 1 - in: query name: pageSize schema: type: integer default: 10 - in: query name: status schema: type: string enum: - initiated - deposited - pending - fulfilling - fulfilled - validated - settling - settled - cancelled - refunding - refunded - expired - $ref: '#/components/parameters/OptionalOrderDirection' responses: '200': description: List of orders content: application/json: schema: type: object properties: status: type: string data: $ref: '#/components/schemas/V2PaymentOrderListResponse' '401': description: Unauthorized security: - ApiKeyAuth: [] servers: - url: https://api.paycrest.io/v2 components: parameters: OptionalOrderDirection: name: direction in: query required: false schema: type: string enum: - onramp - offramp description: > Filter to **onramp** (fiat → crypto) or **offramp** (crypto → fiat). Omit to include **both** directions. On **stats** endpoints, invalid values return **400 Bad Request**. On **list** endpoints, values other than `onramp` or `offramp` are ignored (no direction filter). **HMAC (GET):** the signed payload includes all query parameters—include `direction` when you send it (alongside `timestamp`, `currency`, etc.). schemas: V2PaymentOrderListResponse: type: object properties: total: type: integer page: type: integer pageSize: type: integer orders: type: array items: $ref: '#/components/schemas/V2PaymentOrderGetResponse' V2PaymentOrderGetResponse: type: object description: Response for a single order (or list item) properties: id: type: string format: uuid status: type: string enum: - initiated - deposited - pending - fulfilling - fulfilled - validated - settling - settled - cancelled - refunding - refunded - expired orderType: type: string enum: - regular direction: type: string enum: - offramp - onramp createdAt: type: string format: date-time updatedAt: type: string format: date-time amount: type: string amountInUsd: type: string amountPaid: type: string amountReturned: type: string percentSettled: type: string rate: type: string senderFee: type: string senderFeePercent: type: string transactionFee: type: string reference: type: string txHash: type: string providerAccount: oneOf: - $ref: '#/components/schemas/V2CryptoProviderAccount' - $ref: '#/components/schemas/V2FiatProviderAccount' source: oneOf: - $ref: '#/components/schemas/V2CryptoSource' - $ref: '#/components/schemas/V2FiatSource' destination: oneOf: - $ref: '#/components/schemas/V2FiatDestination' - $ref: '#/components/schemas/V2CryptoDestination' statusDetail: type: string enum: - under_review description: >- On-ramp only. `under_review` while the order is `pending` because its deposit is held for compliance review. Absent otherwise. refundReason: type: string enum: - payer_mismatch - payer_unverified description: >- On-ramp only, on `refunding` and `refunded` orders whose deposit was returned to the account it came from. `payer_mismatch`, the deposit came from an account not in the customer's name; `payer_unverified`, the payer could not be confirmed. Absent for any other refund. V2CryptoProviderAccount: type: object description: Returned for offramp orders — where to send the stablecoins. properties: network: type: string description: Network to send the stablecoins on receiveAddress: type: string description: Address on `network` to send the stablecoins to validUntil: type: string format: date-time description: Deadline for the stablecoin deposit amountToTransfer: type: string description: >- The exact amount of `currency` to send — `amount + senderFee + transactionFee`. When the sender pays the transaction fee, this is `amount + max(configured fee, transactionFee)`. currency: type: string description: Token symbol to send (e.g. USDC). memo: type: string description: >- Present only when the deposit must include it. Send it with the deposit, or the deposit cannot be credited. V2FiatProviderAccount: type: object description: Returned for onramp orders — the virtual account to deposit fiat into properties: institution: type: string description: >- Institution label for the virtual account (human-readable; from provider or stored metadata). accountIdentifier: type: string description: Account number or mobile number to send fiat to accountName: type: string amountToTransfer: type: string description: >- Exact fiat amount the user must deposit. It covers the crypto amount, the sender fee and the transaction fee at the order's rate. currency: type: string description: Fiat currency code validUntil: type: string format: date-time description: Deadline — order expires if fiat not received by this time V2CryptoSource: type: object required: - type - currency - network - refundAddress properties: type: type: string enum: - crypto currency: type: string description: Stablecoin symbol (e.g. USDT, USDC, cNGN) network: type: string enum: - ethereum - base - bnb-smart-chain - lisk - celo - arbitrum-one - polygon - starknet - tron - solana description: Network the deposit is made on. refundAddress: type: string description: >- Wallet address on `network` for refunds if the order can't be fulfilled (e.g. a Solana address when `network` is `solana`). kyc: writeOnly: true description: Optional. The customer sending the stablecoin on off-ramp. allOf: - $ref: '#/components/schemas/KYCDetail' V2FiatSource: type: object required: - type - currency - refundAccount - kyc properties: type: type: string enum: - fiat currency: type: string description: Fiat currency code (e.g. NGN, KES, TZS) country: type: string description: ISO 3166-1 alpha-2 country code (optional) refundAccount: $ref: '#/components/schemas/V2FiatRefundAccount' kyc: writeOnly: true description: > The customer paying in. **Required on on-ramp.** On top of the shared `KYCDetail` shape, an on-ramp requires: - **person:** `personDetails.fullName`, `birthDate` (18 or over) and `idDocument` (`type`, `number`, `issuerCountry`). NGN: the `idDocument` must be the BVN (`type: "BVN"`, 11 digits, issuer `NG`), which needs no other document, or the NIN (`nationalID`, 11 digits, issuer `NG`). KES: `contact.phoneE164` must be a Kenyan mobile number. - **organization:** `organizationDetails.legalName`, `registrationNumber`, `registrationCountry`, and at least one director whose `personDetails` meets the person rules. KES: the organization's `contact.phoneE164` must be a Kenyan mobile number. Missing or malformed fields return **400** with `field: "Source"` and a message listing every problem by path. Where the bank resolves the refund account holder's name (NGN), it must match `personDetails.fullName` (or the organization's `legalName` / `tradingName`); a mismatch returns **400**. allOf: - $ref: '#/components/schemas/KYCDetail' V2FiatDestination: type: object required: - type - currency - recipient properties: type: type: string enum: - fiat currency: type: string description: Fiat currency code (e.g. NGN, KES) country: type: string description: ISO 3166-1 alpha-2 country code (optional) providerId: type: string description: > Pin order to a single provider (optional). Retained for backward compatibility — prefer `providerIds`, which expresses the same thing as a one-entry queue. providerIds: type: array writeOnly: true maxItems: 3 items: type: string pattern: ^[A-Za-z]{8}$ description: > Optional ordered provider queue (max 3). Assignment tries entries in order, moving to the next when one declines, expires, or exhausts its retries. Typically the `providerIds` from a [rate quote](/api-reference/general/get-token-rate). Mutually exclusive with `providerId` — sending both returns **400**. A one-entry queue is exactly a single-provider pin, so `providerIds: [X]` routes like `providerId: X` for every provider you can pin. Multi-entry queues must name providers that can serve this corridor: active, with a live standard offer, and — for a provider restricted to specific senders — one whose list includes you. The fallback provider may be listed but is ignored; it is already tried after the queue is exhausted. Accepted on create only; order responses and webhooks return the singular assigned `providerId`. kyc: description: >- Optional destination (recipient) KYC for offramp. Do not send sender or provider KYB on offramp create. allOf: - $ref: '#/components/schemas/KYCDetail' recipient: $ref: '#/components/schemas/V2FiatRecipient' V2CryptoDestination: type: object required: - type - currency - recipient properties: type: type: string enum: - crypto currency: type: string description: Stablecoin symbol (e.g. USDT, USDC) providerId: type: string description: > Pin order to a single provider (optional). Retained for backward compatibility — prefer `providerIds`. providerIds: type: array writeOnly: true maxItems: 1 items: type: string pattern: ^[A-Za-z]{8}$ description: > Optional provider pin in queue form, for parity with offramp. Onramp selects its provider when the order is created rather than walking a queue, so **at most one entry** is accepted — more returns **400**. Mutually exclusive with `providerId`. The provider must be one you can route to: pinning a provider restricted to other senders returns **400**. Accepted on create only; order responses and webhooks return the singular assigned `providerId`. kyc: writeOnly: true description: Optional. The recipient of the stablecoin on on-ramp. allOf: - $ref: '#/components/schemas/KYCDetail' recipient: $ref: '#/components/schemas/V2CryptoRecipient' KYCDetail: type: object description: > Identity of a party to an order, accepted on both sides of both directions: | Field | Direction | Who | Required | |-------|-----------|-----|----------| | `source.kyc` | on-ramp | Customer paying in fiat | Yes (see `V2FiatSource.kyc`) | | `destination.kyc` | on-ramp | Recipient of the stablecoin | No | | `source.kyc` | off-ramp | Customer sending the stablecoin | No | | `destination.kyc` | off-ramp | Recipient of the fiat payout | No | Which fields are required depends on where it is sent; only on-ramp `source.kyc` has required fields. properties: entityType: type: string enum: - person - organization personDetails: $ref: '#/components/schemas/KYCPersonDetails' organizationDetails: $ref: '#/components/schemas/KYCOrganizationDetails' principalAddress: $ref: '#/components/schemas/KYCPrincipalAddress' V2FiatRefundAccount: type: object required: - institution - accountIdentifier - accountName properties: institution: type: string description: >- Bank or mobile provider code (SWIFT prefix or Paycrest institution code) institutionName: type: string description: >- Human-readable institution name (e.g. OPay). Present on GET responses when the code resolves in Paycrest. accountIdentifier: type: string description: Account number or mobile number accountName: type: string description: Account holder name V2FiatRecipient: type: object required: - institution - accountIdentifier - accountName - memo properties: institution: type: string description: >- Institution code (e.g. SAFAKEPC for Safaricom M-Pesa). Till and Paybill use the same mobile institution with channel metadata. institutionName: type: string description: >- Human-readable institution name (e.g. OPay). Present on GET responses when the code resolves in Paycrest. accountIdentifier: type: string description: >- Bank account, mobile phone (E.164 or local), till number, or paybill account reference depending on channel. accountName: type: string memo: type: string description: Payment narration / reference metadata: type: object description: >- Corridor-specific hints. For KES mobile offramp, use channel and optional businessNumber (see Sender API Integration guide). properties: channel: type: string enum: - Mobile - Till - Paybill description: >- KES payout channel. Mobile = phone M-Pesa; Till = buy goods; Paybill = paybill. Omit for default phone M-Pesa when accountIdentifier is a mobile number. businessNumber: type: string description: >- Paybill business number (required for Paybill when not inferrable from accountIdentifier alone). V2CryptoRecipient: type: object required: - address - network properties: address: type: string description: >- Wallet address on `network` to receive stablecoins. On Solana, the wallet must already have a token account for the stablecoin's mint. network: type: string enum: - ethereum - base - bnb-smart-chain - lisk - celo - arbitrum-one - polygon - starknet - tron - solana description: >- Network the stablecoins are delivered on. `solana` accepts the tokens `GET /v2/tokens` lists on `solana`. KYCPersonDetails: type: object description: Set when `entityType` is `person`. properties: fullName: type: string birthDate: type: string format: date description: YYYY-MM-DD nationality: type: string description: ISO 3166-1 alpha-2 contact: $ref: '#/components/schemas/KYCContact' idDocument: $ref: '#/components/schemas/KYCIDDocument' taxId: $ref: '#/components/schemas/KYCTaxID' KYCOrganizationDetails: type: object description: Set when `entityType` is `organization`. properties: legalName: type: string tradingName: type: string registrationNumber: type: string registrationDate: type: string format: date description: YYYY-MM-DD registrationCountry: type: string description: ISO 3166-1 alpha-2 contact: $ref: '#/components/schemas/KYCContact' taxId: $ref: '#/components/schemas/KYCTaxID' directors: type: array description: Directors or beneficial owners. items: type: object properties: personDetails: $ref: '#/components/schemas/KYCPersonDetails' role: type: string example: Director ownershipPercentage: type: number description: 0–100 KYCPrincipalAddress: type: object properties: street: type: string city: type: string state: type: string postalCode: type: string country: type: string description: ISO 3166-1 alpha-2 KYCContact: type: object properties: email: type: string phoneE164: type: string description: E.164, e.g. `+254712345678` KYCIDDocument: type: object properties: type: type: string enum: - passport - nationalID - driverLicense - BVN description: '`BVN` is accepted on NGN on-ramp only.' number: type: string issuerCountry: type: string description: ISO 3166-1 alpha-2 KYCTaxID: type: object properties: type: type: string description: >- Person: `TIN`, `CPF`, `SSN` or `Other`. Organization: `VAT`, `CorpTIN`, `LEI` or `Other`. Send a BVN as the `idDocument`. value: type: string country: type: string description: ISO 3166-1 alpha-2 securitySchemes: ApiKeyAuth: type: apiKey in: header name: API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.