{ "components" : { "callbacks" : { "TerminalPaymentEvent" : { "https://merchant.example/fondeka/webhooks" : { "post" : { "description" : "POST to the originating credential's webhook URL configured when this delivery attempt is claimed. Owners can edit an active key's URL in the portal without rotating its signing secret; queued retries use the updated URL, while in-flight attempts may use the previous URL. The URL below is a placeholder, not an API endpoint. HMAC-SHA256 uses the webhook secret over UTF-8 timestamp + '.' + exact raw request bytes. X-Fondeka-Signature is v1=. Verify in constant time, reject stale timestamps (recommended ±300s), validate environment and deduplicate event ID before fulfillment. Return any 2xx after durable acceptance. Non-2xx, redirects and transport failures retry up to 10 attempts with 30/60/120/240/480/960/1800/1800/1800-second scheduled delays; scheduling can be later. IDs and payload bytes stay fixed; attempt timestamp/signature change. Revoked credentials still deliver accepted payments. Payments still ACCEPTED or PROCESSING do not emit terminal events. Cancellation/expiry generate failed events. No ordering guarantee across payments.", "operationId" : "receiveTerminalPaymentEvent", "parameters" : [ { "description" : "Stable event UUID, equal to body.id.", "in" : "header", "name" : "X-Fondeka-Event-Id", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Current delivery attempt's Unix timestamp in seconds.", "in" : "header", "name" : "X-Fondeka-Timestamp", "required" : true, "schema" : { "pattern" : "^[0-9]+$", "type" : "string" } }, { "description" : "HMAC with this credential's webhook secret; not the API key.", "in" : "header", "name" : "X-Fondeka-Signature", "required" : true, "schema" : { "pattern" : "^v1=[a-f0-9]{64}$", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "completedCollection" : { "value" : { "createdAt" : "2026-10-23T12:00:00Z", "data" : { "environment" : "SANDBOX", "service" : "BUSINESS_API", "action" : "BUSINESS_API_COLLECTION", "orderReference" : "order-0001", "fondekaReference" : "SBX00000000000000000000000000000001", "amount" : 10.0, "fee" : 0.3, "grossAmount" : 10.3, "currency" : "USD", "status" : "COMPLETED" }, "environment" : "SANDBOX", "id" : "11111111-1111-4111-8111-111111111111", "type" : "business_api.collection.completed" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiWebhookEvent" } } }, "required" : true }, "responses" : { "200" : { "description" : "Event durably accepted or already processed; any 2xx acknowledges delivery." } }, "security" : [ ], "summary" : "Receive a signed terminal payment event" } } } }, "headers" : { "RequestId" : { "description" : "Server-generated support identifier. Different for each HTTP attempt, including idempotent replays.", "schema" : { "format" : "uuid", "type" : "string" } } }, "schemas" : { "Balance" : { "description" : "Target balance snapshot. A quote does not change balances.", "properties" : { "balance" : { "description" : "Available balance in this environment; Businesses sharing an owner share wallets.", "example" : 100.0, "type" : "number" }, "currency" : { "description" : "Three-letter fiat currency.", "example" : "USD", "type" : "string" }, "environment" : { "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" } }, "required" : [ "balance", "currency", "environment" ], "type" : "object" }, "BusinessApiError" : { "description" : "HTTP request error. Branch on HTTP status/errorCode, never message. A payment accepted with 202 reports its financial outcome through the transaction resource/webhook instead.", "properties" : { "access" : { "description" : "Current access summary when BUSINESS_TOOLS_ACCESS_REQUIRED.", "type" : "object" }, "blacklistedReason" : { "description" : "Compatibility field for restricted accounts.", "type" : "string" }, "code" : { "description" : "Compatibility alias for entitlement errors only.", "type" : "string" }, "details" : { "additionalProperties" : { "description" : "Optional structured context; validation errors may include fieldErrors.", "type" : "object" }, "description" : "Optional structured context; validation errors may include fieldErrors.", "type" : "object" }, "errorCode" : { "description" : "Stable machine-readable request error code.", "example" : "INVALID_REQUEST", "type" : "string" }, "message" : { "description" : "Human-readable request error.", "type" : "string" }, "reason" : { "description" : "Compatibility field for restricted accounts.", "type" : "string" }, "requestId" : { "description" : "Server-generated identifier, also in X-Request-Id. Include when contacting support.", "type" : "string" }, "status" : { "description" : "HTTP status, also present as statusCode.", "example" : 400, "format" : "int32", "type" : "integer" }, "statusCode" : { "description" : "Compatibility alias of status.", "example" : 400, "format" : "int32", "type" : "integer" } }, "required" : [ "errorCode", "message", "requestId", "status", "statusCode" ], "type" : "object" }, "BusinessApiErrorCatalogResource" : { "description" : "Endpoint-specific business error codes, HTTP statuses and supported sandbox error simulations.", "properties" : { "endpoints" : { "items" : { "$ref" : "#/components/schemas/Endpoint" }, "type" : "array" }, "environment" : { "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" }, "simulationEnabled" : { "type" : "boolean" }, "simulationHeader" : { "type" : "string" } }, "type" : "object" }, "BusinessApiTransactionRequest" : { "anyOf" : [ { "properties" : { "paymentMethodName" : { "type" : "string" } }, "required" : [ "paymentMethodName" ], "type" : "object" }, { "properties" : { "paymentMethodId" : { "format" : "int32", "type" : "integer" } }, "required" : [ "paymentMethodId" ], "type" : "object" } ], "description" : "Fiat-priced collection/payout. Supply paymentMethodName or its legacy ID. Crypto additionally requires a compatible networkName/networkId. Mobile money requires accountRef; all payouts require a destination. Enum membership does not guarantee route/currency/network availability.", "properties" : { "accountRef" : { "description" : "Payer phone for mobile-money collection; recipient phone or crypto address for payout. Phone numbers should use international +country-code format. Optional for crypto collection.", "example" : "+254707371664", "maxLength" : 254, "minLength" : 0, "nullable" : true, "type" : "string" }, "amount" : { "description" : "Fiat amount in currency, never a literal token amount. EXCLUSIVE requests net; INCLUSIVE requests gross. At most two decimal places.", "example" : 10.0, "exclusiveMinimum" : false, "maximum" : 1.0E16, "minimum" : 0.01, "multipleOf" : 0.01, "type" : "number" }, "currency" : { "description" : "Three-letter fiat wallet currency, case-insensitive. Availability depends on configured currency and payment route.", "example" : "USD", "maxLength" : 3, "minLength" : 3, "pattern" : "^[A-Za-z]{3}$", "type" : "string" }, "feeApplicationMode" : { "description" : "EXCLUSIVE: amount is net and fees are added. INCLUSIVE: amount is gross and fees are deducted. Null uses the route default; sandbox defaults to EXCLUSIVE.", "enum" : [ "EXCLUSIVE", "INCLUSIVE" ], "example" : "EXCLUSIVE", "nullable" : true, "type" : "string" }, "networkId" : { "deprecated" : true, "description" : "Legacy database ID; prefer networkName. If both are supplied they must match.", "format" : "int64", "minimum" : 1, "nullable" : true, "type" : "integer" }, "networkName" : { "description" : "Stable crypto-network enum code. Required for crypto unless networkId is supplied.", "enum" : [ "BTC", "LIGHTNING", "ERC20", "BEP20", "TRC20", "POLYGON", "BSC", "ARBITRUM", "BASE", "AVALANCHE", "SOLANA" ], "example" : "TRC20", "nullable" : true, "type" : "string" }, "orderReference" : { "description" : "Your order/invoice reference, returned in payment resources and webhook data. Not an idempotency key.", "example" : "order-0001", "maxLength" : 128, "minLength" : 0, "nullable" : true, "type" : "string" }, "paymentMethodId" : { "deprecated" : true, "description" : "Legacy database ID; prefer paymentMethodName. If both are supplied they must match.", "format" : "int64", "minimum" : 1, "nullable" : true, "type" : "integer" }, "paymentMethodName" : { "description" : "Stable payment-method enum code. Supply this or paymentMethodId.", "enum" : [ "MPESA_DRC", "AIRTEL_MONEY_DRC", "ORANGE_MONEY_DRC", "AFRIMONEY_DRC", "AIRTEL_MONEY_DRC_CDF", "MPESA_DRC_CDF", "ORANGE_MONEY_DRC_CDF", "AFRIMONEY_DRC_CDF", "BTC", "ETH", "USDT", "OTHER_CRYPTOS", "FONDEKA", "BANK", "CARD", "APPLE_PAY_OR_GOOGLE_PAY", "PAYPAL", "BINANCEPAY", "EQUITY_DRC", "BTC_LIGHTENING", "VODACOM_DRC", "AIRTEL_DRC", "ORANGE_DRC", "AFRICELL_DRC", "STABLECOINS", "USDC", "BNB", "SOL", "EURC", "INT_EURO_BANK_ACCOUNT", "INT_USD_BANK_ACCOUNT", "FONDEKA_BALANCE", "PAY_LATER", "AIRTIME_TOPUP", "GHANA_MOBILE_MONEY", "MTN_MOMO_GHANA", "VODAFONE_CASH_GHANA", "AIRTEL_MONEY_GHANA", "GHANA_BANK_TRANSFER", "MPESA_KENYA", "AIRTEL_MONEY_KENYA", "KENYA_BANK_TRANSFER", "MTN_MOMO_CAMEROON", "ORANGE_MONEY_CAMEROON", "MTN_MOMO_COTE_DIVOIRE", "ORANGE_MONEY_COTE_DIVOIRE", "MOOV_MONEY_COTE_DIVOIRE", "WAVE_COTE_DIVOIRE", "MTN_MOMO_BENIN", "ORANGE_MONEY_BENIN", "MOOV_MONEY_BENIN", "CELTIS_MONEY_BENIN", "WAVE_BENIN", "MTN_MOMO_UGANDA", "AIRTEL_MONEY_UGANDA", "TIGO_PESA_TANZANIA", "AIRTEL_MONEY_TANZANIA", "HALOPESA_TANZANIA", "VODACOM_TANZANIA", "MTN_MOMO_RWANDA", "AIRTEL_MONEY_RWANDA", "NIGERIA_NIP_BANK_TRANSFER", "MOOV_MONEY_BURKINA_FASO", "ORANGE_MONEY_BURKINA_FASO", "MPESA_ETHIOPIA", "AIRTEL_MONEY_GABON", "MPESA_LESOTHO", "AIRTEL_MONEY_MALAWI", "TNM_MONEY_MALAWI", "MOVITEL_MOZAMBIQUE", "VODACOM_MOZAMBIQUE", "AIRTEL_MONEY_NIGERIA", "MTN_MOMO_NIGERIA", "AIRTEL_MONEY_CONGO_BRAZZAVILLE", "MTN_MOMO_CONGO_BRAZZAVILLE", "FREE_MONEY_SENEGAL", "ORANGE_MONEY_SENEGAL", "WAVE_SENEGAL", "ORANGE_MONEY_SIERRA_LEONE", "AIRTEL_MONEY_ZAMBIA", "MTN_MOMO_ZAMBIA", "ZAMTEL_MONEY_ZAMBIA", "ECOCASH_BURUNDI", "LUMICASH_BURUNDI" ], "example" : "MPESA_KENYA", "nullable" : true, "type" : "string" } }, "required" : [ "amount", "currency" ], "type" : "object" }, "BusinessApiTransactionResource" : { "description" : "Payment state. Money fields are fiat values in currency; completed collections show settled amounts. HTTP acceptance is not financial completion.", "properties" : { "action" : { "enum" : [ "BUSINESS_API_COLLECTION", "BUSINESS_API_PAYOUT" ], "type" : "string" }, "amount" : { "description" : "Net fiat amount after fees. For a completed collection this is the reconciled wallet credit; before completion it is the quote.", "example" : 10.0, "type" : "number" }, "cryptoDetails" : { "allOf" : [ { "$ref" : "#/components/schemas/CryptoDetails" } ], "description" : "Crypto instructions, omitted for mobile money or while invoice creation is queued. Token amounts are separate from fiat values.", "nullable" : true }, "currency" : { "description" : "Fiat denomination for amount, grossAmount and fee.", "example" : "USD", "type" : "string" }, "environment" : { "description" : "Determined by the API key, not the URL.", "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" }, "failureCode" : { "description" : "Optional sanitized payment failure code. Not an HTTP request error; do not branch on translated messages.", "type" : "string" }, "failureMessage" : { "description" : "Optional displayable failure message; not guaranteed for every provider/outcome.", "type" : "string" }, "fee" : { "description" : "One consolidated fiat fee, including all fee components. grossAmount = amount + fee.", "example" : 0.3, "type" : "number" }, "fondekaReference" : { "description" : "Opaque Fondeka payment reference used for polling. Preserve exactly; do not infer environment from its format.", "example" : "SBX00000000000000000000000000000001", "type" : "string" }, "grossAmount" : { "description" : "Gross fiat amount including fee; payout wallet debit. Completed collections show reconciled gross.", "example" : 10.3, "type" : "number" }, "orderReference" : { "description" : "Merchant-supplied order/invoice reference.", "nullable" : true, "type" : "string" }, "service" : { "enum" : [ "BUSINESS_API" ], "type" : "string" }, "status" : { "description" : "ACCEPTED means queued for execution. PROCESSING means execution has started or the outcome is unresolved. COMPLETED and FAILED are terminal; cancellation/expiry are FAILED. Poll ACCEPTED and PROCESSING with the original reference.", "enum" : [ "ACCEPTED", "PROCESSING", "COMPLETED", "FAILED" ], "type" : "string" } }, "required" : [ "action", "amount", "currency", "environment", "fee", "fondekaReference", "grossAmount", "service", "status" ], "type" : "object" }, "BusinessApiWebhookEvent" : { "description" : "Terminal payment event. Verify timestamp and HMAC against raw bytes before processing. Deduplicate by id; delivery is at least once.", "properties" : { "createdAt" : { "description" : "Snapshot creation time, not the delivery-attempt timestamp.", "format" : "date-time", "type" : "string" }, "data" : { "$ref" : "#/components/schemas/BusinessApiTransactionResource" }, "environment" : { "description" : "Must match your expected environment and data.environment.", "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" }, "id" : { "description" : "Stable event UUID, also sent in X-Fondeka-Event-Id. Unchanged across retries.", "format" : "uuid", "type" : "string" }, "type" : { "enum" : [ "business_api.collection.completed", "business_api.collection.failed", "business_api.payout.completed", "business_api.payout.failed" ], "type" : "string" } }, "required" : [ "createdAt", "data", "environment", "id", "type" ], "type" : "object" }, "Conversion" : { "description" : "Synthetic sandbox conversion. QUOTED has null id/createdAt and reserves nothing. COMPLETED atomically posts two entries, has an id, and returns both balances. Rate is target units per source unit; amounts are rounded to two decimals.", "properties" : { "createdAt" : { "description" : "Completion time; null for a quote.", "format" : "date-time", "nullable" : true, "type" : "string" }, "environment" : { "description" : "Always SANDBOX.", "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" }, "feeAmount" : { "description" : "Source currency fee; currently zero in sandbox.", "type" : "number" }, "id" : { "description" : "Completed conversion ID; null for a quote.", "format" : "uuid", "nullable" : true, "type" : "string" }, "netSourceAmount" : { "description" : "Source amount after the conversion fee.", "type" : "number" }, "rate" : { "description" : "Synthetic target units per source unit. Display rate may be rounded; targetAmount is authoritative.", "type" : "number" }, "sourceAmount" : { "description" : "Amount debited/quoted in source units.", "type" : "number" }, "sourceCurrency" : { "description" : "Currency debited.", "type" : "string" }, "sourceWallet" : { "$ref" : "#/components/schemas/Balance" }, "status" : { "description" : "Quotes reserve nothing; completed conversions post atomically.", "enum" : [ "QUOTED", "COMPLETED" ], "type" : "string" }, "targetAmount" : { "description" : "Target units, rounded to two decimals.", "type" : "number" }, "targetCurrency" : { "description" : "Currency credited.", "type" : "string" }, "targetWallet" : { "$ref" : "#/components/schemas/Balance" } }, "required" : [ "environment", "feeAmount", "netSourceAmount", "rate", "sourceAmount", "sourceCurrency", "status", "targetAmount", "targetCurrency" ], "type" : "object" }, "ConversionRequest" : { "properties" : { "amount" : { "description" : "Amount in source currency, at most two decimal places.", "example" : 10.0, "exclusiveMaximum" : false, "exclusiveMinimum" : false, "maximum" : 1000000.0, "minimum" : 0.01, "type" : "number" }, "sourceCurrency" : { "description" : "Fiat currency to debit.", "example" : "USD", "maxLength" : 3, "minLength" : 3, "pattern" : "^[A-Za-z]{3}$", "type" : "string" }, "targetCurrency" : { "description" : "Different fiat currency to credit; pair must have configured sandbox fixtures.", "example" : "EUR", "maxLength" : 3, "minLength" : 3, "pattern" : "^[A-Za-z]{3}$", "type" : "string" } }, "required" : [ "amount", "sourceCurrency", "targetCurrency" ], "type" : "object" }, "CryptoDetails" : { "description" : "Crypto invoice/destination instructions, included only when available. Token fields are distinct from fiat amounts.", "nullable" : true, "properties" : { "address" : { "description" : "Crypto collection address or payout destination on the selected network.", "nullable" : true, "type" : "string" }, "amountInCrypto" : { "description" : "Token quantity to pay/send, not fiat units. Sandbox uses synthetic 1:1 fixtures.", "nullable" : true, "type" : "number" }, "cryptoCurrency" : { "description" : "Token currency, distinct from the payment's fiat currency.", "nullable" : true, "type" : "string" }, "exchangeRate" : { "description" : "Units of exchangeRateCurrency per token. LIVE rates are USD/token; sandbox is synthetic.", "nullable" : true, "type" : "number" }, "exchangeRateCurrency" : { "description" : "Rate denomination: USD in LIVE, the payment fiat currency in SANDBOX. Separate from the wallet currency.", "nullable" : true, "type" : "string" }, "expiresAt" : { "description" : "Optional crypto invoice expiry; do not pay an expired invoice.", "format" : "date-time", "nullable" : true, "type" : "string" }, "invoiceUrl" : { "description" : "Optional externally generated invoice URL.", "nullable" : true, "type" : "string" }, "network" : { "description" : "Crypto network code; must match the destination.", "nullable" : true, "type" : "string" } }, "type" : "object" }, "Endpoint" : { "properties" : { "additionalRequestErrorsPossible" : { "type" : "boolean" }, "available" : { "type" : "boolean" }, "method" : { "type" : "string" }, "operationId" : { "type" : "string" }, "path" : { "type" : "string" }, "processingErrors" : { "items" : { "$ref" : "#/components/schemas/ProcessingError" }, "type" : "array" }, "requestErrors" : { "items" : { "$ref" : "#/components/schemas/RequestError" }, "type" : "array" } }, "type" : "object" }, "Entry" : { "description" : "One immutable sandbox ledger entry. Signed amount: positive credit, negative debit. sequence orders entries; paymentReference is null for funding/conversions.", "properties" : { "amount" : { "description" : "Signed amount: credits positive, debits negative.", "type" : "number" }, "balanceAfter" : { "description" : "Wallet balance immediately after this entry.", "type" : "number" }, "businessId" : { "description" : "Business that initiated the operation; the wallet is account-owned.", "format" : "int64", "type" : "integer" }, "conversionId" : { "description" : "Shared conversion ID linking debit and credit, null for other entry kinds.", "format" : "uuid", "nullable" : true, "type" : "string" }, "createdAt" : { "description" : "Entry creation time.", "format" : "date-time", "type" : "string" }, "currency" : { "description" : "Fiat currency of this entry.", "type" : "string" }, "environment" : { "description" : "Always SANDBOX.", "enum" : [ "LIVE", "SANDBOX" ], "type" : "string" }, "id" : { "description" : "Immutable ledger entry ID.", "format" : "uuid", "type" : "string" }, "kind" : { "description" : "Reason for the balance movement.", "enum" : [ "TOP_UP", "COLLECTION_CREDIT", "PAYOUT_DEBIT", "PAYOUT_REFUND", "CONVERSION_DEBIT", "CONVERSION_CREDIT" ], "type" : "string" }, "paymentReference" : { "description" : "Related sandbox payment reference, null for funding and conversions.", "nullable" : true, "type" : "string" }, "sequence" : { "description" : "Monotonic ledger sequence used for ordering.", "format" : "int64", "type" : "integer" } }, "required" : [ "amount", "balanceAfter", "businessId", "createdAt", "currency", "environment", "id", "kind", "sequence" ], "type" : "object" }, "PageMetadata" : { "properties" : { "number" : { "format" : "int64", "type" : "integer" }, "size" : { "format" : "int64", "type" : "integer" }, "totalElements" : { "format" : "int64", "type" : "integer" }, "totalPages" : { "format" : "int64", "type" : "integer" } }, "required" : [ "size", "number", "totalElements", "totalPages" ], "type" : "object" }, "PagedModelEntry" : { "description" : "Stable page envelope: content holds entries; page holds zero-based number, size and totals.", "properties" : { "content" : { "items" : { "$ref" : "#/components/schemas/Entry" }, "type" : "array" }, "page" : { "$ref" : "#/components/schemas/PageMetadata" } }, "required" : [ "content", "page" ], "type" : "object" }, "ProcessingError" : { "description" : "Outcome after HTTP 202 acceptance. Terminal failures carry errorCode as failureCode in polling and webhooks. A PROCESSING outcome remains unresolved and emits no terminal webhook. No provider is called in sandbox.", "properties" : { "description" : { "type" : "string" }, "errorCode" : { "type" : "string" }, "paymentMethodTypes" : { "items" : { "enum" : [ "MOBILE_MONEY", "CRYPTO", "BALANCE", "CREDIT", "AIRTIME", "BANK" ], "type" : "string" }, "type" : "array" }, "resultingStatus" : { "enum" : [ "ACCEPTED", "PROCESSING", "COMPLETED", "FAILED" ], "type" : "string" }, "simulatable" : { "type" : "boolean" }, "simulationValue" : { "nullable" : true, "type" : "string" } }, "type" : "object" }, "RequestError" : { "properties" : { "description" : { "type" : "string" }, "errorCode" : { "type" : "string" }, "howToTest" : { "type" : "string" }, "httpStatus" : { "format" : "int32", "type" : "integer" }, "simulatable" : { "type" : "boolean" }, "simulationValue" : { "nullable" : true, "type" : "string" } }, "type" : "object" }, "TopUp" : { "properties" : { "amount" : { "description" : "Virtual funding, at most two decimal places. No actual funds are transferred.", "example" : 100.0, "exclusiveMaximum" : false, "exclusiveMinimum" : false, "maximum" : 1000000.0, "minimum" : 0.01, "type" : "number" }, "currency" : { "description" : "ISO fiat currency for the virtual wallet.", "example" : "USD", "maxLength" : 3, "minLength" : 3, "pattern" : "^[A-Za-z]{3}$", "type" : "string" } }, "required" : [ "amount", "currency" ], "type" : "object" } }, "securitySchemes" : { "Business API Key" : { "description" : "Secret Business-specific credential. Keep server-side. Obtain through the authenticated Business portal. New LIVE keys use fdk_live_; SANDBOX keys use fdk_sandbox_. Existing fdk_biz_live_ and fdk_biz_ LIVE keys, and fdk_biz_sandbox_ and fdk_biz_test_ SANDBOX keys, remain accepted. The stored credential environment is authoritative.", "in" : "header", "name" : "X-API-Key", "type" : "apiKey" } } }, "info" : { "contact" : { "email" : "info@fondeka.com", "name" : "Fondeka", "url" : "https://www.fondeka.com" }, "description" : "Collect and pay out through mobile money and crypto, settling in account fiat wallets. API keys select LIVE or SANDBOX on the same URLs. Merchant endpoints do not use customer JWTs or device sessions. HTTP 202 accepts queued work; only confirmed completion represents a successful payment. Sandbox uses virtual wallets and deterministic fixtures without real providers. The /v1 path is the API major version; info.version versions this documentation contract.", "title" : "Fondeka Business API", "version" : "1.3.0" }, "openapi" : "3.0.3", "paths" : { "/business-api/v1/businesses/{businessId}/collections" : { "post" : { "callbacks" : { "terminalPayment" : { "$ref" : "#/components/callbacks/TerminalPaymentEvent" } }, "description" : "Accept an asynchronous mobile-money or crypto collection. Amount and currency refer to fiat settlement, including crypto. Credit the account wallet only after confirmation. HTTP 202 is acceptance, not payment success. Repeat the same normalized request with the same Idempotency-Key to retrieve its current state without another payment.", "operationId" : "createCollection", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "Required per logical intent. Reuse exactly on retries; changed normalized content returns 409. Payments are scoped to Business+environment; sandbox funding/conversion keys are account-scoped per operation.", "example" : "order-0001-collect", "in" : "header", "name" : "Idempotency-Key", "required" : true, "schema" : { "maxLength" : 128, "minLength" : 1, "pattern" : "^[A-Za-z0-9_.:-]{1,128}$", "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "INVALID_DESTINATION", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "crypto" : { "summary" : "Fiat-priced USDT on TRON", "value" : { "amount" : 10.0, "currency" : "USD", "feeApplicationMode" : "EXCLUSIVE", "networkName" : "TRC20", "orderReference" : "crypto-order-0001", "paymentMethodName" : "USDT" } }, "mobileMoney" : { "summary" : "USD-priced mobile money (route availability applies)", "value" : { "accountRef" : "+254707371664", "amount" : 10.0, "currency" : "USD", "feeApplicationMode" : "EXCLUSIVE", "orderReference" : "order-0001", "paymentMethodName" : "MPESA_KENYA" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiTransactionRequest" } } }, "required" : true }, "responses" : { "202" : { "content" : { "*/*" : { "examples" : { "sandboxAccepted" : { "value" : { "environment" : "SANDBOX", "service" : "BUSINESS_API", "action" : "BUSINESS_API_COLLECTION", "orderReference" : "order-0001", "fondekaReference" : "SBX00000000000000000000000000000001", "amount" : 10.0, "fee" : 0.3, "grossAmount" : 10.3, "currency" : "USD", "status" : "ACCEPTED" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiTransactionResource" } } }, "description" : "Accepted for asynchronous processing, including idempotent replays. Inspect status; acceptance is not completion.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "CRYPTO_NETWORK_REQUIRED" : { "description" : "Omit networkName/networkId for a crypto payment.", "value" : { "errorCode" : "CRYPTO_NETWORK_REQUIRED", "message" : "Crypto payments require a network.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "DESTINATION_REQUIRED" : { "description" : "Omit accountRef for mobile money or a payout.", "value" : { "errorCode" : "DESTINATION_REQUIRED", "message" : "The payer phone number or payout destination is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "FX_ROUTE_UNAVAILABLE" : { "description" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "value" : { "errorCode" : "FX_ROUTE_UNAVAILABLE", "message" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_IDEMPOTENCY_KEY" : { "description" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "value" : { "errorCode" : "INVALID_IDEMPOTENCY_KEY", "message" : "Idempotency-Key has invalid characters or length.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "PAYMENT_METHOD_UNAVAILABLE" : { "description" : "Use an inactive/disabled payment method in a controlled test account.", "value" : { "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "message" : "The configured payment method is unavailable for this operation.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "WARNING_MESSAGE" : { "description" : "Configuration/account dependent; use the normal availability checks.", "value" : { "errorCode" : "WARNING_MESSAGE", "message" : "A route or collection/payout feature is unavailable.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BLACKLISTED" : { "description" : "Use a restricted test account or simulate this request rejection in sandbox.", "value" : { "errorCode" : "BLACKLISTED", "message" : "The owning account is restricted.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_API_LIVE_PAYMENTS_DISABLED" : { "description" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "value" : { "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "message" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } }, "CRYPTO_NETWORK_NOT_FOUND" : { "description" : "Send an unconfigured network identifier.", "value" : { "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "message" : "The crypto network is not configured.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } }, "PAYMENT_METHOD_NOT_FOUND" : { "description" : "Send an unconfigured payment-method identifier.", "value" : { "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "message" : "The named payment method is not configured.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "409" : { "content" : { "application/json" : { "examples" : { "IDEMPOTENCY_CONFLICT" : { "description" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "value" : { "errorCode" : "IDEMPOTENCY_CONFLICT", "message" : "Idempotency key reused with different normalized content.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Idempotency key reused for different normalized content; no new operation accepted.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Collect a payment", "tags" : [ "Payments" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : false }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : false }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : false }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : false }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : false }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : false }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : false }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : false }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_NOT_FOUND" }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_NOT_FOUND" }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_REQUIRED" }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "DESTINATION_REQUIRED" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED" }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_UNAVAILABLE" }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "FX_ROUTE_UNAVAILABLE" }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "WARNING_MESSAGE" } ] }, "x-processing-errors" : [ { "description" : "Sandbox: the payment destination is invalid. Check the number or address and try again.", "errorCode" : "INVALID_DESTINATION", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "INVALID_DESTINATION" }, { "description" : "Sandbox: the payment request was not approved on the payer's phone.", "errorCode" : "PAYMENT_NOT_APPROVED", "paymentMethodTypes" : [ "MOBILE_MONEY" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_NOT_APPROVED" }, { "description" : "Sandbox: the payer has insufficient funds. Ask them to fund their mobile money account and retry.", "errorCode" : "PAYER_INSUFFICIENT_FUNDS", "paymentMethodTypes" : [ "MOBILE_MONEY" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYER_INSUFFICIENT_FUNDS" }, { "description" : "Sandbox: the provider could not process the payment. Try again later.", "errorCode" : "PROVIDER_UNAVAILABLE", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PROVIDER_UNAVAILABLE" }, { "description" : "Sandbox: the payment request expired before it was completed.", "errorCode" : "PAYMENT_EXPIRED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_EXPIRED" }, { "description" : "Sandbox: the payment was cancelled before it was completed.", "errorCode" : "PAYMENT_CANCELLED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_CANCELLED" }, { "description" : "Sandbox: the crypto invoice expired without receiving payment. Create a new collection and use its new payment instructions.", "errorCode" : "CRYPTO_INVOICE_EXPIRED", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_INVOICE_EXPIRED" }, { "description" : "Sandbox: the crypto network was unavailable before a transfer could be broadcast. Try again later.", "errorCode" : "CRYPTO_NETWORK_UNAVAILABLE", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_UNAVAILABLE" }, { "description" : "Sandbox: the crypto payment is awaiting network confirmations. Keep polling its existing reference and do not submit a duplicate payment.", "errorCode" : "CRYPTO_CONFIRMATIONS_PENDING", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "PROCESSING", "simulatable" : true, "simulationValue" : "CRYPTO_CONFIRMATIONS_PENDING" } ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "BLACKLISTED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_CONFLICT", "PAYMENT_METHOD_NOT_FOUND", "CRYPTO_NETWORK_NOT_FOUND", "CRYPTO_NETWORK_REQUIRED", "DESTINATION_REQUIRED", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL", "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "PAYMENT_METHOD_UNAVAILABLE", "FX_ROUTE_UNAVAILABLE", "WARNING_MESSAGE", "INVALID_DESTINATION", "PAYMENT_NOT_APPROVED", "PAYER_INSUFFICIENT_FUNDS", "PROVIDER_UNAVAILABLE", "PAYMENT_EXPIRED", "PAYMENT_CANCELLED", "CRYPTO_INVOICE_EXPIRED", "CRYPTO_NETWORK_UNAVAILABLE", "CRYPTO_CONFIRMATIONS_PENDING" ] } }, "/business-api/v1/businesses/{businessId}/error-codes" : { "get" : { "description" : "Read endpoint-specific HTTP request errors and supported asynchronous payment outcomes. The authenticated key determines the environment. X-Simulate-Error-Code selects an immediate request rejection, a deferred payment failure, or a crypto confirmation hold that remains PROCESSING without a terminal webhook. Check resultingStatus, paymentMethodTypes and the operation before selecting a scenario. Real authentication, ownership and access checks run first. LIVE keys ignore the header. This read submits no payment and calls no provider.", "operationId" : "getErrorCodes", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "endpoints" : [ { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "POST", "operationId" : "createCollection", "path" : "/business-api/v1/businesses/{businessId}/collections", "processingErrors" : [ { "description" : "Sandbox: the payment destination is invalid. Check the number or address and try again.", "errorCode" : "INVALID_DESTINATION", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "INVALID_DESTINATION" }, { "description" : "Sandbox: the payment request was not approved on the payer's phone.", "errorCode" : "PAYMENT_NOT_APPROVED", "paymentMethodTypes" : [ "MOBILE_MONEY" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_NOT_APPROVED" }, { "description" : "Sandbox: the payer has insufficient funds. Ask them to fund their mobile money account and retry.", "errorCode" : "PAYER_INSUFFICIENT_FUNDS", "paymentMethodTypes" : [ "MOBILE_MONEY" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYER_INSUFFICIENT_FUNDS" }, { "description" : "Sandbox: the provider could not process the payment. Try again later.", "errorCode" : "PROVIDER_UNAVAILABLE", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PROVIDER_UNAVAILABLE" }, { "description" : "Sandbox: the payment request expired before it was completed.", "errorCode" : "PAYMENT_EXPIRED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_EXPIRED" }, { "description" : "Sandbox: the payment was cancelled before it was completed.", "errorCode" : "PAYMENT_CANCELLED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_CANCELLED" }, { "description" : "Sandbox: the crypto invoice expired without receiving payment. Create a new collection and use its new payment instructions.", "errorCode" : "CRYPTO_INVOICE_EXPIRED", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_INVOICE_EXPIRED" }, { "description" : "Sandbox: the crypto network was unavailable before a transfer could be broadcast. Try again later.", "errorCode" : "CRYPTO_NETWORK_UNAVAILABLE", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_UNAVAILABLE" }, { "description" : "Sandbox: the crypto payment is awaiting network confirmations. Keep polling its existing reference and do not submit a duplicate payment.", "errorCode" : "CRYPTO_CONFIRMATIONS_PENDING", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "PROCESSING", "simulatable" : true, "simulationValue" : "CRYPTO_CONFIRMATIONS_PENDING" } ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_NOT_FOUND" }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_NOT_FOUND" }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_REQUIRED" }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "DESTINATION_REQUIRED" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED" }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_UNAVAILABLE" }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "FX_ROUTE_UNAVAILABLE" }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "WARNING_MESSAGE" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "POST", "operationId" : "createPayout", "path" : "/business-api/v1/businesses/{businessId}/payouts", "processingErrors" : [ { "description" : "Sandbox: the payment destination is invalid. Check the number or address and try again.", "errorCode" : "INVALID_DESTINATION", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "INVALID_DESTINATION" }, { "description" : "Sandbox: the provider could not process the payment. Try again later.", "errorCode" : "PROVIDER_UNAVAILABLE", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PROVIDER_UNAVAILABLE" }, { "description" : "Sandbox: the payment request expired before it was completed.", "errorCode" : "PAYMENT_EXPIRED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_EXPIRED" }, { "description" : "Sandbox: the payment was cancelled before it was completed.", "errorCode" : "PAYMENT_CANCELLED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_CANCELLED" }, { "description" : "Sandbox: the payout address is invalid for the selected crypto network. Check the address and network together before retrying.", "errorCode" : "CRYPTO_ADDRESS_INVALID", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_ADDRESS_INVALID" }, { "description" : "Sandbox: the crypto network was unavailable before a transfer could be broadcast. Try again later.", "errorCode" : "CRYPTO_NETWORK_UNAVAILABLE", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_UNAVAILABLE" }, { "description" : "Sandbox: the crypto payout was rejected before broadcast. Check the destination and network before retrying.", "errorCode" : "CRYPTO_TRANSFER_REJECTED", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_TRANSFER_REJECTED" }, { "description" : "Sandbox: the crypto payment is awaiting network confirmations. Keep polling its existing reference and do not submit a duplicate payment.", "errorCode" : "CRYPTO_CONFIRMATIONS_PENDING", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "PROCESSING", "simulatable" : true, "simulationValue" : "CRYPTO_CONFIRMATIONS_PENDING" } ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_NOT_FOUND" }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_NOT_FOUND" }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_REQUIRED" }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "DESTINATION_REQUIRED" }, { "description" : "The owner's wallet cannot cover the debit including applicable fees.", "errorCode" : "INSUFFICIENT_FUNDS", "howToTest" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INSUFFICIENT_FUNDS" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED" }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_UNAVAILABLE" }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "FX_ROUTE_UNAVAILABLE" }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "WARNING_MESSAGE" }, { "description" : "Required payout identity verification is incomplete.", "errorCode" : "KYC_NEEDED", "howToTest" : "Requires an unverified test account and an applicable payout policy.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "KYC_NEEDED" }, { "description" : "An overdue-loan policy blocks payout.", "errorCode" : "OUTSTANDING_DEBT", "howToTest" : "Requires an applicable overdue-loan restriction on the test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "OUTSTANDING_DEBT" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "GET", "operationId" : "getTransaction", "path" : "/business-api/v1/businesses/{businessId}/transactions/{reference}", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "PAYMENT_NOT_FOUND", "howToTest" : "Use an unknown payment reference in this Business/environment.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "GET", "operationId" : "listWallets", "path" : "/business-api/v1/businesses/{businessId}/wallets", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "GET", "operationId" : "listSandboxWalletEntries", "path" : "/business-api/v1/businesses/{businessId}/sandbox-wallets/{currency}/entries", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "POST", "operationId" : "createSandboxTopUp", "path" : "/business-api/v1/businesses/{businessId}/sandbox-wallets/top-ups", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The target wallet would exceed its supported balance limit.", "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "howToTest" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "WALLET_BALANCE_LIMIT_EXCEEDED" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "POST", "operationId" : "quoteSandboxConversion", "path" : "/business-api/v1/businesses/{businessId}/sandbox-wallets/convert/quote", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "POST", "operationId" : "createSandboxConversion", "path" : "/business-api/v1/businesses/{businessId}/sandbox-wallets/convert", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The target wallet would exceed its supported balance limit.", "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "howToTest" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "WALLET_BALANCE_LIMIT_EXCEEDED" }, { "description" : "The owner's wallet cannot cover the debit including applicable fees.", "errorCode" : "INSUFFICIENT_FUNDS", "howToTest" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INSUFFICIENT_FUNDS" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, { "additionalRequestErrorsPossible" : false, "available" : true, "method" : "GET", "operationId" : "getErrorCodes", "path" : "/business-api/v1/businesses/{businessId}/error-codes", "processingErrors" : [ ], "requestErrors" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] } ], "environment" : "SANDBOX", "simulationEnabled" : true, "simulationHeader" : "X-Simulate-Error-Code" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiErrorCatalogResource" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "List endpoint error codes and sandbox simulations", "tags" : [ "Reference" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/payouts" : { "post" : { "callbacks" : { "terminalPayment" : { "$ref" : "#/components/callbacks/TerminalPaymentEvent" } }, "description" : "Accept an asynchronous mobile-money or crypto payout. Reserve/debit the account fiat wallet gross amount including fees at acceptance. Crypto token amounts are quoted server-side. A completed payout does not debit again. ACCEPTED means queued; PROCESSING includes execution and unresolved provider outcomes. Both keep funds reserved; do not submit a replacement payment while investigating.", "operationId" : "createPayout", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "Required per logical intent. Reuse exactly on retries; changed normalized content returns 409. Payments are scoped to Business+environment; sandbox funding/conversion keys are account-scoped per operation.", "example" : "order-0001-collect", "in" : "header", "name" : "Idempotency-Key", "required" : true, "schema" : { "maxLength" : 128, "minLength" : 1, "pattern" : "^[A-Za-z0-9_.:-]{1,128}$", "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "INVALID_DESTINATION", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "crypto" : { "summary" : "Fiat-priced USDT on TRON", "value" : { "accountRef" : "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "amount" : 10.0, "currency" : "USD", "feeApplicationMode" : "EXCLUSIVE", "networkName" : "TRC20", "orderReference" : "crypto-order-0001", "paymentMethodName" : "USDT" } }, "mobileMoney" : { "summary" : "USD-priced mobile money (route availability applies)", "value" : { "accountRef" : "+254707371664", "amount" : 10.0, "currency" : "USD", "feeApplicationMode" : "EXCLUSIVE", "orderReference" : "order-0001", "paymentMethodName" : "MPESA_KENYA" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiTransactionRequest" } } }, "required" : true }, "responses" : { "202" : { "content" : { "*/*" : { "examples" : { "sandboxAccepted" : { "value" : { "environment" : "SANDBOX", "service" : "BUSINESS_API", "action" : "BUSINESS_API_PAYOUT", "orderReference" : "order-0001", "fondekaReference" : "SBX00000000000000000000000000000001", "amount" : 10.0, "fee" : 0.3, "grossAmount" : 10.3, "currency" : "USD", "status" : "ACCEPTED" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiTransactionResource" } } }, "description" : "Accepted for asynchronous processing, including idempotent replays. Inspect status; acceptance is not completion.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "CRYPTO_NETWORK_REQUIRED" : { "description" : "Omit networkName/networkId for a crypto payment.", "value" : { "errorCode" : "CRYPTO_NETWORK_REQUIRED", "message" : "Crypto payments require a network.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "DESTINATION_REQUIRED" : { "description" : "Omit accountRef for mobile money or a payout.", "value" : { "errorCode" : "DESTINATION_REQUIRED", "message" : "The payer phone number or payout destination is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "FX_ROUTE_UNAVAILABLE" : { "description" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "value" : { "errorCode" : "FX_ROUTE_UNAVAILABLE", "message" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INSUFFICIENT_FUNDS" : { "description" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "value" : { "errorCode" : "INSUFFICIENT_FUNDS", "message" : "The owner's wallet cannot cover the debit including applicable fees.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_IDEMPOTENCY_KEY" : { "description" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "value" : { "errorCode" : "INVALID_IDEMPOTENCY_KEY", "message" : "Idempotency-Key has invalid characters or length.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "KYC_NEEDED" : { "description" : "Requires an unverified test account and an applicable payout policy.", "value" : { "errorCode" : "KYC_NEEDED", "message" : "Required payout identity verification is incomplete.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "OUTSTANDING_DEBT" : { "description" : "Requires an applicable overdue-loan restriction on the test account.", "value" : { "errorCode" : "OUTSTANDING_DEBT", "message" : "An overdue-loan policy blocks payout.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "PAYMENT_METHOD_UNAVAILABLE" : { "description" : "Use an inactive/disabled payment method in a controlled test account.", "value" : { "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "message" : "The configured payment method is unavailable for this operation.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "WARNING_MESSAGE" : { "description" : "Configuration/account dependent; use the normal availability checks.", "value" : { "errorCode" : "WARNING_MESSAGE", "message" : "A route or collection/payout feature is unavailable.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BLACKLISTED" : { "description" : "Use a restricted test account or simulate this request rejection in sandbox.", "value" : { "errorCode" : "BLACKLISTED", "message" : "The owning account is restricted.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_API_LIVE_PAYMENTS_DISABLED" : { "description" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "value" : { "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "message" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } }, "CRYPTO_NETWORK_NOT_FOUND" : { "description" : "Send an unconfigured network identifier.", "value" : { "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "message" : "The crypto network is not configured.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } }, "PAYMENT_METHOD_NOT_FOUND" : { "description" : "Send an unconfigured payment-method identifier.", "value" : { "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "message" : "The named payment method is not configured.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "409" : { "content" : { "application/json" : { "examples" : { "IDEMPOTENCY_CONFLICT" : { "description" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "value" : { "errorCode" : "IDEMPOTENCY_CONFLICT", "message" : "Idempotency key reused with different normalized content.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Idempotency key reused for different normalized content; no new operation accepted.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Send a payout", "tags" : [ "Payments" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : false }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : false }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : false }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : false }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : false }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : false }, { "description" : "The owner's wallet cannot cover the debit including applicable fees.", "errorCode" : "INSUFFICIENT_FUNDS", "howToTest" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "httpStatus" : 400, "simulatable" : false }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : false }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : false }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Required payout identity verification is incomplete.", "errorCode" : "KYC_NEEDED", "howToTest" : "Requires an unverified test account and an applicable payout policy.", "httpStatus" : 400, "simulatable" : false }, { "description" : "An overdue-loan policy blocks payout.", "errorCode" : "OUTSTANDING_DEBT", "howToTest" : "Requires an applicable overdue-loan restriction on the test account.", "httpStatus" : 400, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The named payment method is not configured.", "errorCode" : "PAYMENT_METHOD_NOT_FOUND", "howToTest" : "Send an unconfigured payment-method identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_NOT_FOUND" }, { "description" : "The crypto network is not configured.", "errorCode" : "CRYPTO_NETWORK_NOT_FOUND", "howToTest" : "Send an unconfigured network identifier.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_NOT_FOUND" }, { "description" : "Crypto payments require a network.", "errorCode" : "CRYPTO_NETWORK_REQUIRED", "howToTest" : "Omit networkName/networkId for a crypto payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_REQUIRED" }, { "description" : "The payer phone number or payout destination is required.", "errorCode" : "DESTINATION_REQUIRED", "howToTest" : "Omit accountRef for mobile money or a payout.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "DESTINATION_REQUIRED" }, { "description" : "The owner's wallet cannot cover the debit including applicable fees.", "errorCode" : "INSUFFICIENT_FUNDS", "howToTest" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INSUFFICIENT_FUNDS" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" }, { "description" : "New LIVE API payments are disabled. Use SANDBOX for testing.", "errorCode" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "howToTest" : "Simulate BUSINESS_API_LIVE_PAYMENTS_DISABLED in sandbox. For LIVE, wait for Fondeka to enable new payments; accepted payments remain readable and replayable.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_API_LIVE_PAYMENTS_DISABLED" }, { "description" : "The configured payment method is unavailable for this operation.", "errorCode" : "PAYMENT_METHOD_UNAVAILABLE", "howToTest" : "Use an inactive/disabled payment method in a controlled test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "PAYMENT_METHOD_UNAVAILABLE" }, { "description" : "The winning payment route lacks an active settlement/provider currency or usable exchange rate. No payment is accepted or funds held.", "errorCode" : "FX_ROUTE_UNAVAILABLE", "howToTest" : "Simulate FX_ROUTE_UNAVAILABLE in sandbox. Choose another method/currency, or ask support to check the route configuration.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "FX_ROUTE_UNAVAILABLE" }, { "description" : "A route or collection/payout feature is unavailable.", "errorCode" : "WARNING_MESSAGE", "howToTest" : "Configuration/account dependent; use the normal availability checks.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "WARNING_MESSAGE" }, { "description" : "Required payout identity verification is incomplete.", "errorCode" : "KYC_NEEDED", "howToTest" : "Requires an unverified test account and an applicable payout policy.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "KYC_NEEDED" }, { "description" : "An overdue-loan policy blocks payout.", "errorCode" : "OUTSTANDING_DEBT", "howToTest" : "Requires an applicable overdue-loan restriction on the test account.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "OUTSTANDING_DEBT" } ] }, "x-processing-errors" : [ { "description" : "Sandbox: the payment destination is invalid. Check the number or address and try again.", "errorCode" : "INVALID_DESTINATION", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "INVALID_DESTINATION" }, { "description" : "Sandbox: the provider could not process the payment. Try again later.", "errorCode" : "PROVIDER_UNAVAILABLE", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PROVIDER_UNAVAILABLE" }, { "description" : "Sandbox: the payment request expired before it was completed.", "errorCode" : "PAYMENT_EXPIRED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_EXPIRED" }, { "description" : "Sandbox: the payment was cancelled before it was completed.", "errorCode" : "PAYMENT_CANCELLED", "paymentMethodTypes" : [ "MOBILE_MONEY", "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "PAYMENT_CANCELLED" }, { "description" : "Sandbox: the payout address is invalid for the selected crypto network. Check the address and network together before retrying.", "errorCode" : "CRYPTO_ADDRESS_INVALID", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_ADDRESS_INVALID" }, { "description" : "Sandbox: the crypto network was unavailable before a transfer could be broadcast. Try again later.", "errorCode" : "CRYPTO_NETWORK_UNAVAILABLE", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_NETWORK_UNAVAILABLE" }, { "description" : "Sandbox: the crypto payout was rejected before broadcast. Check the destination and network before retrying.", "errorCode" : "CRYPTO_TRANSFER_REJECTED", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "FAILED", "simulatable" : true, "simulationValue" : "CRYPTO_TRANSFER_REJECTED" }, { "description" : "Sandbox: the crypto payment is awaiting network confirmations. Keep polling its existing reference and do not submit a duplicate payment.", "errorCode" : "CRYPTO_CONFIRMATIONS_PENDING", "paymentMethodTypes" : [ "CRYPTO" ], "resultingStatus" : "PROCESSING", "simulatable" : true, "simulationValue" : "CRYPTO_CONFIRMATIONS_PENDING" } ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "BLACKLISTED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_CONFLICT", "PAYMENT_METHOD_NOT_FOUND", "CRYPTO_NETWORK_NOT_FOUND", "CRYPTO_NETWORK_REQUIRED", "DESTINATION_REQUIRED", "INSUFFICIENT_FUNDS", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL", "BUSINESS_API_LIVE_PAYMENTS_DISABLED", "PAYMENT_METHOD_UNAVAILABLE", "FX_ROUTE_UNAVAILABLE", "WARNING_MESSAGE", "KYC_NEEDED", "OUTSTANDING_DEBT", "INVALID_DESTINATION", "PROVIDER_UNAVAILABLE", "PAYMENT_EXPIRED", "PAYMENT_CANCELLED", "CRYPTO_ADDRESS_INVALID", "CRYPTO_NETWORK_UNAVAILABLE", "CRYPTO_TRANSFER_REJECTED", "CRYPTO_CONFIRMATIONS_PENDING" ] } }, "/business-api/v1/businesses/{businessId}/sandbox-wallets/convert" : { "post" : { "description" : "SANDBOX only. Atomically debit source and credit target using current synthetic rates. Return COMPLETED with a conversion id and both balances. Idempotent across this account's Businesses/keys; conflicting reuse returns 409. No real money, provider call or payment webhook is involved.", "operationId" : "createSandboxConversion", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "Required per logical intent. Reuse exactly on retries; changed normalized content returns 409. Payments are scoped to Business+environment; sandbox funding/conversion keys are account-scoped per operation.", "example" : "order-0001-collect", "in" : "header", "name" : "Idempotency-Key", "required" : true, "schema" : { "maxLength" : 128, "minLength" : 1, "pattern" : "^[A-Za-z0-9_.:-]{1,128}$", "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "convert" : { "value" : { "amount" : 10.0, "sourceCurrency" : "USD", "targetCurrency" : "EUR" } } }, "schema" : { "$ref" : "#/components/schemas/ConversionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "createdAt" : "2026-10-23T12:00:00Z", "environment" : "SANDBOX", "feeAmount" : 0, "id" : "44444444-4444-4444-8444-444444444444", "netSourceAmount" : 10, "rate" : 0.9, "sourceAmount" : 10, "sourceCurrency" : "USD", "sourceWallet" : { "balance" : 90, "currency" : "USD", "environment" : "SANDBOX" }, "status" : "COMPLETED", "targetAmount" : 9, "targetCurrency" : "EUR", "targetWallet" : { "balance" : 9, "currency" : "EUR", "environment" : "SANDBOX" } } } }, "schema" : { "$ref" : "#/components/schemas/Conversion" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INSUFFICIENT_FUNDS" : { "description" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "value" : { "errorCode" : "INSUFFICIENT_FUNDS", "message" : "The owner's wallet cannot cover the debit including applicable fees.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_IDEMPOTENCY_KEY" : { "description" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "value" : { "errorCode" : "INVALID_IDEMPOTENCY_KEY", "message" : "Idempotency-Key has invalid characters or length.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BLACKLISTED" : { "description" : "Use a restricted test account or simulate this request rejection in sandbox.", "value" : { "errorCode" : "BLACKLISTED", "message" : "The owning account is restricted.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "SANDBOX_ONLY" : { "description" : "Call this sandbox-only route using a LIVE key.", "value" : { "errorCode" : "SANDBOX_ONLY", "message" : "This operation requires sandbox credentials.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "409" : { "content" : { "application/json" : { "examples" : { "IDEMPOTENCY_CONFLICT" : { "description" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "value" : { "errorCode" : "IDEMPOTENCY_CONFLICT", "message" : "Idempotency key reused with different normalized content.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } }, "WALLET_BALANCE_LIMIT_EXCEEDED" : { "description" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "value" : { "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "message" : "The target wallet would exceed its supported balance limit.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Idempotency key reused for different normalized content; no new operation accepted.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Convert sandbox funds", "tags" : [ "Wallets", "Sandbox wallets" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "This operation requires sandbox credentials.", "errorCode" : "SANDBOX_ONLY", "howToTest" : "Call this sandbox-only route using a LIVE key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The target wallet would exceed its supported balance limit.", "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "howToTest" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "WALLET_BALANCE_LIMIT_EXCEEDED" }, { "description" : "The owner's wallet cannot cover the debit including applicable fees.", "errorCode" : "INSUFFICIENT_FUNDS", "howToTest" : "Submit a sandbox payout/conversion that exceeds its virtual wallet balance. This rejects synchronously and creates no accepted payment.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INSUFFICIENT_FUNDS" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "BLACKLISTED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_CONFLICT", "WALLET_BALANCE_LIMIT_EXCEEDED", "INSUFFICIENT_FUNDS", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/sandbox-wallets/convert/quote" : { "post" : { "description" : "SANDBOX only. Return QUOTED with no conversion id. Uses configurable synthetic FX fixtures and zero fees. A quote does not reserve funds or lock a rate. Source and target currencies must differ and have configured fixture rates.", "operationId" : "quoteSandboxConversion", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "convert" : { "value" : { "amount" : 10.0, "sourceCurrency" : "USD", "targetCurrency" : "EUR" } } }, "schema" : { "$ref" : "#/components/schemas/ConversionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "createdAt" : null, "environment" : "SANDBOX", "feeAmount" : 0, "id" : null, "netSourceAmount" : 10, "rate" : 0.9, "sourceAmount" : 10, "sourceCurrency" : "USD", "sourceWallet" : { "balance" : 100, "currency" : "USD", "environment" : "SANDBOX" }, "status" : "QUOTED", "targetAmount" : 9, "targetCurrency" : "EUR", "targetWallet" : { "balance" : 0, "currency" : "EUR", "environment" : "SANDBOX" } } } }, "schema" : { "$ref" : "#/components/schemas/Conversion" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "SANDBOX_ONLY" : { "description" : "Call this sandbox-only route using a LIVE key.", "value" : { "errorCode" : "SANDBOX_ONLY", "message" : "This operation requires sandbox credentials.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Preview a sandbox currency conversion", "tags" : [ "Wallets", "Sandbox wallets" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "This operation requires sandbox credentials.", "errorCode" : "SANDBOX_ONLY", "howToTest" : "Call this sandbox-only route using a LIVE key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/sandbox-wallets/top-ups" : { "post" : { "description" : "SANDBOX only. Add virtual funds synchronously. Maximum 1,000,000 per call and 100 new top-ups per account/currency wallet per UTC day. Replaying an existing identical intent does not consume another quota slot. No provider or real wallet is used.", "operationId" : "createSandboxTopUp", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "Required per logical intent. Reuse exactly on retries; changed normalized content returns 409. Payments are scoped to Business+environment; sandbox funding/conversion keys are account-scoped per operation.", "example" : "order-0001-collect", "in" : "header", "name" : "Idempotency-Key", "required" : true, "schema" : { "maxLength" : 128, "minLength" : 1, "pattern" : "^[A-Za-z0-9_.:-]{1,128}$", "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "examples" : { "fund" : { "value" : { "amount" : 100.0, "currency" : "USD" } } }, "schema" : { "$ref" : "#/components/schemas/TopUp" } } }, "required" : true }, "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "amount" : 100, "balanceAfter" : 100, "businessId" : 42, "conversionId" : null, "createdAt" : "2026-10-23T12:00:00Z", "currency" : "USD", "environment" : "SANDBOX", "id" : "33333333-3333-4333-8333-333333333333", "kind" : "TOP_UP", "paymentReference" : null, "sequence" : 1 } } }, "schema" : { "$ref" : "#/components/schemas/Entry" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_IDEMPOTENCY_KEY" : { "description" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "value" : { "errorCode" : "INVALID_IDEMPOTENCY_KEY", "message" : "Idempotency-Key has invalid characters or length.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BLACKLISTED" : { "description" : "Use a restricted test account or simulate this request rejection in sandbox.", "value" : { "errorCode" : "BLACKLISTED", "message" : "The owning account is restricted.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "SANDBOX_ONLY" : { "description" : "Call this sandbox-only route using a LIVE key.", "value" : { "errorCode" : "SANDBOX_ONLY", "message" : "This operation requires sandbox credentials.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "409" : { "content" : { "application/json" : { "examples" : { "IDEMPOTENCY_CONFLICT" : { "description" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "value" : { "errorCode" : "IDEMPOTENCY_CONFLICT", "message" : "Idempotency key reused with different normalized content.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } }, "WALLET_BALANCE_LIMIT_EXCEEDED" : { "description" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "value" : { "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "message" : "The target wallet would exceed its supported balance limit.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 409, "statusCode" : 409 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Idempotency key reused for different normalized content; no new operation accepted.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Fund a sandbox wallet", "tags" : [ "Wallets", "Sandbox wallets" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "This operation requires sandbox credentials.", "errorCode" : "SANDBOX_ONLY", "howToTest" : "Call this sandbox-only route using a LIVE key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "The owning account is restricted.", "errorCode" : "BLACKLISTED", "howToTest" : "Use a restricted test account or simulate this request rejection in sandbox.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BLACKLISTED" }, { "description" : "Idempotency-Key has invalid characters or length.", "errorCode" : "INVALID_IDEMPOTENCY_KEY", "howToTest" : "Send an invalid Idempotency-Key. A missing required HTTP header may instead return INVALID_REQUEST.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_IDEMPOTENCY_KEY" }, { "description" : "Idempotency key reused with different normalized content.", "errorCode" : "IDEMPOTENCY_CONFLICT", "howToTest" : "Repeat a successful intent with the same Idempotency-Key and a different amount.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "IDEMPOTENCY_CONFLICT" }, { "description" : "The target wallet would exceed its supported balance limit.", "errorCode" : "WALLET_BALANCE_LIMIT_EXCEEDED", "howToTest" : "Use the sandbox simulation code; real funding/conversion validates the supported wallet maximum.", "httpStatus" : 409, "simulatable" : true, "simulationValue" : "WALLET_BALANCE_LIMIT_EXCEEDED" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "BLACKLISTED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_CONFLICT", "WALLET_BALANCE_LIMIT_EXCEEDED", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/sandbox-wallets/{currency}/entries" : { "get" : { "description" : "SANDBOX only. Read append-only account wallet entries, newest sequence first. Includes top-ups, payment credits, payout debits/refunds and conversion entries. LIVE credentials are rejected with 403.", "operationId" : "listSandboxWalletEntries", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "ISO fiat currency, normalized to uppercase. Omit on wallet listing to return all existing wallets.", "example" : "USD", "in" : "path", "name" : "currency", "required" : true, "schema" : { "type" : "string" } }, { "description" : "Zero-based page.", "in" : "query", "name" : "page", "required" : false, "schema" : { "default" : 0, "format" : "int32", "minimum" : 0, "type" : "integer" } }, { "description" : "Entries per page, 1–100.", "in" : "query", "name" : "size", "required" : false, "schema" : { "default" : 20, "format" : "int32", "maximum" : 100, "minimum" : 1, "type" : "integer" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "content" : [ { "amount" : 100, "balanceAfter" : 100, "businessId" : 42, "conversionId" : null, "createdAt" : "2026-10-23T12:00:00Z", "currency" : "USD", "environment" : "SANDBOX", "id" : "33333333-3333-4333-8333-333333333333", "kind" : "TOP_UP", "paymentReference" : null, "sequence" : 1 } ], "page" : { "number" : 0, "size" : 20, "totalElements" : 1, "totalPages" : 1 } } } }, "schema" : { "$ref" : "#/components/schemas/PagedModelEntry" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "SANDBOX_ONLY" : { "description" : "Call this sandbox-only route using a LIVE key.", "value" : { "errorCode" : "SANDBOX_ONLY", "message" : "This operation requires sandbox credentials.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "List sandbox wallet entries", "tags" : [ "Wallets", "Sandbox wallets" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "This operation requires sandbox credentials.", "errorCode" : "SANDBOX_ONLY", "howToTest" : "Call this sandbox-only route using a LIVE key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/transactions/{reference}" : { "get" : { "description" : "Read the current payment state using its opaque reference and a key belonging to the same Business and environment. Use fondekaReference from submission; the URL path is unchanged. Crypto payment instructions are omitted until available. Poll with backoff until instructions or a terminal result are available. Status is ACCEPTED, PROCESSING, COMPLETED or FAILED. FAILED does not imply a refund.", "operationId" : "getTransaction", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque fondekaReference returned by payment submission, from the same Business and environment. The URL path is unchanged.", "example" : "SBX00000000000000000000000000000001", "in" : "path", "name" : "reference", "required" : true, "schema" : { "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : { "environment" : "SANDBOX", "service" : "BUSINESS_API", "action" : "BUSINESS_API_COLLECTION", "orderReference" : "order-0001", "fondekaReference" : "SBX00000000000000000000000000000001", "amount" : 10.0, "fee" : 0.3, "grossAmount" : 10.3, "currency" : "USD", "status" : "COMPLETED" } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiTransactionResource" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "PAYMENT_NOT_FOUND" : { "description" : "Use an unknown payment reference in this Business/environment.", "value" : { "errorCode" : "PAYMENT_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "Retrieve a payment", "tags" : [ "Payments" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Business or payment not found.", "errorCode" : "PAYMENT_NOT_FOUND", "howToTest" : "Use an unknown payment reference in this Business/environment.", "httpStatus" : 404, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "PAYMENT_NOT_FOUND", "howToTest" : "Use an unknown payment reference in this Business/environment.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "PAYMENT_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "PAYMENT_NOT_FOUND", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } }, "/business-api/v1/businesses/{businessId}/wallets" : { "get" : { "description" : "LIVE keys read the owning account's real fiat wallets; SANDBOX keys read isolated virtual wallets. Businesses under the same account share balances within their environment. An absent wallet queried by currency has zero balance.", "operationId" : "listWallets", "parameters" : [ { "description" : "Business ID associated with this API key. A foreign Business returns 403.", "example" : 42, "in" : "path", "name" : "businessId", "required" : true, "schema" : { "format" : "int64", "minimum" : 1, "type" : "integer" } }, { "description" : "ISO fiat currency, normalized to uppercase. Omit on wallet listing to return all existing wallets.", "example" : "USD", "in" : "query", "name" : "currency", "required" : false, "schema" : { "type" : "string" } }, { "description" : "SANDBOX only. Select a requestErrors code for an immediate HTTP rejection without side effects, or a processingErrors code for an accepted asynchronous outcome. Read paymentMethodTypes and resultingStatus: terminal failures expose failureCode in polling/webhooks; CRYPTO_CONFIRMATIONS_PENDING remains PROCESSING with no terminal webhook or payout refund. Real authentication, ownership and access checks run first. Blank, unknown or unsupported codes return 400 INVALID_TEST_ERROR_CODE. Omit for normal success. LIVE credentials ignore any value, regardless of server profile.", "example" : "RATE_LIMITED", "in" : "header", "name" : "X-Simulate-Error-Code", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "*/*" : { "examples" : { "sandbox" : { "value" : [ { "balance" : 100, "currency" : "USD", "environment" : "SANDBOX" } ] } }, "schema" : { "items" : { "$ref" : "#/components/schemas/Balance" }, "type" : "array" } } }, "description" : "Successful read or synchronous sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "400" : { "content" : { "application/json" : { "examples" : { "INVALID_REQUEST" : { "description" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "value" : { "errorCode" : "INVALID_REQUEST", "message" : "Invalid fields, JSON, required headers or unsupported values.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } }, "INVALID_TEST_ERROR_CODE" : { "description" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "value" : { "errorCode" : "INVALID_TEST_ERROR_CODE", "message" : "The simulation code is blank or unsupported for this endpoint.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 400, "statusCode" : 400 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Invalid JSON, fields, required headers, method/network, currency, amount or sandbox simulation code.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "401" : { "content" : { "application/json" : { "examples" : { "AUTHENTICATION_FAILED" : { "description" : "Omit X-API-Key or use an invalid/revoked test key.", "value" : { "errorCode" : "AUTHENTICATION_FAILED", "message" : "Missing, invalid or revoked API credential.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 401, "statusCode" : 401 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Missing, invalid or revoked API key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "403" : { "content" : { "application/json" : { "examples" : { "BUSINESS_MISMATCH" : { "description" : "Use a different Business ID with the same test key.", "value" : { "errorCode" : "BUSINESS_MISMATCH", "message" : "Credential does not belong to the requested Business.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } }, "BUSINESS_TOOLS_ACCESS_REQUIRED" : { "description" : "Use a test account without access while entitlement enforcement is enabled.", "value" : { "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "message" : "The owner's Business Tools entitlement is required.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 403, "statusCode" : 403 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Foreign Business, missing Business Tools access, restricted account or LIVE key on a sandbox operation.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "404" : { "content" : { "application/json" : { "examples" : { "BUSINESS_NOT_FOUND" : { "description" : "Use a missing resource in an otherwise authenticated test request.", "value" : { "errorCode" : "BUSINESS_NOT_FOUND", "message" : "Business or payment not found.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 404, "statusCode" : 404 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Business or same-environment payment not found.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "429" : { "content" : { "application/json" : { "examples" : { "RATE_LIMITED" : { "description" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "value" : { "errorCode" : "RATE_LIMITED", "message" : "A request or sandbox funding quota was reached.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 429, "statusCode" : 429 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "A configured limit was reached; sandbox funding permits 100 new top-ups per account/currency wallet per UTC day.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "500" : { "content" : { "application/json" : { "examples" : { "SOMETHING_WENT_WRONG" : { "description" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "value" : { "errorCode" : "SOMETHING_WENT_WRONG", "message" : "Unexpected server failure; payment outcome must be reconciled.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 500, "statusCode" : 500 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Unexpected request failure. Reconcile/retry the same idempotency key, not a new payment.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } }, "503" : { "content" : { "application/json" : { "examples" : { "BULKHEAD_FULL" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "BULKHEAD_FULL", "message" : "The service has no available execution capacity.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } }, "CIRCUIT_OPEN" : { "description" : "Simulate this request error in sandbox.", "value" : { "errorCode" : "CIRCUIT_OPEN", "message" : "An upstream circuit is open.", "requestId" : "22222222-2222-4222-8222-222222222222", "status" : 503, "statusCode" : 503 } } }, "schema" : { "$ref" : "#/components/schemas/BusinessApiError" } } }, "description" : "Service temporarily unavailable. Retry with backoff and the same idempotency key.", "headers" : { "X-Request-Id" : { "$ref" : "#/components/headers/RequestId" } } } }, "security" : [ { "Business API Key" : [ ] } ], "summary" : "List account wallet balances", "tags" : [ "Wallets" ], "x-error-codes" : { "LIVE" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : false }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : false }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : false }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : false }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : false }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : false }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : false } ], "SANDBOX" : [ { "description" : "Invalid fields, JSON, required headers or unsupported values.", "errorCode" : "INVALID_REQUEST", "howToTest" : "Omit a required field, send malformed JSON, or use invalid currency/pagination values.", "httpStatus" : 400, "simulatable" : true, "simulationValue" : "INVALID_REQUEST" }, { "description" : "The simulation code is blank or unsupported for this endpoint.", "errorCode" : "INVALID_TEST_ERROR_CODE", "howToTest" : "Send an unsupported code in X-Simulate-Error-Code with a SANDBOX key.", "httpStatus" : 400, "simulatable" : false }, { "description" : "Missing, invalid or revoked API credential.", "errorCode" : "AUTHENTICATION_FAILED", "howToTest" : "Omit X-API-Key or use an invalid/revoked test key.", "httpStatus" : 401, "simulatable" : true, "simulationValue" : "AUTHENTICATION_FAILED" }, { "description" : "Credential does not belong to the requested Business.", "errorCode" : "BUSINESS_MISMATCH", "howToTest" : "Use a different Business ID with the same test key.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_MISMATCH" }, { "description" : "The owner's Business Tools entitlement is required.", "errorCode" : "BUSINESS_TOOLS_ACCESS_REQUIRED", "howToTest" : "Use a test account without access while entitlement enforcement is enabled.", "httpStatus" : 403, "simulatable" : true, "simulationValue" : "BUSINESS_TOOLS_ACCESS_REQUIRED" }, { "description" : "Business or payment not found.", "errorCode" : "BUSINESS_NOT_FOUND", "howToTest" : "Use a missing resource in an otherwise authenticated test request.", "httpStatus" : 404, "simulatable" : true, "simulationValue" : "BUSINESS_NOT_FOUND" }, { "description" : "A request or sandbox funding quota was reached.", "errorCode" : "RATE_LIMITED", "howToTest" : "Exercise the configured sandbox quota with distinct intents; never load-test LIVE to trigger this.", "httpStatus" : 429, "simulatable" : true, "simulationValue" : "RATE_LIMITED" }, { "description" : "Unexpected server failure; payment outcome must be reconciled.", "errorCode" : "SOMETHING_WENT_WRONG", "howToTest" : "Simulate this request error in sandbox; real server errors require reconciliation with the original intent.", "httpStatus" : 500, "simulatable" : true, "simulationValue" : "SOMETHING_WENT_WRONG" }, { "description" : "An upstream circuit is open.", "errorCode" : "CIRCUIT_OPEN", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "CIRCUIT_OPEN" }, { "description" : "The service has no available execution capacity.", "errorCode" : "BULKHEAD_FULL", "howToTest" : "Simulate this request error in sandbox.", "httpStatus" : 503, "simulatable" : true, "simulationValue" : "BULKHEAD_FULL" } ] }, "x-processing-errors" : [ ], "x-simulatable-error-codes" : [ "INVALID_REQUEST", "AUTHENTICATION_FAILED", "BUSINESS_MISMATCH", "BUSINESS_TOOLS_ACCESS_REQUIRED", "BUSINESS_NOT_FOUND", "RATE_LIMITED", "SOMETHING_WENT_WRONG", "CIRCUIT_OPEN", "BULKHEAD_FULL" ] } } }, "security" : [ { "Business API Key" : [ ] } ], "servers" : [ { "description" : "LIVE and SANDBOX use this server; the API key determines the environment.", "url" : "https://api.fondeka.com" } ], "tags" : [ { "description" : "Asynchronous collections, payouts and current state.", "name" : "Payments" }, { "description" : "Account fiat balances in the authenticated environment.", "name" : "Wallets" }, { "description" : "Virtual funding, history and synthetic FX. LIVE keys are rejected.", "name" : "Sandbox wallets" }, { "description" : "Endpoint errors and supported sandbox simulation metadata.", "name" : "Reference" } ] }