> ## 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. # Review Payout > Reviews a payout by creating a pending, time-limited proposal. The proposal must be submitted via `POST /v1/payouts/{id}/submit` to execute the payment. No funds are moved at this step. ## OpenAPI ````yaml POST /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: post: tags: - Payouts description: >- Reviews a payout by creating a pending, time-limited proposal. The proposal must be submitted via `POST /v1/payouts/{id}/submit` to execute the payment. No funds are moved at this step. operationId: Review parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiatePayoutRequest' responses: '201': description: Payout created content: application/json: schema: $ref: '#/components/schemas/PayoutProposalResponse' '404': description: The request failed because the resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: The request failed because a business rule constraint was violated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The request failed because it is either semantically incorrect or has failed business validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api-key: [] components: schemas: InitiatePayoutRequest: description: >- Request body for `POST /v1/payouts` (review). Creates a pending, time-limited payout proposal that must be submitted via `POST /v1/payouts/{id}/submit` before it expires. properties: externalVendorId: $ref: '#/components/schemas/ExternalVendorId' description: Your own reference id for the vendor receiving the payout. externalPayoutId: $ref: '#/components/schemas/ExternalPayoutId' description: Your own reference number for this payout. 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 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 description: Optional free-form description for the payout. example: Payment for services required: - externalVendorId - externalPayoutId - currency - amount - reason type: object additionalProperties: false PayoutProposalResponse: description: >- A pending payout proposal, returned by `POST /v1/payouts` (review). Submit it via `POST /v1/payouts/{id}/submit` to execute the payout. properties: id: $ref: '#/components/schemas/UUID' description: The id of the payout proposal within the Grain platform. example: 8173b9a7-ee61-413e-b9e3-7c04b2a067c5 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. validUntilTs: type: number format: double description: >- When the proposal expires if not submitted, as a Unix timestamp in seconds. example: 1779805920 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 - externalPayoutId - currency - amount - fee - totalAmount - reason - description - validUntilTs - payoutMethod - vendorDetails type: object additionalProperties: false ErrorResponse: description: An API Error properties: message: type: string description: A short explanation of the error. example: Can't perform this action reason: type: string description: A detailed description of the reason for the failure. example: >- Supplied object is in *Cancelled* state, which prevents performing this action required: - message type: object additionalProperties: false ExternalVendorId: type: string example: vendor_001 description: Partner's own reference ID for the vendor. pattern: ^[A-Za-z0-9_.\-]{1,64}$ ExternalPayoutId: type: string example: inv_2026_001 description: Partner's own reference number for this payout. pattern: ^[A-Za-z0-9_.\-]{1,64}$ CurrencyCode: type: string example: EUR description: The alpha-3 ISO 4217 currency code of the related entity. pattern: ^[A-Za-z]{3}$ 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 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} 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 ````