{ "openapi": "3.1.0", "info": { "title": "NorthFond Business API", "version": "1.0.0", "summary": "Provider-neutral stablecoin on-ramp and off-ramp infrastructure.", "description": "NorthFond lets businesses accept payments, inspect treasury balances, provision or register EVM wallets, store beneficiaries, request quotes, initiate on-ramps and off-ramps, confirm settlement, and track transactions. Sandbox and live credentials use the same API contract and remain isolated.", "contact": { "name": "NorthFond API Support" } }, "externalDocs": { "description": "NorthFond developer documentation", "url": "/docs" }, "servers": [ { "url": "https://payment.gideondevrel.xyz", "description": "Configured NorthFond API environment" } ], "tags": [ { "name": "Account", "description": "Authenticated business context." }, { "name": "Customers", "description": "Business-owned customers and managed wallets." }, { "name": "Beneficiaries", "description": "Encrypted, reusable payout destinations." }, { "name": "Wallets", "description": "Managed and external EVM funding wallets." }, { "name": "Quotes", "description": "Provider-neutral off-ramp prices." }, { "name": "Off-ramps", "description": "Stablecoin-to-fiat payout initiation." }, { "name": "On-ramps", "description": "Fiat-to-stablecoin deposit initiation." }, { "name": "Payment intents", "description": "Customer payment collection and lifecycle management." }, { "name": "Treasury", "description": "Business settlement wallet, balances, deposits, and ledger activity." }, { "name": "Transactions", "description": "Payment status, events, and settlement." } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v1/business/account": { "get": { "tags": [ "Account" ], "operationId": "getBusinessAccount", "summary": "Retrieve the authenticated business", "responses": { "200": { "description": "BusinessAccount returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessAccount" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/customers": { "get": { "tags": [ "Customers" ], "operationId": "listCustomers", "summary": "List customers", "x-required-scope": "customers:read", "responses": { "200": { "description": "Customer collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Customers" ], "operationId": "createCustomer", "summary": "Create a customer and managed wallet", "description": "Creates one reusable managed EVM wallet. Reusing the same external reference returns the existing customer.", "x-required-scope": "customers:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } } }, "responses": { "201": { "description": "Customer and managed wallet created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/customers/{id}": { "get": { "tags": [ "Customers" ], "operationId": "getCustomer", "summary": "Retrieve a customer", "x-required-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Customer returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/beneficiaries/requirements": { "get": { "tags": [ "Beneficiaries" ], "operationId": "getBeneficiaryRequirements", "summary": "Load destination-specific beneficiary fields", "x-required-scope": "beneficiaries:read", "parameters": [ { "name": "currency", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 3, "example": "KES" } }, { "name": "payment_method", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/PaymentMethod" } } ], "responses": { "200": { "description": "BeneficiaryRequirements returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryRequirements" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/beneficiaries": { "get": { "tags": [ "Beneficiaries" ], "operationId": "listBeneficiaries", "summary": "List beneficiaries", "x-required-scope": "beneficiaries:read", "parameters": [ { "name": "include_archived", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Beneficiary collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Beneficiary" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Beneficiaries" ], "operationId": "createBeneficiary", "summary": "Create an encrypted beneficiary", "x-required-scope": "beneficiaries:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBeneficiaryRequest" } } } }, "responses": { "201": { "description": "Beneficiary created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/beneficiaries/{id}": { "get": { "tags": [ "Beneficiaries" ], "operationId": "getBeneficiary", "summary": "Retrieve a beneficiary", "x-required-scope": "beneficiaries:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Beneficiary returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "tags": [ "Beneficiaries" ], "operationId": "updateBeneficiary", "summary": "Update a beneficiary label", "x-required-scope": "beneficiaries:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": [ "string", "null" ], "maxLength": 120 } } } } } }, "responses": { "200": { "description": "Beneficiary updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Beneficiaries" ], "operationId": "archiveBeneficiary", "summary": "Archive a beneficiary", "x-required-scope": "beneficiaries:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Beneficiary archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Beneficiary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/wallets": { "get": { "tags": [ "Wallets" ], "operationId": "listWallets", "summary": "List active wallets", "x-required-scope": "wallets:read", "responses": { "200": { "description": "Wallet collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Wallets" ], "operationId": "registerExternalWallet", "summary": "Register an external EVM wallet", "description": "Managed wallets are created through the customer endpoint.", "x-required-scope": "wallets:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWalletRequest" } } } }, "responses": { "201": { "description": "External wallet registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/wallets/{id}": { "get": { "tags": [ "Wallets" ], "operationId": "getWallet", "summary": "Retrieve a wallet", "x-required-scope": "wallets:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Wallet returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "tags": [ "Wallets" ], "operationId": "archiveWallet", "summary": "Archive a wallet", "x-required-scope": "wallets:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Wallet archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/wallets/{id}/balance": { "get": { "tags": [ "Wallets" ], "operationId": "getWalletBalance", "summary": "Read a wallet USDC balance", "description": "The chain query parameter is required for managed wallets. Sandbox returns a simulated balance; live reads canonical USDC on-chain.", "x-required-scope": "wallets:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "chain", "in": "query", "schema": { "$ref": "#/components/schemas/EvmChain" } } ], "responses": { "200": { "description": "WalletBalance returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalance" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/wallets/{id}/verification-challenges": { "post": { "tags": [ "Wallets" ], "operationId": "createWalletVerificationChallenge", "summary": "Create a wallet ownership challenge", "x-required-scope": "wallets:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletVerificationChallenge" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/wallets/{id}/verify": { "post": { "tags": [ "Wallets" ], "operationId": "verifyWalletOwnership", "summary": "Submit a wallet ownership signature", "x-required-scope": "wallets:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyWalletRequest" } } } }, "responses": { "200": { "description": "Wallet ownership verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/quotes": { "post": { "tags": [ "Quotes" ], "operationId": "createQuote", "summary": "Create an on-ramp or off-ramp quote", "x-required-scope": "quotes:read", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" } } } }, "responses": { "201": { "description": "Quote created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/quotes/{id}": { "get": { "tags": [ "Quotes" ], "operationId": "getQuote", "summary": "Retrieve a quote", "x-required-scope": "quotes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Quote returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/offramps": { "post": { "tags": [ "Off-ramps" ], "operationId": "createOfframp", "summary": "Initiate an off-ramp", "description": "Consumes an available quote and creates settlement instructions. Sandbox never moves funds or contacts a provider.", "x-required-scope": "offramps:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOfframpRequest" } } } }, "responses": { "201": { "description": "Off-ramp created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "required": [ "settlement" ], "properties": { "settlement": { "$ref": "#/components/schemas/Settlement" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/offramps/capabilities": { "get": { "tags": [ "Off-ramps" ], "operationId": "getOfframpCapabilities", "summary": "List available off-ramp routes", "description": "Returns the provider-neutral countries, payout methods, chains, and business policy limits available to the authenticated environment.", "x-required-scope": "quotes:read", "responses": { "200": { "description": "OfframpCapabilities returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfframpCapabilities" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/onramps": { "post": { "tags": [ "On-ramps" ], "operationId": "createOnramp", "summary": "Initiate a managed-wallet on-ramp", "description": "Consumes an on-ramp quote and initiates mobile-money collection. Sandbox simulates the lifecycle without moving funds; live availability depends on the authenticated environment readiness response.", "x-required-scope": "onramps:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnrampRequest" } } } }, "responses": { "201": { "description": "On-ramp created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/onramps/readiness": { "get": { "tags": [ "On-ramps" ], "operationId": "getOnrampReadiness", "summary": "Check on-ramp environment readiness", "description": "Returns configuration readiness without creating a quote, provider request, or payment.", "x-required-scope": "onramps:write", "responses": { "200": { "description": "On-ramp readiness returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "environment", "enabled", "provider", "chain", "asset", "currencies", "checks" ], "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "enabled": { "type": "boolean" }, "provider": { "const": "pretium" }, "chain": { "$ref": "#/components/schemas/EvmChain" }, "asset": { "const": "USDC" }, "currencies": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/payment-intents": { "get": { "tags": [ "Payment intents" ], "operationId": "listPaymentIntents", "summary": "List payment intents", "description": "Returns the most recent payment intents for the authenticated business environment.", "x-required-scope": "payment_intents:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "PaymentIntent collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntent" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "tags": [ "Payment intents" ], "operationId": "createPaymentIntent", "summary": "Create a payment intent", "description": "Creates a tenant-scoped collection request. KES pricing currently uses mobile money; USDC pricing uses stablecoin. Live routes remain subject to business policy and runtime readiness.", "x-required-scope": "payment_intents:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentIntentRequest" } } } }, "responses": { "201": { "description": "Payment intent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/payment-intents/{id}": { "get": { "tags": [ "Payment intents" ], "operationId": "getPaymentIntent", "summary": "Retrieve a payment intent", "x-required-scope": "payment_intents:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PaymentIntent returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/payment-intents/{id}/cancel": { "post": { "tags": [ "Payment intents" ], "operationId": "cancelPaymentIntent", "summary": "Cancel a payment intent", "description": "Cancels an intent only while its current lifecycle state permits cancellation.", "x-required-scope": "payment_intents:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Payment intent cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/payment-intents/{id}/simulate": { "post": { "tags": [ "Payment intents" ], "operationId": "simulatePaymentIntent", "summary": "Simulate payment completion", "description": "Sandbox only. Simulates a supported payment method, completes the intent, and posts the corresponding treasury ledger credit without moving funds.", "x-required-scope": "payment_intents:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_method" ], "additionalProperties": false, "properties": { "payment_method": { "type": "string", "enum": [ "mobile_money", "stablecoin" ] } } } } } }, "responses": { "200": { "description": "Payment intent completed in sandbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/treasury": { "get": { "tags": [ "Treasury" ], "operationId": "getTreasury", "summary": "Retrieve the business treasury", "description": "Returns the treasury wallet, settlement configuration, and summarized balances for the authenticated environment. Sandbox may provision on first access; live must be provisioned by NorthFond.", "x-required-scope": "treasury:read", "responses": { "200": { "description": "Treasury returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Treasury" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/treasury/balances": { "get": { "tags": [ "Treasury" ], "operationId": "getTreasuryBalances", "summary": "Retrieve treasury balances", "x-required-scope": "treasury:read", "responses": { "200": { "description": "TreasuryBalances returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryBalances" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/treasury/deposits": { "get": { "tags": [ "Treasury" ], "operationId": "listTreasuryDeposits", "summary": "List treasury deposits", "x-required-scope": "treasury:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "TreasuryDeposit collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryDeposit" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/treasury/ledger": { "get": { "tags": [ "Treasury" ], "operationId": "listTreasuryLedger", "summary": "List treasury ledger entries", "x-required-scope": "treasury:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "TreasuryLedgerEntry collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryLedgerEntry" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/transactions": { "get": { "tags": [ "Transactions" ], "operationId": "listTransactions", "summary": "List transactions", "x-required-scope": "transactions:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Transaction collection returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/transactions/{id}": { "get": { "tags": [ "Transactions" ], "operationId": "getTransaction", "summary": "Retrieve a transaction and its status events", "x-required-scope": "transactions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transaction returned", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionEvent" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/transactions/{id}/settlement": { "get": { "tags": [ "Transactions" ], "operationId": "getTransactionSettlement", "summary": "Retrieve settlement instructions", "x-required-scope": "transactions:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Settlement returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/transactions/{id}/settlement/confirm": { "post": { "tags": [ "Transactions" ], "operationId": "confirmTransactionSettlement", "summary": "Attach and verify an EVM settlement transaction", "description": "Sandbox accepts a simulated transaction hash. Live verifies the USDC contract, sender, receiver, exact amount, receipt, and confirmations.", "x-required-scope": "offramps:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmSettlementRequest" } } } }, "responses": { "200": { "description": "Settlement confirmed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "202": { "description": "Settlement detected; awaiting confirmations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/business/transactions/{id}/retry": { "post": { "tags": [ "Transactions" ], "operationId": "retryManagedWalletTransaction", "summary": "Retry managed-wallet settlement execution", "description": "Retries a managed-wallet transaction in action_required after the underlying operational issue has been corrected.", "x-required-scope": "offramps:write", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NorthFond resource identifier.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Managed-wallet retry accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "nf_test_… or nf_live_…", "description": "A secret NorthFond business API key. Keep it on your server." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A unique key for this logical write operation. Reuse it when retrying the exact same request.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 }, "example": "operation_01K4ZJBP5S9J9T7AM6XW8HCT2F" } }, "responses": { "BadRequest": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "The API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The API key lacks the required scope or the source IP is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The tenant-scoped resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "The request conflicts with current resource or idempotency state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnprocessableEntity": { "description": "The request is understood but cannot be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "The credential rate limit was exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unavailable": { "description": "A required service or environment configuration is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "Environment": { "type": "string", "enum": [ "sandbox", "live" ] }, "EvmChain": { "type": "string", "enum": [ "base", "polygon", "arbitrum", "optimism", "avalanche" ] }, "PaymentMethod": { "type": "string", "enum": [ "mobile_money", "bank_transfer", "paybill", "buy_goods", "email_transfer", "swift_transfer" ] }, "ResourceStatus": { "type": "string", "enum": [ "active", "archived" ] }, "TransactionStatus": { "type": "string", "enum": [ "created", "awaiting_funds", "funded", "signing", "submitting", "processing", "action_required", "completed", "failed" ] }, "BusinessAccount": { "type": "object", "required": [ "id", "name", "environment", "credential" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "credential": { "type": "object", "required": [ "id", "prefix", "scopes" ], "properties": { "id": { "type": "string", "format": "uuid" }, "prefix": { "type": "string", "example": "nf_test_V2nJ64JC" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } }, "CreateCustomerRequest": { "type": "object", "required": [ "external_reference" ], "additionalProperties": false, "properties": { "external_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "Customer": { "type": "object", "required": [ "id", "external_reference", "status", "wallet", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "display_name": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResourceStatus" }, "wallet": { "$ref": "#/components/schemas/ManagedWalletSummary" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ManagedWalletSummary": { "type": "object", "required": [ "id", "type", "address", "asset", "supported_chains", "ownership_status", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "managed_wallet" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "asset": { "const": "USDC" }, "supported_chains": { "type": "array", "items": { "$ref": "#/components/schemas/EvmChain" } }, "ownership_status": { "const": "managed" }, "status": { "$ref": "#/components/schemas/ResourceStatus" } } }, "BeneficiaryFieldOption": { "type": "object", "required": [ "key", "name" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "BeneficiaryField": { "type": "object", "required": [ "key", "name", "required", "values_allowed" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "boolean" }, "example": { "type": [ "string", "null" ] }, "values_allowed": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryFieldOption" } } } }, "BeneficiaryRequirements": { "type": "object", "required": [ "currency", "payment_method", "fields" ], "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryField" } } } }, "OfframpCapabilities": { "type": "object", "required": [ "environment", "enabled", "source", "limits", "countries" ], "properties": { "environment": { "$ref": "#/components/schemas/Environment" }, "enabled": { "type": "boolean" }, "source": { "type": "object", "required": [ "asset", "chains" ], "properties": { "asset": { "const": "USDC" }, "chains": { "type": "array", "items": { "$ref": "#/components/schemas/EvmChain" } } } }, "limits": { "type": "object", "required": [ "maximum_transaction_usdc", "manual_review_threshold_usdc" ], "properties": { "maximum_transaction_usdc": { "type": [ "string", "null" ] }, "manual_review_threshold_usdc": { "type": [ "string", "null" ] } } }, "countries": { "type": "array", "items": { "type": "object", "required": [ "country_code", "country", "currency", "currency_name", "payment_methods" ], "properties": { "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "country": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "currency_name": { "type": "string" }, "payment_methods": { "type": "array", "items": { "type": "object", "required": [ "type", "label" ], "properties": { "type": { "$ref": "#/components/schemas/PaymentMethod" }, "label": { "type": "string" } } } } } } } } }, "CreateBeneficiaryRequest": { "type": "object", "required": [ "currency", "payment_method", "account_holder_name", "details" ], "additionalProperties": false, "properties": { "external_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "KES" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "account_holder_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "label": { "type": "string", "maxLength": 120 }, "details": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "Beneficiary": { "type": "object", "required": [ "id", "currency", "payment_method", "account_holder_name", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "payment_method": { "$ref": "#/components/schemas/PaymentMethod" }, "account_holder_name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ResourceStatus" }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Returned only on detail/create and redacted where sensitive." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "RegisterWalletRequest": { "type": "object", "required": [ "type", "chain", "address" ], "additionalProperties": false, "properties": { "type": { "const": "external_wallet" }, "customer_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "maxLength": 120 }, "chain": { "$ref": "#/components/schemas/EvmChain" }, "asset": { "const": "USDC", "default": "USDC" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "Wallet": { "type": "object", "required": [ "id", "type", "chain", "supported_chains", "asset", "address", "ownership_status", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "type": { "type": "string", "enum": [ "managed_wallet", "external_wallet" ] }, "customer_reference": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "chain": { "type": "string", "description": "`evm` for managed wallets." }, "supported_chains": { "type": "array", "items": { "$ref": "#/components/schemas/EvmChain" } }, "asset": { "const": "USDC" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "ownership_status": { "type": "string", "enum": [ "managed", "unverified", "verified" ] }, "status": { "$ref": "#/components/schemas/ResourceStatus" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WalletBalance": { "type": "object", "required": [ "wallet_id", "chain", "asset", "available", "simulated", "checked_at" ], "properties": { "wallet_id": { "type": "string", "format": "uuid" }, "chain": { "$ref": "#/components/schemas/EvmChain" }, "asset": { "const": "USDC" }, "token_address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "available": { "type": "string", "example": "10000" }, "simulated": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" } } }, "WalletVerificationChallenge": { "type": "object", "required": [ "id", "wallet_id", "message", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "wallet_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "VerifyWalletRequest": { "type": "object", "required": [ "challenge_id", "signature" ], "additionalProperties": false, "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" } } }, "CreateQuoteRequest": { "oneOf": [ { "type": "object", "required": [ "direction", "beneficiary_id", "source_amount", "chain" ], "additionalProperties": false, "properties": { "direction": { "const": "offramp" }, "beneficiary_id": { "type": "string", "format": "uuid" }, "source_asset": { "const": "USDC", "default": "USDC" }, "source_amount": { "type": "number", "minimum": 0.000001, "maximum": 1000000 }, "chain": { "$ref": "#/components/schemas/EvmChain" } } }, { "type": "object", "required": [ "direction", "wallet_id", "source_currency", "source_amount", "chain" ], "additionalProperties": false, "properties": { "direction": { "const": "onramp" }, "wallet_id": { "type": "string", "format": "uuid" }, "source_currency": { "type": "string", "enum": [ "CDF", "GHS", "KES", "MWK", "UGX" ] }, "source_amount": { "type": "number", "minimum": 1, "maximum": 10000000 }, "destination_asset": { "const": "USDC", "default": "USDC" }, "chain": { "$ref": "#/components/schemas/EvmChain" } } } ] }, "Quote": { "type": "object", "required": [ "id", "direction", "status", "source", "destination", "fees", "exchange_rate", "expires_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "offramp", "onramp" ] }, "status": { "type": "string", "enum": [ "available", "consumed", "expired" ] }, "beneficiary_id": { "type": [ "string", "null" ], "format": "uuid" }, "wallet_id": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": "object", "properties": { "asset": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "chain": { "$ref": "#/components/schemas/EvmChain" } } }, "destination": { "type": "object", "properties": { "currency": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "chain": { "$ref": "#/components/schemas/EvmChain" } } }, "fees": { "type": "object", "properties": { "provider": { "type": "string" }, "platform": { "type": "string" }, "platform_bps": { "type": "integer" }, "total_required": { "type": "string" } } }, "exchange_rate": { "type": "string" }, "estimated_delivery": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "FundingSource": { "type": "object", "required": [ "type", "wallet_id" ], "properties": { "type": { "type": "string", "enum": [ "managed_wallet", "external_wallet" ] }, "wallet_id": { "type": "string", "format": "uuid" } } }, "CreateOfframpRequest": { "type": "object", "required": [ "quote_id", "funding_source" ], "additionalProperties": false, "properties": { "quote_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "funding_source": { "$ref": "#/components/schemas/FundingSource" }, "simulation": { "type": "string", "enum": [ "success", "failed", "delayed", "action_required" ], "default": "success", "description": "Sandbox only." } } }, "CreateOnrampRequest": { "type": "object", "required": [ "quote_id", "payment_method" ], "additionalProperties": false, "properties": { "quote_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "payment_method": { "type": "object", "required": [ "type", "phone_number", "mobile_network" ], "additionalProperties": false, "properties": { "type": { "const": "mobile_money" }, "phone_number": { "type": "string", "pattern": "^\\+?[0-9]{7,15}$" }, "mobile_network": { "type": "string", "minLength": 2, "maxLength": 50 } } }, "simulation": { "type": "string", "enum": [ "success", "failed", "delayed", "action_required" ], "default": "success", "description": "Sandbox only." } } }, "CreatePaymentIntentRequest": { "type": "object", "required": [ "external_reference", "amount", "accepted_payment_methods", "settlement" ], "additionalProperties": false, "properties": { "external_reference": { "type": "string", "minLength": 1, "maxLength": 128, "example": "order_1042" }, "amount": { "type": "object", "required": [ "currency", "value" ], "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "KES", "USDC" ] }, "value": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d+)?$", "maxLength": 32, "example": "100" } } }, "accepted_payment_methods": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "mobile_money", "stablecoin" ] }, "description": "KES pricing currently requires mobile_money. USDC pricing currently requires stablecoin." }, "settlement": { "oneOf": [ { "type": "object", "required": [ "mode", "asset", "chain" ], "additionalProperties": false, "properties": { "mode": { "const": "stablecoin" }, "asset": { "const": "USDC" }, "chain": { "const": "base" } } }, { "type": "object", "required": [ "mode", "currency", "beneficiary_id" ], "additionalProperties": false, "properties": { "mode": { "const": "local_currency" }, "currency": { "const": "KES" }, "beneficiary_id": { "type": "string", "format": "uuid" } } } ] }, "customer": { "type": "object", "additionalProperties": false, "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 128 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } } }, "metadata": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Merchant-defined scalar metadata. The serialized object may not exceed 8 KB." }, "expires_in_seconds": { "type": "integer", "minimum": 300, "maximum": 604800, "default": 1800 } } }, "PaymentIntentStatus": { "type": "string", "enum": [ "awaiting_payment", "funds_detected", "processing", "completed", "expired", "cancelled", "failed", "review_required", "approved" ] }, "PaymentIntent": { "type": "object", "required": [ "id", "external_reference", "amount", "accepted_payment_methods", "settlement", "payment_instructions", "status", "customer", "metadata", "expires_at", "cancelled_at", "completed_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "amount": { "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string", "enum": [ "KES", "USDC" ] }, "value": { "type": "string" } } }, "accepted_payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "mobile_money", "stablecoin" ] } }, "settlement": { "type": "object", "required": [ "mode", "currency", "asset", "chain", "amount", "exchange_rate" ], "properties": { "mode": { "type": "string", "enum": [ "stablecoin", "local_currency" ] }, "currency": { "type": "string", "enum": [ "KES", "USDC" ] }, "asset": { "const": "USDC" }, "chain": { "const": "base" }, "amount": { "type": "string" }, "exchange_rate": { "type": "string" }, "beneficiary_id": { "type": [ "string", "null" ], "format": "uuid" }, "payout_status": { "type": [ "string", "null" ] }, "payout_transaction_id": { "type": [ "string", "null" ], "format": "uuid" }, "payout_error": { "type": [ "string", "null" ] } } }, "payment_instructions": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "type", "asset", "chain", "address" ], "properties": { "type": { "const": "stablecoin" }, "asset": { "const": "USDC" }, "chain": { "const": "base" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } } ] }, "status": { "$ref": "#/components/schemas/PaymentIntentStatus" }, "customer": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TreasuryAmount": { "type": "object", "required": [ "atomic", "amount" ], "properties": { "atomic": { "type": "string", "pattern": "^-?\\d+$", "example": "1000000" }, "amount": { "type": "string", "example": "1" } } }, "TreasuryBalances": { "type": "object", "required": [ "asset", "chain", "decimals", "available", "pending", "reserved", "settling", "total" ], "properties": { "asset": { "const": "USDC" }, "chain": { "const": "base" }, "decimals": { "const": 6 }, "available": { "$ref": "#/components/schemas/TreasuryAmount" }, "pending": { "$ref": "#/components/schemas/TreasuryAmount" }, "reserved": { "$ref": "#/components/schemas/TreasuryAmount" }, "settling": { "$ref": "#/components/schemas/TreasuryAmount" }, "total": { "$ref": "#/components/schemas/TreasuryAmount" } } }, "Treasury": { "type": "object", "required": [ "id", "environment_id", "wallet", "settlement", "status", "balances", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "environment_id": { "type": "string", "format": "uuid" }, "wallet": { "type": "object", "required": [ "id", "address", "chain", "supported_chains", "asset", "ownership_status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "chain": { "const": "evm" }, "supported_chains": { "type": "array", "items": { "const": "base" } }, "asset": { "const": "USDC" }, "ownership_status": { "const": "managed" } } }, "settlement": { "type": "object", "required": [ "mode", "asset", "chain" ], "properties": { "mode": { "type": "string", "enum": [ "stablecoin", "local_currency" ] }, "asset": { "const": "USDC" }, "chain": { "const": "base" } } }, "status": { "type": "string" }, "balances": { "$ref": "#/components/schemas/TreasuryBalances" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TreasuryDeposit": { "type": "object", "required": [ "id", "payment_intent_id", "payment_method", "amount", "status", "observed_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "payment_intent_id": { "type": "string", "format": "uuid" }, "payment_method": { "type": "string", "enum": [ "mobile_money", "stablecoin" ] }, "reference": { "type": [ "string", "null" ] }, "amount": { "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "type": "string" }, "value": { "type": "string" } } }, "asset": { "type": [ "string", "null" ] }, "chain": { "type": [ "string", "null" ] }, "transaction_hash": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TreasuryLedgerEntry": { "type": "object", "required": [ "id", "journal_id", "reference", "source_type", "source_id", "account_type", "direction", "amount_atomic", "asset", "chain", "posted_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "journal_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "source_type": { "type": "string" }, "source_id": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "account_type": { "type": "string", "enum": [ "custody", "pending", "available", "reserved", "settlement_payable", "fees_payable" ] }, "direction": { "type": "string", "enum": [ "debit", "credit" ] }, "amount_atomic": { "type": "string", "pattern": "^\\d+$" }, "asset": { "const": "USDC" }, "chain": { "const": "base" }, "posted_at": { "type": "string", "format": "date-time" } } }, "Transaction": { "type": "object", "required": [ "id", "direction", "quote_id", "status", "source", "destination", "fees", "exchange_rate", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "offramp", "onramp" ] }, "external_reference": { "type": [ "string", "null" ] }, "quote_id": { "type": "string", "format": "uuid" }, "beneficiary_id": { "type": [ "string", "null" ], "format": "uuid" }, "wallet_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "funding_source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "managed_wallet", "external_wallet" ] }, "reference": { "type": "string" }, "address": { "type": "string" } } }, "payment_source": { "type": "object", "properties": { "type": { "const": "mobile_money" }, "reference": { "type": "string", "description": "Redacted payment account reference." } } }, "source": { "type": "object", "properties": { "asset": { "const": "USDC" }, "amount": { "type": "string" }, "total_required": { "type": "string" }, "chain": { "$ref": "#/components/schemas/EvmChain" } } }, "destination": { "type": "object", "properties": { "currency": { "type": "string" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "chain": { "$ref": "#/components/schemas/EvmChain" }, "wallet_address": { "type": "string" }, "transaction_hash": { "type": [ "string", "null" ] } } }, "fees": { "type": "object", "properties": { "provider": { "type": "string" }, "platform": { "type": "string" } } }, "exchange_rate": { "type": "string" }, "failure": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": [ "string", "null" ] } } } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TransactionEvent": { "type": "object", "required": [ "id", "to_status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "from_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TransactionStatus" } ] }, "to_status": { "$ref": "#/components/schemas/TransactionStatus" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Settlement": { "type": "object", "required": [ "id", "transaction_id", "status", "chain", "asset", "token_address", "from_address", "to_address", "amount", "confirmations", "required_confirmations", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "transaction_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "awaiting_transfer", "detected", "confirmed" ] }, "chain": { "$ref": "#/components/schemas/EvmChain" }, "asset": { "const": "USDC" }, "token_address": { "type": "string" }, "from_address": { "type": "string" }, "to_address": { "type": "string" }, "amount": { "type": "string" }, "fee_address": { "type": [ "string", "null" ] }, "fee_amount": { "type": "string" }, "total_required": { "type": "string" }, "execution": { "type": "object", "description": "Use direct_transfer when the fee is zero. For fee_splitter, approve the exact raw amount and submit the returned transaction." }, "transaction_hash": { "type": [ "string", "null" ] }, "confirmations": { "type": "integer" }, "required_confirmations": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "detected_at": { "type": [ "string", "null" ], "format": "date-time" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ConfirmSettlementRequest": { "type": "object", "required": [ "transaction_hash" ], "additionalProperties": false, "properties": { "transaction_hash": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "invalid_request" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": {} } } } } } } }