> ## 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.
# Which ways in and out are open for a country
> Cards, bank rails and mobile-money rails for a country, each with its direction and currency - narrowed to the products YOUR key carries. Read it rather than hard-coding a list. Authentication only, no permission: the narrowing is the permission story. A listed method is what the corridor supports, not pre-approval of a user.
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.
**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 get /v1/payment-methods
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/payment-methods:
get:
tags:
- Reference
summary: Which ways in and out are open for a country
description: >-
Cards, bank rails and mobile-money rails for a country, each with its
direction and currency - narrowed to the products YOUR key carries. Read
it rather than hard-coding a list. Authentication only, no permission:
the narrowing is the permission story. A listed method is what the
corridor supports, not pre-approval of a user.
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: paymentMethods
parameters:
- in: query
name: country
schema:
type: string
pattern: ^[A-Za-z]{2}$
description: ISO 3166-1 alpha-2 code of the country (case-insensitive).
example: BR
required: true
description: ISO 3166-1 alpha-2 code of the country (case-insensitive).
- in: query
name: direction
schema:
description: '`in` for money coming in, `out` for payouts. Omit for both.'
example: out
type: string
enum:
- in
- out
description: '`in` for money coming in, `out` for payouts. Omit for both.'
- in: query
name: currency
schema:
description: Narrow the answer to one ISO 4217 currency (case-insensitive).
example: BRL
type: string
pattern: ^[A-Za-z]{3}$
description: Narrow the answer to one ISO 4217 currency (case-insensitive).
responses:
'200':
description: The methods, narrowed to this key.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodsResponse'
'400':
description: >-
Cannot answer this.
- `invalid_request`: country missing, not two letters or not a
country the countries list knows; direction not in/out; currency not
three letters.
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'
'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'
security:
- bearerAuth: []
components:
schemas:
PaymentMethodsResponse:
type: object
properties:
environment:
$ref: '#/components/schemas/Environment'
mock:
$ref: '#/components/schemas/MockFlag'
country:
type: string
description: The country asked about, upper-cased.
example: BR
methods:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
description: >-
One entry per method, direction and currency - narrowed to the
products YOUR key carries, so a key without `cards` never sees a
card entry. Empty for a country we cannot onboard, and for a key
with no product that has a payment method.
required:
- environment
- mock
- country
- methods
additionalProperties: false
description: >-
What can move in and out of a country, for this key. A method listed is
what the corridor supports, not pre-approval of a user.
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.
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
PaymentMethod:
type: object
properties:
type:
$ref: '#/components/schemas/PaymentMethodType'
currency:
$ref: '#/components/schemas/IsoCurrency'
description: The currency this method moves.
example: BRL
direction:
type: string
enum:
- in
- out
description: Which way money moves on this entry.
rail:
description: >-
The bank or mobile rail behind the entry, lowercase snake_case, as
GET /v1/limits names it. Absent on the card entries.
example: pix
type: string
min:
$ref: '#/components/schemas/MockMoney'
max:
$ref: '#/components/schemas/MockMoney'
settlement:
description: >-
The rail's published settlement time, in the notation GET /v1/limits
explains. Absent where no rail is involved.
example: instant
type: string
required:
- type
- currency
- direction
- min
- max
additionalProperties: false
PaymentMethodType:
type: string
enum:
- card
- apple_pay
- virtual_account
- bank_deposit
- bank_payout
- mobile_money
description: >-
`card` and `apple_pay`: the card rail (money in). `virtual_account`:
permanent bank details (money in). `bank_deposit`: a one-off bank
transfer (money in). `bank_payout`: a bank transfer out. `mobile_money`:
a mobile-wallet rail, in the direction the entry says.
IsoCurrency:
type: string
pattern: ^[A-Za-z]{3}$
description: ISO 4217 currency code, three letters (case-insensitive on input).
example: EUR
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'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your API key, issued by us and shown once at creation.
````