> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a hosted ramp session
> POST /ramps/sessions
This endpoint is registered but currently returns `501 not_yet_available`. Track status on the [Availability](/get-started/availability) page.
## OpenAPI
````yaml POST /ramps/sessions
openapi: 3.1.0
info:
title: ZoPay Connect API
description: >-
B2B partner API for crypto custody, deposits, and payouts. Authenticate
every request with a Bearer token (``sk_live_…`` for production,
``sk_test_…`` for sandbox).
version: v1
servers:
- url: https://api.zopay.cash/connect/v1
description: Production
- url: https://dev.api.zopay.cash/connect/v1
description: Development
security:
- BearerAuth: []
tags:
- name: capabilities
description: >-
Static product catalog: which assets, networks, and fiat valuations this
tenant can use. Poll on app startup to drive every UI surface (network
pickers, fee warnings, fiat selection).
- name: addresses
description: >-
Per-user deposit addresses. Mint with ``external_ref`` to attribute to one
of your users; omit for a tenant-treasury (pooled) address.
- name: payment-intents
description: >-
Single-use payment requests. Mint an intent for a specific amount +
currency set; we expand it to per-network deposit addresses. Pass
``external_ref`` to attribute the intent to one of your users for
downstream webhook reconciliation.
- name: balances
description: >-
Per-user or tenant-wide balance snapshot with multi-fiat valuation (USD,
PEN, EUR, MXN, ARS, COP, DOP).
- name: transactions
description: >-
Unified ledger covering deposits, payouts, internal transfers, and (after
Phase 4) conversions and ramps.
- name: payouts
description: >-
Outbound money movement: get a signed quote, then execute it. Quote IDs
are single-use and expire in 60s.
- name: conversions
description: '[Coming soon] Crypto-to-crypto conversions.'
- name: ramps
description: '[Coming soon] Fiat <-> crypto hosted-checkout sessions.'
- name: webhooks
description: '[Coming soon] Subscribe to event streams + replay past events.'
- name: health
description: >-
Auth + connectivity probe. Use to validate your API key works before
depending on a priced endpoint.
- name: test-helpers
description: >-
Sandbox-only simulators. Let you exercise webhook handlers and downstream
state transitions without real testnet activity. Routes return 404 to
``sk_live_…`` keys.
paths:
/ramps/sessions:
post:
tags:
- ramps
summary: '[Coming soon] Create a hosted ramp session'
operationId: create_ramp_session_ramps_sessions_post
parameters:
- name: Idempotency-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Idempotency-Key
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Create Ramp Session Ramps Sessions Post
'400':
description: >-
Invalid request. The body or query parameters failed validation.
``error.code`` names the specific failure (e.g. ``invalid_request``,
``catalog_invalid``, ``min_usdt_amount_requires_solana``);
``error.param`` names the offending field when applicable.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'401':
description: >-
Authentication failed. ``error.code`` distinguishes
``authentication_required`` (missing / malformed / unknown key) from
``expired_credential`` (key matched but past its ``expires_at``).
Rotate the key in the admin panel for the latter.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'403':
description: >-
The key is valid but lacks permission for this endpoint.
``error.code`` is ``forbidden_scope`` when the key is missing a
scope; ``account_pending_approval`` when the org is not yet active
for Connect.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'404':
description: >-
Resource not found in this tenant. Same envelope shape is returned
for genuinely-missing IDs and for cross-tenant accesses -- existence
under other tenants is not leakable.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'409':
description: >-
Conflict. Most commonly ``idempotency_conflict`` -- the same
``Idempotency-Key`` was reused with a different body. Generate a
fresh key or replay the original body.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'422':
description: >-
Validation failed. Runtime translates FastAPI / Pydantic validation
errors into the same Connect envelope you see on 400s; this status
is emitted when the request shape is structurally wrong (missing
required field, wrong type).
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'429':
description: >-
Rate limited. Back off and retry. ``error.code`` is
``rate_limited``; per-key throughput is documented via
``rate_limit_rps`` on the API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'500':
description: >-
Internal server error. ``error.code`` is ``internal_error``. The
request can usually be safely retried with the same
``Idempotency-Key``.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
'501':
description: >-
Endpoint is declared in the router but its implementation has not
shipped yet (``error.code = not_yet_available``). Pinned in the
schema so SDK generators emit the endpoint with a typed error rather
than skipping it.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectErrorEnvelope'
security:
- BearerAuth: []
components:
schemas:
ConnectErrorEnvelope:
properties:
error:
$ref: '#/components/schemas/ConnectErrorBody'
description: >-
Error details. Always present on a non-2xx response from
/connect/v1.
type: object
required:
- error
title: ConnectErrorEnvelope
description: |-
Top-level wrapper for every /connect/v1 failure response.
Wire shape::
{"error": {"type": ..., "code": ..., "message": ..., ...}}
The wrapper is intentional: it keeps error bodies syntactically
distinct from success bodies, so polymorphic partner code paths
that read the same JSON for both states can branch on the
presence of the ``error`` key.
ConnectErrorBody:
properties:
type:
type: string
title: Type
description: >-
Stripe-style error category. One of: ``invalid_request_error``,
``authentication_error``, ``not_found_error``, ``rate_limit_error``,
``idempotency_error``, ``api_error``. Stable across minor versions;
branch on this for top-level error routing.
examples:
- invalid_request_error
code:
type: string
title: Code
description: >-
Machine-stable identifier for the specific failure. More specific
than ``type``. Examples: ``invalid_request``,
``authentication_required``, ``expired_credential``,
``forbidden_scope``, ``account_pending_approval``,
``resource_not_found``, ``idempotency_conflict``, ``rate_limited``,
``internal_error``, ``not_yet_available``. Match on ``code`` in your
client's error handler -- never parse ``message``.
examples:
- authentication_required
message:
type: string
title: Message
description: >-
Human-readable explanation. Safe to surface in your own UI but may
be reworded between releases -- never branch on the string.
examples:
- >-
Missing or malformed Authorization header. Send: Authorization:
Bearer sk_live_... or sk_test_...
doc_url:
type: string
title: Doc Url
description: >-
Link to docs explaining this ``code``. Constructed as
``https://docs.zopay.cash/errors/``. Surface this in support
tickets so we can investigate without a round-trip.
examples:
- https://docs.zopay.cash/errors/authentication_required
param:
anyOf:
- type: string
- type: 'null'
title: Param
description: >-
Names the offending input field when the error is
input-shape-related (mostly ``invalid_request_error`` from 400 and
422). Absent on auth, scope, rate-limit, and internal errors.
examples:
- currencies
type: object
required:
- type
- code
- message
- doc_url
title: ConnectErrorBody
description: |-
The ``error`` object inside every /connect/v1 failure response.
Mirrors ``ConnectError.to_envelope()`` in
``app/api/connect/errors.py``. Field set is locked -- adding a
new field is a partner-visible contract change and requires a
coordinated docs + schema update.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: Connect API key (sk_live_… or sk_test_…)
description: >-
Paste your Connect API key (sk_live_… for production, sk_test_… for
sandbox) without the ``Bearer `` prefix. Mint and rotate keys from the
admin panel.
````