> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rheon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a card payout
> Creates the payout against a quote and answers where the user sends the stablecoins. Nothing moves until they send. `reference` makes the call idempotent: the same reference answers the same payout.
The provider behind this endpoint is currently being connected, docs updating. Until then every answer carries `mock: true`, every money figure is the placeholder `1234567.89`, and ids and shapes are real and deterministic from your input.
**Provider sandbox on this deployment.** Our backend targets the card provider's sandbox: no card is charged and no real transfer settles. Known limits: a purchase never reaches `completed` (it stops at `processing`), the settlement asset is the sandbox's, not production's (read `cryptoCurrency` from GET /v1/config), and the EUR window is unpublished (GET /v1/card/limits says `window: unpublished`). Every response says which environment answered in its `environment` field.
**Currently being connected, docs updating.** This endpoint answers `mock: true`: ids, shapes and statuses are real and deterministic from your input, every money figure is the placeholder `1234567.89`, and nothing is sent to a provider. Integrate against the shape; do not compute anything from the figures.
## OpenAPI
````yaml https://backend.rheon.io/openapi.json post /v1/card/payout
openapi: 3.1.0
info:
title: Rheon partner API
version: 1.0.0
description: >-
The /v1 surface a partner's backend calls with an API key.
**Authentication.** Every route takes `Authorization: Bearer `. One
kind of key: it carries its permissions and limits, and works from your
server, a page, or this playground alike - where it is called from is not
checked. Treat it as a secret all the same: anyone holding it acts under its
permissions until it is rotated.
**Rate limit.** Counted per key, at the requests-per-second rate configured
on the key - never per IP, so your users do not throttle each other. Over
it: `429 rate_limited`.
**Amounts.** Token amounts are decimal strings in the token's smallest unit;
fiat amounts are decimal strings in major units. Never JSON numbers.
**Errors.** One envelope everywhere: `{ error: { code, message } }`, with
`fields` added on bank refusals that named a field. A body that is not valid
JSON answers `400 invalid_request`; an endpoint that does not exist answers
`404 not_found`; a deployment with no partner keys configured answers `404
not_configured` for all of /v1.
**Environment.** Every response carries `environment` as its first field:
`sandbox` or `production`, derived from the upstreams this deployment is
configured against (never a flag). Read it off any response you paste into a
ticket. In `sandbox` no real money moves and the card corridor is the
provider's sandbox asset, which differs from production - read it from GET
/v1/config, not from these docs.
**Card corridor.** The asset and chain a card purchase settles as are fixed
per deployment, not chosen per request. GET /v1/config reports the one
actually configured.
servers:
- url: https://api.rheon.io
description: Production
security:
- bearerAuth: []
tags:
- name: Configuration
- name: Crypto deposits
- name: Orders
- name: Cards
- name: Bank transfers
- name: Virtual accounts
- name: Reference
- name: Sandbox only
paths:
/v1/card/payout:
post:
tags:
- Cards
summary: Create a card payout
description: >-
Creates the payout against a quote and answers where the user sends the
stablecoins. Nothing moves until they send. `reference` makes the call
idempotent: the same reference answers the same payout.
The provider behind this endpoint is currently being connected, docs
updating. Until then every answer carries `mock: true`, every money
figure is the placeholder `1234567.89`, and ids and shapes are real and
deterministic from your input.
operationId: cardPayout
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardPayoutRequest'
responses:
'200':
description: The payout and where to send.
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutCreated'
'400':
description: >-
Cannot create this.
- `invalid_request`: quoteId not one this API issued, accountId
empty, card not exactly one of token or cardId, reference over 64
characters.
x-error-codes:
- invalid_request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: >-
No usable API key.
- `unauthorized`: Missing, malformed or unknown key. One
undifferentiated answer on purpose.
x-error-codes:
- unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'403':
description: >-
Refused by permission.
- `permission_denied`: The key does not carry the `cards`
permission.
x-error-codes:
- permission_denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: >-
Over this key's rate.
- `rate_limited`: More requests per second than the key is
configured for. Counted PER KEY (all your users share one bucket),
never per IP.
x-error-codes:
- rate_limited
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
description: >-
Our fault.
- `internal`: Unexpected server error. Detail is in our logs, never
on the wire.
x-error-codes:
- internal
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- bearerAuth: []
components:
schemas:
CardPayoutRequest:
type: object
properties:
quoteId:
type: string
minLength: 1
description: From POST /v1/card/payout/quote.
accountId:
type: string
minLength: 1
description: The user being paid out - the same id as the incoming direction.
example: acct_8f2c91d0a4
card:
$ref: '#/components/schemas/CardOnFile'
reference:
description: >-
Your idempotency key, up to 64 characters. A retry carrying the same
value answers the original object instead of creating a second one.
example: payout-2026-09-02-115
type: string
maxLength: 64
required:
- quoteId
- accountId
- card
PayoutCreated:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
mock:
$ref: '#/components/schemas/MockFlag'
id:
type: string
description: The payout id. Poll it on the matching status endpoint.
example: bpo_77c2e1f4309a6d5b
depositAddress:
$ref: '#/components/schemas/EvmAddress'
description: >-
Where the user sends the stablecoins. While the payout providers are
being connected this is the zero address and nothing must be sent to
it; wired, it is a single-use address derived per payout.
example: '0x0000000000000000000000000000000000000000'
depositAmount:
$ref: '#/components/schemas/MockMoney'
chain:
$ref: '#/components/schemas/ChainId'
description: >-
The chain `depositAddress` lives on - the chain the quote was made
for.
status:
$ref: '#/components/schemas/PayoutStatus'
expiresAt:
type: string
description: >-
ISO 8601. Stablecoins arriving after this convert at the rate
current on arrival, not the quoted one.
example: '2026-09-08T18:14:12.000Z'
required:
- environment
- mock
- id
- depositAddress
- depositAmount
- chain
- status
- expiresAt
additionalProperties: false
ErrorEnvelope:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
error:
type: object
properties:
code:
type: string
description: >-
Machine-readable error code. Branch on this, never on the
message.
example: invalid_request
message:
type: string
description: Human-readable explanation. Wording may change.
example: amount must be a decimal string of the token's smallest unit.
fields:
description: >-
Per-field complaints from the bank provider, when it named the
field it refused (bank routes only). Field names, never values.
example:
applicantInfo.nationality: iso3166_1_alpha2
type: object
propertyNames:
type: string
additionalProperties:
type: string
required:
- code
- message
additionalProperties: false
required:
- environment
- error
additionalProperties: false
description: The one error shape this API produces.
CardOnFile:
type: object
properties:
token:
description: A tokenised card from the hosted collection page.
example: tok_9c14ba7e02
type: string
cardId:
description: A card already on file from a previous payout.
type: string
description: >-
Where the money lands: exactly one of `token` or `cardId`. Raw card
numbers are never accepted.
Environment:
type: string
enum:
- sandbox
- production
description: >-
Which environment answered. `sandbox`: at least one money upstream is
the provider's sandbox - no real money moves there, and the card
corridor is the sandbox's asset (read GET /v1/config), not the
documented production one. `production`: every configured upstream is
real. Derived from the configured upstream hosts at boot, never a flag.
example: sandbox
MockFlag:
type: boolean
const: true
description: >-
Always `true` on this endpoint: the provider behind it is currently
being connected, docs updating. Ids, shapes and statuses are real and
deterministic from your input; every money figure is the placeholder
`1234567.89`; nothing is sent to a provider. The field disappears the
day the provider is wired, so branch on its presence, not its value.
example: true
EvmAddress:
type: string
pattern: ^0x[0-9a-fA-F]{40}$
description: >-
EVM address: 0x followed by 40 hex characters. Checksum casing is not
required.
example: '0x1111111111111111111111111111111111111111'
MockMoney:
type: string
const: '1234567.89'
description: >-
Placeholder while the provider is being connected: always `1234567.89`,
never a price. Do not compute anything from it. When the provider is
wired this becomes a decimal string in major units.
example: '1234567.89'
ChainId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
description: EVM chain id, a positive integer (e.g. 42161 for Arbitrum One).
example: 42161
PayoutStatus:
type: string
enum:
- pending
- converting
- sent
- settled
- rejected
- returned
description: >-
`pending`: created, waiting for the user's stablecoin at the deposit
address. `converting`: the stablecoin landed and is being converted.
`sent`: left the provider, NOT arrived. `settled`: reached the card or
bank account - the one state to tell the user about. `rejected`: the
provider refused it. `returned`: sent and came back. While the payout
providers are being connected every payout answers `pending`.
example: pending
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your API key, issued by us and shown once at creation.
````