{ "openapi": "3.0.0", "paths": { "/api/v1/business/payouts/recipients": { "post": { "description": "Creates a saved recipient you can pay by `recipientId`. Idempotent on the destination: sending the same rail + account details returns the existing recipient instead of a duplicate. Dashboard (JWT) requests are sanctions-screened on create and a match is refused with 403. Server-to-server requests authenticated with `x-api-key` are not screened by Axra — the merchant is the obligated party under the merchant agreement — and are never refused on a screening result.", "operationId": "BusinessRecipientsController_create", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business workspace", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateRecipientDto" }, { "$ref": "#/components/schemas/CreateLocalBankRecipientDto" }, { "$ref": "#/components/schemas/CreateLocalMomoRecipientDto" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/RecipientResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a payout recipient", "tags": [ "Payout Recipients" ] }, "get": { "description": "Lists saved payout recipients for the active business, newest first. Archived recipients are hidden unless you pass `includeArchived`; filter by `rail` and page with `page` and `limit` (1 and 20 by default, `limit` capped at 100). Destination details come back masked.", "operationId": "BusinessRecipientsController_list", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business workspace", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "rail", "required": false, "in": "query", "schema": { "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ], "type": "string" } }, { "name": "includeArchived", "required": false, "in": "query", "schema": { "default": false, "type": "boolean" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/RecipientListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List payout recipients for the active business", "tags": [ "Payout Recipients" ] } }, "/api/v1/business/payouts/recipients/{id}": { "get": { "description": "Retrieves one saved recipient by id, with the destination details masked. Archived recipients are not returned — an archived id is a 404.", "operationId": "BusinessRecipientsController_findOne", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business workspace", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/RecipientResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a payout recipient by id", "tags": [ "Payout Recipients" ] }, "patch": { "description": "Renames a recipient. The label is the only mutable field: destination details are frozen at creation, so correcting an account number means creating a new recipient. An archived recipient cannot be updated.", "operationId": "BusinessRecipientsController_update", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business workspace", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/RecipientResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update recipient label", "tags": [ "Payout Recipients" ] }, "delete": { "description": "Archives a recipient. This is a soft delete: it drops out of the default listing and can no longer be fetched or paid, while payouts already sent to it keep their history. Idempotent — archiving an already archived recipient still returns 204.", "operationId": "BusinessRecipientsController_archive", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business workspace", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Archive a payout recipient (soft delete)", "tags": [ "Payout Recipients" ] } }, "/api/v1/business/payouts/batches": { "post": { "description": "Validates up to BATCH_MAX_ITEMS line items, resolves each recipient (saved or inline — inline ones are sanctions-screened and saved), server-side quotes every item, and persists a DRAFT batch with child payouts in CREATED (not yet dispatched). Returns the per-item fee breakdown, summed totals, and an affordability flag. Idempotent on (business, idempotencyKey).", "operationId": "BatchPayoutsController_create", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchPreviewResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPreviewResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a draft batch payout (payroll) + preview", "tags": [ "Payout Batches" ] }, "get": { "description": "Lists batch payouts for the active business, newest first. Filter with `status` and page with `skip` and `take` (0 and 20 by default). Line items are not included — fetch a single batch for those.", "operationId": "BatchPayoutsController_list", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "DRAFT", "QUEUED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ], "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List batch payouts for the active business", "tags": [ "Payout Batches" ] } }, "/api/v1/business/payouts/batches/{id}/submit": { "post": { "description": "Re-checks affordability against the live wallet balance, gates 2FA when the summed USD-equivalent >= $10k (dashboard path; api-key exempt), and transitions the batch DRAFT → QUEUED for the fan-out processor.", "operationId": "BatchPayoutsController_submit", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitBatchDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Submit a draft batch for processing", "tags": [ "Payout Batches" ] } }, "/api/v1/business/payouts/batches/{id}": { "get": { "description": "Retrieves one batch with every line item: the per-item amounts, fees and payout status, plus the rows that failed to resolve at creation with the reason each failed, ordered by their index in the list you submitted.", "operationId": "BatchPayoutsController_findOne", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchDetailResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a batch payout with its line items", "tags": [ "Payout Batches" ] } }, "/api/v1/business/payouts/batches/{id}/cancel": { "post": { "description": "Allowed only while the batch is DRAFT or QUEUED and no item has been dispatched.", "operationId": "BatchPayoutsController_cancel", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BatchResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancel a draft or queued batch", "tags": [ "Payout Batches" ] } }, "/api/v1/business/payouts/schedules": { "post": { "description": "Validates the cadence (MONTHLY day-of-month 1–28, optional) and the per-run USD cap (defaults to $50k, rejected above the $250k admin ceiling), sanctions-screens every recipient in the payload, verifies the transaction PIN on the dashboard path (api-key exempt), stamps authorizedAt/By, and computes the first nextRunAt. Unattended runs execute without re-authorization, bounded by maxRunAmountUsd.", "operationId": "SchedulePayoutsController_create", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create + authorize a scheduled payout", "tags": [ "Payout Schedules" ] }, "get": { "description": "Lists scheduled payouts for the active business, newest first. Filter with `status` and page with `skip` and `take` (0 and 20 by default).", "operationId": "SchedulePayoutsController_list", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "ACTIVE", "PAUSED", "COMPLETED", "CANCELLED" ], "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List scheduled payouts for the active business", "tags": [ "Payout Schedules" ] } }, "/api/v1/business/payouts/schedules/{id}": { "get": { "description": "Returns the schedule plus a MASKED list of its recipients (`items[]`): label, rail, corridor (country · currency), and the configured per-run amount only. No account numbers / IBAN / phone and no partner names are exposed.", "operationId": "SchedulePayoutsController_findOne", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleDetailResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a scheduled payout", "tags": [ "Payout Schedules" ] }, "put": { "description": "Replaces the recipient list / amounts (new hire, resignation, raise) WITHOUT recreating the schedule — the cadence, day-of-month and nextRunAt timing are preserved. Every edit re-authorizes: it re-validates the payload + per-run cap, sanctions-screens every recipient in the new payload, re-verifies the transaction PIN on the dashboard path (api-key exempt), and re-stamps authorizedAt/By. Only ACTIVE/PAUSED schedules are editable; changing the cadence/timing still requires recreating the schedule.", "operationId": "SchedulePayoutsController_edit", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditScheduleDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Edit (re-authorize) a scheduled payout", "tags": [ "Payout Schedules" ] }, "patch": { "description": "Only the status (ACTIVE↔PAUSED) and name are editable here (no PIN). Changing the payload or per-run amount requires re-authorization (PIN + screening) — use PUT /schedules/:id.", "operationId": "SchedulePayoutsController_update", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Pause / resume / rename a scheduled payout", "tags": [ "Payout Schedules" ] }, "delete": { "description": "Sets status to CANCELLED (terminal). Idempotent on an already-cancelled schedule.", "operationId": "SchedulePayoutsController_cancel", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ScheduleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancel a scheduled payout", "tags": [ "Payout Schedules" ] } }, "/api/v1/business/payouts/networks": { "get": { "description": "Returns the live upstream catalog filtered to status=active for the given country and rail. Pass the returned `id` back as the recipient `bankCode` (LOCAL_BANK) or `networkId` (LOCAL_MOMO).", "operationId": "BusinessPayoutsController_listNetworks", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "country", "required": true, "in": "query", "schema": { "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ], "type": "string" } }, { "name": "rail", "required": true, "in": "query", "schema": { "enum": [ "LOCAL_BANK", "LOCAL_MOMO" ], "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LocalPayoutNetworkListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List supported banks / mobile money networks for a corridor", "tags": [ "Payouts" ] } }, "/api/v1/business/payouts/resolve-account": { "post": { "description": "Provider-neutral wrapper around the upstream account-name lookup. Returns the resolved holder name for the given (accountNumber, networkId).", "operationId": "BusinessPayoutsController_resolveBankAccount", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAccountRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ResolvedAccountResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Resolve a beneficiary name from a bank account number", "tags": [ "Payouts" ] } }, "/api/v1/business/payouts/quote": { "post": { "description": "Returns a signed quote token valid for 60 seconds. Pass the token to POST /v1/business/payouts within the window to lock the rate.", "operationId": "BusinessPayoutsController_quote", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/QuoteResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "410": { "description": "Quote expired or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "503": { "description": "FX rate unavailable for corridor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a cross-currency payout quote (60s lock)", "tags": [ "Payouts" ] } }, "/api/v1/business/payouts": { "post": { "description": "Confirms a payout against a signed `quoteToken` (LOCAL_BANK / LOCAL_MOMO). Name the destination in exactly one of three ways: `recipientId` for a recipient saved via POST /v1/business/payouts/recipients; inline `recipient` to send the details on the payout itself; or, for requests authenticated with `x-api-key`, inline `destination`. The quote is scoped to corridor, amount and business — never to a recipient — so one token confirms any of the three. Screening differs by channel: dashboard (JWT) payouts are sanctions-screened and a saved recipient carrying a match is refused; `x-api-key` payouts are not screened by Axra (the merchant is the obligated party under the merchant agreement) and an inline recipient/destination is paid ad hoc rather than saved, so the payout returns recipientId null. Server-to-server payouts are also exempt from the interactive 2FA gate — the controls are the secret key and the per-corridor velocity caps.", "operationId": "BusinessPayoutsController_create", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BusinessCreatePayoutDto" }, { "$ref": "#/components/schemas/CreateLocalBankPayoutDto" }, { "$ref": "#/components/schemas/CreateLocalMomoPayoutDto" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Initiate a business payout", "tags": [ "Payouts" ] }, "get": { "description": "Lists payouts for the active business, newest first. Filter with `status` and `rail`, and page with `skip` and `take` (0 and 20 by default, `take` capped at 100). The response carries `total` alongside the page.", "operationId": "BusinessPayoutsController_list", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "CREATED", "SUBMITTED", "PENDING_REVIEW", "SETTLED", "FAILED", "CANCELLED" ], "type": "string" } }, { "name": "rail", "required": false, "in": "query", "schema": { "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ], "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessPayoutListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List payouts for the active business", "tags": [ "Payouts" ] } }, "/api/v1/business/payouts/{id}": { "get": { "description": "Retrieves one payout by id, scoped to the active business — a payout belonging to another business is a 404. Use it to follow a payout to its terminal state.", "operationId": "BusinessPayoutsController_findOne", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a single business payout", "tags": [ "Payouts" ] } }, "/api/v1/business/payouts/{id}/cancel": { "post": { "description": "Cancels a payout that has not been dispatched yet. Only a payout still in CREATED can be cancelled; anything further along is a 409. The amount the attempt debited is reversed back to your balance.", "operationId": "BusinessPayoutsController_cancel", "parameters": [ { "name": "X-Axra-Business-Id", "in": "header", "description": "Active business context", "required": false, "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "description": "Merchant API key (alternative to dashboard JWT)", "required": false, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPayoutDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancel a CREATED payout", "tags": [ "Payouts" ] } }, "/api/v1/business/auth/token": { "post": { "operationId": "BusinessPaymentsController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessLoginDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessAuthTokenResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Authenticate with business API key and secret", "tags": [ "Authentication" ] } }, "/api/v1/business/psp-pricing": { "get": { "description": "The fee schedule in effect for your own account, aggregated to one total per corridor: a combined percentage in basis points, a fixed component and a fee floor, all in minor units of `feeCurrency`, and each row bounded by the amount band it applies to. Covers money-IN (collection) pricing only — payout fees come back on a payout quote.", "operationId": "BusinessPaymentsController_listPspPricing", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPricingResponse" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List merchant pricing per corridor (aggregated total fee, no provider breakdown)", "tags": [ "Payments" ] } }, "/api/v1/business/payment": { "post": { "description": "Creates a one-off hosted payment page for a fixed amount and returns its URL together with the payment id to track it by; a `payment.created` webhook fires immediately. Reach for it when you want one hosted checkout without configuring a reusable link — `POST /business/links` is the reusable, brandable equivalent.", "operationId": "BusinessPaymentsController_createPayment", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkDto" } } } }, "responses": { "201": { "description": "Payment link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PaymentResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create a payment link", "tags": [ "Payments" ] } }, "/api/v1/business/payment/charge": { "post": { "description": "Charges a card server-to-server, with no redirect to a hosted page. Name the card in EXACTLY ONE of `card`, `savedTokenId`, `mpgsSessionId` or `walletToken`: the schema cannot express that constraint, and sending none or more than one is a 400. `customerIp` must be the IP address of the end customer rather than of your server, because it feeds velocity checks, and the charge is refused without it. Server-to-server charging is entitled per account, so an account that does not hold it gets a 403 pointing at checkout sessions and payment links instead. Charges are idempotent on their own parameters: replaying an identical charge returns the original payment rather than charging twice. A response carrying `requiresAction` means 3-D Secure is required — send the payer to `requiresAction.redirectUrl`, then call `POST /business/payment/confirm-3ds`. Unknown body fields are rejected with a 400 rather than ignored, and numeric strings are coerced to numbers.", "operationId": "BusinessPaymentsController_chargeCard", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessChargeDto" } } } }, "responses": { "200": { "description": "Charge processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PaymentResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "503": { "description": "Card payments are temporarily unavailable (error code `CARD_PAYMENTS_TEMPORARILY_UNAVAILABLE`). No charge was attempted; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Charge a card directly (server-to-server)", "tags": [ "Payments" ] } }, "/api/v1/business/payment/confirm-3ds": { "post": { "description": "Completes a charge that came back with `requiresAction`, once the payer has finished the 3-D Secure challenge. Key it on the `transactionId` the charge returned, not on the payment id. The response carries the verdict from the card platform, but only a failure is written back to the payment: a successful authentication leaves the payment pending until the settlement webhook arrives, so treat your webhook endpoint as the authority on a completed payment.", "operationId": "BusinessPaymentsController_confirm3ds", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessConfirm3dsDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PaymentResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Confirm 3D Secure authentication", "tags": [ "Payments" ] } }, "/api/v1/business/payment/{paymentId}": { "get": { "description": "Retrieves one payment by its Axra payment id, with card, customer, failure and authorisation detail normalised so the shape does not change with the rail that collected it. The projection is an allow-list: upstream identifiers and our own costs are never returned.", "operationId": "BusinessPaymentsController_getPayment", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantPaymentDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get payment details", "tags": [ "Payments" ] } }, "/api/v1/business/payment/{paymentId}/refund": { "post": { "description": "Refunds a payment in full — there is no partial-refund parameter. The payment must be COMPLETED and no more than 180 days old; anything else is a 400. On success the payment moves to REFUNDED and a `payment.refunded` webhook fires carrying the refund id. If the refund is declined the response is a 422, and if its outcome cannot be confirmed yet it is a 503. In both cases the payment stays COMPLETED and no `payment.refunded` webhook is sent. Do not resubmit after a 503: our team checks the refund and follows up.", "operationId": "BusinessPaymentsController_refundPayment", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PaymentResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "The refund was declined and nothing was refunded. The payment stays COMPLETED and no `payment.refunded` webhook is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "503": { "description": "The refund outcome could not be confirmed yet. The payment stays COMPLETED and no `payment.refunded` webhook is sent. Do not resubmit; our team checks it and follows up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Refund a payment", "tags": [ "Payments" ] } }, "/api/v1/business/payments": { "get": { "description": "Lists the payments on your account newest-first across every rail, paginated with `page` and `limit` (1 and 20 by default). Same allow-listed projection as retrieving a single payment.", "operationId": "BusinessPaymentsController_listPayments", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PaymentListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List payments", "tags": [ "Payments" ] } }, "/api/v1/business/regenerate-api-key": { "post": { "operationId": "BusinessPaymentsController_regenerateApiKey", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ApiKeyResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Regenerate API key", "tags": [ "Authentication" ] } }, "/api/v1/business/payment/session": { "post": { "description": "Creates a hosted checkout session for one amount and returns `checkoutUrl` to send the payer to, valid for `expiresIn` seconds (one hour by default). If you include `card` or `savedTokenId` in the body the session is charged immediately instead and no `checkoutUrl` comes back — the response then reports `processing`, `3ds_required` with a `threeDsUrl`, or `failed`.", "operationId": "BusinessPaymentsController_createCheckoutSession", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionDto" } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CheckoutSessionResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create a checkout session", "tags": [ "Payments" ] } }, "/api/v1/business/links": { "post": { "description": "Creates a reusable hosted payment page at a slug you choose. The slug is global and must be 3 to 30 characters of lowercase letters, digits and hyphens, not starting or ending with a hyphen; a slug already taken is a 409. `amountType` decides what the payer may pay: `fixed` requires `fixedAmount`, `preset` requires `presetAmounts`, and the default `flexible` lets the payer name an amount within `minAmount` and `maxAmount`.", "operationId": "BusinessPaymentsController_createLink", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLinkDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LinkResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create a payment link", "tags": [ "Payment Links" ] }, "get": { "description": "Lists every payment link on the account, newest first, including deactivated ones (`isActive` false). Not paginated.", "operationId": "BusinessPaymentsController_listLinks", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkResponseDto" } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List payment links", "tags": [ "Payment Links" ] } }, "/api/v1/business/links/{id}": { "patch": { "description": "Updates presentation and amount configuration in place; only the fields you send change. The slug is fixed at creation and cannot be changed here. Setting `isActive` to true reactivates a deactivated link.", "operationId": "BusinessPaymentsController_updateLink", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinkDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LinkResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Update a payment link", "tags": [ "Payment Links" ] }, "delete": { "description": "Deactivates a payment link. This is a soft delete: the link and its payment history are kept, but the hosted page stops resolving and returns 404 to payers. Reversible by sending `isActive` true to `PATCH /business/links/{id}`.", "operationId": "BusinessPaymentsController_deactivateLink", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MessageResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Deactivate a payment link", "tags": [ "Payment Links" ] } }, "/api/v1/business/customers": { "get": { "description": "Lists the customers you have collected from, derived from your own payment history, with the payment count and total collected for each. Paginated with `page` and `limit` (1 and 20 by default).", "operationId": "BusinessPaymentsController_listCustomers", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List customers", "tags": [ "Customers" ] } }, "/api/v1/business/customers/email/{email}": { "get": { "description": "Finds a customer by the email address on their account and returns their customer id with aggregate totals. Returns 404 when no account carries that email, or when that account has never paid you.", "operationId": "BusinessPaymentsController_getCustomerByEmail", "parameters": [ { "name": "email", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Find customer by email", "tags": [ "Customers" ] } }, "/api/v1/business/customers/{customerId}": { "get": { "description": "Retrieves one customer with their saved cards and their 20 most recent payments to you. The customer must have paid you at least once and must have a stored customer profile: a payer who has only ever paid without one returns 404.", "operationId": "BusinessPaymentsController_getCustomerDetails", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerDetailResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Retrieve a customer", "tags": [ "Customers" ] } }, "/api/v1/business/customers/{customerId}/payment-methods/{paymentMethodId}": { "delete": { "description": "Detaches a saved card from a customer so it can no longer be charged. A payment method that does not belong to that customer is a 400.", "operationId": "BusinessPaymentsController_removePaymentMethod", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "paymentMethodId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MessageResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Remove a payment method", "tags": [ "Customers" ] } }, "/api/v1/business/customers/{customerId}/default-payment-method": { "put": { "description": "Marks one of the saved cards on a customer as the default for future charges. Send `paymentMethodId` in the body; a payment method that does not belong to that customer is a 400.", "operationId": "BusinessPaymentsController_setDefaultPaymentMethod", "parameters": [ { "name": "customerId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MessageResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Set default payment method", "tags": [ "Customers" ] } }, "/api/v1/business/disputes/policy/current": { "get": { "description": "Returns the defence policy applied to your disputes: whether evidence is submitted automatically, the minimum win score required before it is, the amount and currency below which a loss is accepted without contest, and your default evidence text. A default policy is created on first read.", "operationId": "DisputeCenterController_getPolicy", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantDisputePolicyDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get merchant dispute defence policy", "tags": [ "Disputes" ] }, "put": { "description": "Updates the defence policy; only the fields you send change. Use it to turn automatic submission on or off, move the win-score bar, or set the amount below which contesting a dispute is not worth it.", "operationId": "DisputeCenterController_updatePolicy", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDisputePolicyDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantDisputePolicyDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Update merchant dispute defence policy", "tags": [ "Disputes" ] } }, "/api/v1/business/disputes/stats": { "get": { "description": "Returns the open, won and lost dispute counts for your account. Cheaper than listing disputes when all you need is the headline numbers.", "operationId": "DisputeCenterController_getStats", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantDisputeStatsResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get dispute count summary (open / won / lost)", "tags": [ "Disputes" ] } }, "/api/v1/business/disputes": { "get": { "description": "Lists disputes raised against your payments. `status` selects one of `open`, `won`, `lost` or `all` and DEFAULTS TO `open`, so pass `all` to see everything; narrow further with `currency`, `from` and `to`, and page with `page` and `limit`. Every response also carries the open, won and lost counts for the whole set, not just for the page.", "operationId": "DisputeCenterController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "description": "open, won, lost", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "ISO date filter start", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "ISO date filter end", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "type": "number" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantDisputeListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List disputes for the authenticated merchant", "tags": [ "Disputes" ] } }, "/api/v1/business/disputes/{paymentId}": { "get": { "description": "Retrieves the dispute on one of your payments, keyed on the PAYMENT id rather than on a dispute id. Returns the payment, the dispute with its reason and evidence deadline, the evidence bundle assembled for it (null if there is none yet) and any files you uploaded. A payment carrying no dispute is a 404.", "operationId": "DisputeCenterController_detail", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MerchantDisputeDetailResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get dispute detail for a payment", "tags": [ "Disputes" ] } }, "/api/v1/business/disputes/{paymentId}/evidence/upload": { "post": { "description": "Uploads a supporting file for a dispute as multipart form data under the field name `file`, up to 5 MB. Files accumulate: each upload is added to the ones already on the dispute rather than replacing them. The payment must carry a dispute, or the request is a 400.", "operationId": "DisputeCenterController_uploadEvidence", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/UploadEvidenceResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Upload merchant dispute evidence file", "tags": [ "Disputes" ] } }, "/api/v1/business/disputes/{paymentId}/accept-loss": { "post": { "description": "Concedes a dispute without contesting it, for when the evidence would not win or the amount is not worth defending. The payment must carry a dispute.", "operationId": "DisputeCenterController_acceptLoss", "parameters": [ { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AcceptLossResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Accept dispute loss (merchant opts not to contest)", "tags": [ "Disputes" ] } }, "/api/v1/webhook-endpoints": { "get": { "operationId": "WebhookEndpointsApiController_list", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List webhook endpoints for the business (API key)", "tags": [ "Webhooks" ] }, "post": { "operationId": "WebhookEndpointsApiController_create", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecretResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create a webhook endpoint (returns signing secret once)", "tags": [ "Webhooks" ] } }, "/api/v1/webhook-endpoints/replay-delivery": { "post": { "operationId": "WebhookEndpointsApiController_replay", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookDeliveryDto" } } } }, "responses": { "201": { "description": "Webhook replay queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ReplayWebhookDeliveryResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Replay a webhook delivery (queues a new delivery)", "tags": [ "Webhooks" ] } }, "/api/v1/webhook-endpoints/{id}": { "get": { "operationId": "WebhookEndpointsApiController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "operationId": "WebhookEndpointsApiController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Update a webhook endpoint", "tags": [ "Webhooks" ] }, "delete": { "operationId": "WebhookEndpointsApiController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ] } }, "/api/v1/webhook-endpoints/{id}/deliveries": { "get": { "operationId": "WebhookEndpointsApiController_listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookDeliveryListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List deliveries for a webhook endpoint", "tags": [ "Webhooks" ] } }, "/api/v1/webhook-endpoints/{id}/rotate-signing-secret": { "post": { "operationId": "WebhookEndpointsApiController_rotate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Signing secret rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecretResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Rotate signing secret (returned once)", "tags": [ "Webhooks" ] } }, "/api/v1/business/fraud/rules": { "post": { "operationId": "FraudRulesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFraudRuleDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FraudRuleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create fraud rule", "tags": [ "Fraud" ] }, "get": { "operationId": "FraudRulesController_findAll", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FraudRuleResponseDto" } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List fraud rules", "tags": [ "Fraud" ] } }, "/api/v1/business/fraud/rules/test": { "post": { "operationId": "FraudRulesController_testRule", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/RiskEvaluationResponseDto" } }, "required": [ "success", "data" ] } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Evaluate fraud rules against sample payload", "tags": [ "Fraud" ] } }, "/api/v1/business/fraud/rules/{id}": { "get": { "operationId": "FraudRulesController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FraudRuleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Get fraud rule", "tags": [ "Fraud" ] }, "patch": { "operationId": "FraudRulesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFraudRuleDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/FraudRuleResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Update fraud rule", "tags": [ "Fraud" ] }, "delete": { "operationId": "FraudRulesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Delete fraud rule", "tags": [ "Fraud" ] } }, "/api/v1/business/fraud/blocked": { "get": { "operationId": "FraudAnalyticsController_blocked", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedEntityItemDto" } } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List blocked entities (merchant-scoped + platform-wide)", "tags": [ "Fraud" ] } }, "/api/v1/business/fraud/blocked/{id}": { "delete": { "operationId": "FraudAnalyticsController_unblock", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/UnblockEntityResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Unblock a blocked entity (merchant-scoped only)", "tags": [ "Fraud" ] } }, "/api/v1/business/collections": { "post": { "description": "Starts a local bank transfer or mobile money collection and returns the instructions the customer follows to pay. The currency must be enabled on your account and the corridor priced, or the request is refused as unsupported; a `momo` channel additionally requires `customer.phone`. Send an `idempotencyKey` to make retries safe — a repeat returns the collection already created rather than a second one. The window defaults to 60 minutes for mobile money and 30 minutes for bank and EFT, overridable with `expiresInSeconds`.", "operationId": "BusinessLocalRailsController_create", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create a local-rails collection (S2S)", "tags": [ "Local Rails" ] }, "get": { "description": "Lists your local-rail collections newest-first, cursor-paginated: pass `limit` (1 to 100, 25 by default) and `starting_after` set to the id of the last collection on the previous page. `hasMore` says whether another page exists.", "operationId": "BusinessLocalRailsController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "starting_after", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ListCollectionsResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List local-rails collections", "tags": [ "Local Rails" ] } }, "/api/v1/business/collections/{id}": { "get": { "description": "Retrieves one collection you own by id, with its current status and payment instructions.", "operationId": "BusinessLocalRailsController_retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Retrieve a local-rails collection", "tags": [ "Local Rails" ] } }, "/api/v1/business/collections/{id}/refresh": { "get": { "description": "Pulls the current state of a collection from upstream and returns the refreshed record, rather than serving the state last stored. Use it to reconcile when a webhook was missed; a collection already in a terminal state is returned unchanged with no upstream call.", "operationId": "BusinessLocalRailsController_refresh", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Force-refresh a local-rails collection from the upstream provider", "tags": [ "Local Rails" ] } }, "/api/v1/business/local-rails/channels": { "get": { "description": "Lists the local-rail channels open to a `country`, `currency` and `amount`, all three required. Channels that cannot take that amount are returned separately with a `BELOW_MIN` or `ABOVE_MAX` reason alongside the corridor bounds, so a below-minimum amount reveals the floor instead of coming back empty. Discovery only: it checks the channel catalogue and your currency configuration but not pricing, so a channel listed here can still be refused when you create the collection.", "operationId": "BusinessLocalRailsController_listChannels", "parameters": [ { "name": "country", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "currency", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "amount", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessListChannelsResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "List available local-rail channels", "tags": [ "Local Rails" ] } }, "/api/v1/treasury/users/{id}/kyc/sandbox-approve": { "post": { "operationId": "TreasuryKycController_sandboxApprove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } } ], "responses": { "201": { "description": "KYC approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/KycStatusResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Sandbox-only: manually approve pending KYC for an end-user", "tags": [ "Treasury — KYC" ] } }, "/api/v1/treasury/users/{id}/kyc/sandbox-reject": { "post": { "operationId": "TreasuryKycController_sandboxReject", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxKycActionDto" } } } }, "responses": { "201": { "description": "KYC rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/KycStatusResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Sandbox-only: manually reject pending KYC for an end-user", "tags": [ "Treasury — KYC" ] } }, "/api/v1/treasury/users/{id}/kyc": { "post": { "operationId": "TreasuryKycController_initiate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateKycDto" } } } }, "responses": { "201": { "description": "KYC initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/KycStatusResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Initiate KYC verification for an end-user", "tags": [ "Treasury — KYC" ] }, "get": { "operationId": "TreasuryKycController_status", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/KycStatusResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get current KYC status for an end-user", "tags": [ "Treasury — KYC" ] } }, "/api/v1/treasury/users": { "post": { "operationId": "TreasuryUsersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEndUserDto" } } } }, "responses": { "201": { "description": "End-user created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EndUserResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a treasury end-user", "tags": [ "Treasury — End-Users" ] }, "get": { "operationId": "TreasuryUsersController_list", "parameters": [ { "name": "status", "required": false, "in": "query", "schema": { "enum": [ "ACTIVE", "SUSPENDED", "CLOSED" ], "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EndUserListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List treasury end-users", "tags": [ "Treasury — End-Users" ] } }, "/api/v1/treasury/users/{id}": { "get": { "operationId": "TreasuryUsersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EndUserResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a treasury end-user by id", "tags": [ "Treasury — End-Users" ] }, "patch": { "operationId": "TreasuryUsersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEndUserDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EndUserResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a treasury end-user", "tags": [ "Treasury — End-Users" ] }, "delete": { "operationId": "TreasuryUsersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EndUserResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Soft-delete a treasury end-user (status CLOSED)", "tags": [ "Treasury — End-Users" ] } }, "/api/v1/treasury/users/{id}/wallets/{walletId}/sandbox-credit": { "post": { "operationId": "TreasuryWalletsController_sandboxCredit", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } }, { "name": "walletId", "required": true, "in": "path", "description": "Partner wallet id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxCreditWalletDto" } } } }, "responses": { "201": { "description": "Sandbox credit applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletSandboxCreditResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Sandbox-only: credit a wallet for integration testing", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/users/{id}/wallets": { "post": { "operationId": "TreasuryWalletsController_createWallet", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTreasuryWalletDto" } } } }, "responses": { "201": { "description": "Wallet created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Provision a wallet for an end-user (currency-scoped)", "tags": [ "Treasury — Wallets" ] }, "get": { "operationId": "TreasuryWalletsController_listWallets", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List an end-user's wallets", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/users/{id}/wallets/{walletId}": { "get": { "operationId": "TreasuryWalletsController_getWallet", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } }, { "name": "walletId", "required": true, "in": "path", "description": "Partner wallet id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get wallet detail", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/users/{id}/wallets/{walletId}/balance": { "get": { "operationId": "TreasuryWalletsController_getBalance", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } }, { "name": "walletId", "required": true, "in": "path", "description": "Partner wallet id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletBalanceResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get wallet balance from ledger", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/users/{id}/wallets/{walletId}/deposit_instructions": { "get": { "operationId": "TreasuryWalletsController_getDepositInstructions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } }, { "name": "walletId", "required": true, "in": "path", "description": "Partner wallet id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DepositInstructionsResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Deposit instructions (fiat VA and/or crypto liquidation address)", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/users/{id}/wallets/{walletId}/transactions": { "get": { "operationId": "TreasuryWalletsController_listTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner end-user id", "schema": { "type": "string" } }, { "name": "walletId", "required": true, "in": "path", "description": "Partner wallet id", "schema": { "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WalletTransactionsResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Partner ledger entries for this wallet currency (paginated)", "tags": [ "Treasury — Wallets" ] } }, "/api/v1/treasury/payouts": { "post": { "operationId": "TreasuryPayoutsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutDto" } } } }, "responses": { "201": { "description": "Payout created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TreasuryPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Initiate a payout from an end-user wallet", "tags": [ "Treasury — Payouts" ] }, "get": { "operationId": "TreasuryPayoutsController_list", "parameters": [ { "name": "partnerEndUserId", "required": false, "in": "query", "description": "Filter by partner end-user id", "schema": { "minLength": 8, "type": "string" } }, { "name": "skip", "required": false, "in": "query", "schema": { "minimum": 0, "default": 0, "type": "number" } }, { "name": "take", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TreasuryPayoutListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List payouts for the authenticated partner", "tags": [ "Treasury — Payouts" ] } }, "/api/v1/treasury/payouts/{id}": { "get": { "operationId": "TreasuryPayoutsController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner payout id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TreasuryPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get payout by id", "tags": [ "Treasury — Payouts" ] } }, "/api/v1/treasury/payouts/{id}/cancel": { "post": { "operationId": "TreasuryPayoutsController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Partner payout id", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Payout cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TreasuryPayoutResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Cancel a payout if it is still PENDING", "tags": [ "Treasury — Payouts" ] } }, "/api/v1/treasury/signup": { "post": { "operationId": "TreasurySandboxSignupController_signup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasurySandboxSignupDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Self-onboard a SANDBOX developer partner (authenticated; requires completed identity verification). TEST keys only.", "tags": [ "Authentication" ] } }, "/api/v1/treasury/whoami": { "get": { "operationId": "TreasuryWhoamiController_whoami", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/TreasuryWhoamiResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Returns authenticated partner id (public contract surface)", "tags": [ "Authentication" ] } }, "/api/v1/treasury/webhook-endpoints": { "get": { "operationId": "TreasuryWebhookEndpointsController_list", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List treasury webhook endpoints for the authenticated partner", "tags": [ "Webhooks" ] }, "post": { "operationId": "TreasuryWebhookEndpointsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecretResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a treasury webhook endpoint (signing secret returned once)", "tags": [ "Webhooks" ] } }, "/api/v1/treasury/webhook-endpoints/replay-delivery": { "post": { "operationId": "TreasuryWebhookEndpointsController_replay", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayWebhookDeliveryDto" } } } }, "responses": { "201": { "description": "Webhook replay queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ReplayWebhookDeliveryResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Replay a webhook delivery (queues a new delivery)", "tags": [ "Webhooks" ] } }, "/api/v1/treasury/webhook-endpoints/{id}": { "get": { "operationId": "TreasuryWebhookEndpointsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get a treasury webhook endpoint", "tags": [ "Webhooks" ] }, "patch": { "operationId": "TreasuryWebhookEndpointsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a treasury webhook endpoint", "tags": [ "Webhooks" ] }, "delete": { "operationId": "TreasuryWebhookEndpointsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete a treasury webhook endpoint", "tags": [ "Webhooks" ] } }, "/api/v1/treasury/webhook-endpoints/{id}/deliveries": { "get": { "operationId": "TreasuryWebhookEndpointsController_listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookDeliveryListResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List deliveries for a treasury webhook endpoint", "tags": [ "Webhooks" ] } }, "/api/v1/treasury/webhook-endpoints/{id}/rotate-signing-secret": { "post": { "operationId": "TreasuryWebhookEndpointsController_rotate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Signing secret rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecretResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Rotate signing secret (returned once)", "tags": [ "Webhooks" ] } }, "/api/v1/status/corridors": { "get": { "description": "Returns one row per country, currency, method and direction, saying whether you can collect or pay out over it at this moment. `status` reflects end-to-end usability through Axra, not just whether an upstream network is reachable — a corridor that is not enabled for your account reports `disabled` rather than `operational`, so you never retry into a wall.\n\nThe answer is measured on a schedule and served from cache, so it is cheap to poll and never blocks on an upstream check. If a refresh has been missed the payload comes back with `stale: true` and the last rows we actually measured; each row carries its own `checkedAt`. A `503` means we have no measurement to show yet — retry shortly.", "operationId": "CorridorStatusController_corridors", "parameters": [ { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CorridorStatusResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Check which corridors are usable right now", "tags": [ "Corridor Status" ] } }, "/api/v1/elements/session": { "post": { "description": "Opens a short-lived tokenisation session for a browser payment form. It authenticates with your publishable key rather than a secret, so it is safe to call from the page: the key is resolved to an active account and a session id is returned with its lifetime in seconds. Rate-limited per publishable key.", "operationId": "ElementsController_createSession", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateElementsSessionDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ElementsSessionResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Create an ephemeral Elements session (publishable key + amount + currency)", "tags": [ "Elements" ] } }, "/api/v1/elements/tokenize": { "post": { "description": "Exchanges card details for a single-use token inside an open session, so the card number never reaches your own server. Callable only from an allow-listed origin — the browser `Origin` header is checked and a missing or unrecognised one is refused — and the session must still be live. Returns the token id with the card brand and last four digits.", "operationId": "ElementsController_tokenize", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizeElementsDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ElementsTokenResponseDto" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "422": { "description": "Unprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpErrorEnvelopeDto" } } } } }, "summary": "Tokenize card data for a session (iframe / allowed origins only)", "tags": [ "Elements" ] } } }, "info": { "title": "Axra Public API", "description": "Merchant and third-party developer API surface", "version": "2026-04-15", "contact": {} }, "tags": [ { "name": "Authentication", "description": "Exchange your API credentials for a short-lived bearer token, rotate a leaked key, and confirm which account a credential belongs to. Start here — every other operation on this page requires one of these credentials." }, { "name": "Payments", "description": "Accept card payments server-to-server, or hand the customer a hosted checkout session, then complete 3-D Secure, retrieve, list and refund what you charged. Also exposes the fee schedule that applies to your own account." }, { "name": "Payment Links", "description": "Shareable hosted payment pages. Create a link, send it to a customer and let us host the checkout, instead of building a payment page of your own." }, { "name": "Local Rails", "description": "Collect from customers over local bank transfer and mobile money in supported markets. List the channels available for a country, currency and amount, then create a collection and poll it for the funds." }, { "name": "Corridor Status", "description": "Whether a corridor is usable right now, per country, currency, method and direction. Poll this before you route a payment rather than discovering an outage by having one fail. The answer reflects end-to-end usability through Axra, not just whether an upstream network is reachable, and it is served from a cached measurement — so polling it is cheap and never blocks on an upstream check." }, { "name": "Elements", "description": "Browser-side card tokenisation for the drop-in payment SDK. Your page exchanges card details for a single-use token, so raw card numbers never reach your server." }, { "name": "Customers", "description": "Customers you have charged and the payment methods saved against them, so a returning buyer can pay without re-entering their card." }, { "name": "Payouts", "description": "Send money out to a bank account or mobile money wallet. Quote a cross-currency payout before you commit to it, look up the destination networks for a corridor, then track or cancel what you sent." }, { "name": "Payout Recipients", "description": "Saved payout destinations. Store a beneficiary once and reference it by id on later payouts, instead of resending full account details every time." }, { "name": "Payout Batches", "description": "Pay many recipients in one submission — payroll and mass disbursement. A batch is created as a priced draft you can inspect, and only moves money once you submit it." }, { "name": "Payout Schedules", "description": "Payouts that run later, once or on a repeating cadence. Authorize the schedule up front, then pause, resume, edit or cancel it." }, { "name": "Disputes", "description": "Chargebacks raised against your payments. Review them, upload evidence to contest one, accept the loss, and set the defence policy applied on your behalf." }, { "name": "Fraud", "description": "Your own fraud rules, evaluated on payments before they are charged, plus the block list those rules produce. Test a rule against a sample payload before enabling it." }, { "name": "Treasury — End-Users", "description": "Banking-as-a-Service. The end-users your platform holds balances for — create one before provisioning a wallet or starting identity verification." }, { "name": "Treasury — KYC", "description": "Identity verification for a treasury end-user: start a check and read its status. Sandbox-only helpers drive a pending check to approved or rejected so you can build against both outcomes." }, { "name": "Treasury — Wallets", "description": "Currency-scoped balances held for an end-user. Provision a wallet, read its ledger balance and entries, and fetch the instructions a customer uses to fund it." }, { "name": "Treasury — Payouts", "description": "Move money out of an end-user wallet, then track or cancel it while it is still pending." }, { "name": "Webhooks", "description": "Register endpoints to receive signed event callbacks, inspect delivery attempts, replay a delivery and rotate a signing secret. The two products keep separate registries: `/webhook-endpoints` for the merchant API, `/treasury/webhook-endpoints` for treasury partners." } ], "servers": [ { "url": "http://localhost:3001", "description": "Local development" }, { "url": "https://staging-api.useaxra.com", "description": "Staging" }, { "url": "https://api.useaxra.com", "description": "Production" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "HttpErrorBodyDto": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "email must be an email" }, "statusCode": { "type": "number", "example": 400 }, "errors": { "type": "object", "description": "Optional per-field validation messages (when present on the source exception)", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "code", "message", "statusCode" ] }, "HttpErrorEnvelopeDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "$ref": "#/components/schemas/HttpErrorBodyDto" } }, "required": [ "success", "error" ] }, "CreateRecipientDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 }, "rail": { "type": "string", "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ] }, "details": { "type": "object", "description": "Rail-specific destination (shape depends on rail)" } }, "required": [ "label", "rail", "details" ] }, "LocalBankDetailsDto": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ] }, "accountNumber": { "type": "string", "description": "Plain at input; encrypted at rest" }, "accountName": { "type": "string", "minLength": 2, "maxLength": 120 }, "bankCode": { "type": "string", "description": "Upstream bank network identifier" }, "bankName": { "type": "string" } }, "required": [ "country", "accountNumber", "accountName", "bankCode", "bankName" ] }, "CreateLocalBankRecipientDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 }, "rail": { "type": "string", "enum": [ "LOCAL_BANK" ] }, "details": { "$ref": "#/components/schemas/LocalBankDetailsDto" } }, "required": [ "label", "rail", "details" ] }, "LocalMomoDetailsDto": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ] }, "phoneNumber": { "type": "string", "description": "E.164 phone number including + and country code" }, "accountName": { "type": "string", "minLength": 2, "maxLength": 120 }, "networkId": { "type": "string", "description": "Upstream mobile-money network identifier" }, "networkName": { "type": "string" } }, "required": [ "country", "phoneNumber", "accountName", "networkId", "networkName" ] }, "CreateLocalMomoRecipientDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 }, "rail": { "type": "string", "enum": [ "LOCAL_MOMO" ] }, "details": { "$ref": "#/components/schemas/LocalMomoDetailsDto" } }, "required": [ "label", "rail", "details" ] }, "RecipientResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "label": { "type": "string" }, "rail": { "type": "string", "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ] }, "detailsMasked": { "type": "object", "description": "Masked destination fields safe for display", "additionalProperties": { "type": "string" } }, "screenedAt": { "type": "string", "nullable": true }, "archivedAt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "businessId", "label", "rail", "detailsMasked", "createdAt", "updatedAt" ] }, "RecipientListResponseDto": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientResponseDto" } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "recipients", "total", "page", "limit" ] }, "UpdateRecipientDto": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 120 } }, "required": [ "label" ] }, "CreateBatchItemDto": { "type": "object", "properties": { "recipientId": { "type": "string", "description": "Saved recipient id. Provide exactly one of recipientId or inline `recipient`." }, "recipient": { "description": "Inline recipient details (mutually exclusive with recipientId). The recipient is sanctions-screened and saved to your recipient book, then paid as part of the batch.", "allOf": [ { "$ref": "#/components/schemas/CreateRecipientDto" } ] }, "country": { "type": "string", "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ], "description": "ISO 3166-1 alpha-2 corridor country (must match the recipient country)." }, "currency": { "type": "string", "description": "Local destination currency for the corridor (e.g. NGN, KES)." }, "srcAmount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "50.00", "description": "Source amount in USDC (the principal to convert/deliver). Provide srcAmount OR dstAmount." }, "dstAmount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "50000", "description": "Destination amount in the local currency. Provide srcAmount OR dstAmount." }, "reference": { "type": "string", "minLength": 0, "maxLength": 140, "description": "Free-form per-item reference echoed back in the preview (e.g. \"March salary\")." } }, "required": [ "country", "currency" ] }, "CreateBatchDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 64, "description": "Idempotency key — unique per (business, key). A replay returns the same batch." }, "source": { "type": "string", "enum": [ "MANUAL", "CSV", "API", "SCHEDULE", "CHANNEL" ], "default": "MANUAL", "description": "How the batch was authored. Defaults to MANUAL." }, "items": { "minItems": 1, "maxItems": 5000, "description": "Line items (one per recipient).", "type": "array", "items": { "$ref": "#/components/schemas/CreateBatchItemDto" } }, "metadata": { "type": "object", "description": "Optional caller metadata persisted on the batch." } }, "required": [ "idempotencyKey", "items" ] }, "SubmitBatchDto": { "type": "object", "properties": { "twoFactorCode": { "type": "string", "minLength": 6, "maxLength": 8, "pattern": "^(?:[0-9]{6}|[A-Z0-9]{8})$", "description": "Second factor, required (dashboard path) when the summed USD-equiv >= $10k: a 6-digit code (authenticator, or the emailed code for accounts with no authenticator) or an 8-character backup code." } } }, "BatchResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "source": { "type": "string", "enum": [ "MANUAL", "CSV", "API", "SCHEDULE", "CHANNEL" ] }, "status": { "type": "string", "enum": [ "DRAFT", "QUEUED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ] }, "totalItems": { "type": "number", "description": "Number of line items in the batch." }, "totalsByCurrency": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BatchCurrencyTotalDto" }, "description": "Summed principal / fee / totalDebit, keyed by wallet currency." }, "twoFaVerifiedAt": { "type": "string", "nullable": true, "description": "When the whole-batch 2FA was satisfied." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string", "nullable": true } }, "required": [ "id", "businessId", "source", "status", "totalItems", "totalsByCurrency", "createdAt", "updatedAt" ] }, "BatchItemResponseDto": { "type": "object", "properties": { "index": { "type": "number", "description": "Zero-based index of the item in the submitted batch." }, "payoutId": { "type": "string", "nullable": true, "description": "Child BusinessPayout id (null on error)." }, "recipientId": { "type": "string", "nullable": true, "description": "Resolved saved recipient id." }, "recipientLabel": { "type": "string", "nullable": true, "description": "Recipient label (merchant-supplied)." }, "rail": { "type": "string", "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ] }, "country": { "type": "string", "description": "Corridor country (ISO 3166-1 alpha-2)." }, "currency": { "type": "string", "description": "Local destination currency." }, "status": { "type": "string", "nullable": true, "enum": [ "CREATED", "SUBMITTED", "PENDING_REVIEW", "SETTLED", "FAILED", "CANCELLED" ] }, "srcAmount": { "type": "string", "nullable": true, "description": "Principal in USDC (the amount delivered)." }, "dstAmount": { "type": "string", "nullable": true, "description": "Destination amount in the local currency." }, "rate": { "type": "string", "nullable": true, "description": "FX rate used for the quote." }, "networkFee": { "type": "string", "nullable": true, "description": "Network cost in USDC (on top)." }, "platformFee": { "type": "string", "nullable": true, "description": "Axra platform fee in USDC (on top)." }, "totalFee": { "type": "string", "nullable": true, "description": "Total fee in USDC = networkFee + platformFee." }, "totalDebit": { "type": "string", "nullable": true, "description": "Total USDC debit for this item = principal + networkFee + platformFee." }, "failureReason": { "type": "string", "nullable": true, "description": "Per-row failure reason when resolution failed." } }, "required": [ "index", "rail", "country", "currency" ] }, "BatchDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "source": { "type": "string", "enum": [ "MANUAL", "CSV", "API", "SCHEDULE", "CHANNEL" ] }, "status": { "type": "string", "enum": [ "DRAFT", "QUEUED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ] }, "totalItems": { "type": "number", "description": "Number of line items in the batch." }, "totalsByCurrency": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BatchCurrencyTotalDto" }, "description": "Summed principal / fee / totalDebit, keyed by wallet currency." }, "twoFaVerifiedAt": { "type": "string", "nullable": true, "description": "When the whole-batch 2FA was satisfied." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResponseDto" } } }, "required": [ "id", "businessId", "source", "status", "totalItems", "totalsByCurrency", "createdAt", "updatedAt", "items" ] }, "BatchListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResponseDto" } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "items", "total", "skip", "take" ] }, "BatchCurrencyTotalDto": { "type": "object", "properties": { "principal": { "type": "string", "description": "Summed principal (delivered amount) in this currency." }, "fee": { "type": "string", "description": "Summed total fee in this currency." }, "totalDebit": { "type": "string", "description": "Summed total debit (principal + fee) in this currency." } }, "required": [ "principal", "fee", "totalDebit" ] }, "BatchPreviewResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "source": { "type": "string", "enum": [ "MANUAL", "CSV", "API", "SCHEDULE", "CHANNEL" ] }, "status": { "type": "string", "enum": [ "DRAFT", "QUEUED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "FAILED", "CANCELLED" ] }, "totalItems": { "type": "number", "description": "Number of line items in the batch." }, "totalsByCurrency": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BatchCurrencyTotalDto" }, "description": "Summed principal / fee / totalDebit, keyed by wallet currency." }, "twoFaVerifiedAt": { "type": "string", "nullable": true, "description": "When the whole-batch 2FA was satisfied." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "completedAt": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResponseDto" } }, "affordable": { "type": "boolean", "description": "True when the summed totalDebit (per currency) is covered by the available wallet balance." }, "errorCount": { "type": "number", "description": "Count of items that failed to resolve/quote (have a failureReason)." }, "requiresTwoFactor": { "type": "boolean", "description": "True when the summed USD-equivalent meets the 2FA threshold (dashboard path)." } }, "required": [ "id", "businessId", "source", "status", "totalItems", "totalsByCurrency", "createdAt", "updatedAt", "items", "affordable", "errorCount", "requiresTwoFactor" ] }, "ScheduleItemSpecDto": { "type": "object", "properties": { "recipientId": { "type": "string", "description": "Saved recipient id. Provide exactly one of recipientId or inline `recipient`." }, "recipient": { "description": "Inline recipient details (mutually exclusive with recipientId). Sanctions-screened and saved to your recipient book at schedule creation.", "allOf": [ { "$ref": "#/components/schemas/CreateRecipientDto" } ] }, "country": { "type": "string", "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ], "description": "ISO 3166-1 alpha-2 corridor country (must match the recipient country)." }, "currency": { "type": "string", "description": "Local destination currency for the corridor (e.g. NGN, KES)." }, "srcAmount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "50.00", "description": "Source amount in USDC (the principal to convert/deliver). Provide srcAmount OR dstAmount." }, "dstAmount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "50000", "description": "Destination amount in the local currency. Provide srcAmount OR dstAmount." }, "reference": { "type": "string", "minLength": 0, "maxLength": 140, "description": "Free-form per-item reference (e.g. \"March salary\")." } }, "required": [ "country", "currency" ] }, "SchedulePayloadDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "SINGLE", "BATCH" ], "description": "SINGLE | BATCH discriminator." }, "items": { "minItems": 1, "maxItems": 5000, "description": "Payout specs. SINGLE must carry exactly one item; BATCH carries up to BATCH_MAX_ITEMS.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleItemSpecDto" } } }, "required": [ "kind", "items" ] }, "ScheduleLocalCapDto": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 8, "example": "NGN", "description": "Destination currency this cap applies to." }, "amount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "20000000", "description": "Maximum total destination amount per run in `currency`. Compared against the sum of the run's destination amounts in that currency — never converted, so it does not move with FX." } }, "required": [ "currency", "amount" ] }, "CreateScheduleDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human label, e.g. \"Monthly payroll\"." }, "cadence": { "type": "string", "enum": [ "ONCE", "WEEKLY", "BIWEEKLY", "MONTHLY" ], "description": "ONCE | WEEKLY | BIWEEKLY | MONTHLY." }, "dayOfMonth": { "type": "number", "minimum": 1, "maximum": 28, "description": "MONTHLY only: day-of-month (1–28) to fire on. Absent → the creation day-of-month. Ignored for other cadences." }, "payloadKind": { "type": "string", "enum": [ "SINGLE", "BATCH" ], "description": "SINGLE | BATCH." }, "payload": { "description": "The frozen payout spec.", "allOf": [ { "$ref": "#/components/schemas/SchedulePayloadDto" } ] }, "maxRunAmountUsd": { "type": "number", "minimum": 0, "example": 50000, "description": "Per-run USD cap (compliance). Defaults to SCHEDULE_RUN_USD_DEFAULT ($50k); rejected if above the SCHEDULE_RUN_USD_CEILING admin cap ($250k)." }, "endAt": { "type": "string", "description": "Optional natural end. After this instant the schedule auto-completes." }, "pin": { "type": "string", "minLength": 4, "maxLength": 6, "description": "Transaction PIN, required on the dashboard path to authorize the schedule (verified server-side). Not required on the api-key path. Future runs execute automatically." }, "metadata": { "type": "object", "description": "Optional caller metadata persisted on the schedule." }, "maxRunLocalCaps": { "maxItems": 20, "description": "Optional per-currency caps for locally-denominated runs. A currency listed here is checked against the run total in that currency and is immune to FX movement; every other currency still falls under maxRunAmountUsd. Omit for USD-only capping (the existing behaviour).", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleLocalCapDto" } } }, "required": [ "name", "cadence", "payloadKind", "payload" ] }, "EditScheduleDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New label (rename). Omit to keep the current name." }, "payloadKind": { "type": "string", "enum": [ "SINGLE", "BATCH" ], "description": "SINGLE | BATCH." }, "payload": { "description": "The replacement frozen payout spec (re-screened on edit).", "allOf": [ { "$ref": "#/components/schemas/SchedulePayloadDto" } ] }, "maxRunAmountUsd": { "type": "number", "minimum": 0, "example": 50000, "description": "Per-run USD cap (compliance). Defaults to SCHEDULE_RUN_USD_DEFAULT ($50k); rejected if above the SCHEDULE_RUN_USD_CEILING admin cap ($250k)." }, "pin": { "type": "string", "minLength": 4, "maxLength": 6, "description": "Transaction PIN, required on the dashboard path to re-authorize the edit (verified server-side). Not required on the api-key path." }, "maxRunLocalCaps": { "maxItems": 20, "description": "Optional per-currency caps for locally-denominated runs. A currency listed here is checked against the run total in that currency and is immune to FX movement; every other currency still falls under maxRunAmountUsd. Omit for USD-only capping (the existing behaviour).", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleLocalCapDto" } } }, "required": [ "payloadKind", "payload" ] }, "UpdateScheduleDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New label (rename)." }, "status": { "type": "number", "enum": [ { "ONCE": "ONCE", "WEEKLY": "WEEKLY", "BIWEEKLY": "BIWEEKLY", "MONTHLY": "MONTHLY" } ], "description": "Pause (PAUSED) or resume (ACTIVE) only. Changing the payload or amount is NOT allowed — recreate the schedule (re-authorization required)." } } }, "ScheduleResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "name": { "type": "string", "description": "Human label, e.g. \"Monthly payroll\"." }, "cadence": { "type": "string", "enum": [ "ONCE", "WEEKLY", "BIWEEKLY", "MONTHLY" ] }, "dayOfMonth": { "type": "number", "nullable": true, "description": "MONTHLY day-of-month (1–28). Null for other cadences." }, "payloadKind": { "type": "string", "enum": [ "SINGLE", "BATCH" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "COMPLETED", "CANCELLED" ] }, "itemCount": { "type": "number", "description": "Number of payout specs in the frozen payload." }, "nextRunAt": { "type": "string", "description": "When the next run fires (ISO-8601)." }, "lastRunAt": { "type": "string", "nullable": true, "description": "When the last run fired (ISO-8601)." }, "endAt": { "type": "string", "nullable": true, "description": "Optional natural end (ISO-8601)." }, "runCount": { "type": "number", "description": "How many times this schedule has run." }, "maxRunAmountUsd": { "type": "string", "description": "Per-run USD cap (compliance)." }, "maxRunLocalCaps": { "nullable": true, "description": "Per-currency run caps, or null for USD-only capping. A currency listed here is checked against the run total in that currency, so it does not breach on FX movement alone.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleLocalCapDto" } }, "authorizedAt": { "type": "string", "description": "When PIN + screening were completed at creation (ISO-8601)." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "businessId", "name", "cadence", "payloadKind", "status", "itemCount", "nextRunAt", "runCount", "maxRunAmountUsd", "authorizedAt", "createdAt", "updatedAt" ] }, "ScheduleItemSummaryDto": { "type": "object", "properties": { "index": { "type": "number", "description": "Zero-based position of this item in the payload." }, "recipientId": { "type": "string", "nullable": true, "description": "Saved-recipient id when this item references the recipient book, for web edit pre-fill. Null for inline recipients (the web treats those as re-enter-to-change). Not PII." }, "recipientLabel": { "type": "string", "description": "Human recipient label (e.g. \"Jane Doe\"). No PII." }, "rail": { "type": "string", "description": "Payout rail (e.g. LOCAL_BANK / LOCAL_MOMO). No partner name." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 corridor country." }, "currency": { "type": "string", "description": "Local destination currency for the corridor." }, "amount": { "type": "string", "nullable": true, "description": "DEPRECATED — collapsed per-run amount (srcAmount ?? dstAmount) kept for backwards compatibility. It does NOT say which side the figure is on, so a client that reads it and writes back cannot know whether \"150000\" meant 150000 USDC or ₦150,000. Read `srcAmount` / `dstAmount` instead.", "deprecated": true }, "srcAmount": { "type": "string", "nullable": true, "description": "Configured per-run source amount in USDC, when the schedule is source-denominated. Exactly one of srcAmount / dstAmount is non-null." }, "dstAmount": { "type": "string", "nullable": true, "description": "Configured per-run destination amount in the local currency, when the schedule is destination-denominated (e.g. a salary contracted in NGN). Each run re-quotes so this exact local amount is delivered and the USDC debit floats with the rate." }, "reference": { "type": "string", "nullable": true, "description": "Optional payment reference." } }, "required": [ "index", "recipientLabel", "rail", "country", "currency" ] }, "ScheduleDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "name": { "type": "string", "description": "Human label, e.g. \"Monthly payroll\"." }, "cadence": { "type": "string", "enum": [ "ONCE", "WEEKLY", "BIWEEKLY", "MONTHLY" ] }, "dayOfMonth": { "type": "number", "nullable": true, "description": "MONTHLY day-of-month (1–28). Null for other cadences." }, "payloadKind": { "type": "string", "enum": [ "SINGLE", "BATCH" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "COMPLETED", "CANCELLED" ] }, "itemCount": { "type": "number", "description": "Number of payout specs in the frozen payload." }, "nextRunAt": { "type": "string", "description": "When the next run fires (ISO-8601)." }, "lastRunAt": { "type": "string", "nullable": true, "description": "When the last run fired (ISO-8601)." }, "endAt": { "type": "string", "nullable": true, "description": "Optional natural end (ISO-8601)." }, "runCount": { "type": "number", "description": "How many times this schedule has run." }, "maxRunAmountUsd": { "type": "string", "description": "Per-run USD cap (compliance)." }, "maxRunLocalCaps": { "nullable": true, "description": "Per-currency run caps, or null for USD-only capping. A currency listed here is checked against the run total in that currency, so it does not breach on FX movement alone.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleLocalCapDto" } }, "authorizedAt": { "type": "string", "description": "When PIN + screening were completed at creation (ISO-8601)." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "items": { "description": "Masked recipient summaries.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleItemSummaryDto" } } }, "required": [ "id", "businessId", "name", "cadence", "payloadKind", "status", "itemCount", "nextRunAt", "runCount", "maxRunAmountUsd", "authorizedAt", "createdAt", "updatedAt", "items" ] }, "ScheduleListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleResponseDto" } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "items", "total", "skip", "take" ] }, "BusinessCreatePayoutDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ] }, "recipientId": { "type": "string", "description": "Saved recipient id. For LOCAL_BANK / LOCAL_MOMO provide exactly one of recipientId, inline `recipient`, or (api-key only) inline `destination`. On other rails it is mutually exclusive with `destination`." }, "recipient": { "description": "Inline recipient details for LOCAL_BANK / LOCAL_MOMO (mutually exclusive with recipientId). Paid in the same call — a single quote→pay round-trip. Behaviour depends on how the request is authenticated: on the DASHBOARD (JWT) the recipient is sanctions-screened, account-resolved and saved to your recipient book; on the MERCHANT API (`x-api-key`) it is treated as an ad-hoc destination — not screened by Axra and not saved, so the payout comes back with recipientId null and cannot be reused by id. Use POST /v1/business/payouts/recipients first if you want a reusable recipientId.", "allOf": [ { "$ref": "#/components/schemas/CreateRecipientDto" } ] }, "destination": { "type": "object", "description": "Ad-hoc destination, mutually exclusive with recipientId. On LOCAL_BANK / LOCAL_MOMO it is accepted only for requests authenticated with `x-api-key`; a dashboard (JWT) request must use recipientId or inline `recipient`. Same fields as the rail's recipient `details` object. Nothing is persisted to your recipient book, so the payout has recipientId null." }, "quoteToken": { "type": "string", "description": "Signed quote token from POST /v1/business/payouts/quote (required for LOCAL_BANK / LOCAL_MOMO)" }, "amount": { "type": "string", "pattern": "/^[0-9]+(\\.[0-9]{1,8})?$/", "example": "50.00", "description": "Decimal string (up to 8 fractional digits). Ignored for LOCAL_* rails — amounts come from quoteToken." }, "currency": { "type": "string", "enum": [ "USDC", "EURC", "GBPC", "NGN" ], "description": "Ignored for LOCAL_* rails — wallet debit currency is USDC from the quote." }, "twoFactorCode": { "type": "string", "minLength": 6, "maxLength": 8, "pattern": "^(?:[0-9]{6}|[A-Z0-9]{8})$", "description": "Second factor when amount >= $10k USD-equivalent: a 6-digit code (authenticator, or the emailed code for accounts with no authenticator) or an 8-character backup code." }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 64 }, "metadata": { "type": "object" } }, "required": [ "rail", "idempotencyKey" ] }, "QuoteRequestDto": { "type": "object", "properties": { "rail": { "enum": [ "LOCAL_BANK", "LOCAL_MOMO" ], "type": "string" }, "country": { "type": "string", "enum": [ "NG", "KE", "ZA", "TZ", "UG", "RW", "MW", "ZM", "BW", "CM", "BJ", "BF", "CD", "CI", "GA", "ML", "CG", "SN", "TG" ], "description": "ISO-2 destination country" }, "currency": { "type": "string", "enum": [ "NGN", "KES", "ZAR", "TZS", "UGX", "RWF", "MWK", "ZMW", "BWP", "XAF", "XOF", "CDF" ], "description": "Local currency code" }, "srcCurrency": { "type": "string", "enum": [ "USDC" ], "default": "USDC", "description": "Source wallet currency — only USDC supported in v1" }, "srcAmount": { "type": "string", "pattern": "/^\\d+(\\.\\d+)?$/", "description": "Decimal string in USDC (e.g. \"100.00\") — XOR with dstAmount" }, "dstAmount": { "type": "string", "pattern": "/^\\d+(\\.\\d+)?$/", "description": "Decimal string in local currency (e.g. \"150000\") — XOR with srcAmount" } }, "required": [ "rail", "country", "currency", "srcCurrency" ] }, "PayoutAmountLimitsDto": { "type": "object", "properties": { "minAmount": { "type": "number", "description": "Smallest payable amount in local major units. 0 = no minimum." }, "maxAmount": { "type": "number", "description": "Largest payable amount in local major units. 0 = no maximum." }, "currency": { "type": "string", "description": "Currency the bounds are denominated in" } }, "required": [ "minAmount", "maxAmount", "currency" ] }, "QuoteResponseDto": { "type": "object", "properties": { "quoteToken": { "type": "string", "description": "Signed quote token — pass to POST /v1/business/payouts within 60s" }, "srcAmount": { "type": "string", "description": "Principal in USDC — the amount converted and delivered to the recipient. The fee is charged ON TOP (see totalDebit)." }, "dstAmount": { "type": "string", "description": "Local-currency amount the recipient receives" }, "rate": { "type": "string", "description": "FX rate (srcCurrency per 1 unit of dstCurrency, decimal string)" }, "axraFee": { "type": "string", "description": "Axra platform fee in USDC (== platformFee), charged on top" }, "networkFee": { "type": "string", "description": "Network (provider) cost in USDC, charged on top" }, "platformFee": { "type": "string", "description": "Axra platform fee in USDC, charged on top" }, "totalFee": { "type": "string", "description": "Total fee in USDC = networkFee + platformFee" }, "totalDebit": { "type": "string", "description": "Total USDC debited from the merchant wallet = srcAmount + networkFee + platformFee" }, "expiresAt": { "type": "string", "description": "ISO timestamp — token rejected if used after this" }, "rail": { "type": "string" }, "country": { "type": "string" }, "currency": { "type": "string" }, "limits": { "description": "Amount bounds for this corridor, in the same units as `dstAmount`. Absent when no bounds could be determined — treat that as \"unknown\", never as \"no payouts allowed\".", "allOf": [ { "$ref": "#/components/schemas/PayoutAmountLimitsDto" } ] } }, "required": [ "quoteToken", "srcAmount", "dstAmount", "rate", "axraFee", "networkFee", "platformFee", "totalFee", "totalDebit", "expiresAt", "rail", "country", "currency" ] }, "CreateLocalBankPayoutDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "LOCAL_BANK" ] }, "quoteToken": { "type": "string", "description": "Signed quote token from POST /v1/business/payouts/quote" }, "recipientId": { "type": "string", "description": "Saved recipient id (from POST /v1/business/payouts/recipients). Provide this OR inline `recipient`, not both." }, "recipient": { "description": "Inline recipient details (mutually exclusive with recipientId) — a single quote→pay round-trip. On the DASHBOARD (JWT) the recipient is created, sanctions-screened and saved to your recipient book. On the MERCHANT API (`x-api-key`) it is paid as an ad-hoc destination: not screened by Axra, not saved, and the payout returns recipientId null. Create the recipient first via POST /v1/business/payouts/recipients if you need a reusable id.", "allOf": [ { "$ref": "#/components/schemas/CreateLocalBankRecipientDto" } ] }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 64 }, "metadata": { "type": "object" } }, "required": [ "rail", "quoteToken", "idempotencyKey" ] }, "CreateLocalMomoPayoutDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "LOCAL_MOMO" ] }, "quoteToken": { "type": "string", "description": "Signed quote token from POST /v1/business/payouts/quote" }, "recipientId": { "type": "string", "description": "Saved recipient id (from POST /v1/business/payouts/recipients). Provide this OR inline `recipient`, not both." }, "recipient": { "description": "Inline recipient details (mutually exclusive with recipientId) — a single quote→pay round-trip. On the DASHBOARD (JWT) the recipient is created, sanctions-screened and saved to your recipient book. On the MERCHANT API (`x-api-key`) it is paid as an ad-hoc destination: not screened by Axra, not saved, and the payout returns recipientId null. Create the recipient first via POST /v1/business/payouts/recipients if you need a reusable id.", "allOf": [ { "$ref": "#/components/schemas/CreateLocalMomoRecipientDto" } ] }, "idempotencyKey": { "type": "string", "minLength": 8, "maxLength": 64 }, "metadata": { "type": "object" } }, "required": [ "rail", "quoteToken", "idempotencyKey" ] }, "LocalPayoutNetworkDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque network id — pass back verbatim when creating a recipient." }, "name": { "type": "string", "description": "Display name, e.g. \"GTBank\" or \"M-Pesa\"." }, "code": { "type": "string", "description": "Optional bank short code (e.g. NUBAN routing prefix)." } }, "required": [ "id", "name" ] }, "LocalPayoutNetworkListResponseDto": { "type": "object", "properties": { "networks": { "type": "array", "items": { "$ref": "#/components/schemas/LocalPayoutNetworkDto" } } }, "required": [ "networks" ] }, "ResolveAccountRequestDto": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 6, "maxLength": 24, "description": "Account / NUBAN number to verify." }, "networkId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Network id from GET /business/payouts/networks." }, "country": { "type": "string", "enum": [ "NG" ], "description": "ISO-2 country code. Only NG is supported today (per upstream constraint)." } }, "required": [ "accountNumber", "networkId", "country" ] }, "ResolvedAccountResponseDto": { "type": "object", "properties": { "accountNumber": { "type": "string" }, "accountName": { "type": "string", "description": "Resolved beneficiary name from upstream catalog." }, "accountBank": { "type": "string", "description": "Resolved bank label, when upstream returns it." } }, "required": [ "accountNumber", "accountName" ] }, "PayoutQuoteBreakdownDto": { "type": "object", "properties": { "dstAmount": { "type": "string" }, "rate": { "type": "string" }, "axraFee": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" } }, "required": [ "dstAmount", "rate", "axraFee", "currency", "country" ] }, "BusinessPayoutResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "rail": { "type": "string", "enum": [ "CRYPTO", "ACH", "WIRE", "SEPA", "SWIFT", "LOCAL_BANK", "LOCAL_MOMO" ] }, "status": { "type": "string", "enum": [ "CREATED", "SUBMITTED", "PENDING_REVIEW", "SETTLED", "FAILED", "CANCELLED" ] }, "amount": { "type": "string", "description": "Principal (USDC) — the amount converted/delivered. Fee is on top." }, "currency": { "type": "string", "enum": [ "USDC", "EURC", "GBPC", "NGN" ] }, "feeAmount": { "type": "string", "description": "Axra platform fee in USDC (== platformFee)" }, "networkFee": { "type": "string", "description": "Network (provider) cost in USDC, charged on top" }, "platformFee": { "type": "string", "description": "Axra platform fee in USDC, charged on top" }, "totalFee": { "type": "string", "description": "Total fee in USDC = networkFee + platformFee" }, "totalDebit": { "type": "string", "description": "Total USDC debited from the merchant = amount + networkFee + platformFee" }, "recipientId": { "type": "string", "nullable": true }, "destinationMasked": { "type": "object", "additionalProperties": { "type": "string" } }, "providerRef": { "type": "string", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "submittedAt": { "type": "string", "nullable": true }, "settledAt": { "type": "string", "nullable": true }, "cancelledAt": { "type": "string", "nullable": true }, "quote": { "description": "Present for LOCAL_BANK / LOCAL_MOMO payouts locked via quote token", "allOf": [ { "$ref": "#/components/schemas/PayoutQuoteBreakdownDto" } ] } }, "required": [ "id", "businessId", "rail", "status", "amount", "currency", "feeAmount", "networkFee", "platformFee", "totalFee", "totalDebit", "destinationMasked", "createdAt" ] }, "BusinessPayoutListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessPayoutResponseDto" } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "items", "total", "skip", "take" ] }, "CancelPayoutDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reserved for future cancel reason" } } }, "BusinessAuthTokenResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string" }, "tokenType": { "type": "string" }, "expiresIn": { "type": "number" }, "businessId": { "type": "string" }, "businessName": { "type": "string" } }, "required": [ "accessToken", "tokenType", "expiresIn", "businessId", "businessName" ] }, "BusinessLoginDto": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "bk_live_abc123...", "description": "Business API key" }, "apiSecret": { "type": "string", "example": "bs_live_xyz789...", "description": "Business API secret" } }, "required": [ "apiKey", "apiSecret" ] }, "MessageResponseDto": { "type": "object", "properties": { "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "message" ] }, "MerchantPricingResponse": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "CARD", "BANK", "MOMO", "EFT", "WALLET", "CRYPTO" ] }, "currency": { "type": "string" }, "country": { "type": "string", "nullable": true }, "minAmountMinor": { "type": "string", "description": "Inclusive lower bound on amount in minor units (string for bigint)." }, "maxAmountMinor": { "type": "string", "nullable": true, "description": "Inclusive upper bound on amount in minor units; null = no upper bound." }, "pctBps": { "type": "number", "description": "Combined fee percentage in basis points (1/100 of a percent)." }, "fixedFeeMinor": { "type": "number", "description": "Combined fixed fee per transaction, in minor units of feeCurrency." }, "minFeeMinor": { "type": "number", "description": "Minimum total fee, in minor units of feeCurrency." }, "feeCurrency": { "type": "string" }, "effectiveFrom": { "format": "date-time", "type": "string" } }, "required": [ "rail", "currency", "minAmountMinor", "pctBps", "fixedFeeMinor", "minFeeMinor", "feeCurrency", "effectiveFrom" ] }, "PaymentResponseDto": { "type": "object", "properties": { "paymentId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "refunded", "disputed" ] }, "amount": { "type": "number", "description": "What you asked us to charge, in major currency units.", "example": 10 }, "chargedAmount": { "type": "number", "description": "What the customer's card was charged, in major currency units. May exceed `amount` by `serviceFee`. The customer's statement shows this figure. Equals `amount` when there is no service fee.", "example": 10.16 }, "serviceFee": { "type": "number", "description": "Service fee added on top of `amount`, in major currency units. `chargedAmount = amount + serviceFee`. Zero when there is no uplift.", "example": 0.16 }, "currency": { "type": "string" }, "provider": { "type": "string", "description": "Payment method family. Always `card` on a card charge, whichever processor handled it.", "enum": [ "card" ], "example": "card" }, "transactionId": { "type": "string" }, "paymentUrl": { "type": "string", "nullable": true }, "refundId": { "type": "string" }, "requiresAction": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "paymentId", "status", "chargedAmount", "serviceFee" ] }, "CreatePaymentLinkDto": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 0.01, "example": 49.99, "description": "Payment amount" }, "currency": { "type": "string", "maxLength": 10, "example": "usd", "description": "ISO 4217 currency code" }, "email": { "type": "string", "format": "email", "example": "customer@example.com", "description": "Customer email for receipts" }, "description": { "type": "string", "maxLength": 500, "example": "Premium plan subscription", "description": "Payment description shown to customer" }, "metadata": { "type": "object", "example": { "orderId": "ORD-123", "sku": "PLAN-PRO" }, "description": "Arbitrary metadata attached to the payment" } }, "required": [ "amount", "currency" ] }, "WalletTokenDto": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "APPLE_PAY", "GOOGLE_PAY" ], "example": "APPLE_PAY" }, "token": { "type": "string", "minLength": 1, "maxLength": 65536 } }, "required": [ "token" ] }, "BillingAddressDto": { "type": "object", "properties": { "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Billing country as an ISO 3166-1 alpha-2 code (2 letters). Lower case is accepted and upper-cased; superseded codes such as \"UK\" are normalised to the canonical code (\"GB\").", "example": "US" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "required": [ "country" ] }, "ThreeDsBrowserDetailsDto": { "type": "object", "properties": { "acceptHeaders": { "type": "string" }, "colorDepth": { "type": "number" }, "javaEnabled": { "type": "boolean" }, "javascriptEnabled": { "type": "boolean" }, "language": { "type": "string" }, "screenHeight": { "type": "number" }, "screenWidth": { "type": "number" }, "timeZone": { "type": "number" }, "3DSecureChallengeWindowSize": { "type": "string" } } }, "StatementDescriptorAddressDto": { "type": "object", "properties": { "city": { "type": "string" }, "company": { "type": "string" }, "country": { "type": "string" }, "postcodeZip": { "type": "string" }, "stateProvince": { "type": "string" }, "street": { "type": "string" } } }, "StatementDescriptorDto": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "description": "Soft descriptor (the BODY). Axra prefixes the first 4 characters of the registered business name plus `*`, and caps the whole string at 22 because the scheme truncates near there. Example: payload `\"ORCHESTRATE\"` on Vincentbyte prints `VINC*ORCHESTRATE`.", "example": "ORCHESTRATE" }, "phone": { "type": "string", "description": "Accepted for compatibility; not sent to the card network." }, "address": { "description": "Accepted for compatibility; not sent to the card network.", "allOf": [ { "$ref": "#/components/schemas/StatementDescriptorAddressDto" } ] } } }, "BusinessCardDto": { "type": "object", "properties": { "number": { "type": "string" }, "expiryMonth": { "type": "number" }, "expiryYear": { "type": "number" }, "cvv": { "type": "string" }, "holderName": { "type": "string" } }, "required": [ "number", "expiryMonth", "expiryYear", "cvv" ] }, "BusinessChargeDto": { "type": "object", "properties": { "mpgsSessionId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Hosted card-session id (SAQ-A) — the card was attached client-side, so no PAN transits your server.", "example": "SESSION0002abcDEF" }, "walletToken": { "$ref": "#/components/schemas/WalletTokenDto" }, "returnUrl": { "type": "string", "format": "uri", "description": "Where the payer is sent after 3DS. Not shared with the card processor." }, "billingAddress": { "description": "Payer billing address. Optional — when omitted no billing country is sent to the card provider. Axra never substitutes a default: a fabricated country would be declared to the issuer that issued the card.", "allOf": [ { "$ref": "#/components/schemas/BillingAddressDto" } ] }, "breezeSessionId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Breeze Risk JS SDK session id from the browser SDK (CIT charges)", "example": "breeze_sess_abc123" }, "browser": { "type": "string", "description": "EMV-3DS2 payer user-agent string (device.browser)", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..." }, "browserDetails": { "description": "EMV-3DS2 browser signals (device.browserDetails) for a 3DS2 challenge", "allOf": [ { "$ref": "#/components/schemas/ThreeDsBrowserDetailsDto" } ] }, "statementDescriptor": { "description": "What the cardholder sees on their statement. Optional — when omitted we derive it from your registered business name. Strongly recommended on a shared acquiring MID, where the fallback is the MID registration rather than your name.", "allOf": [ { "$ref": "#/components/schemas/StatementDescriptorDto" } ] }, "amount": { "type": "number", "minimum": 0.01 }, "currency": { "type": "string" }, "card": { "$ref": "#/components/schemas/BusinessCardDto" }, "savedTokenId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "description": { "type": "string" }, "metadata": { "type": "object" }, "saveCard": { "type": "boolean" }, "customerIp": { "type": "string" } }, "required": [ "amount", "currency" ] }, "BusinessConfirm3dsDto": { "type": "object", "properties": { "transactionId": { "type": "string" }, "sessionToken": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paymentId": { "type": "string" } }, "required": [ "transactionId" ] }, "MerchantCardDto": { "type": "object", "properties": { "last4": { "type": "string", "nullable": true, "example": "7039", "description": "Last four digits of the card." }, "brand": { "type": "string", "nullable": true, "example": "MASTERCARD" }, "expiryMonth": { "type": "number", "nullable": true, "example": 3 }, "expiryYear": { "type": "number", "nullable": true, "example": 2029, "description": "Four-digit year on every rail." }, "fundingType": { "type": "string", "nullable": true, "enum": [ "CREDIT", "DEBIT", "PREPAID", "CHARGE" ] }, "issuerCountry": { "type": "string", "nullable": true, "example": "US", "description": "Issuer country, ISO 3166-1 alpha-2." } } }, "MerchantCustomerDto": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "example": "Ada Obi" }, "email": { "type": "string", "nullable": true, "example": "ada@example.com" }, "phone": { "type": "string", "nullable": true } } }, "MerchantFailureDto": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "example": "51", "description": "Provider decline/gateway code." }, "message": { "type": "string", "nullable": true, "example": "Insufficient funds" }, "at": { "type": "string", "nullable": true, "description": "ISO-8601 timestamp of the decline." } } }, "MerchantAuthorizationDto": { "type": "object", "properties": { "authorizationCode": { "type": "string", "nullable": true, "example": "54370C", "description": "The acquirer's approval code." }, "receiptNumber": { "type": "string", "nullable": true, "example": "623617168693" }, "receiptUrl": { "type": "string", "nullable": true, "description": "Hosted receipt, where the provider issues one." } } }, "MerchantPaymentDto": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "string", "description": "What you asked us to charge, in the charge currency. The customer's statement shows `chargedAmount`, which may exceed this by `serviceFee`.", "example": "10" }, "chargedAmount": { "type": "string", "description": "What the customer's card was charged. May exceed `amount` by `serviceFee`. The customer's statement shows this figure. Equals `amount` when there is no service fee.", "example": "10.16" }, "serviceFee": { "type": "string", "description": "Service fee added on top of `amount`, in the charge currency. `chargedAmount = amount + serviceFee`. Zero when there is no uplift.", "example": "0.16" }, "currency": { "type": "string", "example": "usd" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "DISPUTED" ] }, "type": { "type": "string", "example": "PAYMENT" }, "description": { "type": "string", "nullable": true, "description": "The description you supplied on the charge." }, "idempotencyKey": { "type": "string", "nullable": true, "description": "The idempotency key you supplied, echoed back." }, "card": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/MerchantCardDto" } ] }, "customer": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/MerchantCustomerDto" } ] }, "failure": { "nullable": true, "description": "Present on a failed payment.", "allOf": [ { "$ref": "#/components/schemas/MerchantFailureDto" } ] }, "authorization": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/MerchantAuthorizationDto" } ] }, "settlementStatus": { "type": "string", "nullable": true }, "estimatedSettleAt": { "format": "date-time", "type": "string", "nullable": true }, "settledAt": { "format": "date-time", "type": "string", "nullable": true }, "fee": { "type": "string", "nullable": true, "description": "Axra's fee on this payment." }, "paymentUrl": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The metadata you supplied on the charge, echoed back." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "amount", "chargedAmount", "serviceFee", "currency", "status", "type", "createdAt", "updatedAt" ] }, "PaymentListItemDto": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "string", "description": "What you asked us to charge, in the charge currency. The customer's statement shows `chargedAmount`, which may exceed this by `serviceFee`.", "example": "10" }, "chargedAmount": { "type": "string", "description": "What the customer's card was charged. May exceed `amount` by `serviceFee`. The customer's statement shows this figure. Equals `amount` when there is no service fee.", "example": "10.16" }, "serviceFee": { "type": "string", "description": "Service fee added on top of `amount`, in the charge currency. `chargedAmount = amount + serviceFee`. Zero when there is no uplift.", "example": "0.16" }, "currency": { "type": "string", "example": "xaf" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "REFUNDED", "DISPUTED" ] }, "type": { "type": "string", "example": "PAYMENT" }, "idempotencyKey": { "type": "string", "nullable": true, "description": "The idempotency key you supplied, echoed back." }, "settlementStatus": { "type": "string", "nullable": true, "description": "Settlement state of this payment." }, "estimatedSettleAt": { "format": "date-time", "type": "string", "nullable": true }, "settledAt": { "format": "date-time", "type": "string", "nullable": true }, "fee": { "type": "string", "nullable": true, "description": "Axra fee charged on this payment." }, "paymentUrl": { "type": "string", "nullable": true, "description": "Hosted payment page URL, when one exists." }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "ONLY the metadata you supplied when creating the payment. The stored blob also holds Axra-internal routing and provider-failure detail, which is never returned." }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "amount", "chargedAmount", "serviceFee", "currency", "status", "type", "createdAt", "updatedAt" ] }, "PaymentListPaginationDto": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" }, "totalPages": { "type": "number" } }, "required": [ "page", "limit", "total", "totalPages" ] }, "PaymentListResponseDto": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentListItemDto" } }, "pagination": { "$ref": "#/components/schemas/PaymentListPaginationDto" } }, "required": [ "payments", "pagination" ] }, "ApiKeyResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "apiKey": { "type": "string" }, "businessName": { "type": "string" } }, "required": [ "id", "apiKey", "businessName" ] }, "CheckoutAvailableMethodDto": { "type": "object", "properties": { "provider": { "type": "string" }, "isActive": { "type": "boolean" }, "supportedCurrencies": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "isActive", "supportedCurrencies" ] }, "CheckoutPspPublicKeysDto": { "type": "object", "properties": { "breeze": { "type": "string", "description": "Breeze Risk SDK public key — present when card charges route to Breeze" } } }, "CheckoutLocalRailCorridorDto": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO-3166-1 alpha-2, UPPER", "example": "SN" }, "currency": { "type": "string", "description": "ISO-4217, lower", "example": "xof" }, "rails": { "description": "Rails with at least one active collect channel on this corridor", "example": [ "bank", "momo" ], "type": "array", "items": { "type": "string" } }, "minAmount": { "type": "number", "description": "Local-currency MAJOR units. 0 = unbounded.", "example": 1000 }, "maxAmount": { "type": "number", "description": "Local-currency MAJOR units. 0 = unbounded.", "example": 200000 } }, "required": [ "country", "currency", "rails", "minAmount", "maxAmount" ] }, "CheckoutCardFieldsDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acquirer_elements" ], "description": "Which card-entry component the checkout must render." }, "accountId": { "type": "string", "description": "Acquirer account the card fields are initialised with." }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "amount": { "type": "number", "description": "Amount the card will be charged, in MAJOR units — the same gateway amount the charge uses.", "example": 25.5 }, "currency": { "type": "string", "description": "ISO-4217, lower case.", "example": "usd" } }, "required": [ "kind", "accountId", "environment", "amount", "currency" ] }, "CheckoutSessionResponseDto": { "type": "object", "properties": { "sessionId": { "type": "string" }, "checkoutUrl": { "type": "string" }, "status": { "type": "string" }, "threeDsUrl": { "type": "string" }, "paymentId": { "type": "string" }, "transactionId": { "type": "string" }, "error": { "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "availableMethods": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutAvailableMethodDto" } }, "pspPublicKeys": { "$ref": "#/components/schemas/CheckoutPspPublicKeysDto" }, "localRailCorridors": { "description": "Local-rail corridors this merchant can collect on right now. The checkout page renders its country/currency options from this array — it holds no corridor list of its own.", "type": "array", "items": { "$ref": "#/components/schemas/CheckoutLocalRailCorridorDto" } }, "billingFieldsRequired": { "type": "boolean", "description": "True when the card form must collect the billing country and postal code (and the payer email if the session has none) before a card payment. Absent otherwise." }, "cardFields": { "description": "Present when card details must be entered in the embedded card fields, which mint a single-use `cardToken` the checkout posts instead of `card`. Absent otherwise.", "allOf": [ { "$ref": "#/components/schemas/CheckoutCardFieldsDto" } ] } }, "required": [ "sessionId", "status" ] }, "CreateCheckoutSessionDto": { "type": "object", "properties": { "billingAddress": { "description": "Payer billing address. Optional — when omitted no billing country is sent to the card provider. Axra never substitutes a default.", "allOf": [ { "$ref": "#/components/schemas/BillingAddressDto" } ] }, "amount": { "type": "number", "minimum": 4.99 }, "currency": { "type": "string" }, "description": { "type": "string" }, "customerEmail": { "type": "string", "format": "email" }, "successUrl": { "type": "string", "format": "uri" }, "cancelUrl": { "type": "string", "format": "uri" }, "metadata": { "type": "object" }, "expiresIn": { "type": "number", "minimum": 300 }, "card": { "$ref": "#/components/schemas/BusinessCardDto" }, "savedTokenId": { "type": "string" }, "customerIp": { "type": "string" } }, "required": [ "amount", "currency", "successUrl", "cancelUrl" ] }, "LinkResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "link", "church" ] }, "isActive": { "type": "boolean" }, "redirectUrl": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "businessId", "slug", "title", "amount", "currency", "type", "isActive", "createdAt", "updatedAt" ] }, "CreateLinkDto": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "/^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$/", "example": "my-shop", "description": "URL slug (3-30 chars, lowercase alphanumeric + hyphens)" }, "linkType": { "type": "string", "enum": [ "link", "church" ], "example": "link", "description": "Link type: \"link\" or \"church\"" }, "title": { "type": "string", "minLength": 1, "maxLength": 200, "example": "My Payment Page", "description": "Title displayed on the link page" }, "description": { "type": "string", "maxLength": 1000, "example": "Pay for goods and services" }, "avatarUrl": { "type": "string", "nullable": true, "example": "https://example.com/avatar.png", "maxLength": 2048, "description": "Image shown on the hosted link page. Must be an absolute https URL. Send `null` or an empty string to remove it." }, "accentColor": { "type": "string", "maxLength": 20, "example": "#6366f1" }, "thankYouMessage": { "type": "string", "maxLength": 500, "example": "Thank you for your payment!" }, "amountType": { "type": "string", "enum": [ "flexible", "fixed", "preset" ], "example": "flexible", "description": "\"flexible\" | \"fixed\" | \"preset\"" }, "fixedAmount": { "type": "number", "minimum": 0.01, "example": 49.99, "description": "Fixed amount (required when amountType is \"fixed\")" }, "presetAmounts": { "example": [ 5, 10, 25, 50, 100 ], "description": "Preset amounts (required when amountType is \"preset\")", "type": "array", "items": { "type": "number" } }, "currency": { "type": "string", "maxLength": 10, "example": "USD", "description": "Currency code" }, "minAmount": { "type": "number", "minimum": 0.01, "example": 1, "description": "Minimum amount for flexible payments" }, "maxAmount": { "type": "number", "minimum": 0.01, "example": 10000, "description": "Maximum amount for flexible payments" }, "acceptsCard": { "type": "boolean", "example": true }, "acceptsCrypto": { "type": "boolean", "example": false }, "collectName": { "type": "boolean", "example": true }, "collectEmail": { "type": "boolean", "example": true }, "collectNote": { "type": "boolean", "example": true }, "config": { "type": "object", "description": "Church-specific config (categories, memberId, etc.)" } }, "required": [ "slug", "title" ] }, "UpdateLinkDto": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200, "example": "My Payment Page" }, "description": { "type": "string", "maxLength": 1000, "example": "Pay for goods and services" }, "avatarUrl": { "type": "string", "nullable": true, "example": "https://example.com/avatar.png", "maxLength": 2048, "description": "Image shown on the hosted link page. Must be an absolute https URL. Send `null` or an empty string to remove it." }, "accentColor": { "type": "string", "maxLength": 20, "example": "#6366f1" }, "thankYouMessage": { "type": "string", "maxLength": 500, "example": "Thank you for your payment!" }, "amountType": { "type": "string", "enum": [ "flexible", "fixed", "preset" ], "example": "flexible", "description": "\"flexible\" | \"fixed\" | \"preset\"" }, "fixedAmount": { "type": "number", "minimum": 0.01, "example": 49.99 }, "presetAmounts": { "example": [ 5, 10, 25, 50, 100 ], "type": "array", "items": { "type": "number" } }, "currency": { "type": "string", "maxLength": 10, "example": "USD" }, "minAmount": { "type": "number", "minimum": 0.01, "example": 1 }, "maxAmount": { "type": "number", "minimum": 0.01, "example": 10000 }, "acceptsCard": { "type": "boolean", "example": true }, "acceptsCrypto": { "type": "boolean", "example": false }, "collectName": { "type": "boolean", "example": true }, "collectEmail": { "type": "boolean", "example": true }, "collectNote": { "type": "boolean", "example": true }, "isActive": { "type": "boolean", "example": true }, "config": { "type": "object", "description": "Church-specific config" } } }, "CustomerResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "last4": { "type": "string", "nullable": true }, "brand": { "type": "string", "nullable": true }, "totalPayments": { "type": "number" }, "totalSpent": { "type": "number" }, "createdAt": { "type": "string", "nullable": true } }, "required": [ "id", "customerId", "totalPayments", "totalSpent" ] }, "PaginationMetaDto": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" }, "totalPages": { "type": "number" } }, "required": [ "page", "limit", "total", "totalPages" ] }, "CustomerListResponseDto": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerResponseDto" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetaDto" } }, "required": [ "customers", "pagination" ] }, "PaymentMethodDto": { "type": "object", "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "expiryMonth": { "type": "number" }, "expiryYear": { "type": "number" } }, "required": [ "id" ] }, "CustomerDetailResponseDto": { "type": "object", "properties": { "customerId": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "defaultPaymentMethod": { "type": "string", "nullable": true }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodDto" } }, "recentPayments": { "type": "array", "items": { "type": "object" } } }, "required": [ "customerId", "email", "paymentMethods", "recentPayments" ] }, "MerchantDisputePolicyDto": { "type": "object", "properties": { "autoSubmitEnabled": { "type": "boolean" }, "autoSubmitMinWinScore": { "type": "number", "description": "0–1 win-score threshold for auto-submit" }, "autoAcceptLossThreshold": { "type": "number", "nullable": true }, "autoAcceptLossCurrency": { "type": "string", "nullable": true }, "defaultEvidenceText": { "type": "string", "nullable": true } }, "required": [ "autoSubmitEnabled", "autoSubmitMinWinScore" ] }, "UpdateDisputePolicyDto": { "type": "object", "properties": { "autoSubmitEnabled": { "type": "boolean" }, "autoSubmitMinWinScore": { "type": "number", "minimum": 0.5, "maximum": 0.95, "description": "0.5–0.95 safety bounds" }, "autoAcceptLossThreshold": { "type": "number", "minimum": 0 }, "autoAcceptLossCurrency": { "type": "string" }, "defaultEvidenceText": { "type": "string", "maxLength": 2000 } } }, "MerchantDisputeStatsResponseDto": { "type": "object", "properties": { "open": { "type": "number" }, "won": { "type": "number" }, "lost": { "type": "number" } }, "required": [ "open", "won", "lost" ] }, "MerchantDisputeListItemDto": { "type": "object", "properties": { "paymentId": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "object" }, "winScore": { "type": "number" }, "winScoreLabel": { "type": "object" }, "openedAt": { "type": "string" } }, "required": [ "paymentId", "amount", "currency", "reason", "status", "openedAt" ] }, "MerchantDisputeListCountsDto": { "type": "object", "properties": { "open": { "type": "number" }, "won": { "type": "number" }, "lost": { "type": "number" } }, "required": [ "open", "won", "lost" ] }, "MerchantDisputeListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantDisputeListItemDto" } }, "counts": { "$ref": "#/components/schemas/MerchantDisputeListCountsDto" }, "meta": { "type": "object", "properties": { "page": { "type": "number" }, "limit": { "type": "number" }, "total": { "type": "number" }, "totalPages": { "type": "number" } }, "required": [ "page", "limit", "total", "totalPages" ] } }, "required": [ "items", "counts", "meta" ] }, "MerchantDisputeEvidencePreviewDto": { "type": "object", "properties": { "threeDSStatus": { "type": "object" }, "avsMatch": { "type": "boolean" }, "cvcPass": { "type": "boolean" }, "priorChargesCount": { "type": "number" }, "customerCommunicationFound": { "type": "boolean" }, "uncategorizedText": { "type": "string" } }, "required": [ "threeDSStatus", "avsMatch", "cvcPass", "priorChargesCount", "customerCommunicationFound", "uncategorizedText" ] }, "MerchantDisputeBundleDto": { "type": "object", "properties": { "winScore": { "type": "number" }, "winScoreLabel": { "type": "object" }, "explanation": { "type": "string" }, "status": { "type": "string" }, "evidencePreview": { "$ref": "#/components/schemas/MerchantDisputeEvidencePreviewDto" }, "submittedAt": { "type": "string", "nullable": true }, "autoSubmitted": { "type": "boolean" } }, "required": [ "winScore", "winScoreLabel", "explanation", "status", "evidencePreview", "autoSubmitted" ] }, "MerchantUploadedFileDto": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "uploadedAt": { "type": "string" }, "supabasePath": { "type": "string" } }, "required": [ "id", "filename", "uploadedAt", "supabasePath" ] }, "MerchantDisputeDetailResponseDto": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "createdAt": { "type": "string" }, "customerEmail": { "type": "string", "nullable": true } }, "required": [ "id", "amount", "currency", "createdAt", "customerEmail" ] }, "dispute": { "type": "object", "properties": { "status": { "type": "object" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "reason": { "type": "string" }, "openedAt": { "type": "string" }, "resolvedAt": { "type": "string", "nullable": true }, "evidenceDueBy": { "type": "string", "nullable": true } }, "required": [ "status", "amount", "currency", "reason", "openedAt", "resolvedAt", "evidenceDueBy" ] }, "bundle": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/MerchantDisputeBundleDto" } ] }, "uploadedFiles": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantUploadedFileDto" } } }, "required": [ "payment", "dispute", "uploadedFiles" ] }, "UploadEvidenceResponseDto": { "type": "object", "properties": { "uploaded": { "type": "boolean" }, "supabasePath": { "type": "string" } }, "required": [ "uploaded", "supabasePath" ] }, "AcceptLossResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] }, "WebhookEndpointResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string", "nullable": true }, "partnerId": { "type": "string", "nullable": true }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "apiVersion": { "type": "string", "nullable": true }, "signingSecretHint": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "url", "events", "status", "signingSecretHint", "createdAt", "updatedAt" ] }, "WebhookEndpointListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } } }, "required": [ "items" ] }, "WebhookEndpointWithSecretResponseDto": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" }, "signingSecret": { "type": "string" } }, "required": [ "endpoint", "signingSecret" ] }, "CreateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri", "example": "https://example.com/hooks/axra" }, "description": { "type": "string", "maxLength": 500 }, "events": { "minItems": 1, "description": "Event types to receive, or [\"*\"] for all supported events.", "example": [ "payment.completed", "payment.failed" ], "type": "array", "items": { "type": "string" } }, "apiVersion": { "type": "string", "maxLength": 32, "description": "Optional API version pin for this endpoint" } }, "required": [ "url", "events" ] }, "ReplayWebhookDeliveryResponseDto": { "type": "object", "properties": { "deliveryId": { "type": "string" } }, "required": [ "deliveryId" ] }, "ReplayWebhookDeliveryDto": { "type": "object", "properties": { "deliveryId": { "type": "string" } }, "required": [ "deliveryId" ] }, "WebhookDeliveryResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "partnerId": { "type": "string", "nullable": true }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true }, "status": { "type": "string" }, "attemptCount": { "type": "number" }, "nextRetryAt": { "format": "date-time", "type": "string", "nullable": true }, "lastAttemptAt": { "format": "date-time", "type": "string", "nullable": true }, "responseStatus": { "type": "number", "nullable": true }, "responseBody": { "type": "string", "nullable": true }, "responseTimeMs": { "type": "number", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "endpointId", "eventId", "eventType", "payload", "status", "attemptCount", "createdAt", "updatedAt" ] }, "WebhookDeliveryListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryResponseDto" } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "items", "total", "page", "limit" ] }, "UpdateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "description": { "type": "string", "nullable": true, "maxLength": 500 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "ENABLED", "DISABLED" ] } } }, "FraudRuleResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "number" }, "enabled": { "type": "boolean" }, "conditions": { "type": "object" }, "action": { "type": "string", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "riskScore": { "type": "number" }, "metadata": { "type": "object" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "businessId", "name", "priority", "enabled", "conditions", "action", "riskScore", "createdAt", "updatedAt" ] }, "RuleConditionDto": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "contains" ] }, "value": { "type": "object" } }, "required": [ "field", "operator", "value" ] }, "CreateFraudRuleDto": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "number", "minimum": 0, "default": 100 }, "enabled": { "type": "boolean", "default": true }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleConditionDto" } }, "match": { "type": "string", "enum": [ "all", "any" ] }, "action": { "type": "string", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "riskScore": { "type": "number", "minimum": 0, "maximum": 100, "default": 0 }, "metadata": { "type": "object" } }, "required": [ "name", "conditions", "match", "action" ] }, "TriggeredRuleDto": { "type": "object", "properties": { "ruleId": { "type": "string" }, "name": { "type": "string" }, "action": { "type": "string", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "score": { "type": "number" } }, "required": [ "ruleId", "name", "action", "score" ] }, "RiskEvaluationResponseDto": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "riskScore": { "type": "number" }, "rulesTriggered": { "type": "array", "items": { "$ref": "#/components/schemas/TriggeredRuleDto" } }, "controlChecks": { "type": "object" } }, "required": [ "decision", "riskScore", "rulesTriggered", "controlChecks" ] }, "UpdateFraudRuleDto": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "number", "minimum": 0, "default": 100 }, "enabled": { "type": "boolean", "default": true }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RuleConditionDto" } }, "match": { "type": "string", "enum": [ "all", "any" ] }, "action": { "type": "string", "enum": [ "ALLOW", "REVIEW", "BLOCK" ] }, "riskScore": { "type": "number", "minimum": 0, "maximum": 100, "default": 0 }, "metadata": { "type": "object" } } }, "BlockedEntityItemDto": { "type": "object", "properties": { "id": { "type": "string", "example": "b3e3d2d5-2e1b-4fd0-bb63-6c8ad8c0f8c1" }, "type": { "type": "string", "example": "IP" }, "value": { "type": "string", "example": "192.0.2.10" }, "reason": { "type": "string", "example": "High-risk country + velocity spike" }, "expiresAt": { "type": "string", "nullable": true, "example": "2026-04-23T00:00:00.000Z" }, "createdAt": { "type": "string", "example": "2026-04-16T08:05:23.000Z" }, "createdBy": { "type": "string", "nullable": true, "example": "system" }, "active": { "type": "boolean", "example": true } }, "required": [ "id", "type", "value", "reason", "expiresAt", "createdAt", "createdBy", "active" ] }, "UnblockEntityResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "b3e3d2d5-2e1b-4fd0-bb63-6c8ad8c0f8c1" }, "unblocked": { "type": "boolean", "example": true } }, "required": [ "id", "unblocked" ] }, "CollectionChannelDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "bank", "momo", "eft" ] }, "provider": { "type": "string" }, "channelId": { "type": "string", "nullable": true, "description": "The provider's own channel id for this collection. Null when the provider returned none (older collections, bank rails, and attempts that failed before a payload came back). It is never substituted with `networkId` — if you need the operator we pinned, read `networkId`." }, "networkId": { "type": "string", "description": "The operator network this collection was pinned to. This is the value `customer.networkId` echoes back, and the one to quote when asking about routing." } }, "required": [ "rail", "provider", "channelId", "networkId" ] }, "CollectionInstructionsDto": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bank_transfer", "momo_prompt", "hosted_page" ] }, "bankName": { "type": "string" }, "accountNumber": { "type": "string" }, "accountName": { "type": "string" }, "reference": { "type": "object", "nullable": true }, "phone": { "type": "string" }, "prompt": { "type": "string" }, "url": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "kind" ] }, "CollectionResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "collection" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "expired" ] }, "amount": { "type": "number" }, "currency": { "type": "string" }, "country": { "type": "string" }, "expiresAt": { "type": "string" }, "channel": { "$ref": "#/components/schemas/CollectionChannelDto" }, "instructions": { "$ref": "#/components/schemas/CollectionInstructionsDto" }, "metadata": { "type": "object", "nullable": true }, "businessPaymentId": { "type": "string" }, "source": { "type": "string", "enum": [ "api", "session" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "object", "status", "amount", "currency", "country", "expiresAt", "channel", "instructions", "businessPaymentId", "source", "createdAt" ] }, "ListCollectionsResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResponseDto" } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ] }, "BusinessNetworkDto": { "type": "object", "properties": { "networkId": { "type": "string", "description": "Pass this back as `customer.networkId` when creating the collection." }, "name": { "type": "string", "example": "MTN", "description": "Operator name, for display to the payer." }, "rail": { "type": "string", "enum": [ "bank", "momo", "eft" ], "description": "This network's own rail. Omitted when the provider does not tell us — the network is still usable, we just will not guess its rail. Until 2026-09-10 every row was reported as `momo`, which advertised bank networks as mobile-money operators." } }, "required": [ "networkId", "name" ] }, "BusinessChannelDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "bank", "momo", "eft" ] }, "provider": { "type": "string" }, "providerHint": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "rail", "provider", "providerHint", "min", "max" ] }, "BusinessUnavailableChannelDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "bank", "momo", "eft" ] }, "provider": { "type": "string" }, "providerHint": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "reason": { "type": "string", "enum": [ "BELOW_MIN", "ABOVE_MAX" ], "description": "Why the requested amount does not fit this channel." } }, "required": [ "rail", "provider", "providerHint", "min", "max", "reason" ] }, "BusinessChannelLimitsDto": { "type": "object", "properties": { "minAmount": { "type": "number", "description": "Smallest amount any active channel on this corridor accepts. 0 means at least one channel reports no floor." }, "maxAmount": { "type": "number", "description": "Largest amount any active channel on this corridor accepts. 0 means at least one channel reports no ceiling." } }, "required": [ "minAmount", "maxAmount" ] }, "BusinessListChannelsResponseDto": { "type": "object", "properties": { "networks": { "description": "Mobile-money operators available on this corridor. Where more than one is returned the payer is on exactly ONE of them, and sending the wrong one fails the collection — so echo the right `networkId` back on `customer.networkId`. If you omit it we infer the operator from `customer.phone`, which is correct for the overwhelming majority but cannot see a ported number.", "type": "array", "items": { "$ref": "#/components/schemas/BusinessNetworkDto" } }, "channels": { "description": "Channels that accept the requested amount. Usable right now.", "type": "array", "items": { "$ref": "#/components/schemas/BusinessChannelDto" } }, "unavailable": { "description": "Channels that exist on this corridor but do not accept the requested amount. Returned so an amount outside the limits is self-diagnosable instead of looking like a dead rail.", "type": "array", "items": { "$ref": "#/components/schemas/BusinessUnavailableChannelDto" } }, "limits": { "description": "Corridor bounds across all active channels, independent of the requested amount.", "allOf": [ { "$ref": "#/components/schemas/BusinessChannelLimitsDto" } ] } }, "required": [ "networks", "channels", "unavailable", "limits" ] }, "CustomerDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "pattern": "/^\\+?[0-9]{7,15}$/", "description": "Required for mobile-money channels" }, "networkId": { "type": "string", "description": "The payer's mobile-money operator, from `networks[].networkId` on GET /local-rails/channels. Optional but PREFERRED on any corridor returning more than one network: the payer is on exactly one operator and sending the wrong one fails the collection. Omit it and we infer from `phone`, which cannot detect a ported number." } }, "required": [ "name" ] }, "ChannelSelectionDto": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "bank", "momo", "eft" ] }, "providerHint": { "type": "string" } }, "required": [ "rail" ] }, "CreateCollectionDto": { "type": "object", "properties": { "amount": { "type": "number", "minimum": 1, "description": "Amount in major units (matches hosted checkout)" }, "currency": { "type": "string", "pattern": "/^[a-z]{3}$/", "example": "ngn" }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "example": "NG" }, "customer": { "$ref": "#/components/schemas/CustomerDto" }, "channel": { "$ref": "#/components/schemas/ChannelSelectionDto" }, "metadata": { "type": "object" }, "successUrl": { "type": "string", "format": "uri", "deprecated": true, "description": "Ignored. The payer is returned to the return URL configured on your business settings (PUT /v1/business/config returnUrl), or to Axra's payment-complete page." }, "expiresInSeconds": { "type": "number", "minimum": 60, "maximum": 3600, "default": 600 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "amount", "currency", "country", "customer" ] }, "KycStatusResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "partnerEndUserId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "APPROVED", "REJECTED", "EXPIRED" ] }, "level": { "type": "string", "nullable": true }, "rejectionReasons": { "type": "array", "items": { "type": "string" } }, "kycLinkUrl": { "type": "string", "nullable": true, "description": "Hosted KYC URL when available" }, "updatedAt": { "type": "string" } }, "required": [ "id", "partnerEndUserId", "status", "updatedAt" ] }, "SandboxKycActionDto": { "type": "object", "properties": { "reasons": { "description": "Rejection reasons (sandbox-reject only)", "type": "array", "items": { "type": "string" } } } }, "TreasuryKycApplicantDto": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "maxLength": 320, "format": "email", "description": "Overrides PartnerEndUser.email when set" }, "phone": { "type": "string", "maxLength": 32 }, "birthDate": { "type": "string", "maxLength": 32, "example": "1990-01-15" }, "residentialAddress": { "type": "object" }, "identifyingInformation": { "type": "array", "items": { "type": "object" } }, "sourceOfFunds": { "type": "string" } }, "required": [ "firstName", "lastName" ] }, "InitiateKycDto": { "type": "object", "properties": { "applicant": { "$ref": "#/components/schemas/TreasuryKycApplicantDto" }, "documents": { "type": "array", "description": "Optional document metadata for identity verification", "items": { "type": "object" } } }, "required": [ "applicant" ] }, "EndUserResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "partnerId": { "type": "string" }, "externalId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED", "CLOSED" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "partnerId", "externalId", "email", "status", "createdAt", "updatedAt" ] }, "CreateEndUserDto": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Stable id in the partner system" }, "email": { "type": "string", "maxLength": 320, "format": "email" }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 32 }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "externalId", "email" ] }, "EndUserListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserResponseDto" } }, "total": { "type": "number" } }, "required": [ "items", "total" ] }, "UpdateEndUserDto": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 320, "format": "email" }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 32 }, "metadata": { "type": "object", "additionalProperties": true } } }, "WalletSandboxCreditResponseDto": { "type": "object", "properties": { "walletId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "newBalance": { "type": "string" } }, "required": [ "walletId", "amount", "currency", "newBalance" ] }, "SandboxCreditWalletDto": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "/^\\d+(\\.\\d+)?$/", "example": "10.50", "description": "Credit amount (wallet currency)" }, "currency": { "type": "string", "minLength": 3, "example": "USDC", "description": "Must match the wallet currency" }, "reference": { "type": "string", "description": "Optional client reference (stored on ledger metadata)" } }, "required": [ "amount", "currency" ] }, "WalletResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "partnerEndUserId": { "type": "string", "description": "Partner end-user id" }, "currency": { "type": "string", "example": "USDC" }, "balance": { "type": "string", "description": "Current ledger balance as decimal string" }, "status": { "type": "string", "enum": [ "ACTIVE", "FROZEN", "CLOSED" ] }, "virtualAccountId": { "type": "string", "nullable": true, "description": "Virtual account ID for fiat deposit rails" }, "liquidationAddress": { "type": "string", "nullable": true, "description": "On-chain liquidation address when crypto rails are provisioned" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "partnerEndUserId", "currency", "balance", "status", "createdAt", "updatedAt" ] }, "CreateTreasuryWalletDto": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 2, "maxLength": 16, "description": "Wallet currency (e.g. USDC, EURC, GBPC, NGN). USD/EUR/GBP aliases map to USDC/EURC/GBPC.", "example": "USDC" } }, "required": [ "currency" ] }, "WalletListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WalletResponseDto" } } }, "required": [ "items" ] }, "WalletBalanceResponseDto": { "type": "object", "properties": { "walletId": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" } }, "required": [ "walletId", "currency", "balance" ] }, "DepositInstructionsResponseDto": { "type": "object", "properties": { "walletId": { "type": "string" }, "currency": { "type": "string" }, "accountNumber": { "type": "string", "nullable": true }, "routingNumber": { "type": "string", "nullable": true }, "iban": { "type": "string", "nullable": true }, "bankName": { "type": "string", "nullable": true }, "accountType": { "type": "string", "nullable": true }, "depositInstructions": { "type": "object", "nullable": true, "description": "Additional deposit instructions when available" }, "cryptoDepositAddress": { "type": "string", "nullable": true, "description": "Preferred on-chain deposit address (liquidation address when configured)" }, "cryptoDepositChain": { "type": "string", "nullable": true }, "walletAddress": { "type": "string", "nullable": true }, "chain": { "type": "string", "nullable": true } }, "required": [ "walletId", "currency" ] }, "PartnerLedgerEntryResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "DEPOSIT", "CREDIT", "WITHDRAWAL", "DEBIT", "FEE", "FEE_REVENUE", "PARTNER_REVENUE", "REVERSAL" ] }, "amount": { "type": "string", "description": "Decimal amount as string" }, "currency": { "type": "string" }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "type", "amount", "currency", "createdAt" ] }, "WalletTransactionsResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerLedgerEntryResponseDto" } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "items", "total", "skip", "take" ] }, "TreasuryPayoutResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "partnerId": { "type": "string" }, "partnerEndUserId": { "type": "string" }, "partnerWalletId": { "type": "string", "nullable": true }, "amount": { "type": "string", "example": "100.00" }, "currency": { "type": "string", "example": "USDC" }, "destinationType": { "type": "string" }, "destinationDetails": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ] }, "failureReason": { "type": "string", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "partnerId", "partnerEndUserId", "amount", "currency", "destinationType", "destinationDetails", "status", "createdAt", "updatedAt" ] }, "CreatePayoutDto": { "type": "object", "properties": { "partnerEndUserId": { "type": "string", "minLength": 8, "description": "Partner end-user id (cuid)" }, "partnerWalletId": { "type": "string", "minLength": 8, "description": "Source PartnerWallet id" }, "amount": { "type": "string", "pattern": "/^\\d+(\\.\\d+)?$/", "example": "100.00", "description": "Principal amount to send (wallet currency)" }, "destinationType": { "type": "string", "enum": [ "bank_account", "crypto", "mobile_money" ] }, "destination": { "type": "object", "description": "Destination details (validated in service by destinationType)", "additionalProperties": true }, "idempotencyKey": { "type": "string", "description": "Optional idempotency key (logged in metadata only in v1)" }, "metadata": { "type": "object", "description": "Test mode metadata (sandbox partners). Supported keys: test_outcome", "additionalProperties": true } }, "required": [ "partnerEndUserId", "partnerWalletId", "amount", "destinationType", "destination" ] }, "TreasuryPayoutListResponseDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryPayoutResponseDto" } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "items", "total", "skip", "take" ] }, "TreasurySandboxSignupDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200, "example": "Acme Treasury" }, "slug": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "/^[a-z0-9]+(?:-[a-z0-9]+)*$/", "example": "acme-sandbox" }, "contactEmail": { "type": "string", "format": "email", "example": "ops@acme.test" } }, "required": [ "name", "slug" ] }, "TreasuryWhoamiResponseDto": { "type": "object", "properties": { "partnerId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "object" }, "countriesAllowed": { "type": "array", "items": { "type": "string" } }, "currenciesAllowed": { "type": "array", "items": { "type": "string" } }, "apiKeyPrefix": { "type": "string" } }, "required": [ "partnerId", "slug", "name", "status", "countriesAllowed", "currenciesAllowed", "apiKeyPrefix" ] }, "CorridorStatusDto": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code, e.g. `SN`.", "example": "SN" }, "currency": { "type": "string", "description": "ISO 4217 currency the customer is debited or credited in.", "example": "XOF" }, "method": { "type": "string", "enum": [ "bank", "mobile_money" ], "description": "How the customer pays or is paid — a bank account or a mobile money wallet." }, "direction": { "type": "string", "enum": [ "collection", "payout" ], "description": "Which way the money moves: collecting from a customer, or paying one out." }, "status": { "type": "string", "enum": [ "operational", "degraded", "unavailable", "disabled" ], "description": "Whether this corridor is usable right now. `operational` — working. `degraded` — working, but slower or less reliable than usual; expect retries. `unavailable` — not offered on this account. `disabled` — offered, but switched off for your account; contact support to have it enabled." }, "minAmount": { "type": "string", "description": "Smallest amount accepted on this corridor, as a decimal string in `currency`. Absent when no floor is published.", "example": "100" }, "maxAmount": { "type": "string", "description": "Largest amount accepted on this corridor, as a decimal string in `currency`. Absent when no ceiling is published.", "example": "2000000" }, "checkedAt": { "type": "string", "description": "ISO 8601 timestamp of the check this row is based on.", "example": "2026-09-18T18:05:00.000Z" } }, "required": [ "country", "currency", "method", "direction", "status", "checkedAt" ] }, "CorridorStatusResponseDto": { "type": "object", "properties": { "stale": { "type": "boolean", "description": "True when this answer is older than we would like and has not refreshed on schedule. The rows are still the last thing we actually measured — treat them as indicative and poll again shortly." }, "checkedAt": { "type": "string", "description": "ISO 8601 timestamp of the refresh that produced these rows.", "example": "2026-09-18T18:05:00.000Z" }, "corridors": { "description": "One row per country, currency, method and direction.", "type": "array", "items": { "$ref": "#/components/schemas/CorridorStatusDto" } } }, "required": [ "stale", "checkedAt", "corridors" ] }, "ElementsSessionResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "expiresInSeconds": { "type": "number" } }, "required": [ "id", "expiresInSeconds" ] }, "CreateElementsSessionDto": { "type": "object", "properties": { "publishableKey": { "type": "string", "pattern": "PUBLISHABLE_KEY_RE", "description": "Publishable key (`pk_test_*` / `pk_live_*`) configured on the business profile", "example": "pk_test_01HXYZ" }, "amount": { "type": "number", "minimum": 0.01, "example": 25.5 }, "currency": { "type": "string", "pattern": "/^[a-z]{3}$/i", "example": "usd" } }, "required": [ "publishableKey", "amount", "currency" ] }, "ElementsTokenResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "last4": { "type": "string" }, "brand": { "type": "string" }, "expiresInSeconds": { "type": "number" } }, "required": [ "id", "last4", "brand", "expiresInSeconds" ] }, "TokenizeElementsDto": { "type": "object", "properties": { "sessionId": { "type": "string", "pattern": "/^es_[a-f0-9]{32}$/i", "description": "Session id returned from POST /elements/session", "example": "es_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "number": { "type": "string", "minLength": 12, "maxLength": 19, "pattern": "/^\\d+$/", "example": "4242424242424242" }, "expMonth": { "type": "number", "minimum": 1, "maximum": 12, "example": 12 }, "expYear": { "type": "number", "minimum": 2024, "maximum": 2100, "example": 2030 }, "cvc": { "type": "string", "minLength": 3, "maxLength": 4, "pattern": "/^\\d+$/", "example": "123" } }, "required": [ "sessionId", "number", "expMonth", "expYear", "cvc" ] }, "SuccessResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true }, "meta": { "type": "object", "additionalProperties": true } }, "required": [ "success", "data" ] } } }, "x-tagGroups": [ { "name": "Get started", "tags": [ "Authentication" ] }, { "name": "Accept payments", "tags": [ "Payments", "Payment Links", "Local Rails", "Elements", "Customers" ] }, { "name": "Send money", "tags": [ "Payouts", "Payout Recipients", "Payout Batches", "Payout Schedules" ] }, { "name": "Risk", "tags": [ "Disputes", "Fraud" ] }, { "name": "Treasury", "tags": [ "Treasury — End-Users", "Treasury — KYC", "Treasury — Wallets", "Treasury — Payouts" ] }, { "name": "Webhooks", "tags": [ "Webhooks" ] } ] }