> ## Documentation Index > Fetch the complete documentation index at: https://docs.grainfinance.co/llms.txt > Use this file to discover all available pages before exploring further. # List Payouts > Lists payouts for the partner, most recent first. Supports filtering by status, currency, vendor, payout reference, and payout-date range. ## OpenAPI ````yaml GET /payouts openapi: 3.1.0 info: title: Grain API version: 1.0.0 description: >- Grain's API provides a comprehensive set of endpoints for managing hedging, spot transactions, pricing, and fund movements - enabling seamless integration of FX workflows into your platform. Each API call follows REST conventions, uses secure authentication, and returns standardized responses for consistency across environments. license: name: Creative Commons Attribution 3.0 contact: name: Grain Finance url: https://docs.grainfinance.co email: support@grainfinance.co termsOfService: https://grainfinance.co/terms-of-service/ x-apiClientRegistration: url: https://grainfinance.co/partners servers: - url: https://api.grainfinance.co/v1 description: Grain API security: [] tags: - name: Hedges description: >- Hedge objects represent transactions that lock exchange rates for future dates. A single hedge locks an exchange rate for a future transaction between two currencies. - name: Dual Hedges description: >- A dual hedge mitigates FX risk by automatically generating two linked hedge legs - a customer leg and a supplier leg - both routed through the customer's functional currency. This structure reduces exposure to currency fluctuations for both cash flow and accounting purposes, while allowing independent tracking and reporting of each hedge leg. - name: Customers description: >- Customer objects represent your end customers on the Grain platform. A customer must be created before a hedge or spot transaction can be initiated. - name: Pricing description: >- Pricing endpoints provide access to FX rates for currency pairs that are not being hedged. These endpoints can be used for live rate display or bulk retrieval to support high-volume quoting workflows. - name: Spots description: >- Spot objects represent currency conversions executed for immediate or near-term settlement. - name: Conversions description: >- Conversion objects represent currency conversions executed for immediate or near-term settlement. - name: Wallets description: Endpoints to view balances, manage funding, and perform transfers. paths: /payouts: get: tags: - Payouts description: >- Lists payouts for the partner, most recent first. Supports filtering by status, currency, vendor, payout reference, and payout-date range. operationId: List parameters: - description: Filter by payout status. in: query name: status required: false schema: $ref: '#/components/schemas/DisplayPayoutStatus' - description: Filter by the alpha-3 ISO 4217 currency code of the payout. in: query name: currency required: false schema: $ref: '#/components/schemas/CurrencyCode' - description: Filter by your own reference number for the payout. in: query name: external_payout_id required: false schema: $ref: '#/components/schemas/ExternalPayoutId' - description: Filter by your own reference id for the vendor. in: query name: external_vendor_id required: false schema: $ref: '#/components/schemas/ExternalVendorId' - description: Earliest payout date to include, in `YYYY-MM-DD` format. in: query name: from_date required: false schema: type: string - description: Latest payout date to include, in `YYYY-MM-DD` format. in: query name: to_date required: false schema: type: string - description: Page number indicating which set of items to return. in: query name: page required: false schema: $ref: '#/components/schemas/Page' - description: The number of items in a page. in: query name: per_page required: false schema: $ref: '#/components/schemas/PerPage' responses: '200': description: Payouts found content: application/json: schema: $ref: '#/components/schemas/PayoutListResponse' security: - api-key: [] components: schemas: DisplayPayoutStatus: enum: - in_process - sent - paid - failed - rejected type: string CurrencyCode: type: string example: EUR description: The alpha-3 ISO 4217 currency code of the related entity. pattern: ^[A-Za-z]{3}$ ExternalPayoutId: type: string example: inv_2026_001 description: Partner's own reference number for this payout. pattern: ^[A-Za-z0-9_.\-]{1,64}$ ExternalVendorId: type: string example: vendor_001 description: Partner's own reference ID for the vendor. pattern: ^[A-Za-z0-9_.\-]{1,64}$ Page: type: number format: double description: The page indicating which set of items are returned minimum: 1 PerPage: type: number format: double description: number of items in a page minimum: 1 maximum: 100 PayoutListResponse: description: A paginated list of payouts. properties: payouts: items: $ref: '#/components/schemas/PayoutResponse' type: array description: A list of payouts matching the search criteria. pagination: $ref: '#/components/schemas/PaginationResponse' required: - payouts - pagination type: object additionalProperties: false PayoutResponse: description: >- A Payout represents an executed payment to a vendor. Returned by `GET /v1/payouts/{id}`, `GET /v1/payouts`, and `POST /v1/payouts/{id}/submit`. properties: id: $ref: '#/components/schemas/UUID' description: The id of the payout within the Grain platform. example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5 status: $ref: '#/components/schemas/DisplayPayoutStatus' description: The current status of the payout. example: in_process externalPayoutId: $ref: '#/components/schemas/ExternalPayoutId' description: The payout id, as identified within your system. currency: $ref: '#/components/schemas/CurrencyCode' description: The alpha-3 ISO 4217 currency code of the payout. example: USD amount: type: number format: double description: The payout amount, denoted in `currency`. example: 5000 fee: type: number format: double description: The fee applied to this payout, denoted in `currency`. example: 1.5 totalAmount: type: number format: double description: >- Total amount that will leave the wallet (`amount + fee`), denoted in `currency`. example: 5001.5 reason: $ref: '#/components/schemas/ComplianceReasonCode' description: |- The compliance reason categorising this payout, as a numeric code: 1 - Intercompany Payment 2 - Purchase of Good(s) 3 - Purchase of Service(s) 4 - Transferring to Own Accounts 5 - Valid Vendor Purchases example: 2 description: type: - string - 'null' description: Free-form description supplied when initiating the payout. payoutDate: $ref: '#/components/schemas/GrainDateFormat' description: The date the payout was sent to the bank, in `YYYY-MM-DD` format. example: '2026-05-15' payoutMethod: $ref: '#/components/schemas/DisplayPaymentMethod' description: The payment method that will be used to send the payout. example: SEPA vendorDetails: $ref: '#/components/schemas/PayoutVendorDetails' description: >- The vendor receiving the payout, including their bank account details. required: - id - status - externalPayoutId - currency - amount - fee - totalAmount - reason - description - payoutDate - payoutMethod - vendorDetails type: object additionalProperties: false PaginationResponse: description: Pagination parameters of the returned results. properties: page: $ref: '#/components/schemas/Page' perPage: $ref: '#/components/schemas/PerPage' totalResults: type: number format: double description: The total amount of results available required: - page - perPage - totalResults type: object additionalProperties: false UUID: type: string format: uuid description: |- Stringified UUIDv4. See [RFC 4112](https://tools.ietf.org/html/rfc4122) pattern: >- [0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12} ComplianceReasonCode: description: |- The compliance reason categorising a payout, as a numeric code: 1 - Intercompany Payment 2 - Purchase of Good(s) 3 - Purchase of Service(s) 4 - Transferring to Own Accounts 5 - Valid Vendor Purchases enum: - 1 - 2 - 3 - 4 - 5 type: number GrainDateFormat: type: string example: '2023-04-15' format: YYYY-MM-DD description: >- The date format accepted by Grain's API. We accept dash separated ISO-8601 date-only strings. pattern: \d{4}-\d{2}-\d{2} DisplayPaymentMethod: enum: - SWIFT - SEPA - WIRE - ACH - FPS - EFT - NPP - IBG - BECS - CCASS - SPEI type: string PayoutVendorDetails: description: The vendor receiving the payout, including their bank account details. properties: vendorId: $ref: '#/components/schemas/UUID' description: The id of the vendor within the Grain platform. example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e vendorName: type: string description: The name of the vendor. example: Acme Supplies Ltd externalVendorId: $ref: '#/components/schemas/ExternalVendorId' description: The vendor id, as identified within your system. bankDetails: $ref: '#/components/schemas/VendorBankDetails' description: Bank account details to which the payout will be sent. required: - vendorId - vendorName - externalVendorId - bankDetails type: object additionalProperties: false VendorBankDetails: description: Bank account details of a vendor receiving a payout. properties: accountHolderName: type: string description: The full legal name of the account holder. example: Acme Payments Ltd accountNumber: type: string description: The account number. example: '8290041523' bankName: type: string description: The name of the bank holding the account. example: JPMorgan Chase Bank, N.A. bankAddress: type: string description: The full address of the bank. example: 383 Madison Avenue, New York, NY 10017 bankCountry: type: string description: The alpha-2 ISO 3166 country code of the bank. example: US pattern: ^[A-Za-z]{2}$ bankState: type: string description: The state/region of the bank's location, when applicable. example: NY iban: type: string description: The IBAN of the account, when applicable. pattern: ^[A-Z0-9]{15,34}$ bicSwift: type: string description: The SWIFT/BIC code of the bank, when applicable. example: CHASUS33XXX pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ routingCode: type: string description: >- Country-specific routing code (e.g. IFSC for India, CLABE for Mexico, Canadian transit), when applicable. For US ACH and wire, see `achRoutingCode` / `wireRoutingCode` on wallet responses. bankCode: type: string description: Country-specific bank code, when applicable. branchCode: type: string description: Country-specific branch code, when applicable. sortCode: type: string description: UK sort code, when applicable. Six digits, no hyphens. example: '560036' pattern: ^\d{6}$ bsbCode: type: string description: Australian BSB code, when applicable. Six digits, no hyphens. example: '082902' pattern: ^\d{6}$ required: - accountHolderName - accountNumber - bankName - bankAddress - bankCountry type: object additionalProperties: false securitySchemes: api-key: type: http scheme: basic description: >- Basic authentication using the partner API keys from https://console.grainfinance.co/keys ````