{ "swagger": "2.0", "info": { "contact": { "email": "api@daya.co", "name": "Daya API Support" }, "description": "Daya External API provides endpoints for managing crypto onramp services, webhooks, and exchange rates.\nThis API supports both public and internal operations with different authentication schemes.", "license": { "name": "Proprietary", "url": "https://daya.co/license" }, "title": "Daya External API - Public API", "version": "1.0" }, "host": "api.daya.co", "basePath": "/", "paths": { "/v1/banks": { "get": { "description": "Lists supported Nigerian banks with their codes and names", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListBanksResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Integration failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Banks", "tags": [ "public.recipients" ] } }, "/v1/banks/resolve": { "post": { "consumes": [ "application/json" ], "description": "Verifies a bank account by resolving the account number and bank code to an account name", "parameters": [ { "description": "Account resolution request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/ResolveAccountRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ResolveAccountResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Integration failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Resolve Bank Account", "tags": [ "public.recipients" ] } }, "/v1/customers": { "get": { "consumes": [ "application/json" ], "description": "Lists all customers for the authenticated merchant with optional filtering and pagination", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by exact email address", "in": "query", "name": "email", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListCustomersResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Customers", "tags": [ "public.customers" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates a new customer or returns the existing customer for the authenticated merchant.", "parameters": [ { "description": "Customer creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateCustomerRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Customer", "tags": [ "public.customers" ] } }, "/v1/customers/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single customer by ID for the authenticated merchant", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid customer ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Customer", "tags": [ "public.customers" ] }, "patch": { "consumes": [ "application/json" ], "description": "Updates a customer's profile fields for the authenticated merchant.", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Customer update request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/UpdateCustomerRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Customer already exists", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update Customer", "tags": [ "public.customers" ] } }, "/v1/customers/{id}/balances": { "get": { "description": "Retrieves the available, pending, and locked NGN balances Daya holds for a merchant's customer.", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerBalancesResponse" } }, "400": { "description": "Invalid customer ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "403": { "description": "Customer NGN balances not enabled", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Balance provider unavailable", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Customer Balances", "tags": [ "public.customers" ] } }, "/v1/customers/{id}/business-verification": { "post": { "consumes": [ "application/json" ], "description": "Compatibility route for submitting tier 2 business KYB information for an existing customer. Prefer /v1/customers/{id}/tier2-verification with customer_type=business for new integrations.", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Business verification request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/SubmitBusinessVerificationRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Verification already in progress or requires operations review", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Verification provider failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Submit Business Verification", "tags": [ "public.customers" ] } }, "/v1/customers/{id}/tier1-verification": { "patch": { "consumes": [ "application/json" ], "description": "Adds or replaces bank details for a customer who has completed Tier 1 verification. phone_number is required and accepts Nigerian national or +234 format. Verify the account with POST /v1/banks/resolve before submitting it. This does not repeat BVN or selfie verification or create a funding account. If the customer already has a permanent NGN funding account, Daya starts enabling its Paystack option and reports completion through funding_account.updated.", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Tier 1 bank account", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/UpdateTier1VerificationRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Tier 1 verification is not complete", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Bank account could not be resolved", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Add or replace Tier 1 bank account", "tags": [ "public.customers" ] }, "post": { "consumes": [ "application/json" ], "description": "Submits BVN and a selfie image reference for Tier 1 verification. phone_number is optional unless bank_account is included; when bank details are submitted, phone_number is required and accepts Nigerian national or +234 format so Daya can send it to Paystack. Get the supported bank code from GET /v1/banks and verify the account with POST /v1/banks/resolve before submitting it. Tier 1 remains complete after a successful BVN check even if the additional Paystack funding-account option cannot be enabled. The selfie may be sent as an HTTPS URL or a base64 data URL.", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Tier 1 verification request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/SubmitTier1VerificationRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Verification already in progress or requires operations review", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "422": { "description": "Bank account could not be resolved", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "Identical verification was recently attempted", "headers": { "Retry-After": { "description": "Seconds until the verification may be retried", "type": "integer" } }, "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Verification provider failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Submit Tier 1 Verification", "tags": [ "public.customers" ] } }, "/v1/customers/{id}/tier2-verification": { "post": { "consumes": [ "application/json" ], "description": "Submits tier 2 verification for an existing customer. Individual customers submit KYC fields. Business/entity customers submit business KYB fields with customer_type=business. Identity-document and supporting-document image fields must be sent as base64 data URLs such as data:image/png;base64,...", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Tier 2 verification request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/SubmitTier2VerificationRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/CustomerResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Verification already in progress or requires operations review", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Verification provider failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Submit Tier 2 Verification", "tags": [ "public.customers" ] } }, "/v1/customers/{id}/virtual-accounts": { "get": { "consumes": [ "application/json" ], "description": "Lists all virtual accounts for a specific customer under the authenticated merchant", "parameters": [ { "description": "Customer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by status", "enum": [ "active", "inactive" ], "in": "query", "name": "status", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListVirtualAccountsResponse" } }, "400": { "description": "Invalid parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Customer Virtual Accounts", "tags": [ "public.virtual-accounts" ] } }, "/v1/deposits": { "get": { "consumes": [ "application/json" ], "description": "Lists funding account deposits for NGN and crypto receive flows. When a developer fee is configured, each settled deposit shows the merchant developer fee and the customer amount separately from Daya fees.", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by deposit type", "enum": [ "NGN_DEPOSIT", "CRYPTO_DEPOSIT" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by external status (can be specified multiple times)", "enum": [ "PENDING", "RECEIVED", "PROCESSING", "REQUIRES_REVIEW", "COMPLETED", "FLAGGED", "FAILED", "REVERSED" ], "in": "query", "name": "status", "type": "string" }, { "description": "Filter by exact payment reference. Only applies to NGN deposits", "in": "query", "name": "payment_reference", "type": "string" }, { "description": "Filter by onramp ID (UUID format). Only applies to funding-account NGN deposits", "in": "query", "name": "onramp_id", "type": "string" }, { "description": "Filter by offramp ID (UUID format). Only applies to funding-account crypto deposits", "in": "query", "name": "offramp_id", "type": "string" }, { "description": "Filter deposits created from this time (RFC3339 format, inclusive)", "in": "query", "name": "from", "type": "string" }, { "description": "Filter deposits created before this time (RFC3339 format, exclusive)", "in": "query", "name": "to", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListDepositsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Deposits", "tags": [ "public.deposits" ] } }, "/v1/deposits/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single funding account deposit by ID for the authenticated merchant. When a developer fee is configured, the response shows the merchant developer fee and the customer amount separately from Daya fees.", "parameters": [ { "description": "Deposit ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/DepositResponse" } }, "400": { "description": "Invalid deposit ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Deposit not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Deposit", "tags": [ "public.deposits" ] } }, "/v1/fees": { "get": { "description": "Returns the current merchant fee schedule sourced from app settings", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FeesResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Merchant Fees", "tags": [ "public.fees" ] } }, "/v1/funding-accounts": { "get": { "consumes": [ "application/json" ], "description": "Lists funding accounts for the authenticated merchant with optional filtering and pagination. Provider-backed instructions include provider_availability with the provider's current service state.", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by customer ID", "in": "query", "name": "customer_id", "type": "string" }, { "description": "Filter by funding account type", "enum": [ "TEMPORARY", "PERMANENT" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by rail", "enum": [ "NGN_VIRTUAL_ACCOUNT", "CRYPTO_ADDRESS" ], "in": "query", "name": "rail", "type": "string" }, { "description": "Filter by status", "enum": [ "PENDING", "ACTIVE", "FAILED", "DISABLED" ], "in": "query", "name": "status", "type": "string" }, { "description": "Filter by active NGN virtual account number", "in": "query", "name": "account_number", "type": "string" }, { "description": "Filter by active crypto receive address", "in": "query", "name": "address", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListFundingAccountsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Funding Accounts", "tags": [ "public.funding-accounts" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates a funding account and sets up payment details. settlement_destination.type=CUSTOMER_NGN_BALANCE is generally available for permanent funding accounts: permanent NGN virtual-account deposits are retained for that customer, while supported USDC/USDT deposits on any deposit-enabled chain are automatically converted into that customer's NGN balance. NGN_BALANCE retains NGN at merchant level, and INTERNAL_BALANCE preserves the existing automatic settlement into the merchant balance. Read customer balances with GET /v1/customers/{id}/balances and create an NGN bank transfer with debit_scope=CUSTOMER, debit_currency=NGN, and on_behalf_of.customer_id to pay from that balance. Provider-backed instructions include provider_availability, which reports each provider's current funding-account service state. Permanent NGN creation can continue through Paystack when Flutterwave is UNAVAILABLE and the customer has verified bank details; the response still includes the Flutterwave instruction with provider_availability.status set to UNAVAILABLE. The endpoint returns 503 PROVIDER_UNAVAILABLE only when no configured permanent NGN provider can accept the request, or when the single provider required for another rail is unavailable. Include developer_fee.percentage to keep 0% to 50% of each received deposit; deposit responses and webhooks show the developer fee and customer amount separately from Daya fees. Native SOL uses a PERMANENT CRYPTO_ADDRESS account on SOLANA with INTERNAL_BALANCE settlement and no developer fee. Requires an idempotency key in the X-Idempotency-Key header.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Funding account creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateFundingAccountRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "Returned when an existing permanent funding account is reused", "schema": { "$ref": "#/definitions/FundingAccountResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/FundingAccountResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Provider provisioning failed", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "No configured provider for the requested funding-account rail is available", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Funding Account", "tags": [ "public.funding-accounts" ] } }, "/v1/funding-accounts/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single funding account by ID for the authenticated merchant. Provider-backed instructions include provider_availability with the provider's current service state.", "parameters": [ { "description": "Funding account ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FundingAccountResponse" } }, "400": { "description": "Invalid funding account ID", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Funding account not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Funding Account", "tags": [ "public.funding-accounts" ] } }, "/v1/funding-accounts/{id}/disable": { "post": { "consumes": [ "application/json" ], "description": "Disables an active funding account and its active payment details. Already-disabled accounts return the current resource.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Funding account ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FundingAccountResponse" } }, "400": { "description": "Invalid funding account ID", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Funding account not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Disable Funding Account", "tags": [ "public.funding-accounts" ] } }, "/v1/funding-accounts/{id}/settlement-destination": { "patch": { "consumes": [ "application/json" ], "description": "Rotates the active settlement destination for a permanent active funding account. This does not create new payment details.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Funding account ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Settlement destination update", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/FundingAccountSettlementDestinationRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FundingAccountResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Funding account not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update Funding Account Settlement Destination", "tags": [ "public.funding-accounts" ] } }, "/v1/merchant/balance": { "get": { "description": "Fetches the current merchant USD collection/withdrawal balances and NGN, SOL, and BNB withdrawal balances", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MerchantBalanceResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Merchant Balances", "tags": [ "public.balance" ] } }, "/v1/merchant/balance/transfer": { "post": { "consumes": [ "application/json" ], "description": "Transfers USD from the merchant collection balance into the merchant withdrawal balance", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Merchant balance transfer request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/TransferMerchantBalanceRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/TransferMerchantBalanceResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Transfer Merchant Balance", "tags": [ "public.balance" ] } }, "/v1/merchant/balance/transfers": { "get": { "description": "Lists collection-to-withdrawal balance transfer history for the authenticated merchant", "parameters": [ { "description": "Number of results per page (default: 50)", "in": "query", "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by status", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "in": "query", "name": "status", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListMerchantBalanceTransfersResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Merchant Balance Transfers", "tags": [ "public.balance" ] } }, "/v1/merchant/funding": { "get": { "description": "Returns the merchant's funding setup status, permanent NGN collection account, supported crypto wallet addresses, and ngn_settlement_destination. USD_BALANCE converts merchant NGN bank funding into USD; NGN_BALANCE retains it in withdrawal_balance_ngn.", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MerchantFundingEnvelope" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Merchant funding configuration not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Merchant Funding Instructions", "tags": [ "public.merchant-funding" ] } }, "/v1/merchant/funding/settlement-destination": { "patch": { "consumes": [ "application/json" ], "description": "Selects how future deposits to the merchant's permanent NGN funding account settle. USD_BALANCE preserves automatic NGN-to-USD conversion; NGN_BALANCE retains NGN in withdrawal_balance_ngn. Existing settled deposits are not changed.", "parameters": [ { "description": "NGN funding settlement destination", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/UpdateMerchantNGNFundingSettlementRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/MerchantFundingEnvelope" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Merchant funding configuration not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Update Merchant NGN Funding Settlement Destination", "tags": [ "public.merchant-funding" ] } }, "/v1/merchant/withdrawals": { "get": { "description": "Lists all withdrawals for the authenticated merchant", "parameters": [ { "description": "Number of results per page (default: 50)", "in": "query", "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by status", "enum": [ "PENDING", "SUBMITTED", "SETTLED", "FAILED" ], "in": "query", "name": "status", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListWithdrawalsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Withdrawals", "tags": [ "public.withdrawals" ] }, "post": { "consumes": [ "application/json" ], "description": "Transfers merchant USD-backed stablecoins or native SOL to a pre-approved onchain destination using Utila. Stablecoins use amount_usd; native SOL uses amount. The destination must first be added to the merchant withdrawal whitelist.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Merchant withdrawal request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateMerchantWithdrawalRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/CreateMerchantWithdrawalResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "403": { "description": "Destination address is not whitelisted", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Merchant Withdrawal", "tags": [ "public.withdrawals" ] } }, "/v1/merchant/withdrawals/{id}": { "get": { "description": "Retrieves a single withdrawal by ID for the authenticated merchant", "parameters": [ { "description": "Withdrawal ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/WithdrawalResponse" } }, "400": { "description": "Invalid withdrawal ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Withdrawal not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Withdrawal", "tags": [ "public.withdrawals" ] } }, "/v1/offramps": { "get": { "consumes": [ "application/json" ], "description": "Lists all offramps for the authenticated merchant with optional filtering and pagination", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by offramp type", "enum": [ "TEMPORARY", "PERMANENT" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by blockchain network", "enum": [ "APTOS", "BASE", "BSC", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "SUI", "TEMPO", "TRON" ], "in": "query", "name": "chain", "type": "string" }, { "description": "Filter by asset", "enum": [ "USDC", "USDT" ], "in": "query", "name": "asset", "type": "string" }, { "description": "Filter by offramp status", "in": "query", "name": "status", "type": "string" }, { "description": "Filter by settlement mode", "enum": [ "INTERNAL_BALANCE", "NGN_PAYOUT" ], "in": "query", "name": "settlement_mode", "type": "string" }, { "description": "Filter by active crypto receive address", "in": "query", "name": "address", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListOfframpsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Offramps", "tags": [ "public.offramps" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates an offramp receive address for the authenticated merchant. Include developer_fee.percentage to keep 0% to 50% of each received deposit; deposit responses and webhooks show the developer fee and customer amount separately from Daya fees. TEMPORARY offramps are only supported with NGN_PAYOUT settlement; INTERNAL_BALANCE settlement requires PERMANENT. Requires an idempotency key in the X-Idempotency-Key header.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Offramp creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateOfframpRequest" } } ], "produces": [ "application/json" ], "responses": { "200": { "description": "Returned when an existing address is reused", "schema": { "$ref": "#/definitions/OfframpResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/OfframpResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Offramp", "tags": [ "public.offramps" ] } }, "/v1/offramps/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a specific offramp by ID for the authenticated merchant", "parameters": [ { "description": "Offramp ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/OfframpResponse" } }, "400": { "description": "Invalid offramp ID", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Offramp not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Offramp", "tags": [ "public.offramps" ] } }, "/v1/onramps": { "get": { "consumes": [ "application/json" ], "description": "Lists all onramps for the authenticated merchant with optional filtering by type and pagination", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by onramp type", "enum": [ "TEMPORARY", "PERMANENT" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by active virtual account number", "in": "query", "name": "account_number", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListOnrampsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Onramps", "tags": [ "public.onramps" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates either a temporary or permanent onramp configuration. Include developer_fee.percentage to keep 0% to 50% of each received deposit; deposit responses and webhooks show the developer fee and customer amount separately from Daya fees. Requires an idempotency key in the X-Idempotency-Key header.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Onramp creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateOnrampRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/CreateOnrampResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "429": { "description": "Identical customer verification was recently attempted", "headers": { "Retry-After": { "description": "Seconds until the verification may be retried", "type": "integer" } }, "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Verification or virtual account provisioning failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Onramp", "tags": [ "public.onramps" ] } }, "/v1/onramps/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single onramp by ID for the authenticated merchant. Returns both temporary and permanent onramps.", "parameters": [ { "description": "Onramp ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/OnrampResponse" } }, "400": { "description": "Invalid onramp ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Onramp not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Onramp", "tags": [ "public.onramps" ] } }, "/v1/payouts": { "get": { "description": "Lists all payouts for the authenticated merchant across crypto and NGN settlement transfers", "parameters": [ { "description": "Filter by payout type", "enum": [ "CRYPTO_PAYOUT", "NGN_PAYOUT" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by external status", "enum": [ "PROCESSING", "SETTLED", "FAILED" ], "in": "query", "name": "status", "type": "string" }, { "description": "Number of results per page (default: 20, max: 100)", "in": "query", "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "type": "integer" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListPayoutsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Payouts", "tags": [ "public.payouts" ] } }, "/v1/payouts/{id}": { "get": { "description": "Retrieves a specific payout by ID for the authenticated merchant", "parameters": [ { "description": "Payout ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/PayoutResponse" } }, "400": { "description": "Invalid payout ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Payout not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Payout", "tags": [ "public.payouts" ] } }, "/v1/rates": { "get": { "consumes": [ "application/json" ], "description": "Retrieves the latest exchange rate snapshot for a currency pair and side", "parameters": [ { "description": "Source currency code", "example": "NGN", "in": "query", "name": "from", "required": true, "type": "string" }, { "description": "Target currency code", "example": "USDC", "in": "query", "name": "to", "required": true, "type": "string" }, { "description": "Rate side (BUY or SELL)", "example": "BUY", "in": "query", "name": "side", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetLatestRateResponse" } }, "400": { "description": "Invalid request parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "503": { "description": "Quoting service unavailable", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Latest Exchange Rate", "tags": [ "public.rates" ] } }, "/v1/recipients": { "get": { "description": "Lists saved payout recipients for the authenticated merchant with optional filtering and pagination", "parameters": [ { "description": "Filter by recipient type", "enum": [ "BANK_ACCOUNT", "CRYPTO_ADDRESS" ], "in": "query", "name": "type", "type": "string" }, { "description": "Filter by customer ID", "in": "query", "name": "customer_id", "type": "string" }, { "description": "Search across names and addresses", "in": "query", "name": "search", "type": "string" }, { "description": "Number of results per page (default: 20, max: 100)", "in": "query", "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "name": "page", "type": "integer" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListRecipientsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Recipients", "tags": [ "public.recipients" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates a saved payout recipient (bank account or crypto address). Crypto recipients support USDC, USDT, native SOL on Solana, and native BNB on BSC. Native recipients are used through the transfers API. Duplicate destinations are deduplicated by fingerprint. Requires an idempotency key.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Recipient creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateRecipientRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/RecipientResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Recipient", "tags": [ "public.recipients" ] } }, "/v1/recipients/{id}": { "delete": { "description": "Soft-deletes a payout recipient by ID", "parameters": [ { "description": "Recipient ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "204": { "description": "No content" }, "400": { "description": "Invalid recipient ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Recipient not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Delete Recipient", "tags": [ "public.recipients" ] }, "get": { "description": "Retrieves a specific payout recipient by ID", "parameters": [ { "description": "Recipient ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/RecipientResponse" } }, "400": { "description": "Invalid recipient ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Recipient not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Recipient", "tags": [ "public.recipients" ] } }, "/v1/sandbox/deposits": { "post": { "consumes": [ "application/json" ], "description": "Creates a mock deposit for an existing funding account for testing purposes. funding_account_scope defaults to CUSTOMER. Set it to MERCHANT when funding_account_id is the id returned by GET /v1/merchant/funding. Merchant simulations accept currency=NGN with a required amount to credit withdrawal_balance_ngn, or currency=USD with an optional amount to credit withdrawal_balance_usd; omitting both preserves the legacy fixed 10 USD simulation. The endpoint uses the selected scope and does not search both account types. Pass scenario to force a deterministic sandbox deposit lifecycle outcome. payout_scenario is only supported for CUSTOMER deposits. Only available in sandbox.", "parameters": [ { "description": "Required for MERCHANT funding simulations; reuse the same value when retrying a request", "in": "header", "name": "X-Idempotency-Key", "type": "string" }, { "description": "Sandbox deposit request with funding_account_id, optional funding_account_scope, merchant-only currency and amount, scenario, and customer-only payout_scenario", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.CreateSandboxDepositRequest" } } ], "produces": [ "application/json" ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.CreateSandboxDepositResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "403": { "description": "Not available outside sandbox", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Funding account not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Sandbox Deposit", "tags": [ "public.deposits" ] } }, "/v1/supported-chains": { "get": { "description": "Returns supported settlement chains with deposit and withdrawal token support. This endpoint is public and does not require authentication.", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListSupportedChainsResponse" } } }, "summary": "List Supported Chains", "tags": [ "public.supported-chains" ] } }, "/v1/transfers": { "get": { "description": "Lists merchant-initiated transfers for the authenticated merchant. Transfer webhook events use the transfer.* namespace.", "parameters": [ { "description": "Number of results per page (default: 20, max: 100)", "in": "query", "maximum": 100, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by external status", "enum": [ "PROCESSING", "SETTLED", "FAILED" ], "in": "query", "name": "status", "type": "string" }, { "description": "Filter by transfer currency", "enum": [ "NGN", "USD", "SOL", "BNB" ], "in": "query", "name": "currency", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListTransfersResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Transfers", "tags": [ "public.transfers" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates a merchant-initiated transfer to a saved recipient or an inline destination. Transfers debit the merchant balance by default. To pay from one customer's retained NGN balance, set currency=NGN, debit_currency=NGN, debit_scope=CUSTOMER, and on_behalf_of.customer_id; the recipient must belong to that customer. Transfers support NGN bank recipients, USD ACH, wire, RTP, or SWIFT recipients, USDC/USDT crypto addresses funded from the merchant USD balance, and native SOL/BNB addresses funded from the matching merchant native-asset balance. NGN payouts continue to debit USD by default; set debit_currency=NGN to debit retained NGN with no FX conversion. Omit debit_currency for native SOL/BNB transfers. NGN bank recipients must receive at least 100 NGN. Recipient amounts below 1,000 NGN incur a flat 20 NGN fee; recipient amounts of 1,000 NGN or more use the configured percentage fee and cap. Use /v1/supported-chains to discover currently enabled asset and chain combinations. Transfer webhooks use public transfer events: transfer.created, transfer.processing, transfer.requires_review, transfer.submitted, transfer.completed, transfer.failed, and transfer.reversed.", "parameters": [ { "description": "Idempotency key for request deduplication", "in": "header", "name": "X-Idempotency-Key", "required": true, "type": "string" }, { "description": "Transfer creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateTransferRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/TransferResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Recipient not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "409": { "description": "Idempotency conflict", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Transfer", "tags": [ "public.transfers" ] } }, "/v1/transfers/{id}": { "get": { "description": "Retrieves a single merchant-initiated transfer by ID for the authenticated merchant. Use this endpoint to refresh transfer state after receiving transfer.* webhooks.", "parameters": [ { "description": "Transfer ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/TransferResponse" } }, "400": { "description": "Invalid transfer ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Transfer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Transfer", "tags": [ "public.transfers" ] } }, "/v1/virtual-account-deposits": { "get": { "consumes": [ "application/json" ], "description": "Lists USD account deposits for the authenticated merchant", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by customer ID (UUID format)", "in": "query", "name": "customer_id", "type": "string" }, { "description": "Filter by virtual account ID (UUID format)", "in": "query", "name": "virtual_account_id", "type": "string" }, { "description": "Filter by public status", "enum": [ "PENDING", "COMPLETED", "FLAGGED", "FAILED" ], "in": "query", "name": "status", "type": "string" }, { "description": "Filter deposits created from this time (RFC3339 format, inclusive)", "in": "query", "name": "from", "type": "string" }, { "description": "Filter deposits created before this time (RFC3339 format, exclusive)", "in": "query", "name": "to", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListDepositsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List USD Account Deposits", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-account-deposits/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single USD account deposit by ID for the authenticated merchant", "parameters": [ { "description": "Deposit ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/DepositResponse" } }, "400": { "description": "Invalid deposit ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Deposit not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get USD Account Deposit", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-accounts": { "get": { "consumes": [ "application/json" ], "description": "Lists all virtual accounts for the authenticated merchant with optional filtering and pagination", "parameters": [ { "description": "Number of results per page (default: 50, max: 200)", "in": "query", "maximum": 200, "minimum": 1, "name": "limit", "type": "integer" }, { "description": "Page number (default: 1)", "in": "query", "minimum": 1, "name": "page", "type": "integer" }, { "description": "Filter by customer ID (UUID format)", "in": "query", "name": "customer_id", "type": "string" }, { "description": "Filter by status", "enum": [ "active", "inactive" ], "in": "query", "name": "status", "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListVirtualAccountsResponse" } }, "400": { "description": "Invalid query parameters", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "List Virtual Accounts", "tags": [ "public.virtual-accounts" ] }, "post": { "consumes": [ "application/json" ], "description": "Creates a new USD virtual account for a customer via Bridge. Include developer_fee.percentage to keep 0% to 50% of each received USD deposit; Daya calculates this fee when deposits arrive and does not send it to Bridge. The customer must have completed tier 2 verification.", "parameters": [ { "description": "Virtual account creation request", "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/CreateVirtualAccountRequest" } } ], "produces": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/VirtualAccountResponse" } }, "400": { "description": "Invalid request", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Customer not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "502": { "description": "Bridge integration failed", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Create Virtual Account", "tags": [ "public.virtual-accounts" ] } }, "/v1/virtual-accounts/{id}": { "get": { "consumes": [ "application/json" ], "description": "Retrieves a single virtual account by ID for the authenticated merchant", "parameters": [ { "description": "Virtual Account ID (UUID format)", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/VirtualAccountResponse" } }, "400": { "description": "Invalid virtual account ID format", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "404": { "description": "Virtual account not found", "schema": { "$ref": "#/definitions/ErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ErrorResponse" } } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Get Virtual Account", "tags": [ "public.virtual-accounts" ] } } }, "definitions": { "AssociatedPerson": { "properties": { "birth_date": { "example": "1990-05-15", "type": "string" }, "documents": { "items": { "$ref": "#/definitions/Document" }, "type": "array" }, "email": { "example": "jane@example.com", "type": "string" }, "first_name": { "example": "Jane", "maxLength": 100, "minLength": 1, "type": "string" }, "has_control": { "example": true, "type": "boolean" }, "has_ownership": { "example": true, "type": "boolean" }, "identifying_information": { "items": { "$ref": "#/definitions/IdentifyingInformation" }, "minItems": 1, "type": "array" }, "is_director": { "example": true, "type": "boolean" }, "is_signer": { "example": true, "type": "boolean" }, "last_name": { "example": "Doe", "maxLength": 100, "minLength": 1, "type": "string" }, "middle_name": { "maxLength": 100, "type": "string" }, "nationality": { "example": "GBR", "type": "string" }, "ownership_percentage": { "example": 50, "maximum": 100, "minimum": 0, "type": "integer" }, "phone": { "maxLength": 40, "type": "string" }, "relationship_established_at": { "example": "2020-01-01", "type": "string" }, "residential_address": { "$ref": "#/definitions/ResidentialAddress" }, "title": { "example": "Director", "maxLength": 100, "type": "string" } }, "required": [ "birth_date", "email", "first_name", "has_control", "has_ownership", "identifying_information", "is_signer", "last_name", "nationality", "residential_address" ], "type": "object" }, "BankAccountInput": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" }, "bank_code": { "type": "string" } }, "required": [ "account_number", "bank_code" ], "type": "object" }, "BankAccountRequest": { "properties": { "account_number": { "example": "0123456789", "type": "string" }, "bank_code": { "example": "058", "type": "string" } }, "type": "object" }, "BankAccountResponse": { "properties": { "account_name": { "type": "string" }, "account_number_last4": { "type": "string" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" } }, "type": "object" }, "BankResponse": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "CreateCustomerRequest": { "properties": { "email": { "example": "customer@example.com", "type": "string" }, "first_name": { "example": "John", "maxLength": 100, "minLength": 1, "type": "string" }, "last_name": { "example": "Doe", "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "email" ], "type": "object" }, "CreateFundingAccountRequest": { "properties": { "amount": { "description": "Required for TEMPORARY NGN_VIRTUAL_ACCOUNT accounts. Accepted only for TEMPORARY accounts.", "example": 50000, "type": "integer" }, "asset": { "description": "Required when rail is CRYPTO_ADDRESS. Supported values are USDC, USDT, SOL, and BNB.", "enum": [ "USDC", "USDT", "SOL", "BNB" ], "example": "USDC", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "BSC", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "SUI", "TEMPO", "TRON" ], "example": "BASE", "type": "string" }, "currency": { "enum": [ "NGN" ], "example": "NGN", "type": "string" }, "customer": { "$ref": "#/definitions/FundingAccountCustomerRequest" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeRequest" } ], "description": "Optional percentage developer fee kept by the merchant from each received deposit. Omit to use 0%." }, "rail": { "enum": [ "NGN_VIRTUAL_ACCOUNT", "CRYPTO_ADDRESS" ], "example": "NGN_VIRTUAL_ACCOUNT", "type": "string" }, "settlement_destination": { "allOf": [ { "$ref": "#/definitions/FundingAccountSettlementDestinationRequest" } ], "description": "Typed settlement destination details. Shape depends on settlement_destination.type." }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "TEMPORARY", "type": "string" } }, "required": [ "customer", "rail", "settlement_destination", "type" ], "type": "object" }, "CreateMerchantWithdrawalRequest": { "properties": { "amount": { "example": "0.250000000", "type": "string" }, "amount_usd": { "example": "12.3400", "type": "string" }, "chain": { "enum": [ "SOLANA", "TRON", "APTOS", "BASE", "POLYGON", "ETHEREUM", "OPTIMISM", "BSC" ], "example": "SOLANA", "type": "string" }, "destination_address": { "example": "4vJ9JU1bJJE96FWSJN", "type": "string" }, "token": { "enum": [ "USDC", "USDT", "SOL", "BNB" ], "example": "BNB", "type": "string" } }, "required": [ "chain", "destination_address", "token" ], "type": "object" }, "CreateMerchantWithdrawalResponse": { "properties": { "data": { "$ref": "#/definitions/MerchantWithdrawalData" } }, "type": "object" }, "CreateOfframpRequest": { "properties": { "asset": { "enum": [ "USDC", "USDT" ], "example": "USDC", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "BSC", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "SUI", "TEMPO", "TRON" ], "example": "BASE", "type": "string" }, "customer": { "$ref": "#/definitions/OfframpCustomerRequest" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeRequest" } ], "description": "Optional percentage developer fee kept by the merchant from each received deposit. Omit to use 0%." }, "settlement": { "$ref": "#/definitions/OfframpSettlementRequest" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "PERMANENT", "type": "string" } }, "required": [ "asset", "chain", "customer", "settlement", "type" ], "type": "object" }, "CreateOnrampRequest": { "properties": { "amount": { "example": 50000, "type": "integer" }, "customer": { "$ref": "#/definitions/OnrampCustomerRequest" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeRequest" } ], "description": "Optional percentage developer fee kept by the merchant from each received deposit. Omit to use 0%." }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "settlement": { "$ref": "#/definitions/SettlementRequest" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "PERMANENT", "type": "string" } }, "required": [ "customer", "settlement", "type" ], "type": "object" }, "CreateOnrampResponse": { "properties": { "amount": { "example": "50000.50", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeConfigResponse" } ], "description": "Developer fee percentage that will be used for deposits received through this onramp." }, "onramp_id": { "example": "750e8400-e29b-41d4-a716-446655440000", "type": "string" }, "rate_expires_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "settlement": { "$ref": "#/definitions/SettlementDetails" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "PERMANENT", "type": "string" }, "virtual_account": { "$ref": "#/definitions/VirtualAccountDetails" } }, "type": "object" }, "CreateRecipientRequest": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountInput" }, "crypto_address": { "$ref": "#/definitions/CryptoAddressInput" }, "customer_id": { "type": "string" }, "swift_bank_account": { "$ref": "#/definitions/SWIFTBankAccountInput" }, "type": { "enum": [ "BANK_ACCOUNT", "CRYPTO_ADDRESS", "US_BANK_ACCOUNT", "SWIFT_BANK_ACCOUNT" ], "type": "string" }, "us_bank_account": { "$ref": "#/definitions/USBankAccountInput" } }, "required": [ "type" ], "type": "object" }, "CreateTransferRequest": { "properties": { "amount": { "type": "string" }, "currency": { "enum": [ "NGN", "USD", "SOL", "BNB" ], "type": "string" }, "debit_currency": { "description": "Optional funding currency. NGN payouts default to USD for backwards compatibility; set NGN to spend retained NGN balance.", "enum": [ "USD", "NGN" ], "type": "string" }, "debit_scope": { "description": "Optional balance owner. Defaults to MERCHANT. Set CUSTOMER with debit_currency=NGN and on_behalf_of.customer_id to spend that customer's retained NGN balance.", "enum": [ "MERCHANT", "CUSTOMER" ], "type": "string" }, "destination": { "$ref": "#/definitions/TransferDestinationReq" }, "on_behalf_of": { "$ref": "#/definitions/OnBehalfOfReq" }, "recipient_id": { "type": "string" }, "reference": { "type": "string" } }, "required": [ "amount", "currency", "reference" ], "type": "object" }, "CreateVirtualAccountRequest": { "properties": { "currency": { "description": "Currency is the funding currency for the bank virtual account. Use \"usd\". This replaced the old source_currency field.", "example": "usd", "type": "string" }, "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "developer_fee": { "$ref": "#/definitions/DeveloperFeeRequest" } }, "required": [ "customer_id" ], "type": "object" }, "CryptoAddressInput": { "properties": { "address": { "type": "string" }, "asset": { "enum": [ "USDC", "USDT", "SOL", "BNB" ], "type": "string" }, "chain": { "example": "SOLANA", "type": "string" } }, "required": [ "address", "asset", "chain" ], "type": "object" }, "CryptoAddressResponse": { "properties": { "address": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" } }, "type": "object" }, "CryptoWithdrawalsFeesResponse": { "properties": { "default_fee": { "$ref": "#/definitions/FeeAmountResponse" }, "ethereum_fee": { "$ref": "#/definitions/FeeAmountResponse" }, "tron_fee": { "$ref": "#/definitions/FeeAmountResponse" } }, "type": "object" }, "CustomerBalanceData": { "properties": { "available": { "example": "125000.00", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "customer_id": { "type": "string" }, "locked": { "example": "0.00", "type": "string" }, "pending": { "example": "0.00", "type": "string" } }, "type": "object" }, "CustomerBalancesResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/CustomerBalanceData" }, "type": "array" } }, "type": "object" }, "CustomerCapability": { "properties": { "name": { "description": "Name is the customer capability identifier. Currently returned values are \"base\" and \"usd_banking\".", "example": "base", "type": "string" }, "status": { "description": "Status is the capability state. Returned values are \"approved\", \"pending\", \"information_requested\", \"rejected\", or \"missing\".", "example": "approved", "type": "string" } }, "type": "object" }, "CustomerResponse": { "properties": { "capabilities": { "items": { "$ref": "#/definitions/CustomerCapability" }, "type": "array" }, "created_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "email": { "example": "customer@example.com", "type": "string" }, "first_name": { "example": "John", "type": "string" }, "id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "is_verified": { "example": false, "type": "boolean" }, "last_name": { "example": "Doe", "type": "string" }, "paystack_funding_account_readiness": { "$ref": "#/definitions/PaystackFundingAccountReadiness" }, "rejection_reasons": { "description": "RejectionReasons contains the current blocking verification/capability issues. It is empty after approval.", "items": { "type": "string" }, "type": "array" }, "tier_1_kyc_complete": { "example": false, "type": "boolean" }, "tier_2_kyc_complete": { "example": false, "type": "boolean" }, "updated_at": { "example": "2025-01-05T15:04:05Z", "type": "string" } }, "type": "object" }, "CustomerVerificationRequest": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountRequest" }, "bvn": { "example": "22345678901", "type": "string" }, "image_url": { "description": "ImageURL supports either an HTTPS URL or a base64 data URL up to 1 MiB decoded, such as data:image/jpeg;base64,...", "example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...", "type": "string" }, "phone_number": { "example": "+2348012345678", "type": "string" } }, "required": [ "phone_number" ], "type": "object" }, "DepositCustomerAmountResponse": { "properties": { "amount": { "description": "Amount left for the customer after Daya fees and the merchant developer fee.", "example": "98.5000", "type": "string" }, "currency": { "example": "USD", "type": "string" } }, "type": "object" }, "DepositDeveloperFeeResponse": { "properties": { "amount": { "description": "Amount kept by the merchant. Present after the deposit has been settled.", "example": "1.5000", "type": "string" }, "currency": { "description": "Currency of the developer fee amount.", "example": "USD", "type": "string" }, "percentage": { "description": "Percentage kept by the merchant from this received deposit.", "example": "1.5", "type": "string" } }, "type": "object" }, "DepositFeesResponse": { "properties": { "deposit_fee": { "$ref": "#/definitions/FeeAmountResponse" }, "total_fee_usd": { "type": "string" }, "withdrawal_fee": { "$ref": "#/definitions/FeeAmountResponse" } }, "type": "object" }, "DepositResponse": { "properties": { "amount": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "customer_amount": { "allOf": [ { "$ref": "#/definitions/DepositCustomerAmountResponse" } ], "description": "Amount left for the customer after Daya fees and the merchant developer fee." }, "customer_id": { "type": "string" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DepositDeveloperFeeResponse" } ], "description": "Merchant developer fee kept from this deposit. This is separate from Daya fees." }, "fees": { "$ref": "#/definitions/DepositFeesResponse" }, "flag_code": { "type": "string" }, "flag_message": { "type": "string" }, "funding_account_id": { "type": "string" }, "id": { "type": "string" }, "offramp_id": { "type": "string" }, "onramp_id": { "type": "string" }, "rate": { "type": "string" }, "rate_id": { "type": "string" }, "sender": { "$ref": "#/definitions/DepositSender" }, "settled_amount": { "type": "string" }, "settled_currency": { "type": "string" }, "settlement_mode": { "type": "string" }, "settlement_status": { "type": "string" }, "status": { "type": "string" }, "tx_hash": { "type": "string" }, "type": { "type": "string" }, "updated_at": { "type": "string" }, "va_deposit_id": { "type": "string" } }, "type": "object" }, "DepositSender": { "properties": { "account_number": { "example": "****1234", "type": "string" }, "bank_name": { "example": "Chase", "type": "string" }, "name": { "example": "Jane Doe", "type": "string" } }, "type": "object" }, "DestinationBank": { "properties": { "account_name": { "example": "Jane Doe", "maxLength": 120, "minLength": 1, "type": "string" }, "account_number": { "example": "0123456789", "maxLength": 32, "minLength": 6, "type": "string" }, "bank_code": { "example": "058", "maxLength": 16, "minLength": 3, "type": "string" } }, "required": [ "account_number", "bank_code" ], "type": "object" }, "DeveloperFeeConfigResponse": { "properties": { "percentage": { "description": "Percentage configured for deposits received through this account or receive address.", "example": "1.5", "type": "string" } }, "type": "object" }, "DeveloperFeeRequest": { "properties": { "percentage": { "description": "Percentage of each received deposit that the merchant keeps. Use a decimal string from 0 to 50.", "example": "1.5", "type": "string" } }, "required": [ "percentage" ], "type": "object" }, "Document": { "properties": { "file": { "description": "File must be a base64 data URL up to 5 MiB decoded, for example: data:image/png;base64,iVBORw0KGgo...", "example": "data:image/png;base64,iVBORw0KGgo...", "type": "string" }, "purposes": { "example": [ "proof_of_address" ], "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "file", "purposes" ], "type": "object" }, "ErrorBody": { "properties": { "code": { "description": "Stable application error code.", "example": "VALIDATION_FAILED", "type": "string" }, "message": { "description": "Human-readable error message.", "example": "Invalid request", "type": "string" }, "request_id": { "description": "Request ID for debugging.", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "retry_after_seconds": { "description": "RetryAfterSeconds is present for retryable rate-limit responses.", "example": 60, "type": "integer" }, "validation": { "description": "Validation contains validator output when a request fails validation.", "example": "Key: 'CreateCustomerRequest.Email' Error:Field validation for 'Email' failed on the 'required' tag", "type": "string" } }, "type": "object" }, "ErrorResponse": { "description": "Standard public/internal error response structure", "properties": { "error": { "$ref": "#/definitions/ErrorBody" } }, "type": "object" }, "FeeAmountResponse": { "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "type": "object" }, "FeesResponse": { "properties": { "crypto_withdrawals": { "$ref": "#/definitions/CryptoWithdrawalsFeesResponse" }, "ngn": { "$ref": "#/definitions/NGNFeesResponse" }, "usd_transfers": { "$ref": "#/definitions/USDTransferFeesResponse" }, "usd_virtual_account": { "$ref": "#/definitions/USDVirtualAccountFeesResponse" } }, "type": "object" }, "FundingAccountCustomerRequest": { "properties": { "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" } }, "required": [ "customer_id" ], "type": "object" }, "FundingAccountDestinationBankRequest": { "properties": { "account_number": { "description": "Recipient bank account number.", "example": "0123456789", "maxLength": 32, "minLength": 6, "type": "string" }, "bank_code": { "description": "Recipient bank code.", "example": "058", "maxLength": 16, "minLength": 3, "type": "string" } }, "required": [ "account_number", "bank_code" ], "type": "object" }, "FundingAccountInstructionFailureResponse": { "properties": { "code": { "example": "ACCOUNT_NAME_MISMATCH", "type": "string" }, "message": { "example": "The bank account name does not match the customer's verified identity.", "type": "string" } }, "type": "object" }, "FundingAccountInstructionResponse": { "properties": { "account_name": { "example": "Daya-John Doe", "type": "string" }, "account_number": { "example": "1234567890", "type": "string" }, "address": { "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "type": "string" }, "bank_code": { "example": "035", "type": "string" }, "bank_name": { "example": "Wema Bank", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "BSC", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "SUI", "TEMPO", "TRON" ], "example": "BASE", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "expires_at": { "example": "2026-01-05T16:04:05Z", "type": "string" }, "failure": { "$ref": "#/definitions/FundingAccountInstructionFailureResponse" }, "provider": { "description": "Provider is returned only for merchant-facing NGN providers.", "enum": [ "FLUTTERWAVE", "PAYSTACK" ], "example": "FLUTTERWAVE", "type": "string" }, "provider_availability": { "$ref": "#/definitions/FundingAccountProviderAvailabilityResponse" }, "required_fields": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "REQUIRES_INFORMATION", "PENDING", "ACTIVE", "FAILED", "DISABLED" ], "example": "ACTIVE", "type": "string" }, "type": { "enum": [ "NGN_VIRTUAL_ACCOUNT", "CRYPTO_ADDRESS" ], "example": "NGN_VIRTUAL_ACCOUNT", "type": "string" } }, "type": "object" }, "FundingAccountProviderAvailabilityResponse": { "properties": { "message": { "description": "User-facing explanation of a degraded or unavailable state.", "example": "This provider is experiencing funding-account delays.", "type": "string" }, "status": { "description": "Current provider service state.", "enum": [ "OPERATIONAL", "DEGRADED", "UNAVAILABLE" ], "example": "DEGRADED", "type": "string" } }, "type": "object" }, "FundingAccountResponse": { "properties": { "amount": { "example": "50000.75", "type": "string" }, "asset": { "enum": [ "USDC", "USDT", "SOL", "BNB" ], "example": "USDC", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "BSC", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "SUI", "TEMPO", "TRON" ], "example": "BASE", "type": "string" }, "created_at": { "example": "2026-01-05T15:04:05Z", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeConfigResponse" } ], "description": "Developer fee percentage that will be used for deposits received through this funding account." }, "disabled_at": { "example": "2026-01-05T16:04:05Z", "type": "string" }, "expires_at": { "example": "2026-01-05T16:04:05Z", "type": "string" }, "failure_code": { "example": "PROVISIONING_FAILED", "type": "string" }, "failure_message": { "example": "virtual account provisioning failed", "type": "string" }, "id": { "example": "750e8400-e29b-41d4-a716-446655440000", "type": "string" }, "instructions": { "items": { "$ref": "#/definitions/FundingAccountInstructionResponse" }, "type": "array" }, "object": { "example": "funding_account", "type": "string" }, "rail": { "enum": [ "NGN_VIRTUAL_ACCOUNT", "CRYPTO_ADDRESS" ], "example": "NGN_VIRTUAL_ACCOUNT", "type": "string" }, "settlement_destination": { "$ref": "#/definitions/FundingAccountSettlementDestinationResponse" }, "status": { "enum": [ "PENDING", "ACTIVE", "FAILED", "DISABLED" ], "example": "ACTIVE", "type": "string" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "TEMPORARY", "type": "string" }, "updated_at": { "example": "2026-01-05T15:04:05Z", "type": "string" } }, "type": "object" }, "FundingAccountSettlementDestinationRequest": { "properties": { "destination_address": { "description": "Required when type is ONCHAIN.", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "maxLength": 128, "minLength": 3, "type": "string" }, "destination_asset": { "description": "Required when type is ONCHAIN. Supported values are USDC and USDT.", "enum": [ "USDC", "USDT" ], "example": "USDC", "type": "string" }, "destination_bank": { "allOf": [ { "$ref": "#/definitions/FundingAccountDestinationBankRequest" } ], "description": "Required when type is NGN_PAYOUT. Shape: account_number and bank_code. Daya resolves the account name." }, "destination_chain": { "description": "Required when type is ONCHAIN.", "enum": [ "APTOS", "BASE", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "TRON" ], "example": "BASE", "type": "string" }, "rate_id": { "description": "Required for TEMPORARY accounts. Rejected for PERMANENT accounts.", "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "type": { "description": "Settlement destination type. NGN_BALANCE retains NGN at merchant level. CUSTOMER_NGN_BALANCE retains NGN for the funding account's customer. For permanent stablecoin funding accounts, it converts supported USDC/USDT deposits into that customer's NGN balance.", "enum": [ "INTERNAL_BALANCE", "NGN_BALANCE", "CUSTOMER_NGN_BALANCE", "ONCHAIN", "NGN_PAYOUT" ], "example": "INTERNAL_BALANCE", "type": "string" } }, "required": [ "type" ], "type": "object" }, "FundingAccountSettlementDestinationResponse": { "properties": { "destination_address": { "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "type": "string" }, "destination_asset": { "enum": [ "USDC", "USDT" ], "example": "USDC", "type": "string" }, "destination_bank": { "$ref": "#/definitions/DestinationBank" }, "destination_chain": { "enum": [ "APTOS", "BASE", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "TRON" ], "example": "BASE", "type": "string" }, "destination_currency": { "example": "NGN", "type": "string" }, "expires_at": { "example": "2026-01-05T16:04:05Z", "type": "string" }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "type": { "enum": [ "INTERNAL_BALANCE", "NGN_BALANCE", "CUSTOMER_NGN_BALANCE", "ONCHAIN", "NGN_PAYOUT" ], "example": "INTERNAL_BALANCE", "type": "string" } }, "type": "object" }, "GetLatestRateResponse": { "properties": { "expires_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "from": { "example": "NGN", "type": "string" }, "rate": { "example": "1550.50", "type": "string" }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "side": { "example": "BUY", "type": "string" }, "to": { "example": "USDC", "type": "string" } }, "type": "object" }, "IdentifyingInformation": { "properties": { "expiration": { "example": "2030-01-01", "type": "string" }, "image_back": { "description": "ImageBack must be a base64 data URL up to 1 MiB decoded when provided, for example: data:image/png;base64,iVBORw0KGgo...", "example": "data:image/png;base64,iVBORw0KGgo...", "type": "string" }, "image_front": { "description": "ImageFront must be a base64 data URL up to 1 MiB decoded when provided. It is required for passport, drivers_license, and national_id, but optional for tin.", "example": "data:image/png;base64,iVBORw0KGgo...", "type": "string" }, "issuing_country": { "example": "NGA", "type": "string" }, "number": { "example": "A12345678", "type": "string" }, "type": { "enum": [ "passport", "drivers_license", "national_id", "tin" ], "example": "passport", "type": "string" } }, "required": [ "issuing_country", "type" ], "type": "object" }, "ListBanksResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/BankResponse" }, "type": "array" } }, "type": "object" }, "ListCustomersResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/CustomerResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListDepositsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/DepositResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListFundingAccountsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/FundingAccountResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListMerchantBalanceTransfersResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/MerchantBalanceTransferResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListOfframpsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/OfframpResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListOnrampsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/OnrampResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListPayoutsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/PayoutResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListRecipientsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/RecipientResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListSupportedChainsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/SupportedChainResponse" }, "type": "array" } }, "type": "object" }, "ListTransfersResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/TransferResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListVirtualAccountsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/VirtualAccountResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "ListWithdrawalsResponse": { "properties": { "data": { "items": { "$ref": "#/definitions/WithdrawalResponse" }, "type": "array" }, "limit": { "type": "integer" }, "page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "MerchantBalanceData": { "properties": { "collection_balance_usd": { "example": "100.1234", "type": "string" }, "withdrawal_balance_bnb": { "example": "1.25000000", "type": "string" }, "withdrawal_balance_ngn": { "example": "250000.00", "type": "string" }, "withdrawal_balance_sol": { "example": "2.450000000", "type": "string" }, "withdrawal_balance_usd": { "example": "80.1234", "type": "string" } }, "type": "object" }, "MerchantBalanceResponse": { "properties": { "data": { "$ref": "#/definitions/MerchantBalanceData" } }, "type": "object" }, "MerchantBalanceTransferResponse": { "properties": { "amount_usd": { "type": "string" }, "collection_balance_after_usd": { "type": "string" }, "collection_balance_before_usd": { "type": "string" }, "created_at": { "type": "string" }, "failure_message": { "type": "string" }, "id": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "withdrawal_balance_after_usd": { "type": "string" }, "withdrawal_balance_before_usd": { "type": "string" } }, "type": "object" }, "MerchantFundingEnvelope": { "properties": { "data": { "$ref": "#/definitions/MerchantFundingResponse" } }, "type": "object" }, "MerchantFundingResponse": { "properties": { "crypto_wallet": { "$ref": "#/definitions/github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingCryptoWalletResponse" }, "id": { "example": "750e8400-e29b-41d4-a716-446655440000", "type": "string" }, "ngn_account": { "$ref": "#/definitions/github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingNGNAccountResponse" }, "ngn_settlement_destination": { "enum": [ "USD_BALANCE", "NGN_BALANCE" ], "example": "USD_BALANCE", "type": "string" }, "setup_status": { "example": "ACTIVE", "type": "string" } }, "type": "object" }, "MerchantWithdrawalData": { "properties": { "transaction_id": { "example": "transactions/abc123", "type": "string" } }, "type": "object" }, "NGNFeesResponse": { "properties": { "deposit_fee_cap": { "$ref": "#/definitions/FeeAmountResponse" }, "deposit_fee_percent": { "type": "string" }, "low_value_transfer_fee": { "allOf": [ { "$ref": "#/definitions/FeeAmountResponse" } ], "description": "Flat fee charged when the NGN recipient amount is less than the low-value threshold." }, "low_value_transfer_threshold": { "allOf": [ { "$ref": "#/definitions/FeeAmountResponse" } ], "description": "NGN recipient amount below which the flat low-value fee applies." }, "minimum_transfer_amount": { "allOf": [ { "$ref": "#/definitions/FeeAmountResponse" } ], "description": "Minimum amount that an NGN bank recipient must receive." }, "transfer_fee_cap": { "$ref": "#/definitions/FeeAmountResponse" }, "transfer_fee_percent": { "type": "string" } }, "type": "object" }, "OfframpCustomerRequest": { "properties": { "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "email": { "example": "user@example.com", "type": "string" }, "first_name": { "example": "John", "maxLength": 100, "minLength": 1, "type": "string" }, "last_name": { "example": "Doe", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" }, "OfframpResponse": { "properties": { "address": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "created_at": { "type": "string" }, "customer_id": { "type": "string" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeConfigResponse" } ], "description": "Developer fee percentage that will be used for deposits received through this offramp." }, "id": { "type": "string" }, "settlement": { "$ref": "#/definitions/OfframpSettlementResponse" }, "status": { "type": "string" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "PERMANENT", "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "OfframpSettlementRequest": { "properties": { "destination_bank": { "$ref": "#/definitions/DestinationBank" }, "mode": { "enum": [ "INTERNAL_BALANCE", "NGN_PAYOUT" ], "example": "INTERNAL_BALANCE", "type": "string" }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, "required": [ "mode" ], "type": "object" }, "OfframpSettlementResponse": { "properties": { "destination_bank": { "$ref": "#/definitions/DestinationBank" }, "expires_at": { "type": "string" }, "mode": { "type": "string" }, "rate_id": { "type": "string" } }, "type": "object" }, "OnBehalfOfReq": { "properties": { "customer_id": { "type": "string" } }, "required": [ "customer_id" ], "type": "object" }, "OnrampCustomerRequest": { "properties": { "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "email": { "example": "user@example.com", "type": "string" }, "first_name": { "example": "John", "maxLength": 100, "minLength": 1, "type": "string" }, "last_name": { "example": "Doe", "maxLength": 100, "minLength": 1, "type": "string" }, "verification": { "$ref": "#/definitions/CustomerVerificationRequest" } }, "type": "object" }, "OnrampResponse": { "properties": { "amount": { "example": "50000.50", "type": "string" }, "created_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "currency": { "example": "NGN", "type": "string" }, "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "developer_fee": { "allOf": [ { "$ref": "#/definitions/DeveloperFeeConfigResponse" } ], "description": "Developer fee percentage that will be used for deposits received through this onramp." }, "id": { "example": "750e8400-e29b-41d4-a716-446655440000", "type": "string" }, "provisioning_status": { "enum": [ "PENDING", "ACTIVE", "FAILED" ], "example": "ACTIVE", "type": "string" }, "rate_expires_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "rate_id": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" }, "settlement": { "$ref": "#/definitions/SettlementDetails" }, "type": { "enum": [ "TEMPORARY", "PERMANENT" ], "example": "PERMANENT", "type": "string" }, "virtual_account": { "$ref": "#/definitions/VirtualAccountDetails" } }, "type": "object" }, "PayoutRateResponse": { "properties": { "captured_at": { "type": "string" }, "side": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "PayoutResponse": { "properties": { "created_at": { "type": "string" }, "destination_amount": { "type": "string" }, "destination_currency": { "type": "string" }, "fee": { "type": "string" }, "id": { "type": "string" }, "rate": { "$ref": "#/definitions/PayoutRateResponse" }, "recipient": { "$ref": "#/definitions/RecipientResponse" }, "reference": { "type": "string" }, "sender": { "$ref": "#/definitions/PayoutSenderResponse" }, "settled_at": { "type": "string" }, "source_amount": { "type": "string" }, "source_currency": { "type": "string" }, "status": { "type": "string" }, "tx_hash": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "PayoutSenderResponse": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "PaystackFundingAccountReadiness": { "properties": { "account_number_last4": { "example": "6789", "type": "string" }, "bank_code": { "example": "058", "type": "string" }, "missing_fields": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "READY", "REQUIRES_INFORMATION" ], "example": "READY", "type": "string" }, "updated_at": { "example": "2026-08-10T12:00:00Z", "type": "string" } }, "type": "object" }, "RecipientAddressInput": { "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "state": { "type": "string" }, "street_line_1": { "type": "string" }, "street_line_2": { "type": "string" } }, "required": [ "city", "country", "postal_code", "street_line_1" ], "type": "object" }, "RecipientResponse": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountResponse" }, "created_at": { "type": "string" }, "crypto_address": { "$ref": "#/definitions/CryptoAddressResponse" }, "first_name": { "type": "string" }, "id": { "type": "string" }, "last_name": { "type": "string" }, "swift_bank_account": { "$ref": "#/definitions/SWIFTBankAccountResponse" }, "type": { "type": "string" }, "us_bank_account": { "$ref": "#/definitions/USBankAccountResponse" } }, "type": "object" }, "ResidentialAddress": { "properties": { "city": { "example": "Lagos", "maxLength": 100, "minLength": 1, "type": "string" }, "country": { "example": "NGA", "type": "string" }, "postal_code": { "example": "100001", "maxLength": 20, "minLength": 1, "type": "string" }, "street_line_1": { "example": "123 Main St", "maxLength": 255, "minLength": 1, "type": "string" }, "subdivision": { "example": "LA", "maxLength": 10, "minLength": 1, "type": "string" } }, "required": [ "city", "country", "postal_code", "street_line_1", "subdivision" ], "type": "object" }, "ResolveAccountRequest": { "properties": { "account_number": { "type": "string" }, "bank_code": { "type": "string" } }, "required": [ "account_number", "bank_code" ], "type": "object" }, "ResolveAccountResponse": { "properties": { "account_name": { "type": "string" }, "account_number": { "type": "string" } }, "type": "object" }, "SWIFTBankAccountInput": { "properties": { "account_country": { "type": "string" }, "account_owner_name": { "type": "string" }, "account_owner_type": { "enum": [ "individual", "business" ], "type": "string" }, "address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_name": { "type": "string" }, "bic": { "type": "string" }, "business_name": { "type": "string" }, "category": { "enum": [ "client", "parent_company", "subsidiary", "supplier" ], "type": "string" }, "first_name": { "type": "string" }, "iban": { "type": "string" }, "last_name": { "type": "string" }, "purpose_of_funds": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "short_business_description": { "type": "string" } }, "required": [ "account_country", "account_owner_name", "account_owner_type", "address", "bank_address", "category", "iban", "purpose_of_funds", "short_business_description" ], "type": "object" }, "SWIFTBankAccountResponse": { "properties": { "account_country": { "type": "string" }, "account_owner_name": { "type": "string" }, "account_owner_type": { "type": "string" }, "address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_name": { "type": "string" }, "bic": { "type": "string" }, "business_name": { "type": "string" }, "category": { "type": "string" }, "first_name": { "type": "string" }, "iban_last4": { "type": "string" }, "last_name": { "type": "string" }, "purpose_of_funds": { "items": { "type": "string" }, "type": "array" }, "short_business_description": { "type": "string" } }, "type": "object" }, "SettlementDetails": { "properties": { "asset": { "enum": [ "USDC", "USDT" ], "example": "USDC", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "TRON" ], "example": "BASE", "type": "string" }, "destination_address": { "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "type": "string" }, "mode": { "enum": [ "ONCHAIN", "INTERNAL_BALANCE" ], "example": "ONCHAIN", "type": "string" } }, "type": "object" }, "SettlementRequest": { "properties": { "asset": { "enum": [ "USDC", "USDT" ], "example": "USDC", "type": "string" }, "chain": { "enum": [ "APTOS", "BASE", "CELO", "ETHEREUM", "POLYGON", "SOLANA", "TRON" ], "example": "BASE", "type": "string" }, "destination_address": { "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "maxLength": 128, "minLength": 3, "type": "string" }, "mode": { "enum": [ "ONCHAIN", "INTERNAL_BALANCE" ], "example": "ONCHAIN", "type": "string" } }, "required": [ "asset", "mode" ], "type": "object" }, "SubmitBusinessVerificationRequest": { "properties": { "account_purpose": { "example": "operating_a_company", "type": "string" }, "account_purpose_other": { "maxLength": 255, "type": "string" }, "associated_persons": { "items": { "$ref": "#/definitions/AssociatedPerson" }, "minItems": 1, "type": "array" }, "business_description": { "example": "Cross-border collection and treasury operations", "maxLength": 1000, "minLength": 1, "type": "string" }, "business_industry": { "items": { "type": "string" }, "type": "array" }, "business_legal_name": { "example": "Ada Labs Ltd", "maxLength": 255, "minLength": 1, "type": "string" }, "business_type": { "example": "corporation", "type": "string" }, "conducts_money_services": { "example": false, "type": "boolean" }, "conducts_money_services_description": { "maxLength": 1000, "type": "string" }, "conducts_money_services_using_bridge": { "example": false, "type": "boolean" }, "customer_type": { "enum": [ "business" ], "example": "business", "type": "string" }, "documents": { "items": { "$ref": "#/definitions/Document" }, "minItems": 1, "type": "array" }, "estimated_annual_revenue_usd": { "example": "1000000_4999999", "type": "string" }, "expected_monthly_payments_usd": { "example": "50000_plus", "type": "string" }, "has_material_intermediary_ownership": { "example": false, "type": "boolean" }, "high_risk_activities": { "items": { "type": "string" }, "type": "array" }, "high_risk_activities_explanation": { "maxLength": 1000, "type": "string" }, "identifying_information": { "items": { "$ref": "#/definitions/IdentifyingInformation" }, "minItems": 1, "type": "array" }, "is_dao": { "example": false, "type": "boolean" }, "operates_in_prohibited_countries": { "example": false, "type": "boolean" }, "other_websites": { "items": { "type": "string" }, "type": "array" }, "ownership_threshold": { "example": 25, "maximum": 100, "minimum": 0, "type": "integer" }, "physical_address": { "$ref": "#/definitions/ResidentialAddress" }, "primary_website": { "example": "https://example.com", "type": "string" }, "registered_address": { "$ref": "#/definitions/ResidentialAddress" }, "source_of_funds": { "example": "company_funds", "type": "string" }, "source_of_funds_description": { "maxLength": 1000, "type": "string" } }, "required": [ "account_purpose", "associated_persons", "business_description", "business_legal_name", "business_type", "conducts_money_services", "documents", "estimated_annual_revenue_usd", "expected_monthly_payments_usd", "identifying_information", "is_dao", "operates_in_prohibited_countries", "registered_address", "source_of_funds" ], "type": "object" }, "SubmitTier1VerificationRequest": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountRequest" }, "bvn": { "example": "22345678901", "type": "string" }, "image_url": { "description": "ImageURL supports either an HTTPS URL or a base64 data URL up to 1 MiB decoded, such as data:image/jpeg;base64,...", "example": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...", "type": "string" }, "phone_number": { "example": "+2348012345678", "type": "string" } }, "required": [ "bvn", "image_url" ], "type": "object" }, "SubmitTier2VerificationRequest": { "properties": { "account_purpose": { "enum": [ "charitable_donations", "ecommerce_retail_payments", "investment_purposes", "operating_a_company", "other", "payments_to_friends_or_family_abroad", "personal_or_living_expenses", "protect_wealth", "purchase_goods_and_services", "receive_payment_for_freelancing", "receive_salary" ], "example": "personal_or_living_expenses", "type": "string" }, "acting_as_intermediary": { "description": "ActingAsIntermediary indicates whether the customer is acting as an intermediary for a third party.", "example": false, "type": "boolean" }, "birth_date": { "example": "1990-05-15", "type": "string" }, "customer_type": { "enum": [ "individual", "business" ], "example": "individual", "type": "string" }, "documents": { "items": { "$ref": "#/definitions/Document" }, "type": "array" }, "employment_status": { "description": "EmploymentStatus is the customer's current employment status. Required for high risk customers.", "enum": [ "employed", "homemaker", "retired", "self_employed", "student", "unemployed" ], "example": "employed", "type": "string" }, "expected_monthly_payments_usd": { "enum": [ "0_4999", "5000_9999", "10000_49999", "50000_plus" ], "example": "0_4999", "type": "string" }, "identifying_information": { "items": { "$ref": "#/definitions/IdentifyingInformation" }, "minItems": 1, "type": "array" }, "most_recent_occupation": { "description": "MostRecentOccupation is the customer's most recent occupation category.", "enum": [ "BUSINESS_ADMIN", "STEM", "HEALTHCARE_SOCIAL", "EDUCATION_ARTS_MEDIA", "SERVICE_PUBLIC_SAFETY", "TRADES_LABOR" ], "example": "BUSINESS_ADMIN", "type": "string" }, "nationality": { "example": "NGA", "type": "string" }, "residential_address": { "$ref": "#/definitions/ResidentialAddress" }, "source_of_funds": { "enum": [ "company_funds", "ecommerce_reseller", "gambling_proceeds", "gifts", "government_benefits", "inheritance", "investments_loans", "pension_retirement", "salary", "sale_of_assets_real_estate", "savings", "someone_elses_funds" ], "example": "salary", "type": "string" } }, "required": [ "account_purpose", "acting_as_intermediary", "birth_date", "employment_status", "expected_monthly_payments_usd", "identifying_information", "most_recent_occupation", "nationality", "residential_address", "source_of_funds" ], "type": "object" }, "SupportedChainResponse": { "properties": { "chain": { "example": "POLYGON", "type": "string" }, "chain_id": { "example": 137, "type": "integer" }, "display_name": { "example": "Polygon", "type": "string" }, "icon": { "example": "https://cryptologos.cc/logos/polygon-matic-logo.svg", "type": "string" }, "tokens": { "items": { "$ref": "#/definitions/SupportedChainTokenResponse" }, "type": "array" } }, "type": "object" }, "SupportedChainTokenResponse": { "properties": { "contract_address": { "example": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "type": "string" }, "decimals": { "example": 6, "type": "integer" }, "deposit_enabled": { "example": true, "type": "boolean" }, "display_name": { "example": "Tether USD", "type": "string" }, "icon": { "example": "https://cryptologos.cc/logos/tether-usdt-logo.svg", "type": "string" }, "symbol": { "example": "USDT", "type": "string" }, "withdraw_enabled": { "example": true, "type": "boolean" } }, "type": "object" }, "TransferDestinationReq": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountInput" }, "crypto_address": { "$ref": "#/definitions/CryptoAddressInput" }, "swift_bank_account": { "$ref": "#/definitions/SWIFTBankAccountInput" }, "type": { "enum": [ "BANK_ACCOUNT", "CRYPTO_ADDRESS", "US_BANK_ACCOUNT", "SWIFT_BANK_ACCOUNT" ], "type": "string" }, "us_bank_account": { "$ref": "#/definitions/USBankAccountInput" } }, "required": [ "type" ], "type": "object" }, "TransferMerchantBalanceRequest": { "properties": { "amount_usd": { "example": "12.3400", "type": "string" } }, "required": [ "amount_usd" ], "type": "object" }, "TransferMerchantBalanceResponse": { "properties": { "data": { "$ref": "#/definitions/MerchantBalanceData" } }, "type": "object" }, "TransferRateResponse": { "properties": { "captured_at": { "type": "string" }, "side": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "TransferResponse": { "properties": { "amount": { "type": "string" }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "debit_amount": { "type": "string" }, "debit_currency": { "type": "string" }, "debit_scope": { "type": "string" }, "fee": { "type": "string" }, "flag_reason": { "type": "string" }, "id": { "type": "string" }, "on_behalf_of": { "$ref": "#/definitions/OnBehalfOfReq" }, "rail": { "type": "string" }, "rate": { "$ref": "#/definitions/TransferRateResponse" }, "recipient": { "$ref": "#/definitions/RecipientResponse" }, "reference": { "type": "string" }, "settled_at": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "USBankAccountInput": { "properties": { "account_number": { "type": "string" }, "account_owner_name": { "type": "string" }, "account_type": { "enum": [ "checking", "savings" ], "type": "string" }, "address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_name": { "type": "string" }, "payout_scheme": { "enum": [ "ach", "wire", "rtp" ], "type": "string" }, "routing_number": { "type": "string" } }, "required": [ "account_number", "account_owner_name", "account_type", "address", "bank_name", "payout_scheme", "routing_number" ], "type": "object" }, "USBankAccountResponse": { "properties": { "account_number_last4": { "type": "string" }, "account_owner_name": { "type": "string" }, "account_type": { "type": "string" }, "address": { "$ref": "#/definitions/RecipientAddressInput" }, "bank_name": { "type": "string" }, "payout_scheme": { "type": "string" }, "routing_number": { "type": "string" } }, "type": "object" }, "USDTransferFeesResponse": { "properties": { "fee_percent": { "type": "string" } }, "type": "object" }, "USDVirtualAccountFeesResponse": { "properties": { "deposit_fee_percent": { "type": "string" } }, "type": "object" }, "UpdateCustomerRequest": { "properties": { "email": { "example": "customer@example.com", "type": "string" }, "first_name": { "example": "John", "maxLength": 100, "minLength": 1, "type": "string" }, "last_name": { "example": "Doe", "maxLength": 100, "minLength": 1, "type": "string" } }, "type": "object" }, "UpdateMerchantNGNFundingSettlementRequest": { "properties": { "ngn_settlement_destination": { "enum": [ "USD_BALANCE", "NGN_BALANCE" ], "example": "NGN_BALANCE", "type": "string" } }, "required": [ "ngn_settlement_destination" ], "type": "object" }, "UpdateTier1VerificationRequest": { "properties": { "bank_account": { "$ref": "#/definitions/BankAccountRequest" }, "phone_number": { "example": "+2348012345678", "type": "string" } }, "required": [ "bank_account", "phone_number" ], "type": "object" }, "VADepositInstructions": { "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" } }, "type": "object" }, "VirtualAccountDetails": { "properties": { "account_name": { "example": "Daya-John Doe", "type": "string" }, "account_number": { "example": "1234567890", "type": "string" }, "bank_name": { "example": "Wema Bank", "type": "string" }, "expires_at": { "example": "2025-01-05T16:04:05Z", "type": "string" } }, "type": "object" }, "VirtualAccountResponse": { "properties": { "created_at": { "example": "2025-01-05T15:04:05Z", "type": "string" }, "currency": { "example": "usd", "type": "string" }, "customer_id": { "example": "650e8400-e29b-41d4-a716-446655440002", "type": "string" }, "deposit_instructions": { "$ref": "#/definitions/VADepositInstructions" }, "developer_fee": { "$ref": "#/definitions/DeveloperFeeConfigResponse" }, "id": { "example": "650e8400-e29b-41d4-a716-446655440000", "type": "string" }, "merchant_id": { "example": "650e8400-e29b-41d4-a716-446655440001", "type": "string" }, "provider": { "example": "bridge", "type": "string" }, "status": { "example": "active", "type": "string" }, "updated_at": { "example": "2025-01-05T15:04:05Z", "type": "string" } }, "type": "object" }, "WithdrawalResponse": { "properties": { "amount": { "type": "string" }, "amount_usd": { "type": "string" }, "asset": { "type": "string" }, "chain": { "type": "string" }, "created_at": { "type": "string" }, "destination_address": { "type": "string" }, "failure_code": { "type": "string" }, "failure_message": { "type": "string" }, "fee_usd": { "type": "string" }, "id": { "type": "string" }, "provider_tx_id": { "type": "string" }, "settled_at": { "type": "string" }, "status": { "type": "string" }, "submitted_at": { "type": "string" }, "token": { "type": "string" }, "tx_hash": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.CreateSandboxDepositRequest": { "properties": { "amount": { "example": "10000", "type": "string" }, "currency": { "description": "Merchant funding simulations only. Omit both fields to preserve the legacy fixed 10 USD simulation.", "enum": [ "USD", "NGN" ], "example": "NGN", "type": "string" }, "funding_account_id": { "type": "string" }, "funding_account_scope": { "enum": [ "CUSTOMER", "MERCHANT" ], "example": "CUSTOMER", "type": "string" }, "payout_scenario": { "enum": [ "DEFAULT", "PROCESSING", "SETTLED", "FAILED" ], "example": "SETTLED", "type": "string" }, "scenario": { "enum": [ "DEFAULT", "PROCESSING", "COMPLETED", "REQUIRES_REVIEW", "FAILED" ], "example": "COMPLETED", "type": "string" } }, "required": [ "funding_account_id" ], "type": "object" }, "github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.CreateSandboxDepositResponse": { "properties": { "deposit_id": { "type": "string" }, "message": { "type": "string" }, "payout_scenario": { "type": "string" }, "scenario": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingAddressResponse": { "properties": { "address": { "example": "0x1234", "type": "string" }, "chain": { "example": "POLYGON", "type": "string" } }, "type": "object" }, "github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingCryptoWalletResponse": { "properties": { "addresses": { "items": { "$ref": "#/definitions/github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingAddressResponse" }, "type": "array" }, "wallet_id": { "example": "wallet_123", "type": "string" } }, "type": "object" }, "github_com_Dayaxyz_daya-external-api_cmd_server_handlers_types.MerchantFundingNGNAccountResponse": { "properties": { "account_name": { "example": "Acme Ltd", "type": "string" }, "account_number": { "example": "0123456789", "type": "string" }, "bank_code": { "example": "035", "type": "string" }, "bank_name": { "example": "Wema Bank", "type": "string" } }, "type": "object" } }, "tags": [ { "description": "Public endpoints for fetching exchange rates", "name": "public.rates" }, { "description": "Public endpoints for onramp operations", "name": "public.onramps" }, { "description": "Public endpoints for managing customers and customer verification", "name": "public.customers" }, { "description": "Public endpoints for offramp receive addresses and settlement instructions", "name": "public.offramps" }, { "description": "Public endpoints for funding accounts and payment details", "name": "public.funding-accounts" }, { "description": "Public endpoints for funding account deposits", "name": "public.deposits" }, { "description": "Public endpoints for viewing payouts", "name": "public.payouts" }, { "description": "Public endpoints for creating and viewing transfers", "name": "public.transfers" }, { "description": "Public endpoints for viewing merchant balances", "name": "public.balance" }, { "description": "Public endpoints for viewing merchant funding instructions", "name": "public.merchant-funding" }, { "description": "Public endpoints for creating and viewing customer virtual accounts", "name": "public.virtual-accounts" }, { "description": "Public endpoints for listing supported settlement chains and tokens", "name": "public.supported-chains" }, { "description": "Public endpoints for creating and viewing withdrawals", "name": "public.withdrawals" }, { "description": "Public endpoints for recipients and bank account resolution", "name": "public.recipients" } ], "securityDefinitions": { "ApiKeyAuth": { "description": "Public API Key authentication. Merchants use this for public API access.", "in": "header", "name": "X-API-KEY", "type": "apiKey" } } }