YooBankDocumentação pública
API docs by Redocly

YooBank Next API (0.8.0)

Download OpenAPI specification:

API-first foundation. GET /health is operational and unversioned. Authentication: cookie XOR bearer. CSRF required for cookie mutations. Privileged identities may receive HTTP 200 with status=mfa_required; that response is NOT an authenticated session (no cookie, no bearer token). MFA challenge tokens cannot call /auth/session. Merchant machine credentials use Authorization Bearer tokens of the form ybk_{32hex}{43base64url}. A ybk prefix never falls back to a human session. Machine credentials are limited to merchant.payin.create and merchant.payin.read. Public production API base: https://api.yoobank.net Hosted Checkout is https://pay.yoobank.net and is not this JSON API except GET /c/{token}/status.

Operational health

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "request_id": "string"
}

Authenticate a human identity

Request Body schema: application/json
required
email
required
string <email>
password
required
string [ 12 .. 128 ] characters
transport
required
string
Enum: "cookie" "bearer"

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "stringstring",
  • "transport": "cookie"
}

Response samples

Content type
application/json
Example
{
  • "status": "authenticated",
  • "identity": {
    },
  • "roles": [
    ],
  • "transport": "cookie",
  • "csrf_token": "string",
  • "token": "string",
  • "token_type": "Bearer"
}

Complete MFA challenge (TOTP or recovery code)

Request Body schema: application/json
required
mfa_challenge_token
required
string
code
required
string

Responses

Request samples

Content type
application/json
{
  • "mfa_challenge_token": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "status": "authenticated",
  • "identity": {
    },
  • "roles": [
    ],
  • "transport": "cookie",
  • "csrf_token": "string",
  • "token": "string",
  • "token_type": "Bearer"
}

Inspect current authenticated session

Authorizations:
cookieAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "identity": {
    },
  • "roles": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z",
  • "absolute_expires_at": "2019-08-24T14:15:22Z",
  • "mfa_satisfied": true,
  • "primary_authenticated_at": "2019-08-24T14:15:22Z",
  • "csrf_token": "string"
}

Revoke current session (idempotent)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "status": "logged_out"
}

Change password (revokes other sessions)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
current_password
required
string
new_password
required
string [ 12 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "current_password": "string",
  • "new_password": "stringstring"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

List own active sessions

Authorizations:
cookieAuthbearerAuth

Responses

Revoke one own session

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Revoke all other own sessions

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Start TOTP enrollment (secret returned once)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Confirm TOTP and receive recovery codes once

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Disable TOTP

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Regenerate recovery codes

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List identities

Requires identity.read

Authorizations:
cookieAuthbearerAuth

Responses

Create identity

Requires identity.create and MFA-satisfied recent session

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Read identity

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Disable identity and revoke sessions

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Enable identity (does not restore old sessions)

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Lock identity and revoke sessions

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Unlock identity (does not restore old sessions)

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Assign an existing catalog role

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Remove a role

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
role
required
string
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Read audit records

Requires audit.read. Indexed filters only. Pagination required.

Authorizations:
cookieAuthbearerAuth
query Parameters
actor
string <uuid>
event_type
string
target
string <uuid>
from
string <date-time>
to
string <date-time>
limit
integer [ 1 .. 100 ]
cursor
string

Responses

List merchants

Requires merchant.read. Exact filters on indexed columns only. CLOSED remains listed.

Authorizations:
cookieAuthbearerAuth
query Parameters
status
string
Enum: "inactive" "active" "suspended" "closed"
uuid
string <uuid>
display_name
string
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Create merchant (always inactive)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
display_name
required
string [ 1 .. 150 ] characters
legal_name
string or null [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "display_name": "string",
  • "legal_name": "string"
}

Response samples

Content type
application/json
{
  • "merchant": {
    }
}

Read merchant including CLOSED

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "merchant": {
    }
}

Activate merchant

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Deactivate merchant

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Suspend merchant

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Close merchant (terminal)

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List merchant memberships

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Ensure identity is attached

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
identity_uuid
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "identity_uuid": "625f3b1a-870d-4a79-a558-901ea431d4eb"
}

Ensure identity is detached

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
identity_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List merchant machine API credentials

Human platform_admin with privileged MFA. Lists key_id and status only. Never returns token, secret, or secret_hash. Machine bearer is forbidden (403).

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Create the merchant machine API credential

Human platform_admin with privileged MFA. At most one active credential per merchant. The plaintext token is returned once. Duplicate active create is 409.

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "credential_uuid": "17377ab6-a94f-4768-9f7f-939b5fbc9d4b",
  • "merchant_uuid": "ec27f24b-dbba-4c9a-aed0-9cec1c3b9e51",
  • "key_id": "stringstringstringstringstringst",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "token": "string"
}

Rotate the active merchant machine API credential

Human platform_admin with privileged MFA. Atomically revokes the previous active credential and issues a new token once. Rotate without an active credential is 409.

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "credential_uuid": "17377ab6-a94f-4768-9f7f-939b5fbc9d4b",
  • "merchant_uuid": "ec27f24b-dbba-4c9a-aed0-9cec1c3b9e51",
  • "key_id": "stringstringstringstringstringst",
  • "status": "active",
  • "created_at": "2019-08-24T14:15:22Z",
  • "token": "string"
}

Revoke a merchant machine API credential

Human platform_admin with privileged MFA. Machine bearer is forbidden (403).

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
credential_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List capability catalog

Authorizations:
cookieAuthbearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Enable a platform catalog capability

Authorizations:
cookieAuthbearerAuth
path Parameters
code
required
string
Example: crypto.payin
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Disable a platform catalog capability

Authorizations:
cookieAuthbearerAuth
path Parameters
code
required
string
Example: crypto.payin
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List merchant capability enablement

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Ensure merchant capability is enabled

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
code
required
string
Example: crypto.payin
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Ensure merchant capability is disabled

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
code
required
string
Example: crypto.payin
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List jurisdictions

Authorizations:
cookieAuthbearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

List versioned capability jurisdiction rules

Authorizations:
cookieAuthbearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Close the open rule and create a new version

Authorizations:
cookieAuthbearerAuth
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
capability
required
string
jurisdiction
required
string
effect
required
string
Enum: "allow" "deny"

Responses

Request samples

Content type
application/json
{
  • "capability": "crypto.payin",
  • "jurisdiction": "BR",
  • "effect": "allow"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Read merchant operating profile

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Ensure merchant operating profile

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
operating_mode
required
string
Enum: "non_custodial" "platform_custody" "hybrid"

Responses

Request samples

Content type
application/json
{
  • "operating_mode": "non_custodial"
}

List merchant financial policies

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Close the open policy for the scope and create a new version

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
scope
required
string
Enum: "payin" "payout" "custody" "settlement"
effect
required
string
Enum: "allow" "deny"

Responses

Request samples

Content type
application/json
{
  • "scope": "payin",
  • "effect": "allow"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Enable a financial policy

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
policy_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Disable a financial policy

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
policy_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List provider catalog

Authorizations:
cookieAuthbearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Read a provider

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List merchant provider bindings

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Ensure a merchant provider binding

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
provider_uuid
required
string <uuid>
capability
required
string
jurisdiction
required
string

Responses

Request samples

Content type
application/json
{
  • "provider_uuid": "3bed8db6-d8fa-463d-b321-c9d45dadd5e2",
  • "capability": "crypto.payin",
  • "jurisdiction": "BR"
}

Enable a merchant provider binding

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
binding_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Disable a merchant provider binding

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
binding_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

List merchant provider connections

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
offset
integer >= 0

Responses

Ensure a merchant provider connection

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
provider_uuid
required
string <uuid>
secret_reference
string

Responses

Request samples

Content type
application/json
{
  • "provider_uuid": "3bed8db6-d8fa-463d-b321-c9d45dadd5e2",
  • "secret_reference": "testvault://merchant/example/provider/credential-1"
}

Enable a merchant provider connection

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
connection_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Disable a merchant provider connection

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
connection_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Responses

Rotate a merchant provider connection secret reference

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
connection_uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Request Body schema: application/json
required
secret_reference
required
string

Responses

Request samples

Content type
application/json
{
  • "secret_reference": "testvault://merchant/example/provider/credential-2"
}

Create a merchant pay-in intent

Human merchant membership or merchant machine credential with merchant.payin.create. Path merchant UUID must match the machine credential merchant (mismatch is 403) before resource lookup. Cookie XOR bearer. CSRF required for cookie mutations. Financial authorization uses existing crypto.payin. Funds flow class is always merchant_controlled. Succeeded responses are 201, including idempotent replay. Request field for merchant correlation is reference (not merchant_reference). Do not send rail; routing selects it and returns it on 201. Idempotency-Key is required. Same key + same payload replays 201. Same key + different payload is 400.

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
header Parameters
X-CSRF-Token
string

Required for cookie-authenticated mutations.

Idempotency-Key
required
string [ 1 .. 64 ] characters
Request Body schema: application/json
required
asset
required
string
amount
required
string
jurisdiction
required
string = 2 characters
expires_at
required
string <date-time>
reference
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "asset": "usdt",
  • "amount": "1.25",
  • "jurisdiction": "st",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Response samples

Content type
application/json
{
  • "intent_uuid": "90bc1a1e-e438-4b5f-8358-bba429174bab",
  • "status": "created",
  • "asset": "string",
  • "rail": "string",
  • "expected_amount": "string",
  • "address": "string",
  • "allocation_reference": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

List merchant pay-in intents

Human merchant membership or merchant machine credential with merchant.payin.read. Path merchant UUID must match the machine credential merchant (mismatch is 403) before resource lookup. Cookie XOR bearer.

Authorizations:
cookieAuthbearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
limit
integer [ 1 .. 100 ]
Default: 20
offset
integer >= 0
Default: 0
status
string
Enum: "created" "awaiting_payment" "paid"
asset
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get single merchant pay-in intent

Human merchant membership or merchant machine credential with merchant.payin.read. Path merchant UUID must match the machine credential merchant (mismatch is 403) before lookup. Missing or cross-merchant intent is 404. Cookie XOR bearer.

Authorizations:
cookieAuthbearerAuth
path Parameters
merchant_uuid
required
string <uuid>
intent_uuid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "intent_uuid": "90bc1a1e-e438-4b5f-8358-bba429174bab",
  • "merchant_uuid": "ec27f24b-dbba-4c9a-aed0-9cec1c3b9e51",
  • "status": "created",
  • "asset": "usdt",
  • "rail": "bep20",
  • "expected_amount": "1.00000000",
  • "address": "0x1234567890abcdef1234567890abcdef12345678",
  • "reference": "order-12345",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Public YooCheckout payer-safe status

Narrow JSON for hosted checkout polling. Invalid token is a generic 404. paid is true only when the canonical pay-in intent status is paid. expired_for_payment is presentation-only and does not mutate PAY-IN. HTML checkout pages are not part of this API.

path Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "presentation_state": "select_method",
  • "description": "string",
  • "merchant_display_name": "string",
  • "expected_amount": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "paid": true,
  • "expired_for_payment": true,
  • "asset": "string",
  • "rail": "string",
  • "address": "string",
  • "pay_in_status": "created"
}