{ "openapi": "3.1.0", "info": { "title": "Merchant API", "version": "1.0.0", "description": "Server access API documentation for Merchant Transfer System." }, "servers": [ { "url": "https://client.api-payments.com" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key from approved Server Access credentials." }, "ClientSecretAuth": { "type": "apiKey", "in": "header", "name": "X-Client-Secret", "description": "Client secret from approved Server Access credentials." }, "TimestampAuth": { "type": "apiKey", "in": "header", "name": "X-Timestamp", "description": "Request timestamp used for anti-replay validation." }, "SignatureAuth": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "HMAC-SHA256 signature of timestamp, method, path, and raw body." } } }, "paths": { "/api/clients/card_number": { "post": { "tags": [ "Client Registration" ], "summary": "Register a client card", "description": "Create a client registration request from an approved server access client.", "operationId": "client_registration_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CLIENT_REGISTER" }, "permission": { "type": "string", "example": "CLIENT_REGISTER" }, "route": { "type": "string", "example": "client_registration" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_name", "email", "card_number", "expiry", "cvv", "currency", "balance" ], "properties": { "client_name": { "type": "string", "example": "Test Client" }, "email": { "type": "string", "example": "client@example.com" }, "card_number": { "type": "string", "example": "4111111111111111" }, "expiry": { "type": "string", "example": "12/30" }, "cvv": { "type": "string", "example": "123" }, "currency": { "type": "string", "example": "USD" }, "balance": { "type": "integer", "example": 1000000 } } }, "example": { "client_name": "Test Client", "email": "client@example.com", "card_number": "4111111111111111", "expiry": "12/30", "cvv": "123", "currency": "USD", "balance": 1000000 } } } } } }, "/api/clients/approval-code/reset": { "post": { "tags": [ "Merchant API" ], "summary": "Request an owned client's approval-code reset email", "description": "Owned-client operations-v1. Requires CLIENT_OPERATIONS_READ plus the action permission for POST. Poll operation status; never create a new request after an uncertain outcome. No bank/card refund proof is implied by an internal debit.", "operationId": "api_clients_approval_code_reset_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over timestamp + '.' + METHOD + '.' + exact PATH_AND_QUERY + '.' + raw body. Query must be signed.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_request" } } } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "idempotency_conflict" } } } } } }, "422": { "description": "invalid_operation_parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_operation_parameters" } } } } } }, "503": { "description": "operation_service_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "operation_service_unavailable" } } } } } }, "202": { "description": "Operation queued; poll /api/clients/operations/status. SMTP acceptance and queue acceptance are not approval or external refund completion." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string", "example": "CL-EXAMPLE" } } }, "example": { "client_id": "CL-EXAMPLE" } } } } } }, "/api/clients/card-number/check": { "post": { "tags": [ "Merchant API" ], "summary": "Check an owned registered card", "description": "Owned-client operations-v1. Requires CLIENT_OPERATIONS_READ plus the action permission for POST. Poll operation status; never create a new request after an uncertain outcome. No bank/card refund proof is implied by an internal debit.", "operationId": "api_clients_card_number_check_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over timestamp + '.' + METHOD + '.' + exact PATH_AND_QUERY + '.' + raw body. Query must be signed.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_request" } } } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "idempotency_conflict" } } } } } }, "422": { "description": "invalid_operation_parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_operation_parameters" } } } } } }, "503": { "description": "operation_service_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "operation_service_unavailable" } } } } } }, "202": { "description": "Operation queued; poll /api/clients/operations/status. SMTP acceptance and queue acceptance are not approval or external refund completion." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string", "example": "CL-EXAMPLE" } } }, "example": { "client_id": "CL-EXAMPLE" } } } } } }, "/api/clients/refunds": { "post": { "tags": [ "Merchant API" ], "summary": "Request gateway-approved internal client refund debit", "description": "Owned-client operations-v1. Requires CLIENT_OPERATIONS_READ plus the action permission for POST. Poll operation status; never create a new request after an uncertain outcome. No bank/card refund proof is implied by an internal debit.", "operationId": "api_clients_refunds_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over timestamp + '.' + METHOD + '.' + exact PATH_AND_QUERY + '.' + raw body. Query must be signed.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_request" } } } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "idempotency_conflict" } } } } } }, "422": { "description": "invalid_operation_parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_operation_parameters" } } } } } }, "503": { "description": "operation_service_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "operation_service_unavailable" } } } } } }, "202": { "description": "Operation queued; poll /api/clients/operations/status. SMTP acceptance and queue acceptance are not approval or external refund completion." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "amount", "currency", "reason" ], "properties": { "client_id": { "type": "string", "example": "CL-EXAMPLE" }, "amount": { "type": "string", "example": "5.00" }, "currency": { "type": "string", "example": "USD" }, "reason": { "type": "string", "example": "Client request" } } }, "example": { "client_id": "CL-EXAMPLE", "amount": "5.00", "currency": "USD", "reason": "Client request" } } } } } }, "/api/clients/operations/status": { "get": { "tags": [ "Merchant API" ], "summary": "Read own client-operation status", "description": "Owned-client operations-v1. Requires CLIENT_OPERATIONS_READ plus the action permission for POST. Poll operation status; never create a new request after an uncertain outcome. No bank/card refund proof is implied by an internal debit.", "operationId": "api_clients_operations_status_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over timestamp + '.' + METHOD + '.' + exact PATH_AND_QUERY + '.' + raw body. Query must be signed.", "example": "sha256=0123456789abcdef" }, { "name": "request_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "COP-EXAMPLE" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CLIENT_OPERATIONS_READ" }, "permission": { "type": "string", "example": "CLIENT_OPERATIONS_READ" }, "route": { "type": "string", "example": "client_operations" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_request" } } } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "idempotency_conflict" } } } } } }, "422": { "description": "invalid_operation_parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_operation_parameters" } } } } } }, "503": { "description": "operation_service_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "operation_service_unavailable" } } } } } } } } }, "/api/clients/operations/capabilities": { "get": { "tags": [ "Merchant API" ], "summary": "Read client-operation permissions and required host features", "description": "Owned-client operations-v1. Requires CLIENT_OPERATIONS_READ plus the action permission for POST. Poll operation status; never create a new request after an uncertain outcome. No bank/card refund proof is implied by an internal debit.", "operationId": "api_clients_operations_capabilities_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over timestamp + '.' + METHOD + '.' + exact PATH_AND_QUERY + '.' + raw body. Query must be signed.", "example": "sha256=0123456789abcdef" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CLIENT_OPERATIONS_READ" }, "permission": { "type": "string", "example": "CLIENT_OPERATIONS_READ" }, "route": { "type": "string", "example": "client_operations" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } }, "400": { "description": "invalid_request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_request" } } } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "idempotency_conflict" } } } } } }, "422": { "description": "invalid_operation_parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_operation_parameters" } } } } } }, "503": { "description": "operation_service_unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "operation_service_unavailable" } } } } } } } } }, "/api/transfers/swift": { "post": { "tags": [ "Transfers" ], "summary": "Submit a SWIFT transfer", "description": "Submit a SWIFT transfer request for processing and gateway confirmation. For merchant-wallet funding, client_id may be MERCHANT and is treated as audit identity, not a card payer.", "operationId": "swift_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "TRANSFER_SUBMIT" }, "permission": { "type": "string", "example": "TRANSFER_SUBMIT" }, "route": { "type": "string", "example": "swift" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "beneficiary_name", "beneficiary_bank", "swift_bic", "account_number", "currency", "source_currency", "amount", "quote_id", "funding_source", "funding_reference", "purpose" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "beneficiary_name": { "type": "string", "example": "SWIFT Test Beneficiary" }, "beneficiary_bank": { "type": "string", "example": "JPMorgan Chase Bank N.A." }, "swift_bic": { "type": "string", "example": "CHASUS33XXX" }, "account_number": { "type": "string", "example": "9876543210" }, "currency": { "type": "string", "example": "USD" }, "source_currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 1000 }, "quote_id": { "type": "string", "example": "" }, "funding_source": { "type": "string", "example": "" }, "funding_reference": { "type": "string", "example": "" }, "purpose": { "type": "string", "example": "Invoice payment" } } }, "example": { "client_id": "CL-20260628-ABC123", "beneficiary_name": "SWIFT Test Beneficiary", "beneficiary_bank": "JPMorgan Chase Bank N.A.", "swift_bic": "CHASUS33XXX", "account_number": "9876543210", "currency": "USD", "source_currency": "USD", "amount": 1000, "quote_id": "", "funding_source": "", "funding_reference": "", "purpose": "Invoice payment" } } } } } }, "/api/transfers/wire": { "post": { "tags": [ "Transfers" ], "summary": "Submit a WIRE transfer", "description": "Submit a WIRE transfer request for processing and gateway confirmation. For merchant-wallet funding, client_id may be MERCHANT and is treated as audit identity, not a card payer.", "operationId": "wire_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "TRANSFER_SUBMIT" }, "permission": { "type": "string", "example": "TRANSFER_SUBMIT" }, "route": { "type": "string", "example": "wire" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "beneficiary_name", "beneficiary_bank", "routing_number", "account_number", "currency", "source_currency", "amount", "quote_id", "funding_source", "funding_reference", "purpose" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "beneficiary_name": { "type": "string", "example": "WIRE Test Beneficiary" }, "beneficiary_bank": { "type": "string", "example": "Bank of America, N.A." }, "routing_number": { "type": "string", "example": "026009593" }, "account_number": { "type": "string", "example": "9876543210" }, "currency": { "type": "string", "example": "USD" }, "source_currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 1000 }, "quote_id": { "type": "string", "example": "" }, "funding_source": { "type": "string", "example": "" }, "funding_reference": { "type": "string", "example": "" }, "purpose": { "type": "string", "example": "Business payment" } } }, "example": { "client_id": "CL-20260628-ABC123", "beneficiary_name": "WIRE Test Beneficiary", "beneficiary_bank": "Bank of America, N.A.", "routing_number": "026009593", "account_number": "9876543210", "currency": "USD", "source_currency": "USD", "amount": 1000, "quote_id": "", "funding_source": "", "funding_reference": "", "purpose": "Business payment" } } } } } }, "/api/transfers/rtgs": { "post": { "tags": [ "Transfers" ], "summary": "Submit an RTGS transfer", "description": "Submit an RTGS transfer request for processing and gateway confirmation. For merchant-wallet funding, client_id may be MERCHANT and is treated as audit identity, not a card payer.", "operationId": "rtgs_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "TRANSFER_SUBMIT" }, "permission": { "type": "string", "example": "TRANSFER_SUBMIT" }, "route": { "type": "string", "example": "rtgs" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "beneficiary_name", "beneficiary_bank", "account_number", "currency", "source_currency", "amount", "quote_id", "funding_source", "funding_reference", "purpose" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "beneficiary_name": { "type": "string", "example": "RTGS Test Beneficiary" }, "beneficiary_bank": { "type": "string", "example": "Bank Central Asia" }, "account_number": { "type": "string", "example": "1234567890" }, "currency": { "type": "string", "example": "IDR" }, "source_currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 15000000 }, "quote_id": { "type": "string", "example": "FXQ-20260802-ABC123" }, "funding_source": { "type": "string", "example": "merchant_wallet" }, "funding_reference": { "type": "string", "example": "WT-9E62A32DEA7F73FE" }, "purpose": { "type": "string", "example": "RTGS payment" } } }, "example": { "client_id": "CL-20260628-ABC123", "beneficiary_name": "RTGS Test Beneficiary", "beneficiary_bank": "Bank Central Asia", "account_number": "1234567890", "currency": "IDR", "source_currency": "USD", "amount": 15000000, "quote_id": "FXQ-20260802-ABC123", "funding_source": "merchant_wallet", "funding_reference": "WT-9E62A32DEA7F73FE", "purpose": "RTGS payment" } } } } } }, "/api/transfers/crypto": { "post": { "tags": [ "Transfers" ], "summary": "Submit a crypto transfer", "description": "Submit a crypto transfer request for processing and gateway confirmation. For merchant-wallet funding, client_id may be MERCHANT and is treated as audit identity, not a card payer.", "operationId": "crypto_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "TRANSFER_SUBMIT" }, "permission": { "type": "string", "example": "TRANSFER_SUBMIT" }, "route": { "type": "string", "example": "crypto" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "network", "wallet_address", "asset", "currency", "source_currency", "amount", "quote_id", "funding_source", "funding_reference", "purpose" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "network": { "type": "string", "example": "ETH" }, "wallet_address": { "type": "string", "example": "0x0000000000000000000000000000000000000000" }, "asset": { "type": "string", "example": "USDT" }, "currency": { "type": "string", "example": "USDT" }, "source_currency": { "type": "string", "example": "USD" }, "amount": { "type": "integer", "example": 1000 }, "quote_id": { "type": "string", "example": "FXQ-20260802-ABC123" }, "funding_source": { "type": "string", "example": "merchant_wallet" }, "funding_reference": { "type": "string", "example": "WT-9E62A32DEA7F73FE" }, "purpose": { "type": "string", "example": "Crypto payout" } } }, "example": { "client_id": "CL-20260628-ABC123", "network": "ETH", "wallet_address": "0x0000000000000000000000000000000000000000", "asset": "USDT", "currency": "USDT", "source_currency": "USD", "amount": 1000, "quote_id": "FXQ-20260802-ABC123", "funding_source": "merchant_wallet", "funding_reference": "WT-9E62A32DEA7F73FE", "purpose": "Crypto payout" } } } } } }, "/api/transfers/status": { "get": { "tags": [ "Transfers" ], "summary": "Read transfer status", "description": "Read current transfer status by reference.", "operationId": "transfer_status_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TRN-20260628-ABC123" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "TRANSFER_STATUS" }, "permission": { "type": "string", "example": "TRANSFER_STATUS" }, "route": { "type": "string", "example": "transfer_status" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/transfers/documents": { "get": { "tags": [ "Confirmations" ], "summary": "Read confirmation document", "description": "Read confirmation metadata and printable document links.", "operationId": "confirmation_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TRN-20260628-ABC123" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CONFIRMATION_READ" }, "permission": { "type": "string", "example": "CONFIRMATION_READ" }, "route": { "type": "string", "example": "confirmation" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/transfers/documents/download": { "get": { "tags": [ "Confirmations" ], "summary": "Read confirmation document", "description": "Read confirmation metadata and printable document links.", "operationId": "confirmation_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TRN-20260628-ABC123" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CONFIRMATION_READ" }, "permission": { "type": "string", "example": "CONFIRMATION_READ" }, "route": { "type": "string", "example": "confirmation" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/transfers/documents/ack": { "get": { "tags": [ "Confirmations" ], "summary": "Read confirmation document", "description": "Read confirmation metadata and printable document links.", "operationId": "confirmation_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TRN-20260628-ABC123" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CONFIRMATION_READ" }, "permission": { "type": "string", "example": "CONFIRMATION_READ" }, "route": { "type": "string", "example": "confirmation" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/confirmations/read": { "get": { "tags": [ "Confirmations" ], "summary": "Read confirmation document", "description": "Read confirmation metadata and printable document links.", "operationId": "confirmation_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" }, "example": "TRN-20260628-ABC123" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "CONFIRMATION_READ" }, "permission": { "type": "string", "example": "CONFIRMATION_READ" }, "route": { "type": "string", "example": "confirmation" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/statement": { "get": { "tags": [ "Statements" ], "summary": "Read statement data", "description": "Read statement records for an approved server access client.", "operationId": "statement_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2026-06-01" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2026-06-28" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "STATEMENT_READ" }, "permission": { "type": "string", "example": "STATEMENT_READ" }, "route": { "type": "string", "example": "statement" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/statements/read": { "get": { "tags": [ "Statements" ], "summary": "Read statement data", "description": "Read statement records for an approved server access client.", "operationId": "statement_get", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2026-06-01" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2026-06-28" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "STATEMENT_READ" }, "permission": { "type": "string", "example": "STATEMENT_READ" }, "route": { "type": "string", "example": "statement" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } } } }, "/api/settlement": { "post": { "tags": [ "Settlements" ], "summary": "Request or read settlement data", "description": "POST /api/settlements/approval creates an approval settlement client server request and submits it to the gateway for approve, decline, or not answered results. POST /api/settlement reads existing settlement data and does not create a settlement.", "operationId": "settlement_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "SETTLEMENT_READ" }, "permission": { "type": "string", "example": "SETTLEMENT_READ" }, "route": { "type": "string", "example": "settlement" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "from_date", "to_date", "amount", "currency", "report_format" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "from_date": { "type": "string", "example": "2026-09-10" }, "to_date": { "type": "string", "example": "2026-09-10" }, "amount": { "type": "string", "example": "10.00" }, "currency": { "type": "string", "example": "USD" }, "report_format": { "type": "string", "example": "CAMT.053" } } }, "example": { "client_id": "CL-20260628-ABC123", "from_date": "2026-09-10", "to_date": "2026-09-10", "amount": "10.00", "currency": "USD", "report_format": "CAMT.053" } } } } } }, "/api/settlements/approval": { "post": { "tags": [ "Settlements" ], "summary": "Request or read settlement data", "description": "POST /api/settlements/approval creates an approval settlement client server request and submits it to the gateway for approve, decline, or not answered results. POST /api/settlement reads existing settlement data and does not create a settlement.", "operationId": "settlement_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "SETTLEMENT_READ" }, "permission": { "type": "string", "example": "SETTLEMENT_READ" }, "route": { "type": "string", "example": "settlement" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "from_date", "to_date", "amount", "currency", "report_format" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "from_date": { "type": "string", "example": "2026-09-10" }, "to_date": { "type": "string", "example": "2026-09-10" }, "amount": { "type": "string", "example": "10.00" }, "currency": { "type": "string", "example": "USD" }, "report_format": { "type": "string", "example": "CAMT.053" } } }, "example": { "client_id": "CL-20260628-ABC123", "from_date": "2026-09-10", "to_date": "2026-09-10", "amount": "10.00", "currency": "USD", "report_format": "CAMT.053" } } } } } }, "/api/settlements/read": { "post": { "tags": [ "Settlements" ], "summary": "Request or read settlement data", "description": "POST /api/settlements/approval creates an approval settlement client server request and submits it to the gateway for approve, decline, or not answered results. POST /api/settlement reads existing settlement data and does not create a settlement.", "operationId": "settlement_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "SETTLEMENT_READ" }, "permission": { "type": "string", "example": "SETTLEMENT_READ" }, "route": { "type": "string", "example": "settlement" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "from_date", "to_date", "amount", "currency", "report_format" ], "properties": { "client_id": { "type": "string", "example": "CL-20260628-ABC123" }, "from_date": { "type": "string", "example": "2026-09-10" }, "to_date": { "type": "string", "example": "2026-09-10" }, "amount": { "type": "string", "example": "10.00" }, "currency": { "type": "string", "example": "USD" }, "report_format": { "type": "string", "example": "CAMT.053" } } }, "example": { "client_id": "CL-20260628-ABC123", "from_date": "2026-09-10", "to_date": "2026-09-10", "amount": "10.00", "currency": "USD", "report_format": "CAMT.053" } } } } } }, "/api/fx/quotes": { "post": { "tags": [ "FX Quotes" ], "summary": "Create a locked FX quotation", "description": "Lock an exchange rate, fees, source debit, destination amount, and expiry before a cross-currency transfer. Provide exactly one of source_amount or destination_amount; use destination_amount when the operator enters the payout amount. For merchant-wallet funding, client_id may be MERCHANT and funding_source must be merchant_wallet.", "operationId": "fx_quote_post", "security": [ { "ApiKeyAuth": [], "ClientSecretAuth": [], "TimestampAuth": [], "SignatureAuth": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix epoch seconds or ISO-8601 timestamp. Must be inside the configured replay window.", "example": "2026-07-15T12:00:00Z" }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC-SHA256 over: X-Timestamp + '.' + METHOD + '.' + PATH_AND_QUERY + '.' + raw request body. During migration, Server A also accepts the previous PATH-only signature.", "example": "sha256=0123456789abcdef" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 160 }, "description": "Stable retry key for POST submissions. Reusing the same key returns the original review record.", "example": "retry-20260715-001" } ], "responses": { "200": { "description": "Authorized API response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "status": { "type": "string", "example": "AUTHORIZED" }, "endpoint": { "type": "string", "example": "FX_QUOTE" }, "permission": { "type": "string", "example": "FX_QUOTE" }, "route": { "type": "string", "example": "fx_quote" }, "client_id": { "type": "string", "example": "SRV-20260628-ABC123" }, "message": { "type": "string", "example": "API access authorized. Route-specific processing can continue." } } } } } }, "401": { "description": "Invalid or missing server access credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "invalid_secret" } } } } } }, "403": { "description": "Server access blocked for this host, endpoint, or route", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "route_not_allowed_for_host" } } } } } }, "404": { "description": "Unknown API endpoint", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "endpoint_not_allowed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "route", "funding_source", "source_currency", "destination_currency", "destination_amount" ], "properties": { "client_id": { "type": "string", "example": "MERCHANT" }, "route": { "type": "string", "example": "rtgs" }, "funding_source": { "type": "string", "example": "merchant_wallet" }, "source_currency": { "type": "string", "example": "USD" }, "destination_currency": { "type": "string", "example": "IDR" }, "destination_amount": { "type": "string", "example": "1000000.00" } } }, "example": { "client_id": "MERCHANT", "route": "rtgs", "funding_source": "merchant_wallet", "source_currency": "USD", "destination_currency": "IDR", "destination_amount": "1000000.00" } } } } } } }, "tags": [ { "name": "Client Registration" }, { "name": "Transfers" }, { "name": "Confirmations" }, { "name": "Statements" } ] }