Grain Payouts API

openapi: 3.2.0
info:
  title: Grain Payouts API
  version: 1.0.0
  description: Grain's API provides a comprehensive set of endpoints for managing hedging, currency conversions, 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
tags:
- name: Payouts
paths:
  /payouts:
    post:
      operationId: Review
      responses:
        '201':
          description: Payout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutProposalResponse'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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'
      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.'
      tags:
      - Payouts
      security:
      - api-key: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiatePayoutRequest'
      summary: Review
      x-summary-source: derived
    get:
      operationId: List
      responses:
        '200':
          description: Payouts found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutListResponse'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: 'Lists payouts for the partner, most recent first. Supports filtering by status, currency, vendor,

        payout reference, and payout-date range.'
      tags:
      - Payouts
      security:
      - api-key: []
      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'
      summary: List
      x-summary-source: derived
  /payouts/{proposalId}/submit:
    post:
      operationId: Submit
      responses:
        '200':
          description: Payout submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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'
        '410':
          description: The request failed because the payout proposal has expired.
          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'
      description: 'Submits a previously reviewed payout, executing the payment. The `proposalId` is the id returned

        by `POST /v1/payouts`. Must be called before the proposal''s `validUntilTs`, otherwise it is rejected

        as expired.'
      tags:
      - Payouts
      security:
      - api-key: []
      parameters:
      - description: The id of the payout proposal, as returned by `POST /v1/payouts`.
        in: path
        name: proposalId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      summary: Submit
      x-summary-source: derived
  /payouts/{payoutId}:
    get:
      operationId: Get
      responses:
        '200':
          description: Payout found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '403':
          description: The request failed because the caller has insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The request failed because the resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Retrieves a single payout by its payout id, including its current status and vendor bank details.
      tags:
      - Payouts
      security:
      - api-key: []
      parameters:
      - description: The id of the payout within the Grain platform.
        in: path
        name: payoutId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      summary: Get
      x-summary-source: derived
components:
  schemas:
    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
    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
    DisplayPaymentMethod:
      enum:
      - SWIFT
      - SEPA
      - WIRE
      - ACH
      - FPS
      - CA ACSS
      - NPP
      - IBG
      - BECS
      - CCASS
      - TEF
      - UAEFTS
      - SIC
      - CERTIS
      - DKSMC
      - NICS
      - SORBNET
      - RIX
      - SAMOS
      - ZAHAV
      - SARIE
      - QPS
      type: string
    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
    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}
    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
    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
    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
    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
    UUID:
      type: string
      format: uuid
      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}'
    Page:
      type: number
      format: double
      description: The page indicating which set of items are returned
      minimum: 1
    ExternalVendorId:
      type: string
      example: vendor_001
      description: Partner's own reference ID for the vendor.
      pattern: ^[A-Za-z0-9_.\-]{1,64}$
    DisplayPayoutStatus:
      enum:
      - in_process
      - sent
      - paid
      - failed
      - rejected
      type: string
    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
    ExternalPayoutId:
      type: string
      example: inv_2026_001
      description: Partner's own reference number for this payout.
      pattern: ^[A-Za-z0-9_.\-]{1,64}$
    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
    CurrencyCode:
      type: string
      example: EUR
      description: The alpha-3 ISO 4217 currency code of the related entity, in upper case.
      pattern: ^[A-Z]{3}$
  securitySchemes:
    api-key:
      type: http
      scheme: basic
      description: Basic authentication using the partner API keys from https://console.grainfinance.co/keys