{ "openapi": "3.0.0", "info": { "contact": { "email": "support@yara.cash", "name": "Yara API Support" }, "description": "Create customers and multi-chain wallets, receive deposits, view account balances and transactions, and make payouts.", "license": { "name": "Proprietary" }, "title": "Yara External API - Public API", "version": "1.0" }, "paths": { "/health": { "get": { "description": "Returns process health.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } }, "summary": "Health check", "tags": [ "public.health" ] } }, "/ready": { "get": { "description": "Returns database readiness.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } } }, "summary": "Readiness check", "tags": [ "public.health" ] } }, "/v1/balance": { "get": { "description": "Returns your available and reserved USD balances. Pending deposits are unconfirmed and are not spendable until they confirm.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get merchant USD balance", "tags": [ "public.balance" ] } }, "/v1/chains": { "get": { "description": "Returns the currently configured capabilities for Base, Arbitrum, Polygon, Celo, BSC, Ethereum, Optimism, Solana, Bitcoin, and Tron.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainsResponse" } } } } }, "summary": "List supported chains", "tags": [ "public.chains" ] } }, "/v1/customers": { "get": { "description": "Lists your customers.", "parameters": [ { "description": "Exact merchant customer reference", "in": "query", "name": "external_reference", "schema": { "type": "string" } }, { "description": "Customer type", "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] } }, { "description": "Customer verification status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Created at or after this RFC3339 timestamp", "in": "query", "name": "created_from", "schema": { "type": "string" } }, { "description": "Created at or before this RFC3339 timestamp", "in": "query", "name": "created_to", "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List end customers", "tags": [ "public.customers" ] }, "post": { "description": "Creates a merchant-owned customer and provisions the corresponding verification profile.", "parameters": [ { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } }, "description": "Customer creation request", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create an end customer", "tags": [ "public.customers" ] } }, "/v1/customers/{customer_id}": { "get": { "description": "Returns one customer.", "parameters": [ { "description": "Customer ID", "in": "path", "name": "customer_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get an end customer", "tags": [ "public.customers" ] } }, "/v1/customers/{customer_id}/verification-submissions": { "get": { "description": "Lists immutable verification attempts for one merchant-owned customer.", "parameters": [ { "description": "Customer ID", "in": "path", "name": "customer_id", "required": true, "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVerificationSubmissionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List customer verification submissions", "tags": [ "public.customer-verification" ] }, "post": { "description": "Stores an immutable encrypted verification attempt, submits it for review, and returns the safe asynchronous submission state. A same-tier REQUIRES_REVIEW attempt accepts a corrected submission as a new attempt; unresolved DRAFT, SUBMITTED, or PENDING attempts must reconcile first.", "parameters": [ { "description": "Customer ID", "in": "path", "name": "customer_id", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVerificationSubmissionCreateRequest" } } }, "description": "Tier and customer-type-specific verification fields", "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVerificationSubmissionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Submit customer verification", "tags": [ "public.customer-verification" ] } }, "/v1/customers/{customer_id}/verification-submissions/{submission_id}": { "get": { "description": "Returns safe state for one verification attempt without returning the submitted KYC or KYB payload.", "parameters": [ { "description": "Customer ID", "in": "path", "name": "customer_id", "required": true, "schema": { "type": "string" } }, { "description": "Verification submission ID", "in": "path", "name": "submission_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerVerificationSubmissionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a customer verification submission", "tags": [ "public.customer-verification" ] } }, "/v1/customers/{customer_id}/virtual-accounts": { "get": { "description": "Lists USD virtual accounts created for one customer.", "parameters": [ { "description": "Customer ID", "in": "path", "name": "customer_id", "required": true, "schema": { "type": "string" } }, { "description": "Currency", "in": "query", "name": "currency", "schema": { "type": "string", "enum": [ "USD" ] } }, { "description": "Provisioning state", "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "PROVISIONING", "ACTIVE", "INACTIVE", "FAILED", "REQUIRES_REVIEW" ] } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List one customer's USD virtual accounts", "tags": [ "public.virtual-accounts" ] } }, "/v1/deposits": { "get": { "description": "Lists deposits received by your wallets. Each deposit includes its wallet_id and, when applicable, customer_id.", "parameters": [ { "description": "Chain", "in": "query", "name": "chain", "schema": { "type": "string" } }, { "description": "Deposit status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Transaction hash", "in": "query", "name": "tx_hash", "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List deposits", "tags": [ "public.deposits" ] } }, "/v1/deposits/{id}": { "get": { "description": "Returns one deposit, including its wallet_id and, when applicable, customer_id.", "parameters": [ { "description": "Deposit ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a deposit", "tags": [ "public.deposits" ] } }, "/v1/fees": { "get": { "description": "Returns the active merchant fee schedule.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeScheduleResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get active fees", "tags": [ "public.fees" ] } }, "/v1/rates": { "get": { "description": "Returns current USD conversion rates and expiry information.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RatesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get current rates", "tags": [ "public.rates" ] } }, "/v1/transactions": { "get": { "description": "Lists incoming deposits and outgoing payouts. Deposits include wallet_id and, when applicable, customer_id. Customer-funded payouts include customer_id. Use wallet_id to list deposits received by a particular wallet.", "parameters": [ { "description": "Source type", "in": "query", "name": "source_type", "schema": { "type": "string", "enum": [ "DEPOSIT", "TRANSFER" ] } }, { "description": "Transaction status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Wallet ID", "in": "query", "name": "wallet_id", "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List merchant transactions", "tags": [ "public.transactions" ] } }, "/v1/transfers": { "get": { "description": "Lists merchant transfer intents.", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List transfers", "tags": [ "public.transfers" ] }, "post": { "description": "Creates a payout from a valid quote. Account-funded payouts reserve funds immediately. Bank- or crypto-funded payouts return one-time funding instructions and begin processing after the required payment is received.", "parameters": [ { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreateRequest" } } }, "description": "Transfer creation request", "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Initiate a transfer", "tags": [ "public.transfers" ] } }, "/v1/transfers/quotes": { "post": { "description": "Creates a payout quote for a whitelisted recipient. USD bank payouts require an approved business profile and USD banking access. Bank- or crypto-funded payouts may identify an existing customer as the payer.", "parameters": [ { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferQuoteRequest" } } }, "description": "Transfer quote request", "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferQuoteResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Quote a transfer", "tags": [ "public.transfers" ] } }, "/v1/transfers/{id}": { "get": { "description": "Returns a single merchant transfer, including its funding intent and any provider-confirmed funding receipts.", "parameters": [ { "description": "Transfer ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a transfer", "tags": [ "public.transfers" ] } }, "/v1/transfers/{id}/funding": { "get": { "description": "Returns the immutable funding economics and the transfer-specific bank or crypto instructions. A pending intent without instructions is still being provisioned and may be polled.", "parameters": [ { "description": "Transfer ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferFundingResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get transfer funding details", "tags": [ "public.transfers" ] } }, "/v1/virtual-account-deposits": { "get": { "description": "Lists completed USD deposits received through your customers' virtual accounts, including the customer, fee, and credited amount.", "parameters": [ { "description": "Filter by merchant customer ID", "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "description": "Filter by virtual account ID", "in": "query", "name": "virtual_account_id", "schema": { "type": "string" } }, { "description": "Deposit state", "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "RECEIVED", "PROCESSING", "COMPLETED", "FAILED", "REQUIRES_REVIEW", "REVERSED" ] } }, { "description": "Exact provider deposit reference", "in": "query", "name": "provider_reference", "schema": { "type": "string" } }, { "description": "Created at or after this RFC3339 timestamp", "in": "query", "name": "from", "schema": { "type": "string" } }, { "description": "Created before this RFC3339 timestamp", "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDepositListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List customer USD virtual-account deposits", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-account-deposits/{deposit_id}": { "get": { "description": "Returns one completed USD virtual-account deposit, including its customer, fee, and credited amount.", "parameters": [ { "description": "Virtual-account deposit ID", "in": "path", "name": "deposit_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDepositDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a customer USD virtual-account deposit", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-accounts": { "get": { "description": "Lists your USD virtual accounts. Account details are masked in collection responses.", "parameters": [ { "description": "Filter by merchant customer ID", "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "description": "Currency", "in": "query", "name": "currency", "schema": { "type": "string", "enum": [ "USD" ] } }, { "description": "Provisioning state", "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "PROVISIONING", "ACTIVE", "INACTIVE", "FAILED", "REQUIRES_REVIEW" ] } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List customer USD virtual accounts", "tags": [ "public.virtual-accounts" ] }, "post": { "description": "Creates or returns the existing live USD virtual account for a Tier-2-verified customer. The response is masked; retrieve the account by ID for full active deposit instructions.", "parameters": [ { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountCreateRequest" } } }, "description": "Virtual account creation request", "required": true }, "responses": { "200": { "description": "Existing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountSummaryResponse" } } } }, "201": { "description": "Created account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountSummaryResponse" } } } }, "202": { "description": "Provisioning account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountSummaryResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a customer USD virtual account", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-accounts/{virtual_account_id}": { "get": { "description": "Returns one merchant-owned virtual account. Full deposit instructions are returned only while the account is ACTIVE and the response must not be cached.", "parameters": [ { "description": "Virtual account ID", "in": "path", "name": "virtual_account_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "description": "no-store", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VirtualAccountDetailResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a customer USD virtual account", "tags": [ "public.virtual-accounts" ] } }, "/v1/wallets": { "get": { "description": "Lists your wallets and their receive addresses for each chain.", "parameters": [ { "description": "Customer ID", "in": "query", "name": "customer_id", "schema": { "type": "string" } }, { "description": "Destination chain", "in": "query", "name": "chain", "schema": { "type": "string" } }, { "description": "Wallet status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Search label, address, or wallet ID", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List wallets", "tags": [ "public.wallets" ] }, "post": { "description": "Creates one wallet and generates a receive address for every supported deposit chain.", "parameters": [ { "description": "Idempotency key", "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletCreateRequest" } } }, "description": "Wallet creation request", "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a wallet", "tags": [ "public.wallets" ] } }, "/v1/wallets/{id}": { "get": { "description": "Returns one wallet and its receive address for each supported chain.", "parameters": [ { "description": "Wallet ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get a wallet", "tags": [ "public.wallets" ] } }, "/v1/webhook-events": { "get": { "description": "Lists your webhook events and their delivery status. deposit.confirmed events identify the deposit, wallet, optional customer, chain, asset, transaction, and credited amount.", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List webhook events", "tags": [ "public.webhooks" ] } } }, "servers": [ { "url": "https://api.yara.cash" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "description": "Your Yara API key. Send it in the X-Yara-API-Key header.", "in": "header", "name": "X-Yara-API-Key", "type": "apiKey" } }, "schemas": { "Balance": { "properties": { "available": { "example": "1250.500000", "type": "string" }, "currency": { "example": "USD", "type": "string" }, "ledger_timestamp": { "example": "2026-06-16T03:05:00Z", "type": "string" }, "pending_deposits": { "example": "25.000000", "type": "string" }, "reserved": { "example": "100.000000", "type": "string" } }, "type": "object" }, "BalanceResponse": { "properties": { "data": { "$ref": "#/components/schemas/Balance" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "Chain": { "properties": { "assets": { "example": [ "USDC", "USDT" ], "items": { "type": "string" }, "type": "array" }, "chain": { "example": "BASE", "type": "string" }, "deposit_enabled": { "example": true, "type": "boolean" }, "transfer_enabled": { "example": true, "type": "boolean" } }, "type": "object" }, "ChainsData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Chain" }, "type": "array" } }, "type": "object" }, "ChainsResponse": { "properties": { "data": { "$ref": "#/components/schemas/ChainsData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "CryptoFee": { "properties": { "deposit_fee_percentage": { "example": "0", "type": "string" }, "withdrawal_fee": { "$ref": "#/components/schemas/CryptoWithdrawalFee" } }, "type": "object" }, "CryptoWithdrawalFee": { "properties": { "arbitrum": { "example": "0.1", "type": "string" }, "base": { "example": "0.1", "type": "string" }, "bitcoin": { "example": "0.1", "type": "string" }, "bsc": { "example": "0.1", "type": "string" }, "celo": { "example": "0.1", "type": "string" }, "ethereum": { "example": "0.5", "type": "string" }, "optimism": { "example": "0.1", "type": "string" }, "polygon": { "example": "0.1", "type": "string" }, "solana": { "example": "0.1", "type": "string" }, "tron": { "example": "0.1", "type": "string" } }, "type": "object" }, "CustomerAssociatedPerson": { "properties": { "birth_date": { "example": "1990-05-15", "type": "string" }, "documents": { "items": { "$ref": "#/components/schemas/CustomerVerificationDocument" }, "type": "array" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "has_control": { "type": "boolean" }, "has_ownership": { "type": "boolean" }, "identifying_information": { "items": { "$ref": "#/components/schemas/CustomerIdentifyingInformation" }, "type": "array" }, "is_director": { "type": "boolean" }, "is_signer": { "type": "boolean" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "nationality": { "example": "NGA", "type": "string" }, "ownership_percentage": { "type": "integer" }, "phone": { "type": "string" }, "relationship_established_at": { "type": "string" }, "residential_address": { "$ref": "#/components/schemas/CustomerVerificationAddress" }, "title": { "type": "string" } }, "type": "object" }, "CustomerCreateRequest": { "properties": { "business_name": { "example": "Ada Labs Ltd", "type": "string" }, "email": { "example": "customer@example.com", "type": "string" }, "external_reference": { "example": "customer_001", "type": "string" }, "first_name": { "example": "Ada", "type": "string" }, "last_name": { "example": "Lovelace", "type": "string" }, "type": { "enum": [ "INDIVIDUAL", "BUSINESS" ], "example": "INDIVIDUAL", "type": "string" } }, "type": "object" }, "CustomerIdentifyingInformation": { "properties": { "expiration": { "example": "2030-01-01", "type": "string" }, "image_back": { "type": "string" }, "image_front": { "type": "string" }, "issuing_country": { "example": "NGA", "type": "string" }, "number": { "type": "string" }, "type": { "enum": [ "passport", "drivers_license", "national_id", "tin" ], "type": "string" } }, "type": "object" }, "CustomerListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/model.CustomerAPIResponse" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "CustomerListResponse": { "properties": { "data": { "$ref": "#/components/schemas/CustomerListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "CustomerResponse": { "properties": { "data": { "$ref": "#/components/schemas/model.CustomerAPIResponse" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "CustomerVerificationAddress": { "properties": { "city": { "type": "string" }, "country": { "example": "NGA", "type": "string" }, "postal_code": { "type": "string" }, "street_line_1": { "type": "string" }, "subdivision": { "type": "string" } }, "type": "object" }, "CustomerVerificationDocument": { "properties": { "file": { "type": "string" }, "purposes": { "items": { "enum": [ "proof_of_address", "proof_of_source_of_funds" ], "type": "string" }, "type": "array" } }, "type": "object" }, "CustomerVerificationSubmissionCreateRequest": { "properties": { "account_purpose": { "type": "string" }, "account_purpose_other": { "type": "string" }, "acting_as_intermediary": { "type": "boolean" }, "associated_persons": { "items": { "$ref": "#/components/schemas/CustomerAssociatedPerson" }, "type": "array" }, "birth_date": { "example": "1990-05-15", "type": "string" }, "business_description": { "type": "string" }, "business_industry": { "items": { "type": "string" }, "type": "array" }, "business_legal_name": { "type": "string" }, "business_type": { "type": "string" }, "bvn": { "example": "22345678901", "type": "string" }, "conducts_money_services": { "type": "boolean" }, "conducts_money_services_description": { "type": "string" }, "conducts_money_services_using_bridge": { "type": "boolean" }, "documents": { "items": { "$ref": "#/components/schemas/CustomerVerificationDocument" }, "type": "array" }, "employment_status": { "type": "string" }, "estimated_annual_revenue_usd": { "type": "string" }, "expected_monthly_payments_usd": { "type": "string" }, "has_material_intermediary_ownership": { "type": "boolean" }, "high_risk_activities": { "items": { "type": "string" }, "type": "array" }, "high_risk_activities_explanation": { "type": "string" }, "identifying_information": { "items": { "$ref": "#/components/schemas/CustomerIdentifyingInformation" }, "type": "array" }, "image_url": { "example": "https://files.example.com/selfie.jpg", "type": "string" }, "is_dao": { "type": "boolean" }, "most_recent_occupation": { "type": "string" }, "nationality": { "example": "NGA", "type": "string" }, "operates_in_prohibited_countries": { "type": "boolean" }, "other_websites": { "items": { "type": "string" }, "type": "array" }, "ownership_threshold": { "type": "integer" }, "physical_address": { "$ref": "#/components/schemas/CustomerVerificationAddress" }, "primary_website": { "type": "string" }, "registered_address": { "$ref": "#/components/schemas/CustomerVerificationAddress" }, "residential_address": { "$ref": "#/components/schemas/CustomerVerificationAddress" }, "source_of_funds": { "type": "string" }, "source_of_funds_description": { "type": "string" }, "tier": { "allOf": [ { "$ref": "#/components/schemas/model.VerificationTier" } ], "enum": [ "TIER_1", "TIER_2" ], "example": "TIER_1" } }, "type": "object" }, "CustomerVerificationSubmissionListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/model.VerificationSubmissionAPIResponse" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "CustomerVerificationSubmissionListResponse": { "properties": { "data": { "$ref": "#/components/schemas/CustomerVerificationSubmissionListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "CustomerVerificationSubmissionResponse": { "properties": { "data": { "$ref": "#/components/schemas/model.VerificationSubmissionAPIResponse" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "Deposit": { "properties": { "amount": { "example": "100.000000", "type": "string" }, "amount_raw": { "example": "100000000", "type": "string" }, "amount_usd": { "example": "100.000000", "type": "string" }, "asset": { "example": "USDC", "type": "string" }, "chain": { "example": "BASE", "type": "string" }, "confirmations": { "example": 12, "type": "integer" }, "contract_address": { "example": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "type": "string" }, "created_at": { "example": "2026-06-16T03:00:00Z", "type": "string" }, "customer_id": { "example": "88df63d0-216d-45aa-a027-3efbd3fa95f1", "type": "string" }, "fee_usd": { "example": "0.000000", "type": "string" }, "from_address": { "example": "0x9a5f8dcb7b0d3f2eb59f20e30aa7d0b93af8abcd", "type": "string" }, "id": { "example": "741eec3c-5596-45b6-a88d-3627a236192f", "type": "string" }, "merchant_id": { "example": "8fca3c8d-5d48-4f4d-a286-2ef6d1cd2f01", "type": "string" }, "net_amount_usd": { "example": "100.000000", "type": "string" }, "status": { "example": "CONFIRMED", "type": "string" }, "to_address": { "example": "0x24c3538f4d5302ac58a4c05e7496f4ca4bb551d4", "type": "string" }, "tx_hash": { "example": "0x4f5d2d7a2c8a95c3", "type": "string" }, "wallet_id": { "example": "7f7c6713-3fdc-43fb-a9e7-d3c364e7c763", "type": "string" } }, "type": "object" }, "DepositListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Deposit" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "DepositListResponse": { "properties": { "data": { "$ref": "#/components/schemas/DepositListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "DepositResponse": { "properties": { "data": { "$ref": "#/components/schemas/Deposit" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "ErrorResponse": { "properties": { "data": { "additionalProperties": {}, "type": "object" }, "error": { "example": "validation_error", "type": "string" }, "message": { "example": "invalid JSON body", "type": "string" }, "status": { "enum": [ "error" ], "example": "error", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "FeeSchedule": { "properties": { "crypto": { "$ref": "#/components/schemas/CryptoFee" }, "id": { "example": "b21df7bd-9b49-44f9-9eea-950536b68f81", "type": "string" }, "ngn": { "$ref": "#/components/schemas/NGNFee" }, "status": { "example": "ACTIVE", "type": "string" }, "usd_bank": { "$ref": "#/components/schemas/USDBankFee" } }, "type": "object" }, "FeeScheduleResponse": { "properties": { "data": { "$ref": "#/components/schemas/FeeSchedule" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "HealthResponse": { "properties": { "environment": { "example": "dev", "type": "string" }, "service": { "example": "yara-external-api", "type": "string" }, "status": { "example": "ok", "type": "string" }, "time": { "example": "2026-06-16T03:00:00Z", "type": "string" } }, "type": "object" }, "MaskedVirtualAccountDepositInstructions": { "properties": { "account_number": { "type": "string" }, "account_type": { "type": "string" }, "bank_name": { "type": "string" } }, "type": "object" }, "NGNFee": { "properties": { "deposit_fee_cap": { "example": "0", "type": "string" }, "deposit_fee_percentage": { "example": "0", "type": "string" }, "withdrawal_fee": { "example": "100", "type": "string" } }, "type": "object" }, "Rate": { "properties": { "expires_at": { "example": "2026-06-16T03:05:00Z", "type": "string" }, "from_currency": { "example": "USD", "type": "string" }, "rate": { "example": "1500", "type": "string" }, "to_currency": { "example": "NGN", "type": "string" } }, "type": "object" }, "RatesData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Rate" }, "type": "array" } }, "type": "object" }, "RatesResponse": { "properties": { "data": { "$ref": "#/components/schemas/RatesData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "ReadyResponse": { "properties": { "error": { "example": "database ping failed", "type": "string" }, "status": { "example": "ready", "type": "string" } }, "type": "object" }, "Transaction": { "properties": { "amount_usd": { "example": "10.050000", "type": "string" }, "currency": { "example": "USD", "type": "string" }, "customer_id": { "example": "88df63d0-216d-45aa-a027-3efbd3fa95f1", "type": "string" }, "direction": { "example": "DEBIT", "type": "string" }, "fee_usd": { "example": "0.066667", "type": "string" }, "id": { "example": "98bf1b5c-b741-430b-9e4b-5edae2eb7919", "type": "string" }, "net_amount_usd": { "example": "10.000000", "type": "string" }, "occurred_at": { "example": "2026-06-16T03:00:00Z", "type": "string" }, "reference": { "example": "merchant-transfer-001", "type": "string" }, "source_id": { "example": "76179a66-8695-47fd-bca4-310eaa816077", "type": "string" }, "source_type": { "example": "TRANSFER", "type": "string" }, "status": { "example": "RESERVED", "type": "string" }, "wallet_id": { "example": "7f7c6713-3fdc-43fb-a9e7-d3c364e7c763", "type": "string" } }, "type": "object" }, "TransactionListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Transaction" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "TransactionListResponse": { "properties": { "data": { "$ref": "#/components/schemas/TransactionListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "Transfer": { "properties": { "created_at": { "example": "2026-06-16T03:00:00Z", "type": "string" }, "customer_id": { "example": "4d0a971f-a7ab-4a2f-b635-7a43055edaf0", "type": "string" }, "destination_amount": { "$ref": "#/components/schemas/TransferAmount" }, "destination_rail": { "example": "US_BANK_ACCOUNT", "type": "string" }, "funding": { "$ref": "#/components/schemas/TransferFundingIntent" }, "funding_method": { "example": "BALANCE", "type": "string" }, "funding_receipts": { "items": { "$ref": "#/components/schemas/TransferFundingReceipt" }, "type": "array" }, "id": { "example": "76179a66-8695-47fd-bca4-310eaa816077", "type": "string" }, "quote_id": { "example": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3", "type": "string" }, "recipient_id": { "example": "3bf24579-a35a-4ba9-a936-5df9c1d809f9", "type": "string" }, "reference": { "example": "merchant-transfer-001", "type": "string" }, "status": { "example": "RESERVED", "type": "string" }, "total_debit": { "$ref": "#/components/schemas/TransferAmount" }, "transfer_fee": { "$ref": "#/components/schemas/TransferAmount" }, "updated_at": { "example": "2026-06-16T03:01:00Z", "type": "string" } }, "type": "object" }, "TransferAmount": { "properties": { "asset": { "example": "USDC", "type": "string" }, "currency": { "example": "USD", "type": "string" }, "network": { "example": "BASE", "type": "string" }, "value": { "example": "100.00", "type": "string" } }, "type": "object" }, "TransferBankFundingInstructions": { "properties": { "account_name": { "example": "Yara", "type": "string" }, "account_number": { "example": "1234567890", "type": "string" }, "bank_code": { "example": "035", "type": "string" }, "bank_name": { "example": "Wema Bank", "type": "string" }, "narration": { "example": "funding-76179a66869547fdbca4310eaa816077", "type": "string" }, "reference": { "example": "funding-76179a66869547fdbca4310eaa816077", "type": "string" } }, "type": "object" }, "TransferCreateRequest": { "properties": { "quote_id": { "example": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3", "type": "string" }, "reference": { "example": "merchant-transfer-001", "type": "string" } }, "type": "object" }, "TransferCryptoFundingInstructions": { "properties": { "address": { "example": "0x1234", "type": "string" }, "asset": { "example": "USDC", "type": "string" }, "memo": { "type": "string" }, "network": { "example": "BASE", "type": "string" }, "reference": { "example": "funding-76179a66869547fdbca4310eaa816077", "type": "string" } }, "type": "object" }, "TransferFunding": { "properties": { "customer_id": { "example": "4d0a971f-a7ab-4a2f-b635-7a43055edaf0", "type": "string" }, "funding": { "$ref": "#/components/schemas/TransferFundingQuote" }, "intent": { "$ref": "#/components/schemas/TransferFundingIntent" }, "transfer_id": { "example": "76179a66-8695-47fd-bca4-310eaa816077", "type": "string" }, "transfer_status": { "example": "AWAITING_MERCHANT_FUNDING", "type": "string" } }, "type": "object" }, "TransferFundingFlag": { "properties": { "code": { "example": "AMOUNT_MISMATCH", "type": "string" }, "message": { "example": "Funding amount does not match the expected amount", "type": "string" } }, "type": "object" }, "TransferFundingIntent": { "properties": { "bank_transfer": { "$ref": "#/components/schemas/TransferBankFundingInstructions" }, "crypto_deposit": { "$ref": "#/components/schemas/TransferCryptoFundingInstructions" }, "expires_at": { "type": "string" }, "flag": { "$ref": "#/components/schemas/TransferFundingFlag" }, "id": { "type": "string" }, "method": { "example": "BANK_TRANSFER", "type": "string" }, "payer": { "$ref": "#/components/schemas/TransferFundingPayer" }, "purpose": { "example": "TRANSFER_JIT", "type": "string" }, "required_amount": { "$ref": "#/components/schemas/TransferAmount" }, "reusable": { "example": false, "type": "boolean" }, "status": { "example": "PENDING", "type": "string" } }, "type": "object" }, "TransferFundingPayer": { "properties": { "customer_id": { "example": "4d0a971f-a7ab-4a2f-b635-7a43055edaf0", "type": "string" }, "type": { "example": "CUSTOMER", "type": "string" } }, "type": "object" }, "TransferFundingQuote": { "properties": { "expires_at": { "example": "2026-06-16T03:05:00Z", "type": "string" }, "fee": { "$ref": "#/components/schemas/TransferAmount" }, "method": { "example": "BANK_TRANSFER", "type": "string" }, "mode": { "example": "TRANSFER_JIT", "type": "string" }, "payer": { "$ref": "#/components/schemas/TransferFundingPayer" }, "rate": { "$ref": "#/components/schemas/TransferFundingRate" }, "required_amount": { "$ref": "#/components/schemas/TransferAmount" } }, "type": "object" }, "TransferFundingRate": { "properties": { "base_currency": { "example": "USD", "type": "string" }, "quote_currency": { "example": "NGN", "type": "string" }, "value": { "example": "1600", "type": "string" } }, "type": "object" }, "TransferFundingReceipt": { "properties": { "customer_id": { "example": "4d0a971f-a7ab-4a2f-b635-7a43055edaf0", "type": "string" }, "expected_amount": { "$ref": "#/components/schemas/TransferAmount" }, "fee_usd": { "$ref": "#/components/schemas/TransferAmount" }, "flag": { "$ref": "#/components/schemas/TransferFundingFlag" }, "gross_usd": { "$ref": "#/components/schemas/TransferAmount" }, "id": { "type": "string" }, "method": { "example": "CRYPTO_DEPOSIT", "type": "string" }, "net_usd": { "$ref": "#/components/schemas/TransferAmount" }, "provider_transaction_id": { "type": "string" }, "received_amount": { "$ref": "#/components/schemas/TransferAmount" }, "received_at": { "type": "string" }, "status": { "example": "CREDITED", "type": "string" }, "variance_amount": { "$ref": "#/components/schemas/TransferAmount" } }, "type": "object" }, "TransferFundingResponse": { "properties": { "data": { "$ref": "#/components/schemas/TransferFunding" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "TransferFundingSourceRequest": { "properties": { "asset": { "example": "USDC", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "method": { "example": "BANK_TRANSFER", "type": "string" }, "network": { "example": "BASE", "type": "string" }, "payer_customer_id": { "example": "4d0a971f-a7ab-4a2f-b635-7a43055edaf0", "type": "string" } }, "type": "object" }, "TransferListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Transfer" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "TransferListResponse": { "properties": { "data": { "$ref": "#/components/schemas/TransferListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "TransferQuote": { "properties": { "destination_amount": { "$ref": "#/components/schemas/TransferAmount" }, "destination_rail": { "example": "US_BANK_ACCOUNT", "type": "string" }, "expires_at": { "example": "2026-06-16T03:05:00Z", "type": "string" }, "funding": { "$ref": "#/components/schemas/TransferFundingQuote" }, "id": { "example": "0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3", "type": "string" }, "status": { "example": "ACTIVE", "type": "string" }, "total_debit": { "$ref": "#/components/schemas/TransferAmount" }, "transfer_fee": { "$ref": "#/components/schemas/TransferAmount" } }, "type": "object" }, "TransferQuoteAmountRequest": { "properties": { "currency": { "example": "USD", "type": "string" }, "value": { "example": "100.00", "type": "string" } }, "type": "object" }, "TransferQuoteRequest": { "properties": { "amount": { "$ref": "#/components/schemas/TransferQuoteAmountRequest" }, "funding_source": { "$ref": "#/components/schemas/TransferFundingSourceRequest" }, "recipient_id": { "example": "3bf24579-a35a-4ba9-a936-5df9c1d809f9", "type": "string" } }, "type": "object" }, "TransferQuoteResponse": { "properties": { "data": { "$ref": "#/components/schemas/TransferQuote" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "TransferResponse": { "properties": { "data": { "$ref": "#/components/schemas/Transfer" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "USDBankFee": { "properties": { "deposit_fee_cap": { "example": "0", "type": "string" }, "deposit_fee_percentage": { "example": "0.25", "type": "string" }, "withdrawal_fee_percentage": { "example": "0.4", "type": "string" } }, "type": "object" }, "VirtualAccountCreateRequest": { "properties": { "currency": { "enum": [ "USD" ], "example": "USD", "type": "string" }, "customer_id": { "example": "5ec10df5-acde-4e95-926c-2174279cf2fd", "type": "string" } }, "required": [ "customer_id" ], "type": "object" }, "VirtualAccountCurrency": { "enum": [ "USD" ], "type": "string", "x-enum-varnames": [ "CurrencyUSD" ] }, "VirtualAccountDepositDetailResponse": { "properties": { "data": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_virtual_account_deposit_model.ReadProjection" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "VirtualAccountDepositInstructions": { "properties": { "account_type": { "type": "string" }, "bank_account_number": { "type": "string" }, "bank_address": { "type": "string" }, "bank_beneficiary_address": { "type": "string" }, "bank_beneficiary_name": { "type": "string" }, "bank_name": { "type": "string" }, "bank_routing_number": { "type": "string" }, "bic": { "type": "string" }, "deposit_message": { "type": "string" }, "iban": { "type": "string" }, "payment_rails": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "VirtualAccountDepositListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_virtual_account_deposit_model.ReadProjection" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "VirtualAccountDepositListResponse": { "properties": { "data": { "$ref": "#/components/schemas/VirtualAccountDepositListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "VirtualAccountDetail": { "properties": { "created_at": { "type": "string" }, "currency": { "$ref": "#/components/schemas/VirtualAccountCurrency" }, "customer_id": { "type": "string" }, "deposit_instructions": { "$ref": "#/components/schemas/VirtualAccountDepositInstructions" }, "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/VirtualAccountStatus" }, "supported_rails": { "items": { "type": "string" }, "type": "array" }, "updated_at": { "type": "string" } }, "type": "object" }, "VirtualAccountDetailResponse": { "properties": { "data": { "$ref": "#/components/schemas/VirtualAccountDetail" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "VirtualAccountListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/VirtualAccountSummary" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "VirtualAccountListResponse": { "properties": { "data": { "$ref": "#/components/schemas/VirtualAccountListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "VirtualAccountStatus": { "enum": [ "PROVISIONING", "ACTIVE", "INACTIVE", "FAILED", "REQUIRES_REVIEW" ], "type": "string", "x-enum-varnames": [ "StatusProvisioning", "StatusActive", "StatusInactive", "StatusFailed", "StatusRequiresReview" ] }, "VirtualAccountSummary": { "properties": { "created_at": { "type": "string" }, "currency": { "$ref": "#/components/schemas/VirtualAccountCurrency" }, "customer_id": { "type": "string" }, "deposit_instructions": { "$ref": "#/components/schemas/MaskedVirtualAccountDepositInstructions" }, "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/VirtualAccountStatus" }, "supported_rails": { "items": { "type": "string" }, "type": "array" }, "updated_at": { "type": "string" } }, "type": "object" }, "VirtualAccountSummaryResponse": { "properties": { "data": { "$ref": "#/components/schemas/VirtualAccountSummary" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "Wallet": { "properties": { "created_at": { "example": "2026-08-17T10:00:00Z", "type": "string" }, "customer_id": { "example": "5ec10df5-acde-4e95-926c-2174279cf2fd", "type": "string" }, "destinations": { "items": { "$ref": "#/components/schemas/WalletDestination" }, "type": "array" }, "id": { "example": "7f7c6713-3fdc-43fb-a9e7-d3c364e7c763", "type": "string" }, "label": { "example": "Customer receipts", "type": "string" }, "merchant_id": { "example": "8fca3c8d-5d48-4f4d-a286-2ef6d1cd2f01", "type": "string" }, "status": { "example": "ACTIVE", "type": "string" }, "updated_at": { "example": "2026-08-17T10:00:02Z", "type": "string" } }, "type": "object" }, "WalletCreateRequest": { "properties": { "customer_id": { "example": "5ec10df5-acde-4e95-926c-2174279cf2fd", "type": "string" }, "label": { "example": "Customer receipts", "type": "string" } }, "type": "object" }, "WalletDestination": { "properties": { "address": { "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "type": "string" }, "chain": { "example": "BASE", "type": "string" }, "failure_reason": { "example": "provider unavailable", "type": "string" }, "id": { "example": "ea38c60e-7a0b-44f6-bdf0-8ec13a7e471a", "type": "string" }, "last_attempted_at": { "example": "2026-08-17T10:00:00Z", "type": "string" }, "provisioned_at": { "example": "2026-08-17T10:00:02Z", "type": "string" }, "status": { "example": "ACTIVE", "type": "string" } }, "type": "object" }, "WalletListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/Wallet" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "WalletListResponse": { "properties": { "data": { "$ref": "#/components/schemas/WalletListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "WalletResponse": { "properties": { "data": { "$ref": "#/components/schemas/Wallet" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "WebhookEvent": { "properties": { "created_at": { "example": "2026-08-03T12:05:00Z", "type": "string" }, "event_type": { "example": "customer.verification.approved", "type": "string" }, "id": { "example": "d723cab9-1ad4-4d4d-821f-6704d834d575", "type": "string" }, "payload": { "description": "Payload is event-specific. For deposit.confirmed it contains deposit_id, wallet_id,\noptional customer_id, chain, asset, transaction details, and credited USD amounts.", "type": "object" }, "resource_id": { "example": "945eb980-3420-4454-9784-ebb0050f3393", "type": "string" }, "resource_type": { "example": "customer_verification_submission", "type": "string" }, "status": { "enum": [ "PENDING", "DISPATCHED", "SKIPPED" ], "example": "DISPATCHED", "type": "string" } }, "type": "object" }, "WebhookEventListData": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookEvent" }, "type": "array" }, "limit": { "example": 50, "type": "integer" }, "page": { "example": 1, "type": "integer" }, "total": { "example": 42, "type": "integer" }, "total_pages": { "example": 1, "type": "integer" } }, "type": "object" }, "WebhookEventListResponse": { "properties": { "data": { "$ref": "#/components/schemas/WebhookEventListData" }, "error": { "type": "string" }, "message": { "example": "resource retrieved", "type": "string" }, "status": { "enum": [ "success" ], "example": "success", "type": "string" } }, "required": [ "data", "error", "message", "status" ], "type": "object" }, "github_com_yaracash_yara-api_internal_customer_model.Status": { "enum": [ "PROVISIONING", "CREATED", "TIER_1_PENDING", "TIER_1_COMPLETE", "TIER_2_PENDING", "VERIFIED", "REJECTED", "REQUIRES_REVIEW", "SUSPENDED" ], "type": "string", "x-enum-varnames": [ "StatusProvisioning", "StatusCreated", "StatusTier1Pending", "StatusTier1Complete", "StatusTier2Pending", "StatusVerified", "StatusRejected", "StatusRequiresReview", "StatusSuspended" ] }, "github_com_yaracash_yara-api_internal_customer_model.Type": { "enum": [ "INDIVIDUAL", "BUSINESS" ], "type": "string", "x-enum-varnames": [ "TypeIndividual", "TypeBusiness" ] }, "github_com_yaracash_yara-api_internal_virtual_account_deposit_model.Currency": { "enum": [ "USD" ], "type": "string", "x-enum-varnames": [ "CurrencyUSD" ] }, "github_com_yaracash_yara-api_internal_virtual_account_deposit_model.ReadProjection": { "properties": { "amount": { "type": "number" }, "created_at": { "type": "string" }, "credited_at": { "type": "string" }, "currency": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_virtual_account_deposit_model.Currency" }, "customer_id": { "type": "string" }, "fee": { "$ref": "#/components/schemas/model.FeeSnapshot" }, "id": { "type": "string" }, "merchant_credit_amount": { "type": "number" }, "provider_created_at": { "type": "string" }, "provider_reference": { "type": "string" }, "reversed_at": { "type": "string" }, "status": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_virtual_account_deposit_model.Status" }, "updated_at": { "type": "string" }, "virtual_account_id": { "type": "string" } }, "type": "object" }, "github_com_yaracash_yara-api_internal_virtual_account_deposit_model.Status": { "enum": [ "RECEIVED", "PROCESSING", "COMPLETED", "FAILED", "REQUIRES_REVIEW", "REVERSED" ], "type": "string", "x-enum-varnames": [ "StatusReceived", "StatusProcessing", "StatusCompleted", "StatusFailed", "StatusRequiresReview", "StatusReversed" ] }, "model.CustomerAPIResponse": { "properties": { "business_name": { "type": "string" }, "capabilities": { "additionalProperties": { "type": "string" }, "type": "object" }, "created_at": { "type": "string" }, "email": { "type": "string" }, "external_reference": { "type": "string" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "rejection_reasons": { "items": { "type": "string" }, "type": "array" }, "status": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_customer_model.Status" }, "tier_1_complete": { "type": "boolean" }, "tier_2_complete": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_customer_model.Type" }, "updated_at": { "type": "string" } }, "type": "object" }, "model.FeeSnapshot": { "properties": { "amount": { "type": "number" }, "cap": { "type": "number" }, "percentage": { "type": "number" } }, "type": "object" }, "model.VerificationSubmissionAPIResponse": { "properties": { "completed_at": { "type": "string" }, "created_at": { "type": "string" }, "customer_id": { "type": "string" }, "customer_type": { "$ref": "#/components/schemas/github_com_yaracash_yara-api_internal_customer_model.Type" }, "id": { "type": "string" }, "rejection_reasons": { "items": { "type": "string" }, "type": "array" }, "status": { "$ref": "#/components/schemas/model.VerificationSubmissionStatus" }, "submitted_at": { "type": "string" }, "tier": { "$ref": "#/components/schemas/model.VerificationTier" }, "updated_at": { "type": "string" } }, "type": "object" }, "model.VerificationSubmissionStatus": { "enum": [ "DRAFT", "SUBMITTED", "PENDING", "VERIFIED", "REJECTED", "REQUIRES_REVIEW" ], "type": "string", "x-enum-varnames": [ "VerificationSubmissionStatusDraft", "VerificationSubmissionStatusSubmitted", "VerificationSubmissionStatusPending", "VerificationSubmissionStatusVerified", "VerificationSubmissionStatusRejected", "VerificationSubmissionStatusRequiresReview" ] }, "model.VerificationTier": { "enum": [ "TIER_1", "TIER_2" ], "type": "string", "x-enum-varnames": [ "VerificationTier1", "VerificationTier2" ] } } } }