{types.length > 1 ? shapesDiffer ? <>
{types.length} payout
types available for this pair — shapes differ, choose
carefully.
: `${types.length} payout types available — identical field requirements either way.` : "Only payout type for this pair."}
Required fields
{needsState &&
bankState
ISO state/province code — required because{" "}
bankCountry is {country}
Selected above: {currentState}.
}
{fieldInfos.map((info, i) =>
{info.name}
{info.rule}
{info.sub && {info.sub}}
)}
{row.note &&
{row.note}
}
Example request
;
};
Select a currency, bank country, and payout type below to see exactly which `payoutMethod` fields are required and their format rules, plus a matching example request.
## OpenAPI
````yaml POST /vendors
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,
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
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 conversion 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: 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.
- name: Vendors
description: >-
Vendor objects represent payees that payouts can be sent to. A vendor
holds contact details and one or more payout methods — the bank accounts
payouts are sent to.
paths:
/vendors:
post:
tags:
- Vendors
description: >-
Creates a vendor with a single payout method.
The bank account fields required in `payoutMethod` depend on the
method's currency, bank country and type.
operationId: Create
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVendorRequest'
responses:
'201':
description: Vendor created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerVendor'
'403':
description: The request failed because the caller has insufficient permissions.
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'
'502':
description: >-
The request failed because an upstream provider was unavailable or
returned an unexpected response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- api-key: []
components:
schemas:
CreateVendorRequest:
description: >-
Request body for `POST /v1/vendors`. Creates a vendor with a single
payout method. The conditional
contact fields (`contactState`, `contactTaxId`, `contactPhoneNumber`,
`companyRegisterNumber`) are
required for some countries.
properties:
externalVendorId:
$ref: '#/components/schemas/ExternalVendorId'
description: The vendor id, as identified within your system.
example: vendor_001
contactFullName:
type: string
description: The full name of the vendor's contact person or business.
example: Acme Supplies Ltd
contactCountry:
$ref: '#/components/schemas/CountryCode'
description: The alpha-2 ISO 3166 country code of the vendor.
example: US
contactCity:
type: string
description: The city of the vendor's address.
example: New York
contactEmail:
type: string
description: The email address of the vendor.
example: billing@acmesupplies.com
contactStreetName:
type: string
description: The street name of the vendor's address.
example: Madison Avenue
contactBuildingName:
type: string
description: The building name or number of the vendor's address.
example: '383'
contactPostalCode:
type: string
description: The postal code of the vendor's address.
example: '10017'
contactState:
type: string
description: >-
The ISO state code of the vendor's address. Required for vendors in
US, CA, NZ and AU.
example: NY
contactTaxId:
type: string
description: The tax id of the vendor. Required for vendors in some countries.
example: '901234567'
contactPhoneNumber:
type: string
description: >-
The phone number of the vendor's contact. Required for vendors in
some countries.
example: '+13212312321'
companyRegisterNumber:
type: string
description: >-
The company register number of the vendor. Required for vendors in
some countries.
example: '514455544'
payoutMethod:
$ref: '#/components/schemas/VendorPayoutMethod'
description: The payout method to register for the vendor.
required:
- externalVendorId
- contactFullName
- contactCountry
- contactCity
- contactEmail
- contactStreetName
- contactBuildingName
- contactPostalCode
- payoutMethod
type: object
additionalProperties: false
CustomerVendor:
description: >-
A Vendor represents a payee that payouts can be sent to. Returned by
`POST /v1/vendors`,
`GET /v1/vendors/{vendorId}`, and `GET /v1/vendors`.
properties:
vendorId:
$ref: '#/components/schemas/UUID'
description: The id of the vendor within the Grain platform.
example: 1b0ada1e-fa1b-4cfe-a553-01b340c5650e
externalVendorId:
$ref: '#/components/schemas/ExternalVendorId'
description: The vendor id, as identified within your system.
example: vendor_001
contact:
$ref: '#/components/schemas/VendorContact'
description: The contact details of the vendor.
payoutMethods:
items:
$ref: '#/components/schemas/VendorPayoutMethod'
type: array
description: The payout methods registered for the vendor.
createdAt:
$ref: '#/components/schemas/IsoDateTime'
description: When the vendor was created, as an ISO-8601 date-time in UTC.
example: '2026-05-15T09:12:28.000Z'
updatedAt:
$ref: '#/components/schemas/IsoDateTime'
description: When the vendor was last updated, as an ISO-8601 date-time in UTC.
example: '2026-05-15T09:12:28.000Z'
required:
- vendorId
- externalVendorId
- contact
- payoutMethods
- createdAt
- updatedAt
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}$
CountryCode:
type: string
example: GB
description: The alpha-2 ISO 3166 country code of the entity's country.
pattern: ^[A-Za-z]{2}$
VendorPayoutMethod:
description: >-
A payout method registered for the vendor — the bank account payouts in
`currency` are sent to.
Bank account fields are corridor-specific: only the fields relevant to
the method's currency,
country, and type are returned.
properties:
type:
$ref: '#/components/schemas/DisplayPaymentMethod'
description: The payment method used to send payouts to this bank account.
example: SEPA
currency:
$ref: '#/components/schemas/CurrencyCode'
description: The alpha-3 ISO 4217 currency code of payouts sent with this method.
example: EUR
bankName:
type: string
description: The name of the bank holding the account.
example: JPMorgan Chase Bank, N.A.
bankCountry:
$ref: '#/components/schemas/CountryCode'
description: The alpha-2 ISO 3166 country code of the bank.
example: US
bankState:
type: string
description: The ISO state code of the bank's location, when applicable.
example: NY
accountNumber:
type: string
description: The account number, when applicable.
example: '8290041523'
iban:
type: string
description: The IBAN of the account, when applicable.
example: DE89370400440532013000
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, when applicable — the nine-digit ABA
routing number for USD payouts.
example: '021000021'
bankCode:
type: string
description: >-
Country-specific bank code, when applicable — CAD (EFT), HKD
(CCASS), SGD (IBG) and MXN (SPEI) payouts.
example: '004'
branchCode:
type: string
description: >-
Country-specific branch code, when applicable — CAD (EFT), HKD
(CCASS), SGD (IBG) and MXN (SPEI) payouts.
example: '081'
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}$
bankAddress:
type: string
description: The full address of the bank, when provided.
example: 383 Madison Avenue, New York, NY 10017
required:
- type
- currency
- bankName
- bankCountry
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}
VendorContact:
description: >-
The contact details of the vendor. Conditional fields (`state`, `taxId`,
`phoneNumber`,
`companyRegisterNumber`) are returned only when they were provided.
properties:
fullName:
type: string
description: The full name of the vendor's contact person or business.
example: Acme Supplies Ltd
country:
$ref: '#/components/schemas/CountryCode'
description: The alpha-2 ISO 3166 country code of the vendor.
example: US
city:
type: string
description: The city of the vendor's address.
example: New York
email:
type: string
description: The email address of the vendor, when provided.
example: billing@acmesupplies.com
streetName:
type: string
description: The street name of the vendor's address, when provided.
example: Madison Avenue
buildingName:
type: string
description: The building name or number of the vendor's address, when provided.
example: '383'
postalCode:
type: string
description: The postal code of the vendor's address, when provided.
example: '10017'
state:
type: string
description: >-
The ISO state code of the vendor's address, when provided. Required
for vendors in US, CA, NZ and AU.
example: NY
taxId:
type: string
description: The tax id of the vendor, when provided.
example: '901234567'
phoneNumber:
type: string
description: The phone number of the vendor's contact, when provided.
example: '+13212312321'
companyRegisterNumber:
type: string
description: The company register number of the vendor, when provided.
example: '514455544'
required:
- fullName
- country
- city
type: object
additionalProperties: false
IsoDateTime:
type: string
example: '2026-05-15T09:12:28.000Z'
format: date-time
description: An ISO-8601 date-time string in UTC.
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
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
````