> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nxos.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get fiat payout options
> List the values a fiat payout can be built from.
Reference data, identical for every organization and stable between
releases, so it is safe to cache for a day. Fetch it instead of hardcoding
the codes: new purposes are added here first, and a value absent from this
response is rejected by `POST /v1/transactions/fiat-payouts` with
`400 invalid_request`.
`purposes` carries the ISO 20022 `ExternalPurpose1Code` values we accept.
Send `code` on the payout and show `label` to whoever is choosing.
| Code | Meaning |
| ------ | ----------------------------------------------------- |
| `GDDS` | Purchase of goods |
| `SUPP` | Supplier payment |
| `SCVE` | Purchase of services |
| `GDSV` | Purchase of goods and services together |
| `IVPT` | Payment against an invoice |
| `TRAD` | Trade services operation |
| `ADVA` | Advance payment ahead of delivery |
| `BEXP` | Payment of business expenses |
| `SUBS` | Subscription to information or entertainment services |
| `REFU` | Payment of a refund |
| `AIRB` | Air transport related business |
| `FERB` | Ferry related business |
| `SALA` | Payment of salaries |
| `BONU` | Payment of a bonus |
| `ALLW` | Payment of allowances |
| `COMM` | Payment of commission |
| `COMP` | Payment of compensation |
| `PENS` | Payment of pension |
| `DIVD` | Payment of dividends |
| `INTC` | Payment between two companies in the same group |
| `TREA` | Treasury operation between accounts we hold |
| `INVS` | Payment for investment products, funds or shares |
| `LOAN` | Transfer of a loan to a borrower |
| `LOAR` | Repayment of a loan to a lender |
| `INTE` | Payment of interest |
| `TAXS` | Payment of taxes |
| `GOVT` | Payment to a government department |
| `RENT` | Payment of rent |
| `UBIL` | Gas, water or electricity bill |
| `INSU` | Payment of an insurance premium |
| `ROYA` | Payment of royalties |
| `EDUC` | Study or tuition fees |
| `CHAR` | Payment for charity reasons |
| `GIFT` | Payment with no commercial or statutory purpose |
| `FREX` | Foreign exchange operation |
| `OTHR` | Purpose not covered by another option |
## OpenAPI
````yaml GET /v1/transactions/fiat-payouts/options
openapi: 3.0.0
info:
title: nxos API
version: 1.0.0
contact:
name: nxos
url: https://nxos.io
description: |-
The nxos platform API provides programmatic access to accounts, balances,
quotes, and trades. All endpoints require API key authentication.
servers:
- url: https://api.nxos.io
description: Production
variables: {}
- url: https://api.sandbox.nxos.io
description: Sandbox
variables: {}
security: []
tags:
- name: Accounts
- name: Quotes
- name: Beneficiaries
- name: Fiat Payouts
- name: Crypto Payouts
- name: Sandbox Faucet
- name: Nxosnet
- name: Fees
- name: Sub-Org Tiers
- name: Funding Methods
- name: Transactions
- name: Organizations
- name: Authorizations
- name: Webhooks
description: >-
Register an HTTPS endpoint to receive events (organization verification
and
transaction status changes) instead of polling. Deliveries are signed;
verify
the `svix-signature` header before acting on an event.
See the [Webhooks guide](https://docs.nxos.io/core-concepts/webhooks) for
the
delivery format, signature verification, retries, and broker behavior.
Payload
shapes are documented in the `…Event` models below.
paths:
/v1/transactions/fiat-payouts/options:
get:
tags:
- Fiat Payouts
description: >-
List the values a fiat payout can be built from.
Reference data, identical for every organization and stable between
releases, so it is safe to cache for a day. Fetch it instead of
hardcoding
the codes: new purposes are added here first, and a value absent from
this
response is rejected by `POST /v1/transactions/fiat-payouts` with
`400 invalid_request`.
`purposes` carries the ISO 20022 `ExternalPurpose1Code` values we
accept.
Send `code` on the payout and show `label` to whoever is choosing.
operationId: FiatPayouts_options
parameters:
- $ref: '#/components/parameters/ApiKeyAuth'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/FiatPayoutOptions'
'401':
description: Access is unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'429':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/Error429'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
components:
parameters:
ApiKeyAuth:
name: Authorization
in: header
required: true
description: 'Bearer token. Format: `Bearer `'
schema:
type: string
schemas:
FiatPayoutOptions:
type: object
required:
- object
- purposes
properties:
object:
type: string
enum:
- fiat_payout_options
description: Object type. Always `fiat_payout_options`.
purposes:
type: array
items:
$ref: '#/components/schemas/PurposeCodeOption'
description: >-
Every purpose code accepted by `POST /v1/transactions/fiat-payouts`,
in the
order we recommend presenting them. Safe to render straight into a
picker:
send `code`, show `label`.
description: The values a fiat payout can be built from.
example:
object: fiat_payout_options
purposes:
- code: GDDS
label: Buying goods
description: Purchase of goods
- code: SUPP
label: Paying a supplier
description: Supplier payment
Error401:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
description: Standard error response returned by all endpoints on failure.
example:
error:
code: missing_api_key
message: No Authorization header provided.
requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Error429:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
description: Standard error response returned by all endpoints on failure.
example:
error:
code: rate_limited
message: 'Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.'
requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
Error500:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
description: Standard error response returned by all endpoints on failure.
example:
error:
code: internal_error
message: An unexpected server error occurred.
requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
PurposeCodeOption:
type: object
required:
- code
- label
- description
properties:
code:
allOf:
- $ref: '#/components/schemas/PurposeCode'
description: The value to send as `purpose` on a fiat payout.
label:
type: string
description: >-
Short wording written for the person sending the money, e.g. `Paying
a supplier`.
description:
type: string
description: Formal description of what the code covers, e.g. `Supplier payment`.
description: One selectable purpose code, with the wording to show in a picker.
ErrorBody:
type: object
required:
- code
- message
- requestId
properties:
code:
allOf:
- $ref: '#/components/schemas/ErrorCode'
description: Machine-readable error code.
message:
type: string
description: Human-readable error message.
requestId:
type: string
description: Unique identifier for this request, useful for debugging.
PurposeCode:
type: string
enum:
- GDDS
- SUPP
- SCVE
- GDSV
- IVPT
- TRAD
- ADVA
- BEXP
- SUBS
- REFU
- AIRB
- FERB
- SALA
- BONU
- ALLW
- COMM
- COMP
- PENS
- DIVD
- INTC
- TREA
- INVS
- LOAN
- LOAR
- INTE
- TAXS
- GOVT
- RENT
- UBIL
- INSU
- ROYA
- EDUC
- CHAR
- GIFT
- FREX
- OTHR
description: >-
Why the money is moving. Taken from the ISO 20022 `ExternalPurpose1Code`
list
and reported to the central bank on every wire, so it must describe the
payment honestly rather than being set to a convenient default.
ErrorCode:
type: string
enum:
- missing_api_key
- authentication_failed
- invalid_api_key
- forbidden
- swap_direction_not_allowed
- sub_org_tier_not_available
- service_not_enabled
- not_found
- organization_not_found
- account_not_found
- quote_not_found
- beneficiary_not_found
- transaction_not_found
- funding_method_not_found
- authorization_not_found
- nxosnet_handle_not_found
- sub_org_tier_not_found
- quote_expired
- quote_already_used
- beneficiary_already_archived
- beneficiary_not_archived
- beneficiary_blocked
- nxosnet_not_enabled
- nxosnet_handle_taken
- chain_send_failed
- idempotency_key_in_use
- idempotency_request_in_flight
- invalid_request
- insufficient_funds
- validation_error
- share_token_invalid
- verification_import_unsupported
- verification_required
- rate_limited
- webhooks_unavailable
- internal_error
description: All possible error codes returned by the API.
````