{ "openapi": "3.0.0", "paths": { "/": { "get": { "operationId": "AppController_getHello", "parameters": [], "responses": { "200": { "description": "API health status fetched successfully." } }, "summary": "Get API health status", "tags": [ "Auth" ] } }, "/login": { "post": { "description": "Authenticates user credentials. Returns a JWT access token containing clientId and user info for Bearer authentication, or a temporary twoFactorToken if 2FA is enabled.", "operationId": "AppController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginUserDto" } } } }, "responses": { "200": { "description": "Authentication successful. Returns token and client details, or initiates 2FA flow.", "content": { "application/json": { "schema": { "example": { "statusCode": 200, "message": "Login successful", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": "01J...", "emailAddress": "developer@example.com", "firstName": "Alex", "lastName": "Morgan" }, "client": { "id": "01J...", "name": "Acme Technologies Inc", "type": "Business" } } } } } } }, "400": { "description": "Validation failed or missing required login fields." }, "401": { "description": "Invalid email address, password, or blocked user." } }, "summary": "Login user to receive JWT access token", "tags": [ "Auth" ] } }, "/login/2fa": { "post": { "description": "Submits OTP or TOTP code together with the temporary twoFactorToken received from POST /login to complete authentication.", "operationId": "AppController_validateLogin2FA", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginTwoFactorDto" } } } }, "responses": { "200": { "description": "2FA verification successful. Returns JWT access token.", "content": { "application/json": { "schema": { "example": { "statusCode": 200, "message": "Login successful", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } } } } } }, "400": { "description": "Invalid or expired 2FA token / code." }, "401": { "description": "2FA challenge failed." } }, "summary": "Complete 2FA login challenge", "tags": [ "Auth" ] } }, "/logout": { "post": { "operationId": "AppController_logout", "parameters": [], "responses": { "200": { "description": "Logged out successfully." } }, "summary": "Logout the current user session", "tags": [ "Auth" ] } }, "/health": { "get": { "operationId": "HealthController_liveness", "parameters": [], "responses": { "200": { "description": "Service is live." } }, "summary": "Liveness probe — is the process up?", "tags": [ "Health" ] } }, "/health/ready": { "get": { "operationId": "HealthController_readiness", "parameters": [], "responses": { "200": { "description": "Service is ready." }, "503": { "description": "One or more dependencies are unreachable." } }, "summary": "Readiness probe — are the API dependencies reachable?", "tags": [ "Health" ] } }, "/events/logs": { "get": { "operationId": "EventsController_getLogs", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List event logs", "tags": [ "Events" ] } }, "/events/logs/{logId}": { "get": { "operationId": "EventsController_getLog", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get event log by ID", "tags": [ "Events" ] } }, "/events": { "get": { "operationId": "EventsController_getAll", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List events", "tags": [ "Events" ] } }, "/events/{eventId}": { "get": { "operationId": "EventsController_get", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get an event by ID", "tags": [ "Events" ] } }, "/events/{eventId}/webhooks": { "get": { "operationId": "EventsController_getWebhook", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get webhooks for an event", "tags": [ "Events" ] } }, "/onboarding-sessions": { "post": { "operationId": "OnboardingSessionsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartOnboardingSessionDto" } } } }, "responses": { "201": { "description": "" } }, "summary": "Start a new onboarding session", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/countries": { "get": { "operationId": "OnboardingSessionsController_getCountries", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Get countries", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/{sessionId}": { "get": { "operationId": "OnboardingSessionsController_get", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "Get onboarding session state and progress", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/{sessionId}/owner": { "put": { "operationId": "OnboardingSessionsController_saveOwner", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveOwnerOnboardingDto" } } } }, "responses": { "200": { "description": "" } }, "summary": "Save owner account and KYC draft data", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/{sessionId}/business": { "put": { "operationId": "OnboardingSessionsController_saveBusiness", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveBusinessOnboardingDto" } } } }, "responses": { "200": { "description": "" } }, "summary": "Save business profiling and KYB draft data", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/{sessionId}/documents": { "post": { "operationId": "OnboardingSessionsController_uploadDocuments", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "passportPhoto": { "type": "string", "format": "binary" }, "idCardImage": { "type": "string", "format": "binary" }, "digitalSignature": { "type": "string", "format": "binary" }, "utilityBill": { "type": "string", "format": "binary" }, "enterpriseDocumentMain": { "type": "string", "format": "binary" }, "enterpriseDocumentBack": { "type": "string", "format": "binary" }, "businessDocumentMain": { "type": "string", "format": "binary" }, "businessDocumentBack": { "type": "string", "format": "binary" }, "businessDocument": { "type": "string", "format": "binary" }, "certificateOfIncorporation": { "type": "string", "format": "binary" }, "memorandumOfAssociation": { "type": "string", "format": "binary" }, "cacDocument": { "type": "string", "format": "binary" }, "registrationDocument": { "type": "string", "format": "binary" }, "representativeProofOfAddress": { "type": "string", "format": "binary" }, "businessProofOfAddress": { "type": "string", "format": "binary" }, "proofOfAddress": { "type": "string", "format": "binary" }, "businessUtilityBill": { "type": "string", "format": "binary" }, "addressProof": { "type": "string", "format": "binary" }, "representativeIdentification": { "type": "string", "format": "binary" }, "businessRepresentativeIdentification": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "summary": "Upload onboarding documents to S3", "tags": [ "Onboarding Sessions" ] } }, "/onboarding-sessions/{sessionId}/submit": { "post": { "operationId": "OnboardingSessionsController_submit", "parameters": [ { "name": "sessionId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "202": { "description": "" } }, "summary": "Submit onboarding and create the client and owner user", "tags": [ "Onboarding Sessions" ] } }, "/users/me": { "get": { "operationId": "UsersController_me", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get current user profile", "tags": [ "Users" ] } }, "/users/switch-profile": { "post": { "operationId": "UsersController_switchClientProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchClientProfileDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Switch the active client profile for the current user", "tags": [ "Users" ] } }, "/users/change-password": { "put": { "operationId": "UsersController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Change user password", "tags": [ "Users" ] } }, "/users/change-pin": { "put": { "operationId": "UsersController_changePIN", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Change2FADto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Change user transaction PIN", "tags": [ "Users" ] } }, "/users/2fa/totp": { "get": { "operationId": "UsersController_enrolTOTP2FA", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get TOTP setup details", "tags": [ "Users" ] } }, "/users/2fa": { "post": { "operationId": "UsersController_enrol2FA", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrol2FADto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Enroll a 2FA method", "tags": [ "Users" ] } }, "/users/2fa/{twoFactorAuthId}": { "delete": { "operationId": "UsersController_delete2FA", "parameters": [ { "name": "twoFactorAuthId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a 2FA method", "tags": [ "Users" ] } }, "/clients": { "post": { "operationId": "ClientsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a client", "tags": [ "Clients" ] }, "get": { "operationId": "ClientsController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Data fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List clients", "tags": [ "Clients" ] } }, "/clients/{clientId}": { "get": { "operationId": "ClientsController_get", "parameters": [ { "name": "clientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a client by ID", "tags": [ "Clients" ] }, "put": { "operationId": "ClientsController_update", "parameters": [ { "name": "clientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a client", "tags": [ "Clients" ] }, "delete": { "operationId": "ClientsController_delete", "parameters": [ { "name": "clientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a client", "tags": [ "Clients" ] } }, "/api-keys": { "post": { "description": "Generates a new API key for server-to-server integration. The plaintext token is returned only once in this creation response; store it securely in your secrets manager.", "operationId": "ClientApiKeysController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientAPIKeyDto" } } } }, "responses": { "201": { "description": "API key created successfully. Contains the plaintext token." }, "400": { "description": "Invalid API key parameters or duplicate key name." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create a client API key", "tags": [ "Client API Keys" ] }, "get": { "description": "Retrieves all API keys configured for the active client profile with masked tokens.", "operationId": "ClientApiKeysController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "List of client API keys retrieved successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List client API keys", "tags": [ "Client API Keys" ] } }, "/api-keys/{apiKeyId}": { "get": { "operationId": "ClientApiKeysController_get", "parameters": [ { "name": "apiKeyId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "API key details retrieved successfully." }, "404": { "description": "API key not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a client API key by ID", "tags": [ "Client API Keys" ] }, "put": { "description": "Updates API key metadata, IP whitelist restriction, or sets status to Active/Inactive.", "operationId": "ClientApiKeysController_update", "parameters": [ { "name": "apiKeyId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientAPIKeyDto" } } } }, "responses": { "200": { "description": "API key updated successfully." }, "400": { "description": "Invalid update parameters." }, "404": { "description": "API key not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update a client API key", "tags": [ "Client API Keys" ] }, "delete": { "description": "Permanently deactivates and soft-deletes the API key. Any future calls using this key will be rejected.", "operationId": "ClientApiKeysController_delete", "parameters": [ { "name": "apiKeyId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "API key revoked successfully." }, "404": { "description": "API key not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Revoke / delete a client API key", "tags": [ "Client API Keys" ] } }, "/webhooks": { "post": { "description": "Registers an HTTPS destination URL to receive real-time event notifications (e.g. card authorizations, transactions, settlements).", "operationId": "ClientWebhooksController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientWebhookDto" } } } }, "responses": { "201": { "description": "Webhook endpoint registered successfully." }, "400": { "description": "Invalid webhook payload or malformed URL." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Register a client webhook endpoint", "tags": [ "Client Webhooks" ] }, "get": { "description": "Retrieves all registered webhook endpoints for the active client profile.", "operationId": "ClientWebhooksController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "List of webhook endpoints retrieved successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List client webhook endpoints", "tags": [ "Client Webhooks" ] } }, "/webhooks/notify": { "post": { "description": "Manually dispatches an event to all active client webhooks subscribed to the event topic. Useful for testing integration handlers.", "operationId": "ClientWebhooksController_notify", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotifyClientWebhookDto" } } } }, "responses": { "200": { "description": "Webhook dispatch initiated." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Trigger a test webhook event", "tags": [ "Client Webhooks" ] } }, "/webhooks/deliveries": { "get": { "description": "Retrieves delivery attempts, HTTP response codes, and timestamps for webhook events sent to your endpoints.", "operationId": "ClientWebhooksController_getDeliveries", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Webhook delivery logs fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List outbound webhook delivery logs", "tags": [ "Client Webhooks" ] } }, "/webhooks/deliveries/{deliveryId}": { "get": { "operationId": "ClientWebhooksController_getDelivery", "parameters": [ { "name": "deliveryId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000002", "type": "string" } } ], "responses": { "200": { "description": "Webhook delivery details fetched successfully." }, "404": { "description": "Delivery record not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get an outbound webhook delivery by ID", "tags": [ "Client Webhooks" ] } }, "/webhooks/deliveries/{deliveryId}/resend": { "post": { "description": "Re-attempts delivering a previously sent or failed webhook event to the endpoint.", "operationId": "ClientWebhooksController_resendDelivery", "parameters": [ { "name": "deliveryId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000002", "type": "string" } } ], "responses": { "200": { "description": "Webhook resend queued." }, "404": { "description": "Delivery record not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Resend a failed webhook delivery", "tags": [ "Client Webhooks" ] } }, "/webhooks/{webhookId}": { "get": { "operationId": "ClientWebhooksController_get", "parameters": [ { "name": "webhookId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000003", "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint fetched successfully." }, "404": { "description": "Webhook not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a webhook endpoint by ID", "tags": [ "Client Webhooks" ] }, "put": { "operationId": "ClientWebhooksController_update", "parameters": [ { "name": "webhookId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000003", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientWebhookDto" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully." }, "400": { "description": "Invalid update parameters." }, "404": { "description": "Webhook not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update a webhook endpoint", "tags": [ "Client Webhooks" ] }, "delete": { "operationId": "ClientWebhooksController_delete", "parameters": [ { "name": "webhookId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000003", "type": "string" } } ], "responses": { "200": { "description": "Webhook endpoint deleted successfully." }, "404": { "description": "Webhook not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "Client Webhooks" ] } }, "/accounts": { "post": { "description": "Creates an operational fiat or crypto account for your business entity.", "operationId": "AccountsController_createAccount", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountDto" } } } }, "responses": { "201": { "description": "Account created successfully." }, "400": { "description": "Invalid account payload." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create a client-level account", "tags": [ "Accounts" ] }, "get": { "description": "Retrieves all accounts for the active client. Inspect your USD fiat accounts to find the accountId required when creating cards (POST /cards) or funding prepaid cards (POST /cards/:cardId/fund).", "operationId": "AccountsController_getAccounts", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "description": "Filter accounts by category", "schema": { "enum": [ "fiat", "crypto" ], "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Filter accounts by currency code (e.g. USD, EUR, NGN)", "schema": { "example": "USD", "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "Filter accounts by business vs customer scope", "schema": { "enum": [ "business", "customer" ], "type": "string" } } ], "responses": { "200": { "description": "Accounts fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List accounts (Card funding sources)", "tags": [ "Accounts" ] } }, "/accounts/wallet": { "post": { "description": "Creates a customer-facing fiat wallet account. Optionally accepts accountAutoSweep to configure internal sweeps to a same-currency client-level account.", "operationId": "AccountsController_createWalletAccount", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAccountDto" }, "examples": { "withoutAutoSweep": { "summary": "Create wallet without auto sweep", "value": { "customerId": "01J00000000000000000000002", "name": "Customer USD Wallet", "type": "checking", "category": "fiat", "status": "active", "currency": "USD" } }, "withAutoSweep": { "summary": "Create wallet with instant auto sweep", "value": { "customerId": "01J00000000000000000000002", "name": "Customer USD Wallet", "type": "checking", "category": "fiat", "status": "active", "currency": "USD", "accountAutoSweep": { "autoSweepEnabled": true, "autoSweepDetails": { "account": "01J00000000000000000000003", "schedule": "Instant" } } } } } } } }, "responses": { "201": { "description": "Wallet account created successfully." }, "400": { "description": "Customer is not eligible, Nuvion entity is missing, or auto sweep config is invalid." }, "404": { "description": "Customer not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create customer wallet account", "tags": [ "Accounts" ] } }, "/accounts/{accountId}": { "get": { "operationId": "AccountsController_getAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Account fetched successfully." }, "404": { "description": "Account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get an account by ID", "tags": [ "Accounts" ] } }, "/accounts/{accountId}/transactions": { "get": { "operationId": "AccountsController_getAccountTransactions", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Account transactions fetched successfully." }, "404": { "description": "Account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get account transactions", "tags": [ "Accounts" ] } }, "/accounts/{accountId}/activity": { "get": { "operationId": "AccountsController_getAccountActivity", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } }, { "name": "period", "required": false, "in": "query", "description": "Period in days (30, 60, or 365). Defaults to 30.", "schema": { "example": 30, "type": "number", "enum": [ 30, 60, 365 ] } } ], "responses": { "200": { "description": "Account activity fetched successfully." }, "404": { "description": "Account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get account activity summary", "tags": [ "Accounts" ] } }, "/accounts/{accountId}/auto-sweep": { "patch": { "description": "Enables or disables internal auto sweep for a customer-facing fiat account. The target account must be a same-currency client-level account. This is a local ledger movement and does not require a Nuvion BAN.", "operationId": "AccountsController_updateAutoSweep", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAutoSweepDto" }, "examples": { "enableInstant": { "summary": "Enable instant auto sweep", "value": { "autoSweepEnabled": true, "autoSweepDetails": { "account": "01J00000000000000000000003", "schedule": "Instant" } } }, "enableDaily": { "summary": "Enable daily auto sweep", "value": { "autoSweepEnabled": true, "autoSweepDetails": { "account": "01J00000000000000000000003", "schedule": "Daily" } } }, "disable": { "summary": "Disable auto sweep", "value": { "autoSweepEnabled": false } } } } } }, "responses": { "200": { "description": "Account auto sweep configuration updated successfully." }, "400": { "description": "Source or target account is not eligible for auto sweep." }, "404": { "description": "Account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update account auto sweep configuration", "tags": [ "Accounts" ] } }, "/accounts/{accountId}/details": { "post": { "operationId": "AccountsController_createAccountDetail", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountDetailDto" } } } }, "responses": { "201": { "description": "Account detail created successfully." }, "400": { "description": "Account is not eligible or provider account detail creation failed." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create account details", "tags": [ "Accounts" ] }, "get": { "operationId": "AccountsController_getAccountDetails", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Account details fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List account details", "tags": [ "Accounts" ] } }, "/accounts/{accountId}/details/{detailId}": { "get": { "operationId": "AccountsController_getAccountDetail", "parameters": [ { "name": "accountId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } }, { "name": "detailId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "Account detail fetched successfully." }, "404": { "description": "Account detail not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get account detail by ID", "tags": [ "Accounts" ] } }, "/customers": { "post": { "description": "Creates a customer record (individual or business) for the active client. The returned customer ID is required as the customerId when issuing virtual cards in POST /cards.", "operationId": "CustomersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerDto" } } } }, "responses": { "201": { "description": "Customer created successfully." }, "400": { "description": "Invalid customer payload or validation error." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create a customer / cardholder", "tags": [ "Customers" ] }, "get": { "description": "Retrieves all customer records created under the active client profile.", "operationId": "CustomersController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Customers fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List customers / cardholders", "tags": [ "Customers" ] } }, "/customers/{customerId}": { "get": { "operationId": "CustomersController_get", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Customer profile fetched successfully." }, "404": { "description": "Customer not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a customer by ID", "tags": [ "Customers" ] }, "patch": { "description": "Updates specific fields on a customer profile (contact, address, or identification).", "operationId": "CustomersController_update", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerDto" } } } }, "responses": { "200": { "description": "Customer updated successfully." }, "400": { "description": "Invalid update payload." }, "404": { "description": "Customer not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update customer / cardholder details", "tags": [ "Customers" ] } }, "/customers/{customerId}/submit": { "post": { "description": "Submits the customer profile and uploaded documents upstream for automated and compliance review.", "operationId": "CustomersController_submit", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Customer submitted for KYC verification." }, "404": { "description": "Customer not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Submit customer for KYC verification", "tags": [ "Customers" ] } }, "/customers/{customerId}/documents": { "post": { "operationId": "CustomersController_addDocuments", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerDocumentsDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Add or update customer documents", "tags": [ "Customers" ] } }, "/customers/{customerId}/identity": { "post": { "operationId": "CustomersController_addIdentifications", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerIdentificationsDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Add or update customer identifications", "tags": [ "Customers" ] } }, "/customers/ocr": { "post": { "operationId": "CustomersController_ocr", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OcrDocumentDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Extract text and fields from an identity document via OCR", "tags": [ "Customers" ] } }, "/customers/{customerId}/wallets": { "post": { "operationId": "CustomersController_createWallet", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create or fetch a crypto wallet for a customer", "tags": [ "Customers" ] }, "get": { "operationId": "CustomersController_getWallet", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a customer crypto wallet and addresses", "tags": [ "Customers" ] } }, "/customers/{customerId}/wallets/addresses": { "post": { "operationId": "CustomersController_createAddress", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAddressDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create or fetch a crypto deposit address for a customer", "tags": [ "Customers" ] }, "get": { "operationId": "CustomersController_getAddresses", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List crypto deposit addresses for a customer", "tags": [ "Customers" ] } }, "/transfers/institutions": { "get": { "description": "Returns supported banks, mobile money operators, or other payout institutions for a country and optional institution type.", "operationId": "TransfersController_getInstitutions", "parameters": [ { "name": "type", "required": false, "in": "query", "schema": { "example": "bank", "type": "string" } }, { "name": "countryCode", "required": false, "in": "query", "schema": { "example": "NG", "type": "string" } } ], "responses": { "200": { "description": "Institutions fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "Get supported payout institutions", "tags": [ "Transfers" ] } }, "/transfers/banks": { "get": { "description": "Returns bank codes used when configuring bank-transfer recipient payment details.", "operationId": "TransfersController_getBankCodes", "parameters": [ { "name": "countryCode", "required": false, "in": "query", "schema": { "example": "NG", "type": "string" } } ], "responses": { "200": { "description": "Bank codes fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "Get supported bank codes", "tags": [ "Transfers" ] } }, "/transfers/lookup-triangle-id": { "get": { "description": "Queries businesses and customers by their unique triangleId (e.g. TRI-8K9M3P).", "operationId": "TransfersController_lookupTriangleId", "parameters": [ { "name": "triangleId", "required": true, "in": "query", "schema": { "example": "TRI-8K9M3P", "type": "string" } } ], "responses": { "200": { "description": "Counterparty details fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "Lookup counterparty by Triangle ID", "tags": [ "Transfers" ] } }, "/transfers": { "post": { "description": "Creates a payout transfer, reserves source funds, and accepts it for asynchronous processing. Use an idempotencyKey for safe retries. Cross-currency transfers require a valid fxQuoteId.", "operationId": "TransfersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferDto" }, "examples": { "sameCurrencyBankTransfer": { "summary": "Same-currency bank transfer", "value": { "sourceAccountId": "01J00000000000000000000002", "recipientId": "01J00000000000000000000008", "recipientPaymentDetailId": "01J00000000000000000000009", "paymentMethod": "bank-transfer", "scheme": "nip", "amount": 100000, "currency": "NGN", "reference": "vendor-payout-001", "idempotencyKey": "vendor-payout-001", "narration": "Vendor payout" } }, "crossCurrencyBankTransfer": { "summary": "Cross-currency bank transfer with FX quote", "value": { "sourceAccountId": "01J00000000000000000000002", "recipientId": "01J00000000000000000000008", "recipientPaymentDetailId": "01J00000000000000000000009", "paymentMethod": "bank-transfer", "scheme": "nip", "amount": 100000, "currency": "USD", "fxQuoteId": "01J00000000000000000000010", "reference": "vendor-payout-002", "idempotencyKey": "vendor-payout-002", "narration": "Vendor payout" } }, "bookTransfer": { "summary": "Internal book transfer", "value": { "sourceAccountId": "01J00000000000000000000002", "recipientId": "01J00000000000000000000008", "recipientPaymentDetailId": "01J00000000000000000000009", "paymentMethod": "book-transfer", "amount": 50000, "currency": "USD", "reference": "internal-send-001", "idempotencyKey": "internal-send-001", "narration": "Internal account transfer" } } } } } }, "responses": { "202": { "description": "Transfer is processing." }, "400": { "description": "Transfer request failed validation, balance, route readiness, or FX requirements." }, "409": { "description": "Idempotency key was already used for a different transfer request." } }, "security": [ { "bearer": [] } ], "summary": "Create a transfer", "tags": [ "Transfers" ] }, "get": { "operationId": "TransfersController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Transfers fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List transfers for the active client profile", "tags": [ "Transfers" ] } }, "/transfers/preview": { "post": { "description": "Validates source account, recipient route, balance, fees, provider readiness, and FX requirements without creating a transfer, reserving funds, or calling the provider.", "operationId": "TransfersController_preview", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewTransferDto" }, "examples": { "previewSameCurrency": { "summary": "Preview same-currency transfer", "value": { "sourceAccountId": "01J00000000000000000000002", "recipientId": "01J00000000000000000000008", "recipientPaymentDetailId": "01J00000000000000000000009", "paymentMethod": "bank-transfer", "scheme": "nip", "amount": 100000, "currency": "NGN", "narration": "Vendor payout" } }, "previewCrossCurrency": { "summary": "Preview cross-currency transfer", "value": { "sourceAccountId": "01J00000000000000000000002", "recipientId": "01J00000000000000000000008", "recipientPaymentDetailId": "01J00000000000000000000009", "paymentMethod": "bank-transfer", "scheme": "nip", "amount": 100000, "currency": "USD", "narration": "Vendor payout" } } } } } }, "responses": { "200": { "description": "Transfer preview generated successfully." }, "400": { "description": "Transfer preview failed validation." } }, "security": [ { "bearer": [] } ], "summary": "Preview and validate a transfer", "tags": [ "Transfers" ] } }, "/transfers/attention": { "get": { "description": "Returns pending or processing transfers that may be stale or missing provider progress and need operational review.", "operationId": "TransfersController_getAttention", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Transfers requiring attention fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List transfers needing attention", "tags": [ "Transfers" ] } }, "/transfers/{transferId}/timeline": { "get": { "operationId": "TransfersController_getTimeline", "parameters": [ { "name": "transferId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Transfer timeline fetched successfully." }, "404": { "description": "Transfer not found." } }, "security": [ { "bearer": [] } ], "summary": "Get transfer lifecycle timeline", "tags": [ "Transfers" ] } }, "/transfers/{transferId}/retry": { "post": { "description": "Retries a transfer only when it is safe to do so, such as failures before provider acceptance.", "operationId": "TransfersController_retry", "parameters": [ { "name": "transferId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Transfer retry submitted successfully." }, "400": { "description": "Transfer cannot be retried safely." }, "404": { "description": "Transfer not found." } }, "security": [ { "bearer": [] } ], "summary": "Retry a transfer", "tags": [ "Transfers" ] } }, "/transfers/{transferId}/cancel": { "post": { "description": "Cancels a transfer before provider acceptance and releases any reserved source funds when applicable.", "operationId": "TransfersController_cancel", "parameters": [ { "name": "transferId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Transfer cancelled successfully." }, "400": { "description": "Transfer cannot be cancelled." }, "404": { "description": "Transfer not found." } }, "security": [ { "bearer": [] } ], "summary": "Cancel a transfer", "tags": [ "Transfers" ] } }, "/transfers/{transferId}": { "get": { "operationId": "TransfersController_get", "parameters": [ { "name": "transferId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Transfer fetched successfully." }, "404": { "description": "Transfer not found." } }, "security": [ { "bearer": [] } ], "summary": "Get a transfer by ID", "tags": [ "Transfers" ] }, "patch": { "description": "Updates mutable transfer metadata before the transfer reaches a terminal state.", "operationId": "TransfersController_update", "parameters": [ { "name": "transferId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTransferDto" } } } }, "responses": { "200": { "description": "Transfer updated successfully." }, "400": { "description": "Transfer can no longer be updated." }, "404": { "description": "Transfer not found." } }, "security": [ { "bearer": [] } ], "summary": "Update a draft or pending transfer", "tags": [ "Transfers" ] } }, "/recipients": { "post": { "operationId": "RecipientsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a transfer recipient", "tags": [ "Recipients" ] }, "get": { "operationId": "RecipientsController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List transfer recipients for the active client profile", "tags": [ "Recipients" ] } }, "/recipients/verify": { "post": { "operationId": "RecipientsController_verify", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRecipientDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Verify recipient account details", "tags": [ "Recipients" ] } }, "/recipients/{recipientId}/payment-details": { "post": { "operationId": "RecipientsController_createPaymentDetail", "parameters": [ { "name": "recipientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipientPaymentDetailDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create payment details for a transfer recipient", "tags": [ "Recipients" ] }, "get": { "operationId": "RecipientsController_getPaymentDetails", "parameters": [ { "name": "recipientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List payment details for a transfer recipient", "tags": [ "Recipients" ] } }, "/recipients/{recipientId}": { "get": { "operationId": "RecipientsController_get", "parameters": [ { "name": "recipientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a transfer recipient by ID", "tags": [ "Recipients" ] }, "patch": { "operationId": "RecipientsController_update", "parameters": [ { "name": "recipientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a transfer recipient", "tags": [ "Recipients" ] }, "delete": { "operationId": "RecipientsController_delete", "parameters": [ { "name": "recipientId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000001", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a transfer recipient", "tags": [ "Recipients" ] } }, "/currencies": { "get": { "operationId": "CurrenciesController_getAll", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "example": "active", "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "capabilityStatus", "required": false, "in": "query", "schema": { "example": "active", "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "activity", "required": false, "in": "query", "schema": { "example": "transfer", "type": "string", "enum": [ "account_issuance", "transfer" ] } }, { "name": "paymentMethod", "required": false, "in": "query", "schema": { "example": "bank-transfer", "type": "string", "enum": [ "bank-transfer", "book-transfer", "stablecoin-transfer", "momo-transfer" ] } }, { "name": "scheme", "required": false, "in": "query", "schema": { "example": "wire", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "usd", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List supported currencies", "tags": [ "Currencies" ] } }, "/fx-quotes": { "post": { "operationId": "FxQuotesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFxQuoteDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create an FX quote", "tags": [ "FX Quotes" ] }, "get": { "operationId": "FxQuotesController_getAll", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "used", "expired", "cancelled" ] } }, { "name": "fromCurrency", "required": false, "in": "query", "schema": { "example": "USD", "type": "string" } }, { "name": "toCurrency", "required": false, "in": "query", "schema": { "example": "NGN", "type": "string" } }, { "name": "sourceAccountId", "required": false, "in": "query", "schema": { "example": "01J00000000000000000000002", "type": "string" } }, { "name": "recipientPaymentDetailId", "required": false, "in": "query", "schema": { "example": "01J00000000000000000000009", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List FX quotes for the active client profile", "tags": [ "FX Quotes" ] } }, "/fx-quotes/{quoteId}": { "get": { "operationId": "FxQuotesController_get", "parameters": [ { "name": "quoteId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get an FX quote by ID", "tags": [ "FX Quotes" ] } }, "/developers/metrics": { "get": { "operationId": "DevelopersController_getMetrics", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get aggregated developer metrics for the active client", "tags": [ "Developers" ] } }, "/contracts/default": { "get": { "operationId": "ContractsController_getDefault", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get the default contract", "tags": [ "Contracts" ] } }, "/contracts/{contractId}": { "get": { "operationId": "ContractsController_get", "parameters": [ { "name": "contractId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a contract", "tags": [ "Contracts" ] } }, "/dashboard/metrics": { "get": { "operationId": "DashboardController_getMetrics", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get dashboard metrics for the active client", "tags": [ "Dashboard" ] } }, "/dashboard/currency-breakdown": { "get": { "operationId": "DashboardController_getCurrencyBreakdown", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get currency breakdown, largest wallet, and last transactions", "tags": [ "Dashboard" ] } }, "/card-programs": { "post": { "description": "Creates a custom card program template defining shared controls, spend limits, currency, and card group (debit vs prepaid).", "operationId": "CardProgramsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardProgramDto" } } } }, "responses": { "201": { "description": "Card program created successfully." }, "400": { "description": "Invalid card program configuration." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Create a card program", "tags": [ "Card Programs" ] }, "get": { "description": "Retrieves all card programs configured for the client profile.", "operationId": "CardProgramsController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Card programs fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List card programs", "tags": [ "Card Programs" ] } }, "/card-programs/{programId}": { "get": { "operationId": "CardProgramsController_get", "parameters": [ { "name": "programId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Card program fetched successfully." }, "404": { "description": "Card program not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a card program by ID", "tags": [ "Card Programs" ] }, "patch": { "operationId": "CardProgramsController_update", "parameters": [ { "name": "programId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardProgramDto" } } } }, "responses": { "200": { "description": "Card program updated successfully." }, "400": { "description": "Invalid update parameters." }, "404": { "description": "Card program not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update a card program", "tags": [ "Card Programs" ] }, "delete": { "operationId": "CardProgramsController_delete", "parameters": [ { "name": "programId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Card program deleted successfully." }, "404": { "description": "Card program not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Delete a card program", "tags": [ "Card Programs" ] } }, "/card-programs/{programId}/cards": { "get": { "operationId": "CardProgramsController_getCards", "parameters": [ { "name": "programId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Cards attached to program fetched successfully." }, "404": { "description": "Card program not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List cards attached to a card program", "tags": [ "Card Programs" ] } }, "/cards": { "post": { "description": "Issues a new card for a customer under the client profile. Requires a valid cardholder customerId (created via POST /customers) and an accountId (from GET /accounts). For \"debit\" cards, purchases draw directly from the linked account. For \"prepaid\" cards, initial funding amount in USD is debited from the funding account and loaded onto the card balance.", "operationId": "CardsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardDto" } } } }, "responses": { "201": { "description": "Card created successfully. Returns masked card details (and initialFunding queue status for prepaid cards)." }, "400": { "description": "Invalid card request, customer not found, insufficient account balance, or missing Nuvion entity." }, "403": { "description": "Access denied or source funding account cannot be debited." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Issue a card (Virtual, Disposable, or Physical)", "tags": [ "Cards" ] }, "get": { "description": "Retrieves all cards issued for the active client profile with support for pagination and filtering.", "operationId": "CardsController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } }, { "name": "group", "required": false, "in": "query", "description": "Filter cards by ledger group", "schema": { "enum": [ "prepaid", "debit" ], "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter cards by form factor", "schema": { "enum": [ "virtual", "disposable", "physical" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter cards by operational status", "schema": { "enum": [ "active", "inactive", "suspended", "terminated", "expired" ], "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "description": "Filter cards by cardholder customer ID", "schema": { "example": "01J00000000000000000000001" } } ], "responses": { "200": { "description": "List of cards fetched successfully." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List cards", "tags": [ "Cards" ] } }, "/cards/issuances/{issuanceId}": { "get": { "description": "Polls the status of an asynchronous prepaid card creation and funding reservation job.", "operationId": "CardsController_getIssuance", "parameters": [ { "name": "issuanceId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Card issuance progress details retrieved." }, "404": { "description": "Issuance record not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get prepaid card issuance queue progress", "tags": [ "Cards" ] } }, "/cards/{cardId}": { "get": { "description": "Retrieves card metadata, status, masked PAN, expiration date, and current balance.", "operationId": "CardsController_get", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Card details retrieved successfully." }, "404": { "description": "Card not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Get a card by ID", "tags": [ "Cards" ] }, "patch": { "description": "Changes operational status: freeze (\"suspended\"), unfreeze (\"active\"), or terminate (\"terminated\"). Also updates spending limits.", "operationId": "CardsController_update", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardDto" } } } }, "responses": { "200": { "description": "Card updated successfully." }, "400": { "description": "Invalid card update payload." }, "404": { "description": "Card not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Update card status or spend controls", "tags": [ "Cards" ] }, "delete": { "description": "Soft-deletes the card record from the local database.", "operationId": "CardsController_delete", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Card deleted successfully." }, "404": { "description": "Card not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Delete a card locally", "tags": [ "Cards" ] } }, "/cards/{cardId}/reveal": { "get": { "description": "Securely decrypts and returns unmasked PCI credentials (full 16-digit card number, CVV, and expiration date) and live balance for cardholder display.", "operationId": "CardsController_reveal", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Sensitive card credentials revealed successfully.", "content": { "application/json": { "schema": { "example": { "statusCode": 200, "message": "Card revealed successfully.", "data": { "id": "01J00000000000000000000000", "name": "Marketing Expense Card", "number": "4111111111111111", "cvv": "123", "expiryMonth": "12", "expiryYear": "2028", "balance": 15000, "status": "active" } } } } } }, "404": { "description": "Card not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Reveal sensitive card details (PAN, CVV, Expiry)", "tags": [ "Cards" ] } }, "/cards/{cardId}/fund": { "post": { "description": "Transfers money from a client account (debitAccountId) to load the balance of a prepaid card.", "operationId": "CardsController_fund", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundCardDto" } } } }, "responses": { "200": { "description": "Prepaid card funded successfully." }, "400": { "description": "Card is not a prepaid card, debit account balance insufficient, or amount <= 1 USD." }, "404": { "description": "Card or debit account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Fund / load money into a prepaid card", "tags": [ "Cards" ] } }, "/cards/{cardId}/withdraw": { "post": { "description": "Unloads funds from a prepaid card and returns them back to a client account (creditAccountId).", "operationId": "CardsController_withdraw", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawCardDto" } } } }, "responses": { "200": { "description": "Funds withdrawn from prepaid card successfully." }, "400": { "description": "Card is not a prepaid card or card balance is insufficient." }, "404": { "description": "Card or credit account not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "Withdraw money from a prepaid card", "tags": [ "Cards" ] } }, "/cards/{cardId}/transactions": { "get": { "description": "Retrieves authorization and settlement transactions made on this specific card.", "operationId": "CardsController_getTransactions", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "Card transactions fetched successfully." }, "404": { "description": "Card not found." } }, "security": [ { "x-api-key": [] }, { "bearer": [] } ], "summary": "List card transactions and authorizations", "tags": [ "Cards" ] } }, "/crypto/addresses/validate": { "post": { "operationId": "CryptoController_validateAddress", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCryptoAddressDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCryptoAddressResultDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validate a recipient crypto wallet address and destination tag/memo", "tags": [ "Crypto" ] } }, "/crypto/validate-address": { "post": { "operationId": "CryptoController_validateAddressAlias", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCryptoAddressDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateCryptoAddressResultDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validate a recipient crypto wallet address (alias)", "tags": [ "Crypto" ] } }, "/crypto/assets": { "get": { "operationId": "CryptoController_getAssets", "parameters": [ { "name": "allowDeposit", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "allowSwap", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "allowWithdrawal", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 5, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "usdt", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List configured crypto assets", "tags": [ "Crypto" ] } }, "/crypto/assets/hot": { "get": { "operationId": "CryptoController_getHotAssets", "parameters": [ { "name": "allowDeposit", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "allowSwap", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "allowWithdrawal", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 5, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "usdt", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List hot crypto assets", "tags": [ "Crypto" ] } }, "/crypto/assets/{assetId}": { "get": { "operationId": "CryptoController_getAssetById", "parameters": [ { "name": "assetId", "required": true, "in": "path", "schema": { "example": "USDT", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a configured crypto asset by ID or symbol", "tags": [ "Crypto" ] } }, "/crypto/networks": { "get": { "operationId": "CryptoController_getSupportedNetworks", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List supported crypto networks", "tags": [ "Crypto" ] } }, "/crypto/supported-assets": { "get": { "operationId": "CryptoController_getSupportedAssetsAndNetworks", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List supported crypto assets with per-asset networks", "tags": [ "Crypto" ] } }, "/crypto/supported-assets/{assetId}/networks": { "get": { "operationId": "CryptoController_getSupportedNetworksForAsset", "parameters": [ { "name": "assetId", "required": true, "in": "path", "schema": { "example": "USDT", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List supported networks for a crypto asset", "tags": [ "Crypto" ] } }, "/crypto/withdrawals": { "post": { "operationId": "CryptoController_createWithdrawal", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCryptoWithdrawalDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create and submit a crypto withdrawal through Fireblocks", "tags": [ "Crypto" ] }, "get": { "operationId": "CryptoController_getWithdrawals", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List crypto withdrawals for the active client profile", "tags": [ "Crypto" ] } }, "/crypto/withdrawals/{withdrawalId}": { "get": { "operationId": "CryptoController_getWithdrawal", "parameters": [ { "name": "withdrawalId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a crypto withdrawal by ID", "tags": [ "Crypto" ] } }, "/crypto/swaps/quotes": { "post": { "operationId": "CryptoController_createSwapQuote", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCryptoSwapQuoteDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a Binance Spot-backed crypto swap quote for an asset pair", "tags": [ "Crypto" ] } }, "/crypto/swaps/quotes/{quoteId}": { "get": { "operationId": "CryptoController_getSwapQuote", "parameters": [ { "name": "quoteId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a crypto swap quote by ID", "tags": [ "Crypto" ] } }, "/crypto/swaps": { "post": { "operationId": "CryptoController_createSwap", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCryptoSwapDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Complete a local crypto swap from a Binance-backed asset-pair quote", "tags": [ "Crypto" ] }, "get": { "operationId": "CryptoController_getSwaps", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "Completed", "Failed" ], "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List crypto swaps for the active client profile", "tags": [ "Crypto" ] } }, "/crypto/swaps/summary": { "get": { "operationId": "CryptoController_getSwapSummary", "parameters": [ { "name": "sourceCurrency", "required": true, "in": "query", "schema": { "example": "USDT", "type": "string" } }, { "name": "destinationCurrency", "required": true, "in": "query", "schema": { "example": "BTC", "type": "string" } }, { "name": "fromDate", "required": true, "in": "query", "schema": { "example": "2026-06-01", "type": "string" } }, { "name": "toDate", "required": true, "in": "query", "schema": { "example": "2026-06-15", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Summarize completed crypto swaps for a currency pair and date range", "tags": [ "Crypto" ] } }, "/crypto/swaps/client-summary": { "get": { "operationId": "CryptoController_getSwapClientSummary", "parameters": [ { "name": "fromDate", "required": false, "in": "query", "schema": { "example": "2026-06-01", "type": "string" } }, { "name": "toDate", "required": false, "in": "query", "schema": { "example": "2026-06-15", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get overall swap summary metrics for the active client", "tags": [ "Crypto" ] } }, "/crypto/swaps/pairs": { "get": { "operationId": "CryptoController_getSwapPairs", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "USDT/USDC", "type": "string" } }, { "name": "sourceAsset", "required": false, "in": "query", "schema": { "example": "USDT", "type": "string" } }, { "name": "destAsset", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List active swap pairs (paginated with intelligent search)", "tags": [ "Crypto" ] } }, "/crypto/swaps/pairs/exchange-info": { "get": { "operationId": "CryptoController_getSwapPairExchangeInfo", "parameters": [ { "name": "fromAsset", "required": true, "in": "query", "schema": { "example": "USDT", "type": "string" } }, { "name": "toAsset", "required": true, "in": "query", "schema": { "example": "BTC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get exchange info for a crypto swap pair", "tags": [ "Crypto" ] } }, "/crypto/customer-wallets": { "get": { "operationId": "CryptoController_getCustomerWallets", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "john", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List customer crypto wallets with addresses (paginated)", "tags": [ "Crypto" ] } }, "/crypto/swaps/{swapId}": { "get": { "operationId": "CryptoController_getSwap", "parameters": [ { "name": "swapId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a crypto swap by ID", "tags": [ "Crypto" ] } }, "/staking/summary": { "get": { "operationId": "StakingController_getSummary", "parameters": [], "responses": { "200": { "description": "Staking summary fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "Get staking summary metrics for the active client", "tags": [ "Staking" ] } }, "/staking/products": { "get": { "operationId": "StakingController_getProducts", "parameters": [], "responses": { "200": { "description": "Staking products fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List active staking products", "tags": [ "Staking" ] } }, "/staking": { "post": { "operationId": "StakingController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStakingPositionDto" } } } }, "responses": { "201": { "description": "Staking position created successfully." }, "400": { "description": "Invalid account, product, currency, amount, or balance." } }, "security": [ { "bearer": [] } ], "summary": "Create a staking position", "tags": [ "Staking" ] }, "get": { "operationId": "StakingController_getAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "Active", "Claimed", "EarlyUnstaked" ] } }, { "name": "accountId", "required": false, "in": "query", "schema": { "example": "01J00000000000000000000001", "type": "string" } }, { "name": "customerId", "required": false, "in": "query", "schema": { "example": "01J00000000000000000000002", "type": "string" } } ], "responses": { "200": { "description": "Staking positions fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List staking positions for the active client profile", "tags": [ "Staking" ] } }, "/staking/{positionId}": { "get": { "operationId": "StakingController_get", "parameters": [ { "name": "positionId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Staking position fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "Get a staking position by ID", "tags": [ "Staking" ] } }, "/staking/{positionId}/claim": { "post": { "operationId": "StakingController_claim", "parameters": [ { "name": "positionId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "Staking position claimed successfully." }, "400": { "description": "Staking position has not reached maturity." } }, "security": [ { "bearer": [] } ], "summary": "Claim a matured staking position", "tags": [ "Staking" ] } }, "/hooks/fireblocks": { "post": { "operationId": "HooksController_handleFireblocksWebhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletWebhookDto" } } } }, "responses": { "201": { "description": "" } }, "summary": "Receive Fireblocks webhooks", "tags": [ "Hooks" ] } }, "/hooks/bridge": { "post": { "operationId": "HooksController_handleBridgeTransferWebhook", "parameters": [], "requestBody": { "required": true, "description": "Bridge webhook event envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "responses": { "201": { "description": "" } }, "summary": "Receive Bridge transfer webhooks", "tags": [ "Hooks" ] } }, "/hooks/nuvion": { "post": { "operationId": "HooksController_handleNuvionTransferWebhook", "parameters": [], "requestBody": { "required": true, "description": "Nuvion transfer webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "responses": { "201": { "description": "" } }, "summary": "Receive Nuvion transfer webhooks", "tags": [ "Hooks" ] } }, "/gift-cards/categories": { "get": { "operationId": "GiftCardsController_getCategories", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List gift card categories", "tags": [ "Gift Cards" ] } }, "/gift-cards/catalogues": { "get": { "operationId": "GiftCardsController_getCatalogues", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "description": "Filter catalogues by category name", "schema": { "example": "Games", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Filter catalogues by currency code", "schema": { "example": "USD", "type": "string" } }, { "name": "categoryId", "required": false, "in": "query", "description": "Filter catalogues by category ID", "schema": { "example": "1", "type": "string" } }, { "name": "price", "required": false, "in": "query", "description": "Price of the gift card to check availability for", "schema": { "example": "50.00", "type": "string" } }, { "name": "quantity", "required": false, "in": "query", "description": "Quantity of the gift cards to check availability for", "schema": { "example": "1", "type": "string" } }, { "name": "minPrice", "required": false, "in": "query", "description": "Filter catalogues with minimum price", "schema": { "example": "10.00", "type": "string" } }, { "name": "maxPrice", "required": false, "in": "query", "description": "Filter catalogues with maximum price", "schema": { "example": "100.00", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List gift card catalogues", "tags": [ "Gift Cards" ] } }, "/gift-cards/catalogues/{sku}/availability": { "get": { "operationId": "GiftCardsController_checkAvailability", "parameters": [ { "name": "sku", "required": true, "in": "path", "description": "Product SKU", "schema": { "example": 1234, "type": "number" } }, { "name": "price", "required": true, "in": "query", "description": "Price of the gift card to check availability for", "schema": { "example": "50.00", "type": "string" } }, { "name": "quantity", "required": false, "in": "query", "description": "Quantity of the gift cards to check availability for (default: 1)", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Check gift card availability", "tags": [ "Gift Cards" ] } }, "/gift-cards/orders": { "get": { "operationId": "GiftCardsController_getOrders", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List gift card purchase orders", "tags": [ "Gift Cards" ] } }, "/gift-cards/orders/{orderIdOrRef}": { "get": { "operationId": "GiftCardsController_getOrderById", "parameters": [ { "name": "orderIdOrRef", "required": true, "in": "path", "description": "Order ID or external reference", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a gift card purchase order by ID or external reference", "tags": [ "Gift Cards" ] } }, "/gift-cards": { "get": { "operationId": "GiftCardsController_getGiftCards", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": "1", "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": "20", "type": "number" } }, { "name": "sort", "required": false, "in": "query", "schema": { "example": "-createdAt", "type": "string" } }, { "name": "searchIn", "required": false, "in": "query", "schema": { "example": "name,emailAddress,phoneNumber", "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "triangle", "type": "string" } }, { "name": "filter", "required": false, "in": "query", "schema": { "example": "status=Active", "type": "string" } }, { "name": "fields", "required": false, "in": "query", "schema": { "example": "id,name,emailAddress,createdAt", "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "example": "crypto", "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "example": "USDC", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List issued gift cards", "tags": [ "Gift Cards" ] } }, "/gift-cards/{cardId}": { "get": { "operationId": "GiftCardsController_getGiftCardById", "parameters": [ { "name": "cardId", "required": true, "in": "path", "schema": { "example": "01J00000000000000000000000", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get an issued gift card", "tags": [ "Gift Cards" ] } }, "/gift-cards/buy": { "post": { "operationId": "GiftCardsController_buyGiftCard", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuyGiftCardDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Buy a gift card", "tags": [ "Gift Cards" ] } }, "/transactions": { "get": { "operationId": "TransactionsController_listTransactions", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } } ], "responses": { "200": { "description": "Transactions fetched successfully." } }, "security": [ { "bearer": [] } ], "summary": "List all transactions for the authenticated client", "tags": [ "Transactions" ] } } }, "info": { "title": "Triangle.Biz", "description": "\n# Triangle Business API Documentation\n\nWelcome to the Triangle Business API. This documentation guides you through integrating our financial infrastructure, focusing on our **Virtual Cards Engine**.\n\n---\n\n### 💳 Virtual Cards Integration Journey\n\nTo issue and manage virtual cards, follow this end-to-end flow:\n\n1. **Authentication**\n - Use **Bearer Token** (`Authorization: Bearer `) obtained from `POST /login` (and `POST /login/2fa` if two-factor is enabled).\n - Or use a **Client API Key** (`x-api-key: `) created via `POST /api-keys` or generated in your Developer Portal.\n\n2. **Funding Account (`accountId`)**\n - Call `GET /accounts` to retrieve your client-level fiat accounts (e.g., Primary USD Wallet).\n - The returned account `id` is passed as the `accountId` for card issuance and prepaid card loading.\n\n3. **Cardholder Registration (`customerId`)**\n - Call `POST /customers` to register the cardholder (individual or business).\n - The returned customer `id` is passed as `customerId` when issuing cards.\n - For regulated programs, submit verification documents via `POST /customers/:id/submit`.\n\n4. **Card Programs (Optional)**\n - Call `GET /card-programs` to list existing card programs or `POST /card-programs` to configure spend controls, currency, and card rules.\n\n5. **Virtual Card Operations (`/cards`)**\n - **Issue Virtual Card**: `POST /cards` with `type: \"virtual\"` (or `\"disposable\"`), `group: \"debit\"` or `\"prepaid\"`, `customerId`, and `accountId`.\n - **Get Card Details**: `GET /cards/:cardId` returns masked PAN, card status, and current balance.\n - **Reveal Sensitive Data**: `GET /cards/:cardId/reveal` returns the decrypted 16-digit PAN, CVV, and expiration date for secure display.\n - **Prepaid Card Funding**: `POST /cards/:cardId/fund` loads money from an account; `POST /cards/:cardId/withdraw` unloads money back.\n - **Card Controls**: `PATCH /cards/:cardId` to freeze (`status: \"suspended\"`), unfreeze (`status: \"active\"`), or terminate (`status: \"terminated\"`).\n - **Card Transactions**: `GET /cards/:cardId/transactions` to inspect authorizations, settlements, and declines.\n - **Issuance Status**: `GET /cards/issuances/:issuanceId` to check async prepaid issuance progress.\n\n6. **Webhooks (`/webhooks`)**\n - Register HTTPS endpoints via `POST /webhooks` to receive real-time events for card authorizations, transactions, and status updates.\n", "version": "1.0", "contact": {} }, "tags": [ { "name": "Auth", "description": "User authentication, session verification, and 2FA login" }, { "name": "Client API Keys", "description": "Manage API keys for server-to-server integration" }, { "name": "Accounts", "description": "Funding wallets and accounts used as card funding sources" }, { "name": "Customers", "description": "Cardholder profiles and KYC records required for card issuance" }, { "name": "Card Programs", "description": "Card program configurations, spend limits, and bin rules" }, { "name": "Cards", "description": "Virtual cards lifecycle: issuance, credential reveal, funding, controls, and transactions" }, { "name": "Client Webhooks", "description": "Register and manage webhook endpoints for real-time card and payment events" } ], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Enter your JWT token obtained from POST /login" }, "x-api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Server-to-server Client API Key header (x-api-key)" } }, "schemas": { "LoginUserDto": { "type": "object", "properties": { "emailAddress": { "type": "string", "example": "developer@example.com", "description": "Registered user account email address" }, "password": { "type": "string", "example": "Password123!", "description": "Account password" }, "pin": { "type": "string", "example": "1234", "description": "Optional 4-digit transaction/account PIN" }, "userAgent": { "type": "string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X)", "description": "Client user-agent string" } }, "required": [ "emailAddress", "password" ] }, "LoginTwoFactorDto": { "type": "object", "properties": { "twoFactorAuthType": { "type": "string", "enum": [ "PIN", "TOTP" ], "example": "TOTP", "description": "Type of two-factor authentication challenge" }, "otp": { "type": "string", "example": "123456", "description": "One-time verification code from SMS or email" }, "pin": { "type": "string", "example": "1234", "description": "4-digit transaction security PIN" }, "token": { "type": "string", "example": "654321", "description": "6-digit time-based OTP (TOTP) from Authenticator app" }, "twoFactorToken": { "type": "string", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "description": "Temporary twoFactorToken returned from POST /login when 2FA is required" } }, "required": [ "twoFactorToken" ] }, "StartOnboardingSessionDto": { "type": "object", "properties": {} }, "SaveOwnerOnboardingDto": { "type": "object", "properties": {} }, "SaveBusinessOnboardingDto": { "type": "object", "properties": {} }, "SwitchClientProfileDto": { "type": "object", "properties": {} }, "ChangePasswordDto": { "type": "object", "properties": {} }, "Change2FADto": { "type": "object", "properties": {} }, "Enrol2FADto": { "type": "object", "properties": {} }, "CreateClientDto": { "type": "object", "properties": {} }, "UpdateClientDto": { "type": "object", "properties": {} }, "CreateClientAPIKeyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Production Virtual Cards API Key", "description": "Descriptive name or label for the API key" }, "sourceIp": { "example": [ "192.168.1.1", "10.0.0.0/24" ], "description": "Optional list of allowed IPv4/IPv6 addresses or CIDR ranges. If omitted, key can be used from any IP.", "type": "array", "items": { "type": "string" } }, "expiryDate": { "type": "string", "example": "2028-12-31T23:59:59Z", "description": "Explicit expiration date/time in ISO 8601 format" }, "duration": { "type": "string", "example": "365d", "description": "Duration string for key validity (e.g. 30d, 90d, 1y)" } }, "required": [ "name" ] }, "UpdateClientAPIKeyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated API Key Name", "description": "New label for the API key" }, "sourceIp": { "example": [ "192.168.1.1" ], "description": "Updated IP whitelist array", "type": "array", "items": { "type": "string" } }, "expiryDate": { "type": "string", "example": "2029-12-31T23:59:59Z", "description": "Updated expiration date in ISO 8601 format" }, "duration": { "type": "string", "example": "180d", "description": "Updated validity duration" }, "status": { "type": "string", "enum": [ "Active", "Inactive" ], "example": "Active", "description": "Status of the API key" } } }, "CreateClientWebhookDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Card Events Webhook", "description": "Descriptive name for the webhook endpoint destination" }, "url": { "type": "string", "example": "https://api.yourdomain.com/webhooks/triangle", "description": "Secure HTTPS destination URL where event payloads will be sent via POST" }, "token": { "type": "string", "example": "whsec_custom_secret_key_123", "description": "Optional secret token used to sign webhook payloads with HMAC SHA-256 for integrity verification" }, "contentType": { "type": "string", "example": "application/json", "default": "application/json", "description": "Payload content type format" }, "events": { "example": [ "card.created", "card.authorized", "card.settled", "card.declined", "card.funded", "card.status_updated" ], "description": "List of specific event topics to subscribe to. If omitted or empty, all events are sent.", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "Active", "Inactive" ], "example": "Active", "default": "Active", "description": "Operational status of the webhook endpoint" } }, "required": [ "name", "url" ] }, "NotifyClientWebhookDto": { "type": "object", "properties": { "event": { "type": "string", "example": "card.authorized", "description": "Event type identifier to trigger" }, "data": { "type": "object", "example": { "cardId": "01J00000000000000000000000", "amount": 1500, "currency": "USD", "merchant": "Amazon.com" }, "description": "Payload data sent inside the event envelope" } }, "required": [ "event" ] }, "UpdateClientWebhookDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Updated Webhook Name", "description": "Updated descriptive label for the webhook" }, "url": { "type": "string", "example": "https://api.yourdomain.com/webhooks/v2", "description": "Updated destination HTTPS URL" }, "token": { "type": "string", "example": "whsec_new_secret_key_456", "description": "Updated webhook signature verification secret token" }, "contentType": { "type": "string", "example": "application/json", "description": "Payload content type" }, "events": { "example": [ "card.authorized", "card.settled", "card.declined" ], "description": "Updated list of subscribed event topics", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "Active", "Inactive" ], "example": "Active", "description": "Status of the webhook endpoint" } } }, "AutoSweepDetailsDto": { "type": "object", "properties": { "account": { "type": "string", "example": "01J00000000000000000000003", "description": "Client-level main account ID that receives internal sweeps." }, "schedule": { "type": "string", "enum": [ "Instant", "Daily" ], "example": "Instant", "description": "Instant sweeps after deposit confirmation. Daily sweeps run at 11pm Africa/Lagos." } }, "required": [ "account", "schedule" ] }, "AccountAutoSweepDto": { "type": "object", "properties": { "autoSweepEnabled": { "type": "boolean", "example": true }, "autoSweepDetails": { "description": "Required when autoSweepEnabled is true.", "allOf": [ { "$ref": "#/components/schemas/AutoSweepDetailsDto" } ] }, "autosweepDetails": { "deprecated": true, "description": "Legacy alias for autoSweepDetails. Responses use autoSweepDetails.", "allOf": [ { "$ref": "#/components/schemas/AutoSweepDetailsDto" } ] } }, "required": [ "autoSweepEnabled" ] }, "CreateAccountDto": { "type": "object", "properties": { "clientId": { "type": "string", "example": "01J00000000000000000000001" }, "name": { "type": "string", "example": "Main USD Operating Account" }, "type": { "type": "string", "enum": [ "savings", "checking", "wallet" ], "example": "checking" }, "category": { "type": "string", "enum": [ "fiat", "crypto" ], "example": "fiat" }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "closed" ], "example": "active" }, "currency": { "type": "string", "example": "USD" }, "network": { "type": "string", "example": "ethereum" } }, "required": [ "name", "type", "category", "currency" ] }, "CreateWalletAccountDto": { "type": "object", "properties": { "clientId": { "type": "string", "example": "01J00000000000000000000001" }, "customerId": { "type": "string", "example": "01J00000000000000000000002" }, "name": { "type": "string", "example": "Customer USD Wallet" }, "type": { "type": "string", "enum": [ "savings", "checking" ], "example": "checking" }, "category": { "type": "string", "enum": [ "fiat" ], "example": "fiat", "default": "fiat" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending" ], "example": "active" }, "currency": { "type": "string", "example": "USD" }, "accountAutoSweep": { "description": "Optional internal auto sweep configuration. Target account is a same-currency client-level account ID; no Nuvion BAN is required.", "allOf": [ { "$ref": "#/components/schemas/AccountAutoSweepDto" } ] } }, "required": [ "customerId", "name", "type", "currency" ] }, "CreateAccountDetailDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "active", "inactive", "suspended" ], "example": "pending" }, "type": { "type": "string", "enum": [ "bank_account", "crypto_wallet" ], "example": "bank_account" }, "details": { "type": "object", "example": { "bankName": "CROSS RIVER BANK" } }, "chain": { "type": "string", "example": "ethereum" }, "supportedAssets": { "example": [ "USDC", "USDT" ], "type": "array", "items": { "type": "string" } }, "provider": { "type": "string", "example": "nuvion" }, "providerId": { "type": "string", "example": "provider-detail-id" }, "isPrimary": { "type": "boolean", "example": true } }, "required": [ "type" ] }, "CustomerIndividualProfileDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000001" }, "firstName": { "type": "string", "example": "Ada" }, "lastName": { "type": "string", "example": "Lovelace" }, "middleName": { "type": "string", "example": "Byron" }, "dateOfBirth": { "type": "string", "example": "1990-01-10" }, "nationality": { "type": "string", "example": "NG" }, "gender": { "type": "string", "enum": [ "m", "f" ], "example": "f" }, "taxId": { "type": "string", "example": "1234567890" }, "livenessReportUrl": { "type": "string", "example": "https://files.example.com/liveness.pdf" }, "meta": { "type": "object" } }, "required": [ "firstName", "lastName", "dateOfBirth", "nationality", "gender" ] }, "CustomerBusinessProfileDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000002" }, "legalName": { "type": "string", "example": "Triangle Retail Limited" }, "tradeName": { "type": "string", "example": "Triangle Retail" }, "industry": { "type": "string", "example": "fintech" }, "businessType": { "type": "string", "example": "private_company" }, "description": { "type": "string", "example": "Retail payments and merchant operations." }, "registrationNumber": { "type": "string", "example": "RC1234567" }, "email": { "type": "string", "example": "ops@triangle.example" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "website": { "type": "string", "example": "https://triangle.example" }, "incorporationYear": { "type": "string", "example": "2022" }, "incorporationMonth": { "type": "string", "example": "08" }, "incorporationCountry": { "type": "string", "example": "NG" }, "incorporationState": { "type": "string", "example": "Lagos" }, "taxId": { "type": "string", "example": "1234567890" }, "meta": { "type": "object" } }, "required": [ "legalName", "industry", "businessType", "description", "registrationNumber", "email", "incorporationYear", "incorporationMonth", "incorporationCountry", "incorporationState" ] }, "CustomerAddressDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000003" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "type": { "type": "string", "enum": [ "residential", "registered", "operating", "business", "mailing" ] }, "line1": { "type": "string", "example": "12 Admiralty Way" }, "line2": { "type": "string", "example": "Suite 4" }, "line3": { "type": "string", "example": "Lekki Phase 1" }, "city": { "type": "string", "example": "Lagos" }, "state": { "type": "string", "example": "Lagos" }, "postalCode": { "type": "string", "example": "105102" }, "countryCode": { "type": "string", "example": "NG" }, "meta": { "type": "object" } }, "required": [ "type", "line1", "city", "state", "postalCode", "countryCode" ] }, "CustomerPersonDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000004" }, "firstName": { "type": "string", "example": "Grace" }, "lastName": { "type": "string", "example": "Hopper" }, "middleName": { "type": "string", "example": "Brewster" }, "email": { "type": "string", "example": "grace@example.com" }, "dateOfBirth": { "type": "string", "example": "1985-04-20" }, "nationality": { "type": "string", "example": "NG" }, "gender": { "type": "string", "enum": [ "m", "f" ], "example": "f" }, "jobTitle": { "type": "string", "example": "Director" }, "isControlPerson": { "type": "boolean", "example": true }, "isBeneficialOwner": { "type": "boolean", "example": true }, "ownershipPercentage": { "type": "string", "example": "35" } }, "required": [ "firstName", "lastName", "email", "dateOfBirth", "nationality", "gender" ] }, "CustomerIdentificationDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000005" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "documentType": { "type": "string", "enum": [ "international_passport", "drivers_license", "national_id" ] }, "documentNumber": { "type": "string", "example": "A12345678" }, "issueDate": { "type": "string", "example": "2020-01-01" }, "expiryDate": { "type": "string", "example": "2030-01-01" }, "issuingCountry": { "type": "string", "example": "NG" }, "issuingAuthority": { "type": "string", "example": "NIMC" }, "idSubtype": { "type": "string", "example": "nin" } }, "required": [ "documentType", "documentNumber" ] }, "CustomerDocumentDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000006" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "key": { "type": "string", "enum": [ "identity", "proof_of_address", "address", "tax_verification", "certificate_of_incorporation", "memorandum_of_association" ] }, "description": { "type": "string", "example": "International passport front and back" }, "fileType": { "type": "string", "example": "image/png" }, "frontUrl": { "type": "string", "example": "https://files.example.com/front.png" }, "backUrl": { "type": "string", "example": "https://files.example.com/back.png" } }, "required": [ "key" ] }, "CreateCustomerDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "displayName": { "type": "string", "example": "Ada Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "parentEntity": { "type": "string", "example": "01J00000000000000000000001" }, "parentRelationship": { "type": "string", "example": "subsidiary" }, "individualProfile": { "$ref": "#/components/schemas/CustomerIndividualProfileDto" }, "businessProfile": { "$ref": "#/components/schemas/CustomerBusinessProfileDto" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAddressDto" } }, "persons": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPersonDto" } }, "identifications": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentificationDto" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDocumentDto" } } }, "required": [ "type" ] }, "UpdateCustomerIndividualProfileDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000001" }, "firstName": { "type": "string", "example": "Ada" }, "lastName": { "type": "string", "example": "Lovelace" }, "middleName": { "type": "string", "example": "Byron" }, "dateOfBirth": { "type": "string", "example": "1990-01-10" }, "nationality": { "type": "string", "example": "NG" }, "gender": { "type": "string", "enum": [ "m", "f" ], "example": "f" }, "taxId": { "type": "string", "example": "1234567890" }, "livenessReportUrl": { "type": "string", "example": "https://files.example.com/liveness.pdf" }, "meta": { "type": "object" } } }, "UpdateCustomerBusinessProfileDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000002" }, "legalName": { "type": "string", "example": "Triangle Retail Limited" }, "tradeName": { "type": "string", "example": "Triangle Retail" }, "industry": { "type": "string", "example": "fintech" }, "businessType": { "type": "string", "example": "private_company" }, "description": { "type": "string", "example": "Retail payments and merchant operations." }, "registrationNumber": { "type": "string", "example": "RC1234567" }, "email": { "type": "string", "example": "ops@triangle.example" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "website": { "type": "string", "example": "https://triangle.example" }, "incorporationYear": { "type": "string", "example": "2022" }, "incorporationMonth": { "type": "string", "example": "08" }, "incorporationCountry": { "type": "string", "example": "NG" }, "incorporationState": { "type": "string", "example": "Lagos" }, "taxId": { "type": "string", "example": "1234567890" }, "meta": { "type": "object" } } }, "UpdateCustomerAddressDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000003" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "type": { "type": "string", "enum": [ "residential", "registered", "operating", "business", "mailing" ] }, "line1": { "type": "string", "example": "12 Admiralty Way" }, "line2": { "type": "string", "example": "Suite 4" }, "line3": { "type": "string", "example": "Lekki Phase 1" }, "city": { "type": "string", "example": "Lagos" }, "state": { "type": "string", "example": "Lagos" }, "postalCode": { "type": "string", "example": "105102" }, "countryCode": { "type": "string", "example": "NG" }, "meta": { "type": "object" } } }, "UpdateCustomerPersonDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000004" }, "firstName": { "type": "string", "example": "Grace" }, "lastName": { "type": "string", "example": "Hopper" }, "middleName": { "type": "string", "example": "Brewster" }, "email": { "type": "string", "example": "grace@example.com" }, "dateOfBirth": { "type": "string", "example": "1985-04-20" }, "nationality": { "type": "string", "example": "NG" }, "gender": { "type": "string", "enum": [ "m", "f" ], "example": "f" }, "jobTitle": { "type": "string", "example": "Director" }, "isControlPerson": { "type": "boolean", "example": true }, "isBeneficialOwner": { "type": "boolean", "example": true }, "ownershipPercentage": { "type": "string", "example": "35" } } }, "UpdateCustomerIdentificationDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000005" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "documentType": { "type": "string", "enum": [ "international_passport", "drivers_license", "national_id" ] }, "documentNumber": { "type": "string", "example": "A12345678" }, "issueDate": { "type": "string", "example": "2020-01-01" }, "expiryDate": { "type": "string", "example": "2030-01-01" }, "issuingCountry": { "type": "string", "example": "NG" }, "issuingAuthority": { "type": "string", "example": "NIMC" }, "idSubtype": { "type": "string", "example": "nin" } } }, "UpdateCustomerDocumentDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000006" }, "personId": { "type": "string", "example": "01J00000000000000000000004" }, "key": { "type": "string", "enum": [ "identity", "proof_of_address", "address", "tax_verification", "certificate_of_incorporation", "memorandum_of_association" ] }, "description": { "type": "string", "example": "International passport front and back" }, "fileType": { "type": "string", "example": "image/png" }, "frontUrl": { "type": "string", "example": "https://files.example.com/front.png" }, "backUrl": { "type": "string", "example": "https://files.example.com/back.png" } } }, "UpdateCustomerDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "displayName": { "type": "string", "example": "Ada Lovelace" }, "email": { "type": "string", "example": "ada@example.com" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "parentEntity": { "type": "string", "example": "01J00000000000000000000001" }, "parentRelationship": { "type": "string", "example": "subsidiary" }, "individualProfile": { "$ref": "#/components/schemas/UpdateCustomerIndividualProfileDto" }, "businessProfile": { "$ref": "#/components/schemas/UpdateCustomerBusinessProfileDto" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateCustomerAddressDto" } }, "persons": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateCustomerPersonDto" } }, "identifications": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateCustomerIdentificationDto" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateCustomerDocumentDto" } } } }, "UpsertCustomerDocumentsDto": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDocumentDto" } } }, "required": [ "documents" ] }, "UpsertCustomerIdentificationsDto": { "type": "object", "properties": { "identifications": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerIdentificationDto" } } }, "required": [ "identifications" ] }, "OcrDocumentDto": { "type": "object", "properties": { "url": { "type": "string", "example": "https://bucket.s3.amazonaws.com/passport.jpg" }, "documentType": { "type": "string", "enum": [ "passport", "drivers_license", "national_id", "proof_of_address" ] }, "personId": { "type": "string", "example": "01J00000000000000000000001" } }, "required": [ "url", "documentType" ] }, "CreateWalletAddressDto": { "type": "object", "properties": {} }, "RecipientAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "example": "350 Fifth Avenue" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "New York" }, "postalCode": { "type": "string", "example": "10118" }, "country": { "type": "string", "example": "US" } } }, "BankAddressDto": { "type": "object", "properties": { "line1": { "type": "string", "example": "1801 Main St" }, "line2": { "type": "string", "example": "Suite 100" }, "city": { "type": "string", "example": "Kansas City" }, "state": { "type": "string", "example": "MO" }, "postalCode": { "type": "string", "example": "64108" }, "country": { "type": "string", "example": "US" } } }, "RecipientPaymentDetailsDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bank_account", "crypto_wallet", "mobile_money" ] }, "paymentMethod": { "type": "string", "enum": [ "bank-transfer", "momo-transfer", "book-transfer", "stablecoin-transfer" ] }, "scheme": { "type": "string", "example": "ach" }, "currency": { "type": "string", "example": "USD" }, "accountName": { "type": "string", "example": "Ada Lovelace" }, "country": { "type": "string", "example": "US" }, "accountNumber": { "type": "string", "example": "0123456789" }, "bankName": { "type": "string", "example": "Chase Bank" }, "sortCode": { "type": "string", "example": "123456" }, "iban": { "type": "string", "example": "GB82WEST12345698765432" }, "routingNumber": { "type": "string", "example": "021000021" }, "swiftBic": { "type": "string", "example": "CHASUS33" }, "swiftCode": { "type": "string", "example": "CHASUS33" }, "bankCode": { "type": "string", "example": "058" }, "branchCode": { "type": "string", "example": "001" }, "bankInstitutionNumber": { "type": "string", "example": "001" }, "transitNumber": { "type": "string", "example": "00011" }, "accountType": { "type": "string", "example": "checking" }, "blockchainNetwork": { "type": "string", "example": "BASE_MAINNET" }, "walletAddress": { "type": "string", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "mobileMoneyProvider": { "type": "string", "example": "mtn" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "bankAddress": { "$ref": "#/components/schemas/BankAddressDto" } }, "required": [ "type", "paymentMethod", "currency", "accountName" ] }, "RecipientDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000001" }, "type": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "name": { "type": "string", "example": "Ada Lovelace" }, "emailAddress": { "type": "string", "example": "ada@example.com" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "provider": { "type": "string", "example": "nuvion" }, "providerRecipientId": { "type": "string", "example": "recipient_123" }, "nuvionRecipientId": { "type": "string", "example": "recipient_123" }, "providerPaymentDetailId": { "type": "string", "example": "pd_123" }, "counterpartyType": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "nickname": { "type": "string", "example": "Ada USD ACH" }, "firstName": { "type": "string", "example": "Ada" }, "lastName": { "type": "string", "example": "Lovelace" }, "legalName": { "type": "string", "example": "Acme Technologies Limited" }, "tradingName": { "type": "string", "example": "Acme Tech" }, "relationship": { "type": "string", "example": "vendor" }, "address": { "$ref": "#/components/schemas/RecipientAddressDto" }, "paymentDetails": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientPaymentDetailsDto" } }, "metadata": { "type": "object" } }, "required": [ "name" ] }, "CreateTransferDto": { "type": "object", "properties": { "sourceAccountId": { "type": "string", "example": "01J00000000000000000000002", "description": "Account to debit. Its currency is used as the transfer source currency." }, "sourceAccountDetailId": { "type": "string", "example": "01J00000000000000000000003" }, "recipientId": { "type": "string", "example": "01J00000000000000000000001" }, "recipientPaymentDetailId": { "type": "string", "example": "01J00000000000000000000009" }, "destinationAccountId": { "type": "string", "example": "01J00000000000000000000004", "description": "Destination account ID for direct internal transfers within Triangle." }, "recipient": { "$ref": "#/components/schemas/RecipientDto" }, "recipientEmailAddress": { "type": "string", "example": "ada@example.com", "deprecated": true }, "paymentMethod": { "type": "string", "enum": [ "bank-transfer", "momo-transfer", "book-transfer", "stablecoin-transfer" ], "description": "Payout method for the recipient route." }, "scheme": { "type": "string", "example": "nip", "description": "Required for payment methods that have multiple supported schemes, such as bank transfer." }, "amount": { "type": "number", "example": 1000, "description": "Source amount to debit from the source account." }, "currency": { "type": "string", "example": "NGN", "description": "Legacy source currency field. The API validates against the source account currency." }, "narration": { "type": "string", "example": "Invoice payout" }, "reference": { "type": "string", "example": "client-reference-001" }, "idempotencyKey": { "type": "string", "example": "idem-001" }, "fxQuoteId": { "type": "string", "example": "01J00000000000000000000010", "description": "Required only when the source account currency differs from the recipient payout currency." }, "metadata": { "type": "object" } }, "required": [ "sourceAccountId", "paymentMethod", "amount", "currency" ] }, "PreviewTransferDto": { "type": "object", "properties": { "sourceAccountId": { "type": "string", "example": "01J00000000000000000000002", "description": "Account to debit. Its currency is used as the transfer source currency." }, "sourceAccountDetailId": { "type": "string", "example": "01J00000000000000000000003" }, "recipientId": { "type": "string", "example": "01J00000000000000000000001" }, "recipientPaymentDetailId": { "type": "string", "example": "01J00000000000000000000009" }, "destinationAccountId": { "type": "string", "example": "01J00000000000000000000004", "description": "Destination account ID for direct internal transfers within Triangle." }, "recipient": { "$ref": "#/components/schemas/RecipientDto" }, "recipientEmailAddress": { "type": "string", "example": "ada@example.com", "deprecated": true }, "paymentMethod": { "type": "string", "enum": [ "bank-transfer", "momo-transfer", "book-transfer", "stablecoin-transfer" ], "description": "Payout method for the recipient route." }, "scheme": { "type": "string", "example": "nip", "description": "Required for payment methods that have multiple supported schemes, such as bank transfer." }, "amount": { "type": "number", "example": 1000, "description": "Source amount to debit from the source account." }, "currency": { "type": "string", "example": "NGN", "description": "Legacy source currency field. The API validates against the source account currency." }, "narration": { "type": "string", "example": "Invoice payout" }, "reference": { "type": "string", "example": "client-reference-001" }, "idempotencyKey": { "type": "string", "example": "idem-001" }, "fxQuoteId": { "type": "string", "example": "01J00000000000000000000010", "description": "Required only when the source account currency differs from the recipient payout currency." }, "metadata": { "type": "object" } }, "required": [ "sourceAccountId", "paymentMethod", "amount", "currency" ] }, "UpdateTransferDto": { "type": "object", "properties": { "narration": { "type": "string", "example": "Updated narration" }, "metadata": { "type": "object" } } }, "CreateRecipientDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000001" }, "type": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "name": { "type": "string", "example": "Ada Lovelace" }, "emailAddress": { "type": "string", "example": "ada@example.com" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "provider": { "type": "string", "example": "nuvion" }, "providerRecipientId": { "type": "string", "example": "recipient_123" }, "nuvionRecipientId": { "type": "string", "example": "recipient_123" }, "providerPaymentDetailId": { "type": "string", "example": "pd_123" }, "counterpartyType": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "nickname": { "type": "string", "example": "Ada USD ACH" }, "firstName": { "type": "string", "example": "Ada" }, "lastName": { "type": "string", "example": "Lovelace" }, "legalName": { "type": "string", "example": "Acme Technologies Limited" }, "tradingName": { "type": "string", "example": "Acme Tech" }, "relationship": { "type": "string", "example": "vendor" }, "address": { "$ref": "#/components/schemas/RecipientAddressDto" }, "paymentDetails": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientPaymentDetailsDto" } }, "metadata": { "type": "object" }, "recipientEmailAddress": { "type": "string", "example": "ada@example.com", "deprecated": true }, "recipientName": { "type": "string", "example": "Ada Lovelace", "deprecated": true } }, "required": [ "name" ] }, "VerifyRecipientIssuerDto": { "type": "object", "properties": { "code": { "type": "string", "example": "100033" }, "scheme": { "type": "string", "example": "aba" } }, "required": [ "code", "scheme" ] }, "VerifyRecipientDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "country": { "type": "string", "example": "USA" }, "accountNumber": { "type": "string", "example": "7033870337" }, "issuer": { "$ref": "#/components/schemas/VerifyRecipientIssuerDto" } }, "required": [ "currency", "country", "accountNumber", "issuer" ] }, "CreateRecipientPaymentDetailDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bank_account", "crypto_wallet", "mobile_money" ] }, "paymentMethod": { "type": "string", "enum": [ "bank-transfer", "momo-transfer", "book-transfer", "stablecoin-transfer" ] }, "scheme": { "type": "string", "example": "ach" }, "currency": { "type": "string", "example": "USD" }, "accountName": { "type": "string", "example": "Ada Lovelace" }, "country": { "type": "string", "example": "US" }, "accountNumber": { "type": "string", "example": "0123456789" }, "bankName": { "type": "string", "example": "Chase Bank" }, "sortCode": { "type": "string", "example": "123456" }, "iban": { "type": "string", "example": "GB82WEST12345698765432" }, "routingNumber": { "type": "string", "example": "021000021" }, "swiftBic": { "type": "string", "example": "CHASUS33" }, "swiftCode": { "type": "string", "example": "CHASUS33" }, "bankCode": { "type": "string", "example": "058" }, "branchCode": { "type": "string", "example": "001" }, "bankInstitutionNumber": { "type": "string", "example": "001" }, "transitNumber": { "type": "string", "example": "00011" }, "accountType": { "type": "string", "example": "checking" }, "blockchainNetwork": { "type": "string", "example": "BASE_MAINNET" }, "walletAddress": { "type": "string", "example": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" }, "mobileMoneyProvider": { "type": "string", "example": "mtn" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "bankAddress": { "$ref": "#/components/schemas/BankAddressDto" } }, "required": [ "type", "paymentMethod", "currency", "accountName" ] }, "UpdateRecipientDto": { "type": "object", "properties": { "id": { "type": "string", "example": "01J00000000000000000000001" }, "type": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "name": { "type": "string", "example": "Ada Lovelace" }, "emailAddress": { "type": "string", "example": "ada@example.com" }, "phoneNumber": { "type": "string", "example": "+2348012345678" }, "provider": { "type": "string", "example": "nuvion" }, "providerRecipientId": { "type": "string", "example": "recipient_123" }, "nuvionRecipientId": { "type": "string", "example": "recipient_123" }, "providerPaymentDetailId": { "type": "string", "example": "pd_123" }, "counterpartyType": { "type": "string", "enum": [ "individual", "business" ], "example": "individual" }, "nickname": { "type": "string", "example": "Ada USD ACH" }, "firstName": { "type": "string", "example": "Ada" }, "lastName": { "type": "string", "example": "Lovelace" }, "legalName": { "type": "string", "example": "Acme Technologies Limited" }, "tradingName": { "type": "string", "example": "Acme Tech" }, "relationship": { "type": "string", "example": "vendor" }, "address": { "$ref": "#/components/schemas/RecipientAddressDto" }, "paymentDetails": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientPaymentDetailsDto" } }, "metadata": { "type": "object" } } }, "CreateFxQuoteDto": { "type": "object", "properties": { "sourceAccountId": { "type": "string", "example": "01J00000000000000000000002" }, "fromCurrency": { "type": "string", "example": "USD" }, "toCurrency": { "type": "string", "example": "NGN" }, "amountFrom": { "type": "number", "example": 300 }, "amountTo": { "type": "number", "example": 402222 }, "recipientPaymentDetailId": { "type": "string", "example": "01J00000000000000000000009" }, "metadata": { "type": "object" } }, "required": [ "sourceAccountId", "fromCurrency", "toCurrency" ] }, "CreateCardProgramDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Default Virtual Cards" }, "description": { "type": "string", "example": "Shared controls for virtual USD cards." }, "type": { "type": "string", "enum": [ "physical", "virtual", "disposable" ], "example": "virtual" }, "group": { "type": "string", "enum": [ "prepaid", "debit" ], "example": "prepaid" }, "provider": { "type": "string", "enum": [ "sudo", "nuvion" ], "example": "sudo" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "example": "active" }, "currency": { "type": "string", "example": "USD" }, "requiresDebitAccount": { "type": "boolean", "example": false }, "config": { "type": "object", "example": { "spendingLimits": { "perTransaction": 500, "daily": 2000, "monthly": 10000 }, "fees": {} } }, "controls": { "type": "object", "example": { "blockedMerchantCategories": [ "gambling" ], "allowedCountries": [ "NG", "US" ] } }, "metadata": { "type": "object" } }, "required": [ "name", "type", "group", "currency" ] }, "UpdateCardProgramDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Default Virtual Cards" }, "description": { "type": "string", "example": "Shared controls for virtual USD cards." }, "type": { "type": "string", "enum": [ "physical", "virtual", "disposable" ], "example": "virtual" }, "group": { "type": "string", "enum": [ "prepaid", "debit" ], "example": "prepaid" }, "provider": { "type": "string", "enum": [ "sudo", "nuvion" ], "example": "sudo" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "example": "active" }, "currency": { "type": "string", "example": "USD" }, "requiresDebitAccount": { "type": "boolean", "example": false }, "config": { "type": "object", "example": { "spendingLimits": { "perTransaction": 500, "daily": 2000, "monthly": 10000 }, "fees": {} } }, "controls": { "type": "object", "example": { "blockedMerchantCategories": [ "gambling" ], "allowedCountries": [ "NG", "US" ] } }, "metadata": { "type": "object" } } }, "CreateCardDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Marketing Expense Card", "description": "Friendly name or cardholder label for the card." }, "type": { "type": "string", "enum": [ "virtual", "disposable", "physical" ], "example": "virtual", "description": "Card form factor. Use \"virtual\" for multi-use virtual cards, or \"disposable\" for single-use / short-lived cards." }, "customerId": { "type": "string", "example": "01J00000000000000000000001", "description": "Cardholder customer ID created via POST /customers." }, "group": { "type": "string", "enum": [ "prepaid", "debit" ], "example": "debit", "default": "prepaid", "description": "Card ledger group. \"debit\" draws directly from the linked funding account balance in real-time. \"prepaid\" has its own ledger balance and must be loaded via amount or POST /cards/:id/fund." }, "currency": { "type": "string", "example": "USD", "default": "USD", "description": "Card denomination currency code (ISO-4217). Currently USD." }, "programId": { "type": "string", "example": "01J00000000000000000000000", "description": "Optional card program ID (from GET /card-programs) to inherit BIN controls, spending rules, and fees." }, "accountId": { "type": "string", "example": "01J00000000000000000000001", "description": "Funding account ID (from GET /accounts) used to fund the card. For debit cards, funds are drawn from this account on transactions. For prepaid cards, the initial funding amount is debited from this account." }, "amount": { "type": "number", "example": 50, "description": "Required for prepaid cards (whole positive USD amount). Initial balance loaded onto the prepaid card from the funding account at creation. Must NOT be supplied for debit cards." }, "dailySpendingLimit": { "type": "number", "example": 500, "description": "Optional recurring daily spending limit in card currency (e.g. 500 USD)." }, "totalSpendingLimit": { "type": "number", "example": 5000, "description": "Optional total lifetime spending limit in card currency (e.g. 5000 USD)." }, "expiryMonth": { "type": "string", "example": "12", "description": "Expiration month (MM, 01-12). Required only for disposable cards; automatically computed for virtual cards if omitted." }, "expiryYear": { "type": "number", "example": 2028, "description": "Expiration year (YYYY). Required only for disposable cards; automatically computed for virtual cards if omitted." }, "individualControls": { "type": "object", "example": { "channels": { "atm": false, "pos": true, "web": true }, "dailySpendingLimit": 500, "totalSpendingLimit": 5000 }, "description": "Granular spending and channel controls." }, "individualMccControls": { "example": [ { "mcc": "5732", "action": "allow" } ], "description": "Specific Merchant Category Code (MCC) allow/block rules.", "type": "array", "items": { "type": "object" } }, "mccGroupControls": { "example": [ { "group": "gambling", "action": "block" } ], "description": "MCC group allow/block rules.", "type": "array", "items": { "type": "object" } }, "billingAddress": { "type": "object", "example": { "line1": "123 Market Street", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" }, "description": "AVS billing address verified during online checkout." }, "metadata": { "type": "object", "example": { "internalRef": "REF-7892", "department": "Marketing" }, "description": "Arbitrary custom key-value metadata to attach to the card." } }, "required": [ "name", "type", "customerId", "accountId" ] }, "FundCardDto": { "type": "object", "properties": { "debitAccountId": { "type": "string", "example": "01KPE6ZW6Y420N1KM53P2HH2F5", "description": "ID of the client funding account to debit money from." }, "amount": { "type": "number", "example": 100, "description": "Amount in USD to load onto the prepaid card (must be > 1)." } }, "required": [ "debitAccountId", "amount" ] }, "WithdrawCardDto": { "type": "object", "properties": { "creditAccountId": { "type": "string", "example": "01KPE6ZW6Y420N1KM53P2HH2F5", "description": "ID of the client account to credit with the unloaded card funds." }, "amount": { "type": "number", "example": 50, "description": "Amount in USD to withdraw from the prepaid card back into the client account." } }, "required": [ "creditAccountId", "amount" ] }, "UpdateCardDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Marketing Expense Card", "description": "Friendly name or cardholder label for the card." }, "type": { "type": "string", "enum": [ "virtual", "disposable", "physical" ], "example": "virtual", "description": "Card form factor. Use \"virtual\" for multi-use virtual cards, or \"disposable\" for single-use / short-lived cards." }, "customerId": { "type": "string", "example": "01J00000000000000000000001", "description": "Cardholder customer ID created via POST /customers." }, "group": { "type": "string", "enum": [ "prepaid", "debit" ], "example": "debit", "default": "prepaid", "description": "Card ledger group. \"debit\" draws directly from the linked funding account balance in real-time. \"prepaid\" has its own ledger balance and must be loaded via amount or POST /cards/:id/fund." }, "currency": { "type": "string", "example": "USD", "default": "USD", "description": "Card denomination currency code (ISO-4217). Currently USD." }, "programId": { "type": "string", "example": "01J00000000000000000000000", "description": "Optional card program ID (from GET /card-programs) to inherit BIN controls, spending rules, and fees." }, "accountId": { "type": "string", "example": "01J00000000000000000000001", "description": "Funding account ID (from GET /accounts) used to fund the card. For debit cards, funds are drawn from this account on transactions. For prepaid cards, the initial funding amount is debited from this account." }, "amount": { "type": "number", "example": 50, "description": "Required for prepaid cards (whole positive USD amount). Initial balance loaded onto the prepaid card from the funding account at creation. Must NOT be supplied for debit cards." }, "dailySpendingLimit": { "type": "number", "example": 500, "description": "Optional recurring daily spending limit in card currency (e.g. 500 USD)." }, "totalSpendingLimit": { "type": "number", "example": 5000, "description": "Optional total lifetime spending limit in card currency (e.g. 5000 USD)." }, "expiryMonth": { "type": "string", "example": "12", "description": "Expiration month (MM, 01-12). Required only for disposable cards; automatically computed for virtual cards if omitted." }, "expiryYear": { "type": "number", "example": 2028, "description": "Expiration year (YYYY). Required only for disposable cards; automatically computed for virtual cards if omitted." }, "individualControls": { "type": "object", "example": { "channels": { "atm": false, "pos": true, "web": true }, "dailySpendingLimit": 500, "totalSpendingLimit": 5000 }, "description": "Granular spending and channel controls." }, "individualMccControls": { "example": [ { "mcc": "5732", "action": "allow" } ], "description": "Specific Merchant Category Code (MCC) allow/block rules.", "type": "array", "items": { "type": "object" } }, "mccGroupControls": { "example": [ { "group": "gambling", "action": "block" } ], "description": "MCC group allow/block rules.", "type": "array", "items": { "type": "object" } }, "billingAddress": { "type": "object", "example": { "line1": "123 Market Street", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US" }, "description": "AVS billing address verified during online checkout." }, "metadata": { "type": "object", "example": { "internalRef": "REF-7892", "department": "Marketing" }, "description": "Arbitrary custom key-value metadata to attach to the card." }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "terminated", "expired" ], "example": "suspended", "description": "Update the operational status of the card. Use \"suspended\" to temporarily freeze, \"active\" to unfreeze, or \"terminated\" to permanently cancel." } } }, "ValidateCryptoAddressDto": { "type": "object", "properties": { "address": { "type": "string", "description": "The recipient crypto wallet address to validate", "example": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "network": { "type": "string", "description": "The network key or chain alias (e.g. ETH, SOL, BTC, TRON, POLYGON, ARBITRUM, BASE, BSC, XRP, XLM)", "example": "ETH" }, "assetId": { "type": "string", "description": "The asset symbol or ID (e.g. USDT, USDC, BTC, ETH, SOL)", "example": "USDT" }, "tag": { "type": "string", "description": "Destination tag or memo if required by the target network (e.g. XRP tag or Stellar memo)", "example": "123456" }, "customerId": { "type": "string", "description": "Optional customer ID to check if this address belongs to an internal customer deposit wallet", "example": "01J00000000000000000000000" } }, "required": [ "address" ] }, "ValidateCryptoAddressResultDto": { "type": "object", "properties": { "isValid": { "type": "boolean", "description": "Indicates whether the address (and tag if required) is valid for the network/asset", "example": true }, "address": { "type": "string", "description": "The address that was evaluated", "example": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "normalizedAddress": { "type": "object", "description": "Normalized/Checksummed version of the address (e.g. EIP-55 for EVM)", "example": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "network": { "type": "object", "description": "The identified or matched network key", "example": "ETH" }, "assetId": { "type": "object", "description": "The resolved asset ID or symbol", "example": "USDT" }, "addressType": { "type": "string", "description": "Address structure type (account_based, utxo, tag_memo, unknown)", "example": "account_based" }, "isEvm": { "type": "boolean", "description": "Whether the network is EVM-compatible", "example": true }, "requiresTagOrMemo": { "type": "boolean", "description": "Whether the network/asset requires a destination tag or memo for deposits/transfers", "example": false }, "isTagOrMemoValid": { "type": "boolean", "description": "Whether the provided tag or memo is valid (true if no tag required or valid tag provided)", "example": true }, "isInternalAddress": { "type": "boolean", "description": "Whether this address belongs to an internal customer vault address within Triangle", "example": false }, "reason": { "type": "object", "description": "Explanation or error reason if the address is invalid", "example": null } }, "required": [ "isValid", "address", "addressType", "isEvm", "requiresTagOrMemo", "isTagOrMemoValid", "isInternalAddress" ] }, "CreateCryptoWithdrawalDto": { "type": "object", "properties": { "accountId": { "type": "string", "example": "01J00000000000000000000000" }, "currency": { "type": "string", "example": "USDT" }, "network": { "type": "string", "example": "BSC" }, "amount": { "type": "string", "example": "1057010000", "description": "Withdrawal amount in 8-decimal crypto units." }, "destinationAddress": { "type": "string", "example": "0x0000000000000000000000000000000000000000" }, "tag": { "type": "string", "example": "12345678" }, "memo": { "type": "string", "example": "Client withdrawal" }, "reference": { "type": "string", "example": "wd_20260508_0001" } }, "required": [ "accountId", "currency", "network", "amount", "destinationAddress" ] }, "CreateCryptoSwapQuoteDto": { "type": "object", "properties": { "fromAsset": { "type": "string", "example": "USDT" }, "toAsset": { "type": "string", "example": "BNB" }, "sourceAmount": { "type": "string", "example": "1057010000", "description": "Source amount in 8-decimal crypto units." } }, "required": [ "fromAsset", "toAsset", "sourceAmount" ] }, "CreateCryptoSwapDto": { "type": "object", "properties": { "quoteId": { "type": "string", "example": "01J00000000000000000000003" }, "reference": { "type": "string", "example": "swap_20260603_0001" }, "idempotencyKey": { "type": "string", "example": "idem_20260603_0001" } }, "required": [ "quoteId" ] }, "CreateStakingPositionDto": { "type": "object", "properties": { "accountId": { "type": "string", "example": "01J00000000000000000000001" }, "productId": { "type": "string", "example": "01J00000000000000000000002" }, "amount": { "type": "string", "example": "10000000", "description": "Stake amount in smallest units." }, "reference": { "type": "string", "example": "stake_20260629_0001" }, "idempotencyKey": { "type": "string", "example": "idem_20260629_0001" } }, "required": [ "accountId", "productId", "amount" ] }, "WalletWebhookDto": { "type": "object", "properties": {} }, "Object": { "type": "object", "properties": {} }, "BuyGiftCardDto": { "type": "object", "properties": { "debitAccountId": { "type": "string", "example": "01J00000000000000000000001", "description": "Source account ID" }, "sku": { "type": "number", "example": 5078, "description": "Ezpaypin product SKU" }, "deliveryType": { "type": "number", "example": 1, "enum": [ 0, 1 ], "description": "Delivery type: 0=None, 1=Email, 2=SMS, 3=WhatsApp" }, "destination": { "type": "string", "example": "customer@example.com", "description": "Destination for delivery" }, "price": { "type": "number", "example": 5000, "description": "Gift card purchase price in smallest currency unit (e.g. cents)" }, "quantity": { "type": "number", "example": 1, "description": "Quantity of gift cards to purchase (default: 1)", "minimum": 1 }, "customerId": { "type": "string", "example": "01J00000000000000000000004" }, "userId": { "type": "string", "example": "01J00000000000000000000005" }, "externalReference": { "type": "string", "example": "ext-ref-12345", "description": "External reference for the order" }, "deliveryNote": { "type": "string", "example": "Happy Birthday!", "description": "A note to include with the delivery" } }, "required": [ "debitAccountId", "sku", "deliveryType", "destination", "price" ] } } } }