{ "openapi": "3.1.0", "info": { "title": "Quidkey API", "version": "1.0.0", "description": "API documentation for Quidkey Core Services" }, "servers": [ { "url": "https://core.quidkey.com", "description": "Production" } ], "components": { "schemas": { "shared_BaseResponse": { "title": "Response Base", "description": "Base schema for API responses", "additionalProperties": true, "type": "object", "required": [ "success" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" } } }, "shared_Error400": { "title": "Bad Request Error", "description": "400 Bad Request Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for the specific error type", "examples": [ "VALIDATION_ERROR" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" }, "metadata": { "additionalProperties": true, "description": "Additional error context. For VALIDATION_ERROR, includes a per-field `errors` array.", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "shared_Error401": { "title": "Unauthorized Error", "description": "401 Unauthorized Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "const": "UNAUTHORIZED", "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error403": { "title": "Forbidden Error", "description": "403 Forbidden Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for forbidden access", "examples": [ "FORBIDDEN_CREATE", "FORBIDDEN_VIEW" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error404": { "title": "Not Found Error", "description": "404 Not Found Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for resource not found", "examples": [ "MERCHANT_NOT_FOUND", "BANK_NOT_FOUND" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error409": { "title": "Conflict Error", "description": "409 Conflict Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for conflict errors", "examples": [ "BATCH_ALREADY_PROCESSING", "BATCH_ALREADY_COMPLETED" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error410": { "title": "Gone Error", "description": "410 Gone Error Response — resource has expired or been revoked", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for gone/expired resources", "examples": [ "PAYMENT_LINK_EXPIRED", "PAYMENT_LINK_NOT_ACTIVE", "INVITATION_GONE" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error422": { "title": "Unprocessable Entity Error", "description": "422 Unprocessable Entity Error Response — request is valid but cannot be processed due to missing prerequisites", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for unprocessable entity errors", "examples": [ "MISSING_CONVERTED_AMOUNT" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error502": { "title": "Bad Gateway Error", "description": "502 Bad Gateway Error Response — upstream service returned an error", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for upstream service errors", "examples": [ "TM_API_ERROR" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Error500": { "title": "Internal Server Error", "description": "500 Internal Server Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "description": "Error code for server errors", "examples": [ "MISSING_DEFAULT_CURRENCY", "INTERNAL_SERVER_ERROR" ], "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, "shared_Address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "auth_TokenRequest": { "type": "object", "discriminator": { "propertyName": "grant_type" }, "title": "Token Grant Request", "description": "Request token with given grant type - client_credentials, magic_code, google_id_token, or refresh_token", "oneOf": [ { "additionalProperties": false, "type": "object", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "const": "client_credentials", "type": "string" }, "client_id": { "format": "uuid", "description": "The client ID of the partner or merchant", "examples": [ "547544c3-eeac-492e-8df9-5a52ca4e6bdf" ], "type": "string" }, "client_secret": { "description": "The client secret of the partner or merchant", "examples": [ "b717adcac3f26e8034574021fa647cd7d4edd67b615046df387f6712c3601048" ], "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "grant_type", "email" ], "properties": { "grant_type": { "const": "magic_code", "type": "string" }, "email": { "format": "email", "description": "Admin email address", "examples": [ "admin@example.com" ], "type": "string" }, "code": { "minLength": 6, "maxLength": 6, "description": "The 6-character verification code sent to email", "examples": [ "abc123" ], "type": "string" }, "ctx": { "pattern": "^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$", "description": "Optional context: \"global\", \"partner:uuid\", or \"merchant:uuid\"", "examples": [ "partner:550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "grant_type", "id_token" ], "properties": { "grant_type": { "const": "google_id_token", "type": "string" }, "id_token": { "description": "Google ID token obtained from Google Sign-In", "examples": [ "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." ], "type": "string" }, "ctx": { "pattern": "^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$", "description": "Optional context: \"global\", \"partner:uuid\", or \"merchant:uuid\"", "examples": [ "partner:550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } } }, { "additionalProperties": false, "type": "object", "required": [ "grant_type", "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token", "type": "string" }, "refresh_token": { "description": "The refresh token obtained from a previous token request", "examples": [ "eyJhbGciOiJIUzI1NiIs..." ], "type": "string" }, "ctx": { "pattern": "^(global|(partner|merchant):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$", "description": "Optional context to switch to: \"global\", \"partner:uuid\", or \"merchant:uuid\".", "examples": [ "partner:550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } } } ] }, "auth_TokenData": { "additionalProperties": false, "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "description": "The access token to be used for authenticated requests", "examples": [ "example_access_token_xyz789" ], "type": "string" }, "refresh_token": { "description": "The refresh token used to obtain a new access token. Returned only when a token is first issued (client_credentials, magic_code, google_id_token grants); the refresh grant does not return a new refresh token, so the original is reused until it expires.", "examples": [ "example_refresh_token_abc123" ], "type": "string" }, "token_type": { "description": "The type of token issued", "examples": [ "Bearer" ], "const": "Bearer", "type": "string" }, "expires_in": { "description": "The number of seconds until the access token expires", "examples": [ 900 ], "type": "number" } } }, "auth_TokenResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "description": "The access token to be used for authenticated requests", "examples": [ "example_access_token_xyz789" ], "type": "string" }, "refresh_token": { "description": "The refresh token used to obtain a new access token. Returned only when a token is first issued (client_credentials, magic_code, google_id_token grants); the refresh grant does not return a new refresh token, so the original is reused until it expires.", "examples": [ "example_refresh_token_abc123" ], "type": "string" }, "token_type": { "description": "The type of token issued", "examples": [ "Bearer" ], "const": "Bearer", "type": "string" }, "expires_in": { "description": "The number of seconds until the access token expires", "examples": [ 900 ], "type": "number" } } } } }, "auth_Challenge": { "additionalProperties": false, "type": "object", "required": [ "id", "type", "expires_at" ], "properties": { "id": { "description": "Identifier for the challenge (typically the email address)", "examples": [ "admin@example.com" ], "type": "string" }, "type": { "description": "The type of challenge issued", "examples": [ "email_code" ], "const": "email_code", "type": "string" }, "expires_at": { "format": "date-time", "description": "ISO 8601 timestamp when the challenge expires", "examples": [ "2025-12-15T15:30:00.000Z" ], "type": "string" } } }, "auth_ChallengeResponse": { "additionalProperties": false, "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for challenge responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message", "challenge" ], "properties": { "code": { "description": "Error code indicating a challenge must be completed", "examples": [ "CHALLENGE_REQUIRED" ], "const": "CHALLENGE_REQUIRED", "type": "string" }, "message": { "description": "Human-readable message", "examples": [ "Verification code sent to email" ], "type": "string" }, "challenge": { "additionalProperties": false, "type": "object", "required": [ "id", "type", "expires_at" ], "properties": { "id": { "description": "Identifier for the challenge (typically the email address)", "examples": [ "admin@example.com" ], "type": "string" }, "type": { "description": "The type of challenge issued", "examples": [ "email_code" ], "const": "email_code", "type": "string" }, "expires_at": { "format": "date-time", "description": "ISO 8601 timestamp when the challenge expires", "examples": [ "2025-12-15T15:30:00.000Z" ], "type": "string" } } } } } } }, "auth_Error401OrChallenge": { "oneOf": [ { "title": "Unauthorized Error", "description": "401 Unauthorized Error Response", "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for error responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "allOf": [ { "description": "Error code for the specific error type", "examples": [ "INVALID_INPUT" ], "type": "string" }, { "const": "UNAUTHORIZED", "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid input provided" ], "type": "string" } } } } }, { "additionalProperties": false, "type": "object", "required": [ "success", "error" ], "properties": { "success": { "description": "Always false for challenge responses", "examples": [ false ], "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message", "challenge" ], "properties": { "code": { "description": "Error code indicating a challenge must be completed", "examples": [ "CHALLENGE_REQUIRED" ], "const": "CHALLENGE_REQUIRED", "type": "string" }, "message": { "description": "Human-readable message", "examples": [ "Verification code sent to email" ], "type": "string" }, "challenge": { "additionalProperties": false, "type": "object", "required": [ "id", "type", "expires_at" ], "properties": { "id": { "description": "Identifier for the challenge (typically the email address)", "examples": [ "admin@example.com" ], "type": "string" }, "type": { "description": "The type of challenge issued", "examples": [ "email_code" ], "const": "email_code", "type": "string" }, "expires_at": { "format": "date-time", "description": "ISO 8601 timestamp when the challenge expires", "examples": [ "2025-12-15T15:30:00.000Z" ], "type": "string" } } } } } } } ] }, "auth_RefreshTokenRequest": { "additionalProperties": false, "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "description": "The refresh token obtained from a previous token request", "examples": [ "refresh_token_abc123" ], "type": "string" } } }, "auth_HealthcheckRequest": { "additionalProperties": false, "type": "object", "required": [ "token" ], "properties": { "token": { "description": "The token to check", "examples": [ "example_token_xyz123" ], "type": "string" } } }, "auth_HealthcheckData": { "additionalProperties": false, "type": "object", "required": [ "token", "isExpired" ], "properties": { "token": { "description": "The token that was checked", "examples": [ "example_token_xyz123" ], "type": "string" }, "isExpired": { "description": "Whether the token has expired", "examples": [ false ], "type": "boolean" } } }, "auth_HealthcheckResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "token", "isExpired" ], "properties": { "token": { "description": "The token that was checked", "examples": [ "example_token_xyz123" ], "type": "string" }, "isExpired": { "description": "Whether the token has expired", "examples": [ false ], "type": "boolean" } } } } }, "auth_RegisterRequest": { "title": "Register Request", "description": "Registration request body.", "additionalProperties": false, "type": "object", "required": [ "email", "first_name", "last_name" ], "properties": { "email": { "format": "email", "description": "Email address", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "minLength": 1, "maxLength": 100, "description": "User's first name", "examples": [ "John" ], "type": "string" }, "last_name": { "minLength": 1, "maxLength": 100, "description": "User's last name", "examples": [ "Doe" ], "type": "string" } } }, "authMe_Context": { "title": "Auth Me Context", "description": "Current operating context of the token", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "branding": { "title": "Branding Info", "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "authMe_AvailableContext": { "title": "Auth Me Available Context", "description": "A context the user can switch to, with their roles in that scope", "additionalProperties": false, "type": "object", "required": [ "type", "roles" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "roles": { "description": "All roles the user has in this context", "type": "array", "items": { "description": "Role name (without scope prefix)", "examples": [ "admin" ], "type": "string" } } } }, "authMe_Data": { "title": "Auth Me Data", "description": "Current user identity, context, available contexts, and effective permissions", "additionalProperties": false, "type": "object", "required": [ "subject_type", "id", "current_context", "available_contexts", "effective_roles", "permissions" ], "properties": { "subject_type": { "description": "Type of authenticated subject", "examples": [ "user" ], "anyOf": [ { "const": "user", "type": "string" }, { "const": "client", "type": "string" } ] }, "id": { "format": "uuid", "description": "Subject ID (user ID or client entity ID)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "User email address (present for user subjects)", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "current_context": { "description": "Current operating context. Null when the user has no roles.", "anyOf": [ { "title": "Auth Me Context", "description": "Current operating context of the token", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "branding": { "title": "Branding Info", "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, { "type": "null" } ] }, "available_contexts": { "description": "All contexts the user can switch to", "type": "array", "items": { "title": "Auth Me Available Context", "description": "A context the user can switch to, with their roles in that scope", "additionalProperties": false, "type": "object", "required": [ "type", "roles" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "roles": { "description": "All roles the user has in this context", "type": "array", "items": { "description": "Role name (without scope prefix)", "examples": [ "admin" ], "type": "string" } } } } }, "effective_roles": { "description": "Roles active in the current token", "type": "array", "items": { "description": "Full role strings from the current token", "examples": [ "partner:admin:550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } }, "permissions": { "description": "Effective permissions. Contains [\"*\"] for wildcard access (global admin). Console should check: permissions.includes(\"*\") || permissions.includes(required)", "type": "array", "items": { "description": "Effective permission strings for the current context", "examples": [ "merchants:list" ], "type": "string" } } } }, "authMe_Response": { "title": "Auth Me Response", "description": "Response from GET /auth/me with identity, context, and permissions", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Auth Me Data", "description": "Current user identity, context, available contexts, and effective permissions", "additionalProperties": false, "type": "object", "required": [ "subject_type", "id", "current_context", "available_contexts", "effective_roles", "permissions" ], "properties": { "subject_type": { "description": "Type of authenticated subject", "examples": [ "user" ], "anyOf": [ { "const": "user", "type": "string" }, { "const": "client", "type": "string" } ] }, "id": { "format": "uuid", "description": "Subject ID (user ID or client entity ID)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "User email address (present for user subjects)", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "current_context": { "description": "Current operating context. Null when the user has no roles.", "anyOf": [ { "title": "Auth Me Context", "description": "Current operating context of the token", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "branding": { "title": "Branding Info", "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, { "type": "null" } ] }, "available_contexts": { "description": "All contexts the user can switch to", "type": "array", "items": { "title": "Auth Me Available Context", "description": "A context the user can switch to, with their roles in that scope", "additionalProperties": false, "type": "object", "required": [ "type", "roles" ], "properties": { "type": { "description": "Context scope type", "examples": [ "partner" ], "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "id": { "format": "uuid", "description": "Scope entity ID (absent for global context)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "Scope entity display name (absent for global context)", "examples": [ "Acme Corp" ], "type": "string" }, "roles": { "description": "All roles the user has in this context", "type": "array", "items": { "description": "Role name (without scope prefix)", "examples": [ "admin" ], "type": "string" } } } } }, "effective_roles": { "description": "Roles active in the current token", "type": "array", "items": { "description": "Full role strings from the current token", "examples": [ "partner:admin:550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } }, "permissions": { "description": "Effective permissions. Contains [\"*\"] for wildcard access (global admin). Console should check: permissions.includes(\"*\") || permissions.includes(required)", "type": "array", "items": { "description": "Effective permission strings for the current context", "examples": [ "merchants:list" ], "type": "string" } } } } } }, "merchant_Merchant": { "title": "Merchant", "description": "Merchant information", "additionalProperties": false, "type": "object", "required": [ "id", "brand_name", "uri", "category_code", "activation_status", "mode", "multi_account_setting", "refund_retention_rate", "client_id", "has_client_secret" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "brand_name": { "description": "The brand name of the merchant", "examples": [ "Example Brand" ], "type": "string" }, "uri": { "format": "uri", "description": "The URI of the merchant's website", "examples": [ "https://example-merchant.com" ], "type": "string" }, "category_code": { "description": "The merchant category code", "examples": [ "4816" ], "type": "string" }, "activation_status": { "description": "The activation status of the merchant", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] }, "mode": { "description": "The mode of the merchant", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "settlement_currency": { "description": "The merchant's effective billing/settlement currency, derived from their settlement bank account (with a country fallback). Null when it can't be resolved. Populated by GET /merchants/:id only; absent from list responses.", "examples": [ "EUR", "GBP" ], "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "null" } ] }, "multi_account_setting": { "description": "The multi-account setting of the merchant", "examples": [ true, false ], "type": "boolean" }, "refund_retention_rate": { "description": "The proportion of settled funds retained to cover potential refunds. Null means the global default is used.", "anyOf": [ { "description": "The refund retention rate as a decimal (e.g. \"0.0500\" for 5%)", "examples": [ "0.0500" ], "type": "string" }, { "type": "null" } ] }, "client_id": { "description": "The client ID of the merchant", "examples": [ "merchant_123" ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this merchant", "examples": [ true ], "type": "boolean" }, "account_owners": { "description": "The account owners associated with this merchant", "examples": [ [] ], "type": "array", "items": { "title": "Merchant Account Owner", "description": "Information about a merchant account owner", "additionalProperties": false, "type": "object", "required": [ "id", "full_name", "email", "is_primary", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the account owner", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "full_name": { "description": "The full name of the account owner", "examples": [ "John Doe" ], "maxLength": 255, "type": "string" }, "email": { "format": "email", "description": "The email address of the account owner", "examples": [ "john.doe@example.com" ], "maxLength": 255, "type": "string" }, "phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "role": { "description": "The role of the account owner within the organization", "examples": [ "Owner", "Director", "Manager" ], "maxLength": 100, "type": "string" }, "is_primary": { "description": "Whether this account owner is the primary contact", "examples": [ true, false ], "type": "boolean" }, "created_at": { "format": "date-time", "description": "The timestamp when the account owner was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the account owner was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } } }, "merchant_Input": { "title": "Merchant Input", "description": "Merchant creation input", "additionalProperties": false, "type": "object", "required": [ "brand_name", "uri", "category_code" ], "properties": { "partner_id": { "format": "uuid", "description": "Partner ID. Defaults to the logged-in partner if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "brand_name": { "description": "The brand name of the merchant", "examples": [ "Example Brand" ], "type": "string" }, "uri": { "description": "The URI of the merchant's website (protocol optional, will be normalized)", "examples": [ "example-merchant.com", "https://example-merchant.com" ], "type": "string" }, "category_code": { "description": "The merchant category code", "examples": [ "4816" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "account_owner": { "title": "Merchant Account Owner Input", "description": "Input data for creating a merchant account owner", "additionalProperties": false, "type": "object", "required": [ "full_name", "email" ], "properties": { "full_name": { "description": "The full name of the account owner", "examples": [ "John Doe" ], "maxLength": 255, "type": "string" }, "email": { "format": "email", "description": "The email address of the account owner", "examples": [ "john.doe@example.com" ], "maxLength": 255, "type": "string" }, "phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "role": { "description": "The role of the account owner within the organization", "examples": [ "Owner", "Director", "Manager" ], "maxLength": 100, "type": "string" } } } } }, "merchant_Update": { "title": "Merchant Update", "description": "Merchant update input", "additionalProperties": false, "type": "object", "properties": { "brand_name": { "description": "The updated brand name of the merchant", "examples": [ "Updated Example Brand" ], "type": "string" }, "uri": { "description": "The updated URI of the merchant's website (protocol optional, will be normalized)", "examples": [ "updated-example-merchant.com", "https://updated-example-merchant.com" ], "type": "string" }, "category_code": { "description": "The updated merchant category code", "examples": [ "4816" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "merchant_ActivationStatusUpdate": { "title": "Merchant Activation Status Update", "description": "Merchant activation status update input", "additionalProperties": false, "type": "object", "required": [ "activation_status" ], "properties": { "activation_status": { "description": "The new activation status for the merchant", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] } } }, "merchant_ModeUpdate": { "title": "Merchant Mode Update", "description": "Merchant mode update input", "additionalProperties": false, "type": "object", "required": [ "mode" ], "properties": { "mode": { "description": "The new mode for the merchant", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] } } }, "merchant_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant", "description": "Merchant information", "additionalProperties": false, "type": "object", "required": [ "id", "brand_name", "uri", "category_code", "activation_status", "mode", "multi_account_setting", "refund_retention_rate", "client_id", "has_client_secret" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "brand_name": { "description": "The brand name of the merchant", "examples": [ "Example Brand" ], "type": "string" }, "uri": { "format": "uri", "description": "The URI of the merchant's website", "examples": [ "https://example-merchant.com" ], "type": "string" }, "category_code": { "description": "The merchant category code", "examples": [ "4816" ], "type": "string" }, "activation_status": { "description": "The activation status of the merchant", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] }, "mode": { "description": "The mode of the merchant", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "settlement_currency": { "description": "The merchant's effective billing/settlement currency, derived from their settlement bank account (with a country fallback). Null when it can't be resolved. Populated by GET /merchants/:id only; absent from list responses.", "examples": [ "EUR", "GBP" ], "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "null" } ] }, "multi_account_setting": { "description": "The multi-account setting of the merchant", "examples": [ true, false ], "type": "boolean" }, "refund_retention_rate": { "description": "The proportion of settled funds retained to cover potential refunds. Null means the global default is used.", "anyOf": [ { "description": "The refund retention rate as a decimal (e.g. \"0.0500\" for 5%)", "examples": [ "0.0500" ], "type": "string" }, { "type": "null" } ] }, "client_id": { "description": "The client ID of the merchant", "examples": [ "merchant_123" ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this merchant", "examples": [ true ], "type": "boolean" }, "account_owners": { "description": "The account owners associated with this merchant", "examples": [ [] ], "type": "array", "items": { "title": "Merchant Account Owner", "description": "Information about a merchant account owner", "additionalProperties": false, "type": "object", "required": [ "id", "full_name", "email", "is_primary", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the account owner", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "full_name": { "description": "The full name of the account owner", "examples": [ "John Doe" ], "maxLength": 255, "type": "string" }, "email": { "format": "email", "description": "The email address of the account owner", "examples": [ "john.doe@example.com" ], "maxLength": 255, "type": "string" }, "phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "role": { "description": "The role of the account owner within the organization", "examples": [ "Owner", "Director", "Manager" ], "maxLength": 100, "type": "string" }, "is_primary": { "description": "Whether this account owner is the primary contact", "examples": [ true, false ], "type": "boolean" }, "created_at": { "format": "date-time", "description": "The timestamp when the account owner was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the account owner was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } } } } }, "merchant_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Merchant", "description": "Merchant information", "additionalProperties": false, "type": "object", "required": [ "id", "brand_name", "uri", "category_code", "activation_status", "mode", "multi_account_setting", "refund_retention_rate", "client_id", "has_client_secret" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "brand_name": { "description": "The brand name of the merchant", "examples": [ "Example Brand" ], "type": "string" }, "uri": { "format": "uri", "description": "The URI of the merchant's website", "examples": [ "https://example-merchant.com" ], "type": "string" }, "category_code": { "description": "The merchant category code", "examples": [ "4816" ], "type": "string" }, "activation_status": { "description": "The activation status of the merchant", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] }, "mode": { "description": "The mode of the merchant", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "settlement_currency": { "description": "The merchant's effective billing/settlement currency, derived from their settlement bank account (with a country fallback). Null when it can't be resolved. Populated by GET /merchants/:id only; absent from list responses.", "examples": [ "EUR", "GBP" ], "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "null" } ] }, "multi_account_setting": { "description": "The multi-account setting of the merchant", "examples": [ true, false ], "type": "boolean" }, "refund_retention_rate": { "description": "The proportion of settled funds retained to cover potential refunds. Null means the global default is used.", "anyOf": [ { "description": "The refund retention rate as a decimal (e.g. \"0.0500\" for 5%)", "examples": [ "0.0500" ], "type": "string" }, { "type": "null" } ] }, "client_id": { "description": "The client ID of the merchant", "examples": [ "merchant_123" ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this merchant", "examples": [ true ], "type": "boolean" }, "account_owners": { "description": "The account owners associated with this merchant", "examples": [ [] ], "type": "array", "items": { "title": "Merchant Account Owner", "description": "Information about a merchant account owner", "additionalProperties": false, "type": "object", "required": [ "id", "full_name", "email", "is_primary", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the account owner", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "full_name": { "description": "The full name of the account owner", "examples": [ "John Doe" ], "maxLength": 255, "type": "string" }, "email": { "format": "email", "description": "The email address of the account owner", "examples": [ "john.doe@example.com" ], "maxLength": 255, "type": "string" }, "phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "role": { "description": "The role of the account owner within the organization", "examples": [ "Owner", "Director", "Manager" ], "maxLength": 100, "type": "string" }, "is_primary": { "description": "Whether this account owner is the primary contact", "examples": [ true, false ], "type": "boolean" }, "created_at": { "format": "date-time", "description": "The timestamp when the account owner was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the account owner was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } } } } } }, "merchant_GenerateClientSecretResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "client_secret" ], "properties": { "client_secret": { "description": "The newly generated client secret", "examples": [ "secret_123abc" ], "type": "string" } } } } }, "merchant_RevokeClientSecretResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "A message confirming the client secret was revoked", "examples": [ "Client secret successfully revoked" ], "type": "string" } } } } }, "merchantBankAccount_PaymentSchemeInfo": { "title": "Payment Scheme Info", "description": "Payment scheme information for merchant bank account responses", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_active", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "Human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco" ], "type": "string" }, "is_active": { "description": "Whether this account actively receives payments for this scheme", "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme appears as a separate payment option in UI", "type": "boolean" } } }, "merchantBankAccount_Account": { "title": "Merchant Bank Account", "description": "Merchant bank account information", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "account_number": { "description": "The account number or IBAN of the bank account", "examples": [ "11223344" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "archived", "type": "string" } ] }, "account_information_session_id": { "format": "uuid", "description": "The account information session ID that created this bank account when linked via provider flow", "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account (for EU market)", "examples": [ "DE89370400440532013000" ], "type": "string" }, "bic": { "description": "The BIC of the bank account (for EU market)", "examples": [ "MARKDEF1100" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (for UK market)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (for US market)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., for Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (for Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (for Australia)", "examples": [ "062-000" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith", "Acme Corporation Ltd" ], "type": "string" }, "supported_payment_schemes": { "description": "Payment schemes this account supports", "type": "array", "items": { "title": "Payment Scheme Info", "description": "Payment scheme information for merchant bank account responses", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_active", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "Human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco" ], "type": "string" }, "is_active": { "description": "Whether this account actively receives payments for this scheme", "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme appears as a separate payment option in UI", "type": "boolean" } } } }, "roles": { "description": "The purposes this account serves", "examples": [ [ "receiving", "settlement" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "balance": { "description": "Current balance for accounts that support balance reporting (decimal string)", "examples": [ "1234.56" ], "type": "string" } } }, "merchantBankAccount_Input": { "title": "Merchant Bank Account Input", "description": "Merchant bank account creation/update input", "additionalProperties": false, "type": "object", "required": [ "currency", "country" ], "properties": { "account_number": { "description": "The account number or IBAN of the bank account", "examples": [ "11223344" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account (for EU market)", "examples": [ "DE89370400440532013000" ], "type": "string" }, "bic": { "description": "The BIC of the bank account (for EU market)", "examples": [ "MARKDEF1100" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (for UK market)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (for US market)", "examples": [ "123456789" ], "type": "string" }, "bank_id": { "format": "uuid", "description": "The optional unique identifier of the associated bank entity", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., for Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (for Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (for Australia)", "examples": [ "062-000" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith", "Acme Corporation Ltd" ], "type": "string" }, "supported_payment_schemes": { "description": "Optional array of payment schemes with active status. If omitted, no payment schemes will be attached.", "examples": [ [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": true } ], [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": false }, { "type": "MULTIBANCO", "is_active": true } ] ], "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "is_active": { "description": "Whether this account should actively receive payments for this scheme. Defaults to false if not specified.", "type": "boolean" } } } } } }, "merchantBankAccount_CreateInput": { "title": "Merchant Bank Account Create Input", "description": "Merchant bank account creation input (direct-debit authorization evidence required for user-auth callers)", "additionalProperties": false, "type": "object", "required": [ "currency", "country" ], "properties": { "account_number": { "description": "The account number or IBAN of the bank account", "examples": [ "11223344" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account (for EU market)", "examples": [ "DE89370400440532013000" ], "type": "string" }, "bic": { "description": "The BIC of the bank account (for EU market)", "examples": [ "MARKDEF1100" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (for UK market)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (for US market)", "examples": [ "123456789" ], "type": "string" }, "bank_id": { "format": "uuid", "description": "The optional unique identifier of the associated bank entity", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., for Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (for Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (for Australia)", "examples": [ "062-000" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith", "Acme Corporation Ltd" ], "type": "string" }, "supported_payment_schemes": { "description": "Optional array of payment schemes with active status. If omitted, no payment schemes will be attached.", "examples": [ [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": true } ], [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": false }, { "type": "MULTIBANCO", "is_active": true } ] ], "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "is_active": { "description": "Whether this account should actively receive payments for this scheme. Defaults to false if not specified.", "type": "boolean" } } } }, "client_evidence": { "additionalProperties": false, "type": "object", "required": [ "consented_agreements", "checkbox_language" ], "properties": { "checkout_page_version": { "description": "APP_COMMIT_SHA the page was built from", "examples": [ "a1b2c3d" ], "type": "string" }, "timezone": { "description": "Browser IANA timezone", "examples": [ "Europe/Dublin" ], "type": "string" }, "fingerprint": { "description": "FingerprintJS visitor id if available", "type": "string" }, "consented_agreements": { "description": "One entry per required consent kind for the current acceptance", "minItems": 1, "examples": [ [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "kind", "agreement_id" ], "properties": { "kind": { "description": "AgreementKind literal", "type": "string" }, "agreement_id": { "format": "uuid", "type": "string" } } } }, "checkbox_language": { "description": "Rendered text of each checkbox the user ticked", "examples": [ [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "checkbox_id", "rendered_text", "covers_kinds" ], "properties": { "checkbox_id": { "type": "string" }, "rendered_text": { "type": "string" }, "covers_kinds": { "type": "array", "items": { "type": "string" } } } } } } } } }, "merchantBankAccount_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant Bank Account", "description": "Merchant bank account information", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "account_number": { "description": "The account number or IBAN of the bank account", "examples": [ "11223344" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "archived", "type": "string" } ] }, "account_information_session_id": { "format": "uuid", "description": "The account information session ID that created this bank account when linked via provider flow", "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account (for EU market)", "examples": [ "DE89370400440532013000" ], "type": "string" }, "bic": { "description": "The BIC of the bank account (for EU market)", "examples": [ "MARKDEF1100" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (for UK market)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (for US market)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., for Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (for Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (for Australia)", "examples": [ "062-000" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith", "Acme Corporation Ltd" ], "type": "string" }, "supported_payment_schemes": { "description": "Payment schemes this account supports", "type": "array", "items": { "title": "Payment Scheme Info", "description": "Payment scheme information for merchant bank account responses", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_active", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "Human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco" ], "type": "string" }, "is_active": { "description": "Whether this account actively receives payments for this scheme", "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme appears as a separate payment option in UI", "type": "boolean" } } } }, "roles": { "description": "The purposes this account serves", "examples": [ [ "receiving", "settlement" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "balance": { "description": "Current balance for accounts that support balance reporting (decimal string)", "examples": [ "1234.56" ], "type": "string" } } } } }, "merchantBankAccount_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Merchant Bank Account", "description": "Merchant bank account information", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "account_number": { "description": "The account number or IBAN of the bank account", "examples": [ "11223344" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "archived", "type": "string" } ] }, "account_information_session_id": { "format": "uuid", "description": "The account information session ID that created this bank account when linked via provider flow", "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account (for EU market)", "examples": [ "DE89370400440532013000" ], "type": "string" }, "bic": { "description": "The BIC of the bank account (for EU market)", "examples": [ "MARKDEF1100" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (for UK market)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (for US market)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., for Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (for Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (for Australia)", "examples": [ "062-000" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith", "Acme Corporation Ltd" ], "type": "string" }, "supported_payment_schemes": { "description": "Payment schemes this account supports", "type": "array", "items": { "title": "Payment Scheme Info", "description": "Payment scheme information for merchant bank account responses", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_active", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "Human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco" ], "type": "string" }, "is_active": { "description": "Whether this account actively receives payments for this scheme", "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme appears as a separate payment option in UI", "type": "boolean" } } } }, "roles": { "description": "The purposes this account serves", "examples": [ [ "receiving", "settlement" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "balance": { "description": "Current balance for accounts that support balance reporting (decimal string)", "examples": [ "1234.56" ], "type": "string" } } } } } }, "merchantBankAccount_GetActiveInput": { "title": "Get Active Merchant Bank Accounts Input", "description": "Query parameters for fetching active merchant bank accounts", "additionalProperties": false, "type": "object", "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Optional currency code (ISO 4217) to filter active accounts", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "roles": { "description": "Filter by account role(s). Defaults to settlement if not specified.", "examples": [ [ "settlement" ], [ "receiving", "refund" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "include_balance": { "description": "Include balance for accounts that support it (requires additional API calls)", "default": false, "type": "boolean" } } }, "merchantBankAccount_SetBalanceInput": { "title": "Set Balance Input", "description": "Input for setting refund account balance in sandbox mode", "additionalProperties": false, "type": "object", "required": [ "balance" ], "properties": { "balance": { "description": "The balance to set on the refund account (decimal string)", "examples": [ "1000.00" ], "type": "string" } } }, "legalEntity_Entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity", "description": "Legal entity information - either company or individual", "oneOf": [ { "title": "Company Legal Entity", "description": "Company legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity", "description": "Individual legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] }, "legalEntity_Input": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Input", "description": "Legal entity creation input - either company or individual", "oneOf": [ { "title": "Company Legal Entity Input", "description": "Company legal entity creation/update input", "additionalProperties": false, "type": "object", "required": [ "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Input", "description": "Individual legal entity creation/update input", "additionalProperties": false, "type": "object", "required": [ "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] }, "legalEntity_CreateInput": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Create Input", "description": "Legal entity creation input (includes Nacha acknowledgment evidence) - either company or individual", "oneOf": [ { "title": "Company Legal Entity Create Input", "description": "Company legal entity creation input (Nacha acknowledgment evidence required for user-auth callers)", "additionalProperties": false, "type": "object", "required": [ "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] }, "client_evidence": { "additionalProperties": false, "type": "object", "required": [ "consented_agreements", "checkbox_language" ], "properties": { "checkout_page_version": { "description": "APP_COMMIT_SHA the page was built from", "examples": [ "a1b2c3d" ], "type": "string" }, "timezone": { "description": "Browser IANA timezone", "examples": [ "Europe/Dublin" ], "type": "string" }, "fingerprint": { "description": "FingerprintJS visitor id if available", "type": "string" }, "consented_agreements": { "description": "One entry per required consent kind for the current acceptance", "minItems": 1, "examples": [ [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "kind", "agreement_id" ], "properties": { "kind": { "description": "AgreementKind literal", "type": "string" }, "agreement_id": { "format": "uuid", "type": "string" } } } }, "checkbox_language": { "description": "Rendered text of each checkbox the user ticked", "examples": [ [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "checkbox_id", "rendered_text", "covers_kinds" ], "properties": { "checkbox_id": { "type": "string" }, "rendered_text": { "type": "string" }, "covers_kinds": { "type": "array", "items": { "type": "string" } } } } } } } } }, { "title": "Individual Legal Entity Create Input", "description": "Individual legal entity creation input (Nacha acknowledgment evidence required for user-auth callers)", "additionalProperties": false, "type": "object", "required": [ "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "client_evidence": { "additionalProperties": false, "type": "object", "required": [ "consented_agreements", "checkbox_language" ], "properties": { "checkout_page_version": { "description": "APP_COMMIT_SHA the page was built from", "examples": [ "a1b2c3d" ], "type": "string" }, "timezone": { "description": "Browser IANA timezone", "examples": [ "Europe/Dublin" ], "type": "string" }, "fingerprint": { "description": "FingerprintJS visitor id if available", "type": "string" }, "consented_agreements": { "description": "One entry per required consent kind for the current acceptance", "minItems": 1, "examples": [ [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "kind", "agreement_id" ], "properties": { "kind": { "description": "AgreementKind literal", "type": "string" }, "agreement_id": { "format": "uuid", "type": "string" } } } }, "checkbox_language": { "description": "Rendered text of each checkbox the user ticked", "examples": [ [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "checkbox_id", "rendered_text", "covers_kinds" ], "properties": { "checkbox_id": { "type": "string" }, "rendered_text": { "type": "string" }, "covers_kinds": { "type": "array", "items": { "type": "string" } } } } } } } } } ] }, "legalEntity_Update": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Update", "description": "Legal entity update input - either company or individual with partial updates allowed", "oneOf": [ { "title": "Company Legal Entity Update", "description": "Company legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Update", "description": "Individual legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] }, "legalEntity_Patch": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Update", "description": "Legal entity update input - either company or individual with partial updates allowed", "oneOf": [ { "title": "Company Legal Entity Update", "description": "Company legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Update", "description": "Individual legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] }, "legalEntity_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity", "description": "Legal entity information - either company or individual", "oneOf": [ { "title": "Company Legal Entity", "description": "Company legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity", "description": "Individual legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } }, "shareholder_OwnershipDetails": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "shareholder_Shareholder": { "title": "Shareholder", "description": "Shareholder information", "type": "object", "required": [ "id", "ownership_details", "legal_entity" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity", "description": "Legal entity information - either company or individual", "oneOf": [ { "title": "Company Legal Entity", "description": "Company legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity", "description": "Individual legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } }, "shareholder_Input": { "title": "Shareholder Full Input", "description": "Shareholder creation input (full payload)", "additionalProperties": false, "required": [ "ownership_details", "legal_entity" ], "type": "object", "properties": { "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Input", "description": "Legal entity creation input - either company or individual", "oneOf": [ { "title": "Company Legal Entity Input", "description": "Company legal entity creation/update input", "additionalProperties": false, "type": "object", "required": [ "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Input", "description": "Individual legal entity creation/update input", "additionalProperties": false, "type": "object", "required": [ "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } }, "shareholder_Update": { "title": "Shareholder Update", "description": "Shareholder update input with partial updates supported", "type": "object", "properties": { "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Update", "description": "Legal entity update input - either company or individual with partial updates allowed", "oneOf": [ { "title": "Company Legal Entity Update", "description": "Company legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Update", "description": "Individual legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } }, "shareholder_Patch": { "title": "Shareholder Patch", "description": "Partial update for shareholder - all fields optional. Use this for incremental updates like adding ID details for cross-border.", "additionalProperties": false, "type": "object", "properties": { "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity Update", "description": "Legal entity update input - either company or individual with partial updates allowed", "oneOf": [ { "title": "Company Legal Entity Update", "description": "Company legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity Update", "description": "Individual legal entity update input - type required, other fields optional for partial updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } }, "shareholder_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Shareholder", "description": "Shareholder information", "type": "object", "required": [ "id", "ownership_details", "legal_entity" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity", "description": "Legal entity information - either company or individual", "oneOf": [ { "title": "Company Legal Entity", "description": "Company legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity", "description": "Individual legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } } } }, "shareholder_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Shareholder", "description": "Shareholder information", "type": "object", "required": [ "id", "ownership_details", "legal_entity" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "ownership_details": { "title": "Ownership Details", "description": "The ownership details of the shareholder", "additionalProperties": false, "type": "object", "required": [ "ownership_share", "ownership_roles" ], "properties": { "ownership_share": { "minimum": 0, "maximum": 100, "description": "The percentage of ownership share (0% allowed for directors)", "examples": [ 25, 0 ], "type": "number" }, "ownership_roles": { "minItems": 1, "description": "The roles of the shareholder", "examples": [ [ "owner", "director" ] ], "type": "array", "items": { "anyOf": [ { "const": "owner", "type": "string" }, { "const": "director", "type": "string" }, { "const": "executive", "type": "string" }, { "const": "representative", "type": "string" }, { "const": "user", "type": "string" } ] } }, "id_type": { "description": "The type of identification document", "examples": [ "passport" ], "anyOf": [ { "const": "drivers_license", "type": "string" }, { "const": "identification_card", "type": "string" }, { "const": "passport", "type": "string" } ] }, "id_number": { "description": "The identification document number", "examples": [ "AB123456" ], "type": "string" }, "id_issue_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country that issued the identification document (ISO 2-letter code)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "legal_entity": { "type": "object", "discriminator": { "propertyName": "type" }, "title": "Legal Entity", "description": "Legal entity information - either company or individual", "oneOf": [ { "title": "Company Legal Entity", "description": "Company legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "company_name", "company_number", "company_structure", "country_of_incorporation", "registered_office_address", "contact_name", "contact_email", "contact_phone_number" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "company" ], "const": "company", "type": "string" }, "company_name": { "description": "The name of the company", "examples": [ "Example Company" ], "minLength": 2, "maxLength": 30, "type": "string" }, "company_number": { "description": "The registration number of the company", "examples": [ "12345678" ], "minLength": 4, "maxLength": 20, "type": "string" }, "vat_number": { "description": "The VAT number of the company", "examples": [ "GB123456789" ], "minLength": 4, "maxLength": 20, "type": "string" }, "tax_id": { "description": "The tax identifier of the company (e.g. ABN for Australian companies, EIN for US companies). For US companies this mirrors the company number.", "examples": [ "12345678901" ], "minLength": 4, "maxLength": 20, "type": "string" }, "company_structure": { "description": "The legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "country_of_incorporation": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country where the company is incorporated - ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "incorporation_date": { "format": "date", "description": "The date when the company was incorporated", "examples": [ "2024-01-01" ], "type": "string" }, "registered_office_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "company_operating_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "contact_name": { "description": "The name of the primary contact", "examples": [ "Jane Doe" ], "minLength": 2, "maxLength": 30, "type": "string" }, "contact_email": { "format": "email", "description": "The email of the primary contact", "examples": [ "jane.doe@example.com" ], "type": "string" }, "contact_phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "annual_revenue_amount": { "description": "The annual revenue amount", "examples": [ 1000000 ], "type": "number" }, "annual_revenue_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the annual revenue", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "employees_number": { "description": "The number of employees category", "examples": [ "small" ], "anyOf": [ { "const": "small", "type": "string" }, { "const": "medium", "type": "string" }, { "const": "large", "type": "string" }, { "const": "enterprise", "type": "string" } ] } } }, { "title": "Individual Legal Entity", "description": "Individual legal entity information", "type": "object", "required": [ "id", "verification_required", "verification_status", "type", "first_name", "last_name", "email", "phone_number", "dob", "citizenship", "residency_address" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "verification_required": { "description": "Whether verification is required for this legal entity", "examples": [ true ], "type": "boolean" }, "verification_link": { "description": "The link to verify the legal entity", "examples": [ "https://verify.example.com/entity/123" ], "type": "string" }, "verification_status": { "description": "The verification status of the legal entity", "examples": [ "pending_verification" ], "anyOf": [ { "const": "pending_verification", "type": "string" }, { "const": "in_review", "type": "string" }, { "const": "more_information_required", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "type": { "description": "The type of legal entity", "examples": [ "individual" ], "const": "individual", "type": "string" }, "first_name": { "description": "The first name of the individual", "examples": [ "John" ], "minLength": 1, "maxLength": 30, "type": "string" }, "last_name": { "description": "The last name of the individual", "examples": [ "Alison" ], "minLength": 1, "maxLength": 30, "type": "string" }, "email": { "format": "email", "description": "The email of the individual", "examples": [ "john.alison@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number in E.164 format (+447395236209) or country_code;number (44;7395236209)", "examples": [ "+447395236209", "44;7395236209" ], "pattern": "^(\\+[0-9]{7,16}|[0-9]{1,4};[0-9]{6,15})$", "type": "string" }, "dob": { "format": "date", "description": "The date of birth of the individual", "examples": [ "1990-01-01" ], "type": "string" }, "citizenship": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The Country of citizenship of the individual in ISO Format", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "residency_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } } ] } } } } } }, "shareholder_DeleteResponse": { "title": "Shareholder Delete Response", "description": "Response returned when a shareholder is successfully deleted", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the deleted shareholder", "type": "string" }, "deleted": { "description": "Indicates the shareholder was successfully deleted", "const": true, "type": "boolean" } } } } }, "document_Document": { "title": "Document", "description": "Merchant document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] }, "fileName": { "description": "Original file name", "examples": [ "certificate.pdf", "bank_statement_jan2024.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } }, "document_DocumentType": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] }, "document_UploadRequest": { "title": "Document Upload Request", "description": "Multipart form data for document upload", "type": "object", "required": [ "file", "documentType" ], "properties": { "file": { "description": "The document file to upload (PDF, JPG, PNG, DOC, or DOCX)", "contentMediaType": "application/octet-stream", "format": "binary" }, "documentType": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] } } }, "document_UploadResponse": { "title": "Document Upload Response", "description": "Response after successful document upload", "additionalProperties": false, "examples": [ { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } } ], "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Document", "description": "Merchant document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] }, "fileName": { "description": "Original file name", "examples": [ "certificate.pdf", "bank_statement_jan2024.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } }, "document_ListResponse": { "title": "Documents List Response", "description": "List of merchant documents", "additionalProperties": false, "examples": [ { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "certificate_of_incorporation", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "documentType": "business_proof_of_address", "fileName": "utility_bill.pdf", "uploadedAt": "2024-01-16T14:20:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "documentType": "memorandum_and_articles", "fileName": "memorandum.pdf", "uploadedAt": "2024-01-17T09:15:00.000Z" } ] } ], "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "List of documents", "examples": [ [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "documentType": "BUSINESS_PROOF_OF_ADDRESS", "fileName": "utility_bill.pdf", "uploadedAt": "2024-01-16T14:20:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "documentType": "MEMORANDUM_AND_ARTICLES", "fileName": "memorandum.pdf", "uploadedAt": "2024-01-17T09:15:00.000Z" } ] ], "type": "array", "items": { "title": "Document", "description": "Merchant document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] }, "fileName": { "description": "Original file name", "examples": [ "certificate.pdf", "bank_statement_jan2024.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } } }, "document_TypesResponse": { "title": "Document Types Response", "description": "List of document types uploaded for a merchant", "additionalProperties": false, "examples": [ { "success": true, "data": [ "certificate_of_incorporation", "business_proof_of_address", "memorandum_and_articles", "business_bank_statement" ] } ], "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "List of document types", "examples": [ [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_PROOF_OF_ADDRESS", "MEMORANDUM_AND_ARTICLES", "BUSINESS_BANK_STATEMENT" ] ], "type": "array", "items": { "title": "Document Type", "description": "Valid document types for merchant documents", "examples": [ "CERTIFICATE_OF_INCORPORATION", "BUSINESS_BANK_STATEMENT", "PROOF_OF_ADDRESS" ], "anyOf": [ { "const": "ARTICLES_OF_INCORPORATION", "type": "string" }, { "const": "BOARD_RESOLUTION", "type": "string" }, { "const": "BUSINESS_BANK_STATEMENT", "type": "string" }, { "const": "BUSINESS_DOCUMENTS", "type": "string" }, { "const": "BUSINESS_PROOF_OF_ADDRESS", "type": "string" }, { "const": "BUSINESS_TAX_ID", "type": "string" }, { "const": "CERTIFICATE_OF_INCORPORATION", "type": "string" }, { "const": "CERTIFICATE_OF_REGISTRATION", "type": "string" }, { "const": "CORPORATE_DOCUMENTS_PACK", "type": "string" }, { "const": "MEMORANDUM_AND_ARTICLES", "type": "string" }, { "const": "ORGANIZATION_CHART", "type": "string" }, { "const": "PARTNERSHIP_AGREEMENT", "type": "string" }, { "const": "POWER_OF_ATTORNEY", "type": "string" }, { "const": "PROOF_OF_ADDRESS", "type": "string" }, { "const": "PROOF_OF_TAX_STATUS", "type": "string" }, { "const": "SOURCE_OF_FUNDS", "type": "string" }, { "const": "SOURCE_OF_WEALTH", "type": "string" } ] } } } }, "shareholderDocument_Document": { "title": "Shareholder Document", "description": "Shareholder document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "PROOF_OF_ADDRESS", "fileName": "proof_of_address.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Shareholder Document Type", "description": "Valid document types for shareholder documents", "examples": [ "PROOF_OF_ADDRESS" ], "const": "PROOF_OF_ADDRESS", "type": "string" }, "fileName": { "description": "Original file name", "examples": [ "proof_of_address.pdf", "utility_bill.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } }, "shareholderDocument_DocumentType": { "title": "Shareholder Document Type", "description": "Valid document types for shareholder documents", "examples": [ "PROOF_OF_ADDRESS" ], "const": "PROOF_OF_ADDRESS", "type": "string" }, "shareholderDocument_UploadRequest": { "title": "Shareholder Document Upload Request", "description": "Multipart form data for shareholder document upload", "type": "object", "required": [ "file", "documentType" ], "properties": { "file": { "description": "The document file to upload (PDF, JPG, PNG, DOC, or DOCX)", "contentMediaType": "application/octet-stream", "format": "binary" }, "documentType": { "title": "Shareholder Document Type", "description": "Valid document types for shareholder documents", "examples": [ "PROOF_OF_ADDRESS" ], "const": "PROOF_OF_ADDRESS", "type": "string" } } }, "shareholderDocument_UploadResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Shareholder Document", "description": "Shareholder document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "PROOF_OF_ADDRESS", "fileName": "proof_of_address.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Shareholder Document Type", "description": "Valid document types for shareholder documents", "examples": [ "PROOF_OF_ADDRESS" ], "const": "PROOF_OF_ADDRESS", "type": "string" }, "fileName": { "description": "Original file name", "examples": [ "proof_of_address.pdf", "utility_bill.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } }, "shareholderDocument_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Shareholder Document", "description": "Shareholder document metadata", "examples": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "PROOF_OF_ADDRESS", "fileName": "proof_of_address.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ], "type": "object", "required": [ "id", "documentType", "fileName", "uploadedAt" ], "properties": { "id": { "format": "uuid", "description": "Unique document ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "documentType": { "title": "Shareholder Document Type", "description": "Valid document types for shareholder documents", "examples": [ "PROOF_OF_ADDRESS" ], "const": "PROOF_OF_ADDRESS", "type": "string" }, "fileName": { "description": "Original file name", "examples": [ "proof_of_address.pdf", "utility_bill.pdf" ], "type": "string" }, "uploadedAt": { "format": "date-time", "description": "Upload timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } } }, "customer_Customer": { "title": "Customer", "description": "Customer information", "additionalProperties": false, "anyOf": [ { "required": [ "email" ] }, { "required": [ "phone_number" ] } ], "type": "object", "properties": { "id": { "format": "uuid", "description": "Customer's unique identifier", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "Customer's full name", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Customer's email address", "examples": [ "john.doe@example.com" ], "type": "string" }, "phone_number": { "description": "Customer's phone number in E.164 format", "examples": [ "+491234567890" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Timestamp when the customer was created", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Timestamp when the customer was last updated", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } }, "customer_Input": { "title": "Customer Input", "description": "Customer creation/update input", "additionalProperties": false, "type": "object", "required": [ "name", "email", "phone_number" ], "properties": { "name": { "description": "Customer's full name", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Customer's email address", "examples": [ "john.doe@example.com" ], "type": "string" }, "phone_number": { "description": "Customer's phone number in E.164 format", "examples": [ "+491234567890" ], "type": "string" } } }, "customer_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Customer", "description": "Customer information", "additionalProperties": false, "anyOf": [ { "required": [ "email" ] }, { "required": [ "phone_number" ] } ], "type": "object", "properties": { "id": { "format": "uuid", "description": "Customer's unique identifier", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "Customer's full name", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Customer's email address", "examples": [ "john.doe@example.com" ], "type": "string" }, "phone_number": { "description": "Customer's phone number in E.164 format", "examples": [ "+491234567890" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Timestamp when the customer was created", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Timestamp when the customer was last updated", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } }, "customer_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Customer", "description": "Customer information", "additionalProperties": false, "anyOf": [ { "required": [ "email" ] }, { "required": [ "phone_number" ] } ], "type": "object", "properties": { "id": { "format": "uuid", "description": "Customer's unique identifier", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "Customer's full name", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Customer's email address", "examples": [ "john.doe@example.com" ], "type": "string" }, "phone_number": { "description": "Customer's phone number in E.164 format", "examples": [ "+491234567890" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Timestamp when the customer was created", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Timestamp when the customer was last updated", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } }, "bank_Bank": { "title": "Bank", "description": "A financial institution", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency supported by the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "description": "Displayable logo URL. Prefers the bank's native logo; falls back to a logos.dev URL derived from websiteUrl. Empty string when neither is available.", "examples": [ "https://example.com/logo.png", "https://img.logo.dev/chase.com?token=..." ], "type": "string" }, "websiteUrl": { "description": "The bank's website URL (the logos.dev fallback source for logoUrl).", "examples": [ "https://www.santander.co.uk" ], "type": "string" }, "topInMarket": { "description": "Indicates if the bank is top in the market", "examples": [ true ], "type": "boolean" } } }, "bank_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Bank", "description": "A financial institution", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency supported by the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "description": "Displayable logo URL. Prefers the bank's native logo; falls back to a logos.dev URL derived from websiteUrl. Empty string when neither is available.", "examples": [ "https://example.com/logo.png", "https://img.logo.dev/chase.com?token=..." ], "type": "string" }, "websiteUrl": { "description": "The bank's website URL (the logos.dev fallback source for logoUrl).", "examples": [ "https://www.santander.co.uk" ], "type": "string" }, "topInMarket": { "description": "Indicates if the bank is top in the market", "examples": [ true ], "type": "boolean" } } } } }, "bank_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Bank", "description": "A financial institution", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency supported by the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "description": "Displayable logo URL. Prefers the bank's native logo; falls back to a logos.dev URL derived from websiteUrl. Empty string when neither is available.", "examples": [ "https://example.com/logo.png", "https://img.logo.dev/chase.com?token=..." ], "type": "string" }, "websiteUrl": { "description": "The bank's website URL (the logos.dev fallback source for logoUrl).", "examples": [ "https://www.santander.co.uk" ], "type": "string" }, "topInMarket": { "description": "Indicates if the bank is top in the market", "examples": [ true ], "type": "boolean" } } } } } }, "bank_TopBanksResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "banks" ], "properties": { "banks": { "type": "array", "items": { "title": "Bank", "description": "A financial institution", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency supported by the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "description": "Displayable logo URL. Prefers the bank's native logo; falls back to a logos.dev URL derived from websiteUrl. Empty string when neither is available.", "examples": [ "https://example.com/logo.png", "https://img.logo.dev/chase.com?token=..." ], "type": "string" }, "websiteUrl": { "description": "The bank's website URL (the logos.dev fallback source for logoUrl).", "examples": [ "https://www.santander.co.uk" ], "type": "string" }, "topInMarket": { "description": "Indicates if the bank is top in the market", "examples": [ true ], "type": "boolean" } } } } } } } }, "bankActivation_Input": { "title": "Bank Activation Input", "description": "Input for updating bank activation status", "additionalProperties": false, "type": "object", "required": [ "isActive" ], "properties": { "isActive": { "description": "Whether the bank should be active (true) or inactive (false)", "examples": [ true ], "type": "boolean" } } }, "bankActivation_Result": { "title": "Bank Activation Result", "description": "Result of bank activation/deactivation operation", "additionalProperties": false, "type": "object", "required": [ "bank", "message" ], "properties": { "bank": { "type": "object", "required": [ "id", "name", "market", "currency", "isActive", "previousStatus" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "isActive": { "description": "Current activation status of the bank", "examples": [ true ], "type": "boolean" }, "previousStatus": { "description": "Previous activation status before this update", "examples": [ false ], "type": "boolean" } } }, "message": { "description": "Success message describing the operation", "examples": [ "Bank activated successfully", "Bank deactivated successfully" ], "type": "string" } } }, "bankActivation_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Bank Activation Result", "description": "Result of bank activation/deactivation operation", "additionalProperties": false, "type": "object", "required": [ "bank", "message" ], "properties": { "bank": { "type": "object", "required": [ "id", "name", "market", "currency", "isActive", "previousStatus" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "isActive": { "description": "Current activation status of the bank", "examples": [ true ], "type": "boolean" }, "previousStatus": { "description": "Previous activation status before this update", "examples": [ false ], "type": "boolean" } } }, "message": { "description": "Success message describing the operation", "examples": [ "Bank activated successfully", "Bank deactivated successfully" ], "type": "string" } } } } }, "bankActivation_StatusDetail": { "title": "Bank Status Detail", "description": "Detailed bank information including activation status", "additionalProperties": false, "type": "object", "required": [ "id", "name", "market", "currency", "displayName", "logoUrl", "topInMarket", "isActive", "tinkProvider", "providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "format": "uri", "description": "The URL of the bank logo", "examples": [ "https://example.com/logo.png" ], "type": "string" }, "topInMarket": { "description": "Whether the bank is top in the market", "examples": [ true ], "type": "boolean" }, "isActive": { "description": "Whether the bank is currently active", "examples": [ true ], "type": "boolean" }, "tinkProvider": { "anyOf": [ { "type": "object", "required": [ "id", "popular" ], "properties": { "id": { "description": "The Tink provider ID", "examples": [ "tink-provider-123" ], "type": "string" }, "popular": { "description": "Whether this is a popular provider", "examples": [ true ], "type": "boolean" } } }, { "type": "null" } ] }, "providers": { "description": "Payment providers configured for this bank", "type": "array", "items": { "type": "object", "required": [ "name", "popular" ], "properties": { "name": { "description": "Provider name", "examples": [ "tink" ], "type": "string" }, "popular": { "description": "Whether bank is popular for this provider", "examples": [ true ], "type": "boolean" } } } }, "created_at": { "format": "date-time", "description": "When the bank was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the bank was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } }, "bankActivation_StatusResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Bank Status Detail", "description": "Detailed bank information including activation status", "additionalProperties": false, "type": "object", "required": [ "id", "name", "market", "currency", "displayName", "logoUrl", "topInMarket", "isActive", "tinkProvider", "providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "format": "uri", "description": "The URL of the bank logo", "examples": [ "https://example.com/logo.png" ], "type": "string" }, "topInMarket": { "description": "Whether the bank is top in the market", "examples": [ true ], "type": "boolean" }, "isActive": { "description": "Whether the bank is currently active", "examples": [ true ], "type": "boolean" }, "tinkProvider": { "anyOf": [ { "type": "object", "required": [ "id", "popular" ], "properties": { "id": { "description": "The Tink provider ID", "examples": [ "tink-provider-123" ], "type": "string" }, "popular": { "description": "Whether this is a popular provider", "examples": [ true ], "type": "boolean" } } }, { "type": "null" } ] }, "providers": { "description": "Payment providers configured for this bank", "type": "array", "items": { "type": "object", "required": [ "name", "popular" ], "properties": { "name": { "description": "Provider name", "examples": [ "tink" ], "type": "string" }, "popular": { "description": "Whether bank is popular for this provider", "examples": [ true ], "type": "boolean" } } } }, "created_at": { "format": "date-time", "description": "When the bank was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the bank was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } }, "bankActivation_Query": { "title": "Admin Banks Query", "description": "Query parameters for filtering banks", "additionalProperties": false, "type": "object", "properties": { "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Filter by market (optional)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "isActive": { "description": "Filter by activation status (optional)", "examples": [ "true" ], "type": "string" } } }, "bankActivation_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Bank Status Detail", "description": "Detailed bank information including activation status", "additionalProperties": false, "type": "object", "required": [ "id", "name", "market", "currency", "displayName", "logoUrl", "topInMarket", "isActive", "tinkProvider", "providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "format": "uri", "description": "The URL of the bank logo", "examples": [ "https://example.com/logo.png" ], "type": "string" }, "topInMarket": { "description": "Whether the bank is top in the market", "examples": [ true ], "type": "boolean" }, "isActive": { "description": "Whether the bank is currently active", "examples": [ true ], "type": "boolean" }, "tinkProvider": { "anyOf": [ { "type": "object", "required": [ "id", "popular" ], "properties": { "id": { "description": "The Tink provider ID", "examples": [ "tink-provider-123" ], "type": "string" }, "popular": { "description": "Whether this is a popular provider", "examples": [ true ], "type": "boolean" } } }, { "type": "null" } ] }, "providers": { "description": "Payment providers configured for this bank", "type": "array", "items": { "type": "object", "required": [ "name", "popular" ], "properties": { "name": { "description": "Provider name", "examples": [ "tink" ], "type": "string" }, "popular": { "description": "Whether bank is popular for this provider", "examples": [ true ], "type": "boolean" } } } }, "created_at": { "format": "date-time", "description": "When the bank was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the bank was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } } }, "bankActivation_Params": { "type": "object", "required": [ "bankId" ], "properties": { "bankId": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } } }, "partner_Partner": { "title": "Partner", "description": "Partner information", "additionalProperties": false, "type": "object", "required": [ "id", "name", "email", "client_id", "has_client_secret", "website", "payment_providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the partner", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the partner", "examples": [ "Barclaycard" ], "type": "string" }, "email": { "format": "email", "description": "The email of the partner", "examples": [ "argo@barclaycard.com" ], "type": "string" }, "client_id": { "description": "The client ID of the partner", "examples": [ "partner_123" ], "type": "string" }, "client_secret": { "description": "The hashed client secret of the partner", "examples": [ "$2b$10$..." ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this partner", "examples": [ true ], "type": "boolean" }, "website": { "description": "The website URL of the partner", "examples": [ "https://transfermate.com" ], "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "payment_providers": { "description": "Per-country payment provider routing overrides", "examples": [ { "GB": "fumopay" } ], "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "The creation date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } }, "partner_Input": { "title": "Partner Input", "description": "Partner creation input", "additionalProperties": false, "type": "object", "required": [ "name", "email" ], "properties": { "name": { "description": "The name of the partner", "examples": [ "Barclaycard" ], "type": "string" }, "email": { "format": "email", "description": "The email of the partner", "examples": [ "argo@barclaycard.com" ], "type": "string" }, "website": { "description": "The website URL of the partner (protocol optional, will be normalized)", "examples": [ "barclaycard.com", "https://barclaycard.com" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "partner_Update": { "title": "Partner Update", "description": "Partner update input", "additionalProperties": false, "type": "object", "properties": { "name": { "description": "The updated name of the partner", "examples": [ "BarclayCard International" ], "type": "string" }, "email": { "format": "email", "description": "The updated email of the partner", "examples": [ "argo.international@barclaycard.com" ], "type": "string" }, "website": { "description": "The updated website URL of the partner (protocol optional, will be normalized)", "examples": [ "barclaycard-international.com", "https://barclaycard-international.com" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_providers": { "description": "Per-country payment provider routing overrides. Keys are ISO 3166-1 alpha-2 country codes, values are provider names. Null to use system defaults.", "examples": [ { "GB": "fumopay" } ], "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, { "type": "null" } ] } } }, "partner_CreateResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "id", "name", "email", "client_id", "client_secret", "website" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the created partner", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the created partner", "examples": [ "Barclaycard" ], "type": "string" }, "email": { "format": "email", "description": "The email of the created partner", "examples": [ "argo@barclaycard.com" ], "type": "string" }, "client_id": { "description": "The client ID of the created partner", "examples": [ "partner_123" ], "type": "string" }, "client_secret": { "description": "The unhashed client secret (only returned once upon creation)", "examples": [ "secret_abc123" ], "type": "string" }, "website": { "description": "The website URL of the partner", "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] } } } } }, "partner_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Partner", "description": "Partner information", "additionalProperties": false, "type": "object", "required": [ "id", "name", "email", "client_id", "has_client_secret", "website", "payment_providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the partner", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the partner", "examples": [ "Barclaycard" ], "type": "string" }, "email": { "format": "email", "description": "The email of the partner", "examples": [ "argo@barclaycard.com" ], "type": "string" }, "client_id": { "description": "The client ID of the partner", "examples": [ "partner_123" ], "type": "string" }, "client_secret": { "description": "The hashed client secret of the partner", "examples": [ "$2b$10$..." ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this partner", "examples": [ true ], "type": "boolean" }, "website": { "description": "The website URL of the partner", "examples": [ "https://transfermate.com" ], "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "payment_providers": { "description": "Per-country payment provider routing overrides", "examples": [ { "GB": "fumopay" } ], "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "The creation date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } }, "partner_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Partner", "description": "Partner information", "additionalProperties": false, "type": "object", "required": [ "id", "name", "email", "client_id", "has_client_secret", "website", "payment_providers", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the partner", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the partner", "examples": [ "Barclaycard" ], "type": "string" }, "email": { "format": "email", "description": "The email of the partner", "examples": [ "argo@barclaycard.com" ], "type": "string" }, "client_id": { "description": "The client ID of the partner", "examples": [ "partner_123" ], "type": "string" }, "client_secret": { "description": "The hashed client secret of the partner", "examples": [ "$2b$10$..." ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this partner", "examples": [ true ], "type": "boolean" }, "website": { "description": "The website URL of the partner", "examples": [ "https://transfermate.com" ], "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "payment_providers": { "description": "Per-country payment provider routing overrides", "examples": [ { "GB": "fumopay" } ], "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "The creation date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the partner", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } }, "commandPalette_ReindexResponse": { "title": "Command Palette Reindex Response", "additionalProperties": false, "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Command Palette Reindex Data", "additionalProperties": false, "type": "object", "required": [ "indexed" ], "properties": { "indexed": { "description": "Map of index name → document count indexed in this run", "type": "object", "patternProperties": { "^(.*)$": { "minimum": 0, "type": "integer" } } } } } } }, "commandPalette_SearchQuery": { "additionalProperties": false, "type": "object", "required": [ "q" ], "properties": { "q": { "minLength": 1, "maxLength": 200, "description": "Search query", "type": "string" }, "type": { "description": "Filter to a single entity type. Unknown values are rejected at validation rather than silently returning [].", "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" }, { "const": "payment-link", "type": "string" }, { "const": "payout", "type": "string" }, { "const": "transaction", "type": "string" }, { "const": "invoice", "type": "string" } ] }, "limit": { "minimum": 1, "maximum": 20, "default": 5, "type": "integer" } } }, "commandPalette_SearchResponse": { "title": "Command Palette Search Response", "additionalProperties": false, "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "type", "id", "title" ], "properties": { "type": { "description": "Entity type, e.g. partner | merchant | payment-link | payout | transaction", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "parent_title": { "description": "Parent-entity label for breadcrumb display (e.g. partner name for a merchant).", "type": "string" }, "context": { "description": "If present, the palette calls switchContext(context) before navigating, e.g. 'merchant:'.", "type": "string" } } } } } }, "paymentInitiation_Input": { "anyOf": [ { "type": "object", "required": [ "bankId" ], "properties": { "bankId": { "format": "uuid", "description": "The selected bank ID for redirect-based payment flows", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "paymentScheme": { "description": "Payment scheme selected by user. null = use default scheme for customer country, explicit value = user choice", "examples": [ null, "SEPA_CREDIT_TRANSFER", "MULTIBANCO" ], "anyOf": [ { "type": "null" }, { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] } ] }, "clientEvidence": { "additionalProperties": false, "type": "object", "properties": { "fingerprint": { "type": "string" }, "timezone": { "type": "string" }, "checkout_page_version": { "type": "string" }, "payment_terms_agreement_id": { "format": "uuid", "description": "The Agreement.id of the ACH Authorization (Payment Terms) that the checkout page showed the customer. Server validates it resolves to a kind=ach_authorization agreement.", "type": "string" }, "payment_page_url": { "type": "string" }, "authorization_language": { "maxLength": 4096, "description": "Exact click-wrap text rendered next to Pay at the moment of acceptance. Stored verbatim on the EvidenceRecord so the stored evidence matches what the customer saw.", "type": "string" } } } } }, { "type": "object", "required": [ "customerBankAccountId" ], "properties": { "customerBankAccountId": { "format": "uuid", "description": "The selected customer bank account ID for direct payment flows", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "paymentScheme": { "description": "Payment scheme selected by user. null = use default scheme for customer country, explicit value = user choice", "examples": [ null, "SEPA_CREDIT_TRANSFER", "MULTIBANCO" ], "anyOf": [ { "type": "null" }, { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] } ] }, "clientEvidence": { "additionalProperties": false, "type": "object", "properties": { "fingerprint": { "type": "string" }, "timezone": { "type": "string" }, "checkout_page_version": { "type": "string" }, "payment_terms_agreement_id": { "format": "uuid", "description": "The Agreement.id of the ACH Authorization (Payment Terms) that the checkout page showed the customer. Server validates it resolves to a kind=ach_authorization agreement.", "type": "string" }, "payment_page_url": { "type": "string" }, "authorization_language": { "maxLength": 4096, "description": "Exact click-wrap text rendered next to Pay at the moment of acceptance. Stored verbatim on the EvidenceRecord so the stored evidence matches what the customer saw.", "type": "string" } } } } } ] }, "paymentInitiation_Data": { "title": "Payment Initiation Data", "description": "Payment initiation response data", "additionalProperties": false, "type": "object", "properties": { "order_id": { "description": "The unique identifier of the order of the payment request", "examples": [ "123" ], "type": "string" } } }, "paymentInitiation_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Payment Initiation Data", "description": "Payment initiation response data", "additionalProperties": false, "type": "object", "properties": { "order_id": { "description": "The unique identifier of the order of the payment request", "examples": [ "123" ], "type": "string" } } } } }, "paymentRequest_CustomerInput": { "title": "Customer Input", "description": "Customer information for payment request", "additionalProperties": true, "type": "object", "required": [ "name", "email" ], "properties": { "name": { "description": "The name of the customer", "examples": [ "John Doe" ], "type": "string" }, "email": { "description": "The email of the customer (either email or phone_number must be provided)", "anyOf": [ { "format": "email", "description": "The email of the customer (either email or phone_number must be provided)", "examples": [ "john.doe@example.com" ], "type": "string" }, { "const": "", "type": "string" }, { "type": "null" } ] }, "phone_number": { "description": "The phone number of the customer (either email or phone_number must be provided)", "examples": [ "07123456789" ], "type": "string" } } }, "paymentRequest_BillingAddressInput": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "paymentRequest_Input": { "title": "Payment Request Input", "description": "Payment request input parameters", "additionalProperties": true, "type": "object", "required": [ "customer", "billingAddress", "amount", "currency", "locale", "platform" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "customer": { "description": "The customer details", "required": [ "name", "email" ], "type": "object", "properties": { "name": { "description": "The name of the customer", "examples": [ "John Doe" ], "type": "string" }, "email": { "description": "The email of the customer (either email or phone_number must be provided)", "anyOf": [ { "format": "email", "description": "The email of the customer (either email or phone_number must be provided)", "examples": [ "john.doe@example.com" ], "type": "string" }, { "const": "", "type": "string" }, { "type": "null" } ] }, "phone_number": { "description": "The phone number of the customer (either email or phone_number must be provided)", "examples": [ "07123456789" ], "type": "string" } } }, "billingAddress": { "description": "The billing address details", "required": [ "address_line1", "city", "country", "postal_code" ], "type": "object", "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "amount": { "description": "Decimal amount in MAJOR units (e.g. 19.99 = £19.99). Sent as a number and converted to minor units server-side. This differs from the redirect and embedded endpoints, which take an integer amount in minor units.", "examples": [ 19.99 ], "type": "number" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the payment request", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_reference": { "description": "Payment reference to appear on the payer’s bank statement (max 18 alphanumeric characters)", "examples": [ "ORDER123" ], "maxLength": 18, "pattern": "^[A-Za-z0-9]{1,18}$", "type": "string" }, "order_id": { "description": "The unique identifier for the merchant's order", "examples": [ "1140" ], "type": "string" }, "locale": { "description": "The locale of the payment request", "examples": [ "en_GB" ], "type": "string" }, "platform": { "description": "The platform used for the payment request", "examples": [ "WooCommerce" ], "type": "string" }, "device_type": { "description": "The type of device used for the payment request", "examples": [ "mobile" ], "type": "string" }, "external_payment_request_id": { "description": "External payment reference", "examples": [ "u0nwmSrNntjIWozmNslK5Tlq" ], "type": "string" }, "test_transaction": { "description": "Flag for test transactions", "examples": [ false ], "type": "boolean" }, "group": { "description": "For grouping related transactions", "examples": [ "rZNvy+1jH6Z+BcPqA5U5BSIcnUavBha3C63xBalm+xE=" ], "type": "string" }, "gid": { "description": "Global identifier", "examples": [ "gid://shopify/PaymentSession/u0nwmSrNntjIWozmNslK5Tlq" ], "type": "string" }, "selected_bank_id": { "description": "Selected bank reference", "examples": [ "38c39d03-8df3-4980-b0a8-7e283c8c62dd" ], "type": "string" }, "session_id": { "description": "Session tracking", "examples": [ "4B2dxmle3vGgimS4deUX3+2PgLF2+/0ZWnNsNSZcgdU=" ], "type": "string" }, "success_url_redirect": { "description": "URL to redirect on successful payment", "examples": [ "https://storename.com/success" ], "type": "string" }, "fail_url_redirect": { "description": "URL to redirect on failed payment", "examples": [ "https://storename.com/failure" ], "type": "string" }, "simulation": { "additionalProperties": false, "description": "Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it.", "type": "object", "properties": { "straddle": { "additionalProperties": false, "type": "object", "properties": { "customer_outcome": { "description": "Simulated identity verification outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "review", "type": "string" } ] }, "paykey_outcome": { "description": "Simulated bank account link outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "active", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "charge_outcome": { "description": "Simulated charge outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "on_hold_daily_limit", "type": "string" }, { "const": "cancelled_for_fraud_risk", "type": "string" }, { "const": "cancelled_for_balance_check", "type": "string" }, { "const": "failed_insufficient_funds", "type": "string" }, { "const": "reversed_insufficient_funds", "type": "string" }, { "const": "failed_customer_dispute", "type": "string" }, { "const": "reversed_customer_dispute", "type": "string" }, { "const": "failed_closed_bank_account", "type": "string" }, { "const": "reversed_closed_bank_account", "type": "string" } ] }, "balance_check": { "description": "Balance verification behaviour", "anyOf": [ { "const": "required", "type": "string" }, { "const": "enabled", "type": "string" }, { "const": "disabled", "type": "string" } ] } } }, "flinks": { "additionalProperties": false, "type": "object", "properties": { "outcome": { "description": "Simulated bank-linking lifecycle and data shape", "anyOf": [ { "const": "happy", "type": "string" }, { "const": "async", "type": "string" }, { "const": "no_us_account", "type": "string" }, { "const": "partial_data", "type": "string" }, { "const": "webhook_only", "type": "string" }, { "const": "rate_limit", "type": "string" }, { "const": "unreachable", "type": "string" } ] }, "account": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "minimum": 1, "description": "Total accounts to return", "type": "number" }, "existing": { "description": "Ids of existing accounts to include; (total - existing.length) new ones are minted", "type": "array", "items": { "type": "string" } } } }, "mfa": { "description": "Whether an MFA challenge is presented and how it is answered", "anyOf": [ { "const": "skip", "type": "string" }, { "const": "correct", "type": "string" }, { "const": "wrong", "type": "string" } ] } } } } } } }, "paymentRequest_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Payment Request Data", "description": "Payment request response data", "additionalProperties": true, "type": "object", "required": [ "payment_link" ], "properties": { "payment_link": { "description": "URL of the hosted payment page to redirect the customer to", "examples": [ "https://example.com/pay/abc123" ], "type": "string" } } } } }, "paymentRequest_Data": { "title": "Payment Request Data", "description": "Payment request response data", "additionalProperties": true, "type": "object", "required": [ "payment_link" ], "properties": { "payment_link": { "description": "URL of the hosted payment page to redirect the customer to", "examples": [ "https://example.com/pay/abc123" ], "type": "string" } } }, "redirectPaymentRequest_Input": { "title": "Redirect Payment Request Input", "description": "Strict input parameters for the redirect (Pay by Bank) payment request", "additionalProperties": false, "type": "object", "required": [ "customer", "billing_address", "amount", "currency", "locale" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "customer": { "title": "Redirect Customer Input", "description": "Customer information for the redirect payment request", "additionalProperties": false, "type": "object", "required": [ "name", "email" ], "properties": { "name": { "description": "The name of the customer", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "The email of the customer", "examples": [ "john.doe@example.com" ], "type": "string" }, "phone_number": { "description": "The phone number of the customer", "examples": [ "+447123456789" ], "type": "string" } } }, "billing_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "amount": { "minimum": 1, "maximum": 9999999, "description": "Minor-unit amount (e.g. pence/cents). Decimals are rejected.", "examples": [ 1999 ], "type": "integer" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the payment request", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_reference": { "description": "Payment reference to appear on the payer’s bank statement (max 18 alphanumeric characters)", "examples": [ "ORDER123" ], "maxLength": 18, "pattern": "^[A-Za-z0-9]{1,18}$", "type": "string" }, "order_id": { "description": "The unique identifier for the merchant's order", "examples": [ "1140" ], "type": "string" }, "locale": { "description": "The locale of the payment request", "examples": [ "en_GB" ], "type": "string" }, "success_url_redirect": { "description": "URL to redirect on successful payment", "examples": [ "https://storename.com/success" ], "type": "string" }, "fail_url_redirect": { "description": "URL to redirect on failed payment", "examples": [ "https://storename.com/failure" ], "type": "string" }, "test_transaction": { "description": "Flag for test transactions", "examples": [ false ], "type": "boolean" }, "selected_bank_id": { "description": "Selected bank reference", "examples": [ "38c39d03-8df3-4980-b0a8-7e283c8c62dd" ], "type": "string" }, "simulation": { "additionalProperties": false, "description": "Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it.", "type": "object", "properties": { "straddle": { "additionalProperties": false, "type": "object", "properties": { "customer_outcome": { "description": "Simulated identity verification outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "review", "type": "string" } ] }, "paykey_outcome": { "description": "Simulated bank account link outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "active", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "charge_outcome": { "description": "Simulated charge outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "on_hold_daily_limit", "type": "string" }, { "const": "cancelled_for_fraud_risk", "type": "string" }, { "const": "cancelled_for_balance_check", "type": "string" }, { "const": "failed_insufficient_funds", "type": "string" }, { "const": "reversed_insufficient_funds", "type": "string" }, { "const": "failed_customer_dispute", "type": "string" }, { "const": "reversed_customer_dispute", "type": "string" }, { "const": "failed_closed_bank_account", "type": "string" }, { "const": "reversed_closed_bank_account", "type": "string" } ] }, "balance_check": { "description": "Balance verification behaviour", "anyOf": [ { "const": "required", "type": "string" }, { "const": "enabled", "type": "string" }, { "const": "disabled", "type": "string" } ] } } }, "flinks": { "additionalProperties": false, "type": "object", "properties": { "outcome": { "description": "Simulated bank-linking lifecycle and data shape", "anyOf": [ { "const": "happy", "type": "string" }, { "const": "async", "type": "string" }, { "const": "no_us_account", "type": "string" }, { "const": "partial_data", "type": "string" }, { "const": "webhook_only", "type": "string" }, { "const": "rate_limit", "type": "string" }, { "const": "unreachable", "type": "string" } ] }, "account": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "minimum": 1, "description": "Total accounts to return", "type": "number" }, "existing": { "description": "Ids of existing accounts to include; (total - existing.length) new ones are minted", "type": "array", "items": { "type": "string" } } } }, "mfa": { "description": "Whether an MFA challenge is presented and how it is answered", "anyOf": [ { "const": "skip", "type": "string" }, { "const": "correct", "type": "string" }, { "const": "wrong", "type": "string" } ] } } } } } } }, "redirectPaymentRequest_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Redirect Payment Request Data", "description": "Redirect payment request response data", "additionalProperties": false, "type": "object", "required": [ "redirect_url" ], "properties": { "redirect_url": { "description": "URL to redirect the customer to in order to complete payment", "examples": [ "https://example.com/redirect" ], "type": "string" } } } } }, "paymentStatus_CustomerResponse": { "title": "Customer Payment Status", "description": "Minimal, PII-free payment status view for the checkout page", "additionalProperties": false, "type": "object", "required": [ "status", "transaction", "amount", "currency" ], "properties": { "status": { "description": "Current payment status (e.g. pending, completed, failed, cancelled)", "examples": [ "pending", "completed" ], "type": "string" }, "transaction": { "description": "Minimal transaction marker — `{ status }` once a transaction exists, otherwise null", "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, { "type": "null" } ] }, "amount": { "description": "Payment amount in minor units", "examples": [ "1000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "order_id": { "description": "The merchant's order identifier, if one was provided", "examples": [ "1140" ], "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "paymentStatus_MerchantResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant Payment Status", "description": "Tenant-scoped payment status view", "additionalProperties": false, "type": "object", "required": [ "payment_request_id", "status", "amount", "currency" ], "properties": { "payment_request_id": { "format": "uuid", "description": "Internal payment request identifier", "type": "string" }, "status": { "description": "Current payment status", "examples": [ "pending", "completed" ], "type": "string" }, "status_reason": { "description": "Human-readable reason for the current status, when available", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Payment amount in minor units", "examples": [ "1000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "order_id": { "description": "The merchant's order identifier, if one was provided", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transaction_number": { "description": "Transaction number once a transaction has been created", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "embeddedPaymentRequest_Input": { "type": "object", "required": [ "customer", "order", "redirect_urls" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "customer": { "title": "Payment Customer Input", "description": "Customer information for payment flows", "additionalProperties": false, "type": "object", "required": [ "name", "email", "phone", "country" ], "properties": { "name": { "minLength": 1, "description": "Full name of the customer", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Email address of the customer", "examples": [ "john@example.com" ], "type": "string" }, "phone": { "minLength": 3, "description": "E.164-formatted phone number", "examples": [ "+351960123456" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "order": { "type": "object", "required": [ "order_id", "amount", "currency", "payment_reference", "locale" ], "properties": { "order_id": { "minLength": 1, "examples": [ "ORD-123456" ], "description": "Merchant's order identifier", "type": "string" }, "amount": { "minimum": 1, "examples": [ 9300 ], "description": "Minor-unit amount (e.g. cents)", "type": "integer" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_reference": { "maxLength": 18, "examples": [ "Barcelona Tryp" ], "description": "Up to 18 chars, appears on customer bank statement", "type": "string" }, "locale": { "minLength": 2, "examples": [ "en-GB" ], "description": "BCP-47 locale tag", "type": "string" }, "test_transaction": { "examples": [ true ], "description": "Flag to force sandbox mode", "type": "boolean" }, "rewards": { "additionalProperties": false, "description": "Optional reward information for the customer", "type": "object", "required": [ "extra_rewards" ], "properties": { "extra_rewards": { "minimum": 0, "examples": [ 150 ], "description": "Reward points for this transaction", "type": "number" }, "total_rewards": { "minimum": 0, "examples": [ 300 ], "description": "Total reward points including base and extra rewards (optional)", "type": "number" }, "description": { "maxLength": 255, "examples": [ "Loyalty bonus + base rewards" ], "description": "Optional description of the reward offer", "type": "string" } } } } }, "device_type": { "enum": [ "web", "ios", "android" ], "default": "web", "examples": [ "ios" ], "description": "Platform/device type for the payment request", "type": "string" }, "billing_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } }, "simulation": { "additionalProperties": false, "description": "Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it.", "type": "object", "properties": { "straddle": { "additionalProperties": false, "type": "object", "properties": { "customer_outcome": { "description": "Simulated identity verification outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "review", "type": "string" } ] }, "paykey_outcome": { "description": "Simulated bank account link outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "active", "type": "string" }, { "const": "rejected", "type": "string" } ] }, "charge_outcome": { "description": "Simulated charge outcome", "anyOf": [ { "const": "standard", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "on_hold_daily_limit", "type": "string" }, { "const": "cancelled_for_fraud_risk", "type": "string" }, { "const": "cancelled_for_balance_check", "type": "string" }, { "const": "failed_insufficient_funds", "type": "string" }, { "const": "reversed_insufficient_funds", "type": "string" }, { "const": "failed_customer_dispute", "type": "string" }, { "const": "reversed_customer_dispute", "type": "string" }, { "const": "failed_closed_bank_account", "type": "string" }, { "const": "reversed_closed_bank_account", "type": "string" } ] }, "balance_check": { "description": "Balance verification behaviour", "anyOf": [ { "const": "required", "type": "string" }, { "const": "enabled", "type": "string" }, { "const": "disabled", "type": "string" } ] } } }, "flinks": { "additionalProperties": false, "type": "object", "properties": { "outcome": { "description": "Simulated bank-linking lifecycle and data shape", "anyOf": [ { "const": "happy", "type": "string" }, { "const": "async", "type": "string" }, { "const": "no_us_account", "type": "string" }, { "const": "partial_data", "type": "string" }, { "const": "webhook_only", "type": "string" }, { "const": "rate_limit", "type": "string" }, { "const": "unreachable", "type": "string" } ] }, "account": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "minimum": 1, "description": "Total accounts to return", "type": "number" }, "existing": { "description": "Ids of existing accounts to include; (total - existing.length) new ones are minted", "type": "array", "items": { "type": "string" } } } }, "mfa": { "description": "Whether an MFA challenge is presented and how it is answered", "anyOf": [ { "const": "skip", "type": "string" }, { "const": "correct", "type": "string" }, { "const": "wrong", "type": "string" } ] } } } } }, "redirect_urls": { "type": "object", "required": [ "success_url", "failure_url" ], "properties": { "success_url": { "format": "uri", "examples": [ "https://tryp.com/checkout/success" ], "type": "string" }, "failure_url": { "format": "uri", "examples": [ "https://tryp.com/checkout/error" ], "type": "string" } } }, "webhook_endpoints": { "maxItems": 10, "description": "Optional. Up to 10 registered webhook endpoints to fan this payment's webhooks out to, each signed with its own secret. An endpoint can be test-only, live-only, or both. Omit to use the no-reference precedence: the legacy default URL, then the merchant's default endpoint, then the single active endpoint.", "type": "array", "items": { "description": "Name or id of a registered webhook endpoint to route this payment's webhooks to.", "examples": [ "wizzair-prod" ], "type": "string" } } } }, "embeddedPaymentRequest_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "payment_token", "expires_in" ], "properties": { "payment_token": { "examples": [ "ptok_efghijklm..." ], "description": "Opaque token to be embedded into iframe src", "type": "string" }, "expires_in": { "description": "Seconds until token expiry", "minimum": 1, "examples": [ 900 ], "type": "integer" } } } } }, "embeddedPaymentRequestUpdate_Input": { "type": "object", "required": [ "payment_token" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_token": { "examples": [ "ptok_abcd1234" ], "description": "Payment token identifying the request to update", "type": "string" }, "amount": { "minimum": 1, "description": "Minor-unit amount (e.g. cents)", "examples": [ 1530 ], "type": "integer" }, "rewards": { "additionalProperties": false, "type": "object", "required": [ "extra_rewards" ], "properties": { "extra_rewards": { "minimum": 0, "examples": [ 150 ], "description": "Reward points for this transaction", "type": "number" }, "total_rewards": { "minimum": 0, "examples": [ 300 ], "description": "Total reward points including base and extra rewards", "type": "number" }, "description": { "maxLength": 255, "examples": [ "Updated loyalty bonus" ], "description": "Optional description of the reward offer", "type": "string" } } } } }, "embeddedPaymentRequestUpdate_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "payment_token", "amount", "expires_in" ], "properties": { "payment_token": { "examples": [ "ptok_abcd1234" ], "description": "Same payment token (unchanged)", "type": "string" }, "amount": { "examples": [ 1530 ], "description": "Updated amount", "type": "integer" }, "rewards": { "additionalProperties": false, "type": "object", "required": [ "extra_rewards" ], "properties": { "extra_rewards": { "minimum": 0, "examples": [ 150 ], "description": "Updated reward points for this transaction", "type": "number" }, "total_rewards": { "minimum": 0, "examples": [ 300 ], "description": "Updated total reward points including base and extra rewards", "type": "number" }, "description": { "maxLength": 255, "examples": [ "Updated loyalty bonus" ], "description": "Updated description of the reward offer", "type": "string" } } }, "expires_in": { "examples": [ 750 ], "description": "Remaining TTL in seconds", "type": "integer" } } } } }, "embeddedFlinksSession_Input": { "type": "object", "properties": { "institution_id": { "minimum": 1, "description": "Optional Flinks institution ID. When provided, the Flinks iframe skips bank selection and goes directly to credential entry for that institution.", "examples": [ 42 ], "type": "integer" } } }, "embeddedFlinksSession_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "session_id", "connect_url", "expires_at" ], "properties": { "session_id": { "format": "uuid", "description": "Internal session identifier for the Flinks Connect flow.", "type": "string" }, "connect_url": { "format": "uri", "description": "URL to load in the Flinks Connect iframe.", "type": "string" }, "expires_at": { "format": "date-time", "description": "When this session expires.", "type": "string" } } } } }, "embeddedFlinksSession_Cancel_Input": { "type": "object", "required": [ "payment_token", "reason" ], "properties": { "payment_token": { "description": "Payment token authenticating the cancel request against its PaymentRequest.", "type": "string" }, "reason": { "description": "Why the customer abandoned the Flinks Connect iframe. Used for audit only — the customer-facing outcome is the same for all reasons.", "anyOf": [ { "const": "user_closed", "type": "string" }, { "const": "session_expired", "type": "string" }, { "const": "retry_exhausted", "type": "string" }, { "const": "denied_consent", "type": "string" }, { "const": "institution_unavailable", "type": "string" }, { "const": "token_invalid", "type": "string" } ] } } }, "embeddedFlinksSession_Cancel_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "status", "payment_request_id", "cancel_token" ], "properties": { "status": { "const": "cancelled", "type": "string" }, "payment_request_id": { "format": "uuid", "description": "Internal PaymentRequest id. The frontend uses this to navigate to /api/v1/callback for fail-url redirect.", "type": "string" }, "cancel_token": { "description": "Short-lived (≤5 min) signed proof that this cancel originated server-side. The frontend appends it to the subsequent /api/v1/callback?cancel_from_bank_selection=true URL; /callback rejects URLs without a valid matching token. Prevents arbitrary callers from cancelling a pending PR by guessing payment_request_id.", "type": "string" } } } } }, "seed_Data": { "title": "Seed Data", "description": "Database seeding operation data", "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "A message indicating the seeds were created successfully", "examples": [ "Seeds created successfully" ], "type": "string" } } }, "seed_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Seed Data", "description": "Database seeding operation data", "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "A message indicating the seeds were created successfully", "examples": [ "Seeds created successfully" ], "type": "string" } } } } }, "webhook_Webhook": { "title": "Webhook", "description": "Webhook configuration", "additionalProperties": false, "type": "object", "properties": { "webhook_url": { "format": "uri", "description": "The URL where webhook notifications will be sent", "examples": [ "https://example.com/webhook" ], "type": "string" }, "message": { "description": "Success message", "examples": [ "Webhook URL successfully configured" ], "type": "string" } } }, "webhook_Input": { "title": "Webhook Input", "description": "Webhook configuration input", "additionalProperties": false, "type": "object", "required": [ "webhook_url" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "webhook_url": { "format": "uri", "description": "The URL where webhook notifications will be sent", "examples": [ "https://example.com/webhook" ], "type": "string" } } }, "webhook_SecretInput": { "title": "Webhook Secret Input", "description": "Input for webhook secret operations", "additionalProperties": false, "type": "object", "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" } } }, "webhook_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Webhook", "description": "Webhook configuration", "additionalProperties": false, "type": "object", "properties": { "webhook_url": { "format": "uri", "description": "The URL where webhook notifications will be sent", "examples": [ "https://example.com/webhook" ], "type": "string" }, "message": { "description": "Success message", "examples": [ "Webhook URL successfully configured" ], "type": "string" } } } } }, "webhook_GenerateWebhookSecretResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "webhook_secret" ], "properties": { "webhook_secret": { "description": "The newly generated webhook signing secret", "examples": [ "whsec_a1b2c3d4e5f6…" ], "type": "string" } } } } }, "webhook_RevokeWebhookSecretResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "A message confirming the webhook secret was revoked", "examples": [ "Webhook secret successfully revoked" ], "type": "string" } } } } }, "transfermateWebhook_Input": { "additionalProperties": true, "description": "TransferMate webhook payload", "type": "object", "required": [ "event_id", "customer_id", "event_code" ], "properties": { "event_id": { "description": "Unique identifier for this specific webhook call", "examples": [ "3511e175-ab2c-40ec-ba5d-49e466c86328" ], "type": "string" }, "customer_id": { "description": "ID of customer requesting the webhook", "examples": [ "80812345" ], "type": "string" }, "event_code": { "description": "Numeric code identifying the webhook type", "examples": [ "6", "2", "17", "50" ], "type": "string" }, "event_details": { "additionalProperties": true, "description": "Event-specific details that vary by event type", "type": "object", "properties": { "Unique_Record_id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "value_date": { "type": "string" }, "Global_Account": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "payer": { "type": "string" }, "ga_account_id": { "type": "number" }, "reference": { "type": "string" }, "rail_type": { "type": "string" } } } } }, "transfermateWebhook_SuccessResponse": { "additionalProperties": true, "description": "TransferMate webhook acknowledgment response (echoes payload)", "type": "object", "required": [ "event_id", "customer_id", "event_code" ], "properties": { "event_id": { "description": "Unique identifier for this specific webhook call", "examples": [ "3511e175-ab2c-40ec-ba5d-49e466c86328" ], "type": "string" }, "customer_id": { "description": "ID of customer requesting the webhook", "examples": [ "80812345" ], "type": "string" }, "event_code": { "description": "Numeric code identifying the webhook type", "examples": [ "6", "2", "17", "50" ], "type": "string" }, "event_details": { "additionalProperties": true, "description": "Event-specific details that vary by event type", "type": "object", "properties": { "Unique_Record_id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "value_date": { "type": "string" }, "Global_Account": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "payer": { "type": "string" }, "ga_account_id": { "type": "number" }, "reference": { "type": "string" }, "rail_type": { "type": "string" } } } } }, "tinkWebhook_SuccessResponse": { "additionalProperties": true, "description": "Tink webhook acknowledgment response", "type": "object", "required": [ "success" ], "properties": { "success": { "description": "Indicates webhook was received successfully", "examples": [ true ], "type": "boolean" }, "event_id": { "description": "The event ID from the webhook payload", "examples": [ "evt-123456" ], "type": "string" }, "action": { "description": "The action taken (updated, ignored, conflict, not_found, no_transaction)", "examples": [ "updated", "ignored", "conflict" ], "type": "string" }, "duplicate": { "description": "Whether this was a duplicate event (idempotency)", "examples": [ false ], "type": "boolean" }, "conflict": { "description": "Whether a status conflict was detected", "examples": [ false ], "type": "boolean" }, "note": { "description": "Additional information about the processing result", "type": "string" } } }, "flinksWebhook_Input": { "additionalProperties": true, "description": "Flinks GetAccountsDetail payload", "type": "object", "properties": { "HttpStatusCode": { "description": "HTTP status code echoed in Flinks payload", "examples": [ 200 ], "type": "number" }, "RequestId": { "description": "Flinks request identifier from authorize flow", "examples": [ "22178382-31ee-485c-a750-c20929b6a344" ], "type": "string" }, "Login": { "additionalProperties": true, "type": "object", "properties": { "Id": { "description": "Flinks login identifier used to match sessions", "examples": [ "5602459c-f6d0-4ca0-6750-08dccdcadcc0" ], "type": "string" } } }, "Accounts": { "description": "Raw accounts payload from Flinks", "type": "array", "items": {} }, "InstitutionName": { "examples": [ "FlinksCapital" ], "type": "string" }, "InstitutionId": { "examples": [ 14 ], "type": "number" }, "Institution": { "examples": [ "FlinksCapital" ], "type": "string" } } }, "flinksWebhook_SuccessResponse": { "additionalProperties": false, "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "action" ], "properties": { "action": { "description": "Webhook processing action", "anyOf": [ { "const": "processed", "type": "string" }, { "const": "duplicate", "type": "string" }, { "const": "orphaned", "type": "string" } ] } } } } }, "rate_Schema": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } }, "rate_Input": { "title": "Rate Input", "description": "Rate creation input", "additionalProperties": false, "type": "object", "required": [ "type", "value", "unit", "base" ], "properties": { "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } }, "rate_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } }, "defaultRates_Schema": { "title": "Default Rates", "description": "Default rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the default rates", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } }, "defaultRates_Input": { "title": "Default Rates Input", "description": "Default rates creation input", "additionalProperties": false, "type": "object", "required": [ "rates" ], "properties": { "rates": { "description": "Array of rates to be created", "examples": [ [ { "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "notes": "Standard domestic percentage fee" }, { "type": "fixed_transaction_fee", "value": 0.2, "unit": "currency", "base": "gbp", "notes": "Standard fixed GBP fee" }, { "type": "fixed_transaction_fee", "value": 0.27, "unit": "currency", "base": "eur", "notes": "Standard fixed EUR fee" } ] ], "type": "array", "items": { "title": "Rate Input", "description": "Rate creation input", "additionalProperties": false, "type": "object", "required": [ "type", "value", "unit", "base" ], "properties": { "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } }, "defaultRates_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Default Rates", "description": "Default rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the default rates", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } } } }, "defaultRates_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Default Rates", "description": "Default rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the default rates", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } } } } }, "merchantRates_Schema": { "title": "Merchant Rates", "description": "Merchant rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "merchantId", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant rates", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "merchantId": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } }, "merchantRates_Input": { "title": "Merchant Rates Input", "description": "Merchant rates creation input", "additionalProperties": false, "type": "object", "required": [ "rates" ], "properties": { "rates": { "description": "Array of rates to be created", "examples": [ [ { "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "notes": "Standard domestic percentage fee" }, { "type": "fixed_transaction_fee", "value": 0.2, "unit": "currency", "base": "gbp", "notes": "Standard fixed GBP fee" }, { "type": "fixed_transaction_fee", "value": 0.27, "unit": "currency", "base": "eur", "notes": "Standard fixed EUR fee" } ] ], "type": "array", "items": { "title": "Rate Input", "description": "Rate creation input", "additionalProperties": false, "type": "object", "required": [ "type", "value", "unit", "base" ], "properties": { "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } }, "merchantRates_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant Rates", "description": "Merchant rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "merchantId", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant rates", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "merchantId": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } } } }, "merchantRates_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Merchant Rates", "description": "Merchant rates information", "additionalProperties": false, "type": "object", "required": [ "id", "version", "is_active", "merchantId", "created_by", "created_at", "updated_at", "rates" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant rates", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "version": { "description": "Version identifier for the rates", "examples": [ "v1-2024-01-13T15:00:00Z" ], "type": "string" }, "is_active": { "description": "Whether these rates are currently active", "examples": [ true ], "type": "boolean" }, "merchantId": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "created_by": { "description": "Identifier of the user/system that created these rates", "examples": [ "system_seed", "admin_user" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update timestamp", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "rates": { "type": "array", "items": { "title": "Rate", "description": "Rate information", "additionalProperties": false, "type": "object", "required": [ "id", "defaultRatesId", "merchantRatesId", "type", "value", "unit", "base" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the rate", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "defaultRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the default rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "merchantRatesId": { "anyOf": [ { "format": "uuid", "description": "The ID of the merchant rates this rate belongs to", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee", "conversion_percent_fee", "refund_domestic_percent_fee", "refund_fixed_transaction_fee", "refund_conversion_percent_fee" ], "description": "The type of rate", "examples": [ "domestic_percent_fee" ], "type": "string" }, "value": { "description": "The numeric value of the rate", "examples": [ 1, 0.2 ], "type": "number" }, "unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate (% for percentage, currency for fixed amounts)", "examples": [ "%" ], "type": "string" }, "base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate is applied", "examples": [ "gross_amount" ], "type": "string" }, "conversion_currencies": { "description": "Currency pair for conversion rate (both required when specified)", "examples": [ { "source": "EUR", "destination": "GBP" } ], "type": "object", "required": [ "source", "destination" ], "properties": { "source": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Source currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "destination": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Destination currency for conversion", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "notes": { "description": "Optional notes about the rate", "examples": [ "Standard domestic fee" ], "type": "string" } } } } } } } } }, "bankPrediction_Request": { "additionalProperties": false, "type": "object", "required": [ "customer_country" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "customer_country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "phone_number": { "description": "Customer phone number in international format", "examples": [ "+447395263205" ], "type": "string" }, "email": { "description": "Customer email address", "examples": [ "customer@example.com" ], "format": "email", "type": "string" }, "payment_request_id": { "description": "Payment request ID for Shopify", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "format": "uuid", "type": "string" }, "session_id": { "description": "Session ID for WooCommerce", "examples": [ "wca23456789abcdef" ], "type": "string" } } }, "bankPrediction_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "banks" ], "properties": { "banks": { "type": "array", "items": {} } } } } }, "transaction_Schema": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions (ACH returns) — only present for payment transactions with reversals", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } }, "transaction_DetailedSchema": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions with full details including fees (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions with full details (only present for payment transactions with reversals)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } }, "transaction_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions with full details including fees (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions with full details (only present for payment transactions with reversals)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } } } }, "transaction_SearchResponse": { "title": "Transaction Search Response", "description": "Response for transaction search with filtering, sorting, and currency totals", "type": "object", "required": [ "success", "data", "pagination", "totals" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions (ACH returns) — only present for payment transactions with reversals", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } } }, "pagination": { "type": "object", "required": [ "total", "page", "limit", "totalPages", "hasNextPage", "hasPreviousPage" ], "properties": { "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "search_metadata": { "description": "Metadata about the search operation", "type": "object", "required": [ "filters_applied", "sort_applied", "query_execution_time", "total_records_scanned" ], "properties": { "filters_applied": { "description": "List of filters that were applied", "type": "array", "items": { "type": "string" } }, "sort_applied": { "description": "Sort criteria that were applied", "type": "array", "items": { "title": "Sort Field", "description": "Sort field configuration for transaction search", "examples": [ { "field": "created_at", "direction": "desc" }, { "field": "amount", "direction": "asc" }, { "field": "status", "direction": "desc" } ], "type": "object", "required": [ "field", "direction" ], "properties": { "field": { "enum": [ "created_at", "updated_at", "amount", "converted_amount", "status", "transaction_type" ], "description": "Field to sort by", "examples": [ "created_at", "amount", "status" ], "type": "string" }, "direction": { "enum": [ "asc", "desc" ], "description": "Sort direction", "examples": [ "desc", "asc" ], "type": "string" } } } }, "query_execution_time": { "description": "Query execution time in milliseconds", "type": "number" }, "total_records_scanned": { "description": "Total number of records scanned", "type": "number" } } }, "totals": { "description": "Currency-based totals for filtered transactions", "examples": [ [ { "currency": "EUR", "total_amount": 3034 }, { "currency": "GBP", "total_amount": 534 }, { "currency": "DKK", "total_amount": 2034 } ] ], "type": "array", "items": { "title": "Currency Total", "description": "Total amount for a specific currency", "type": "object", "required": [ "currency", "total_amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "total_amount": { "description": "Raw total amount (e.g., 2299.15)", "examples": [ 3034, 534, 2034.5, 10000.15 ], "type": "number" } } } } } }, "transaction_UpdateStatusInput": { "type": "object", "required": [ "status" ], "properties": { "status": { "description": "New status for the transaction. Use RECEIVED to activate a PENDING refund. Use CANCELLED to cancel a PENDING refund.", "examples": [ "received", "fee_paid", "converted", "completed", "cancelled" ], "anyOf": [ { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "cancelled", "type": "string" } ] } } }, "transaction_UpdateStatusResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions with full details including fees (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions with full details (only present for payment transactions with reversals)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } } } }, "transaction_UpdateBillingAddressInput": { "additionalProperties": false, "type": "object", "required": [ "billing_address" ], "properties": { "billing_address": { "title": "Address", "description": "A physical address", "additionalProperties": false, "type": "object", "required": [ "address_line1", "city", "country", "postal_code" ], "properties": { "address_line1": { "description": "The first line of the address", "examples": [ "12 West Common Drive" ], "type": "string" }, "address_line2": { "description": "The second line of the address", "examples": [ "Flat 1" ], "type": "string" }, "apartment": { "description": "The apartment, unit, or suite number", "examples": [ "Apt 5B", "Unit 12", "Suite 200" ], "type": "string" }, "city": { "description": "The city", "examples": [ "London" ], "type": "string" }, "state_province": { "description": "The state or province", "examples": [ "Greater London" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "postal_code": { "description": "The postal code", "examples": [ "SE1 1AA" ], "type": "string" }, "company_name": { "description": "The company name (if applicable)", "examples": [ "Acme Ltd" ], "type": "string" } } } } }, "transaction_UpdateBillingAddressResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "refunds": { "description": "Refund transactions with full details including fees (only present for payment transactions with refunds)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "description": "Reversal transactions with full details (only present for payment transactions with reversals)", "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "status_message", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "payment_request", "destination_account", "destination_account_type", "remittance_information", "payment_scheme", "platform", "refund_status", "can_refund", "related_transaction", "provider_status_events", "merchant_webhook_deliveries", "fees" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "merchant", "customer", "payment_token", "authorization_agreement_record_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" }, "authorization_agreement_record_id": { "description": "AgreementRecord id documenting the customer acceptance that authorised this payment request (ACH click-wrap).", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } } } }, "transaction_AdminDetailResponse": { "title": "Admin Transaction Detail Response", "description": "Full internal detail for a transaction (admin/debug only): merchant, payment-request and provider references, fees, refunds/reversals, and an optional unified event timeline.", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "transaction" ], "properties": { "transaction": { "type": "object", "required": [ "id", "transaction_number", "transaction_type", "status", "status_message", "target_status", "amount", "currency", "cross_border", "cross_border_provider", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "tpp_transaction_id", "bank_provider_transaction_id", "tpp_created_at", "tpp_updated_at", "payment_scheme", "remittance_information", "customer_account", "customer_account_type", "customer_bank_name", "customer_name", "destination_account", "destination_account_type", "destination_account_holder_name", "payout_at", "payout_batch_id", "invoice_id", "settled_at", "webhook_status", "webhook_error_message", "related_transaction", "test", "platform", "created_at", "updated_at", "refund_status", "payment_request", "fees", "can_refund", "provider_status_events", "merchant_webhook_deliveries" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "cross_border": { "type": "boolean" }, "cross_border_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tpp_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bank_provider_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tpp_created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "tpp_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_bank_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "webhook_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "webhook_error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "status", "external_payment_request_id", "provider_name", "provider_environment", "tink_request_id", "provider_request_id", "payment_token", "payment_token_expires_at", "payment_reference", "selected_bank_id", "payment_link_id", "session_id", "locale", "original_amount", "original_currency", "display_exchange_rate", "authorization_agreement_record_id", "merchant", "customer" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "external_payment_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tink_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selected_bank_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "display_exchange_rate": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "authorization_agreement_record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "brand_name", "uri", "mode", "country", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brand_name": { "type": "string" }, "uri": { "type": "string" }, "mode": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email", "customer_identifier" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_ids": {} } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } }, "can_refund": { "type": "boolean" }, "provider_status_events": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "signature_valid" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "signature_valid": { "type": "boolean" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" }, "provider_request_id": { "type": "string" } } } }, "merchant_webhook_deliveries": { "type": "array", "items": { "type": "object", "required": [ "id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } }, "refunds": { "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "transaction_type", "status", "status_message", "target_status", "amount", "currency", "cross_border", "cross_border_provider", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "tpp_transaction_id", "bank_provider_transaction_id", "tpp_created_at", "tpp_updated_at", "payment_scheme", "remittance_information", "customer_account", "customer_account_type", "customer_bank_name", "customer_name", "destination_account", "destination_account_type", "destination_account_holder_name", "payout_at", "payout_batch_id", "invoice_id", "settled_at", "webhook_status", "webhook_error_message", "related_transaction", "test", "platform", "created_at", "updated_at", "refund_status", "payment_request", "fees" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "cross_border": { "type": "boolean" }, "cross_border_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tpp_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bank_provider_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tpp_created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "tpp_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_bank_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "webhook_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "webhook_error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "status", "external_payment_request_id", "provider_name", "provider_environment", "tink_request_id", "provider_request_id", "payment_token", "payment_token_expires_at", "payment_reference", "selected_bank_id", "payment_link_id", "session_id", "locale", "original_amount", "original_currency", "display_exchange_rate", "authorization_agreement_record_id", "merchant", "customer" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "external_payment_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tink_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selected_bank_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "display_exchange_rate": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "authorization_agreement_record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "brand_name", "uri", "mode", "country", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brand_name": { "type": "string" }, "uri": { "type": "string" }, "mode": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email", "customer_identifier" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_ids": {} } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } }, "reversals": { "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "transaction_type", "status", "status_message", "target_status", "amount", "currency", "cross_border", "cross_border_provider", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "tpp_transaction_id", "bank_provider_transaction_id", "tpp_created_at", "tpp_updated_at", "payment_scheme", "remittance_information", "customer_account", "customer_account_type", "customer_bank_name", "customer_name", "destination_account", "destination_account_type", "destination_account_holder_name", "payout_at", "payout_batch_id", "invoice_id", "settled_at", "webhook_status", "webhook_error_message", "related_transaction", "test", "platform", "created_at", "updated_at", "refund_status", "payment_request", "fees" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "type": "string" }, "status_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "cross_border": { "type": "boolean" }, "cross_border_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "tpp_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bank_provider_transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tpp_created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "tpp_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "remittance_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_bank_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "destination_account_holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "webhook_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "webhook_error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "related_transaction": { "anyOf": [ { "type": "object", "required": [ "id", "transaction_number" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "status", "external_payment_request_id", "provider_name", "provider_environment", "tink_request_id", "provider_request_id", "payment_token", "payment_token_expires_at", "payment_reference", "selected_bank_id", "payment_link_id", "session_id", "locale", "original_amount", "original_currency", "display_exchange_rate", "authorization_agreement_record_id", "merchant", "customer" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "external_payment_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_environment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tink_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_token_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "payment_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selected_bank_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_link_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "original_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "display_exchange_rate": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "authorization_agreement_record_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merchant": { "anyOf": [ { "type": "object", "required": [ "id", "brand_name", "uri", "mode", "country", "partner" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brand_name": { "type": "string" }, "uri": { "type": "string" }, "mode": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "partner": { "anyOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "format": "uuid", "type": "string" } } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "customer": { "anyOf": [ { "type": "object", "required": [ "id", "name", "email", "customer_identifier" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customer_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_ids": {} } }, { "type": "null" } ] } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } }, "timeline": { "description": "Unified, chronological lifecycle events across the payment and its refunds/reversals. Present when include_timeline=true.", "type": "array", "items": { "title": "Transaction Event", "description": "A single lifecycle event in a transaction timeline", "additionalProperties": false, "type": "object", "required": [ "id", "type", "timestamp", "summary", "details" ], "properties": { "id": { "type": "string" }, "type": { "description": "The type of lifecycle event", "anyOf": [ { "const": "provider_status", "type": "string" }, { "const": "merchant_webhook", "type": "string" }, { "const": "tm_webhook", "type": "string" }, { "const": "tm_post_processor", "type": "string" }, { "const": "payout_batch", "type": "string" }, { "const": "refund_session", "type": "string" }, { "const": "fee", "type": "string" }, { "const": "payment_request_update", "type": "string" }, { "const": "refund", "type": "string" }, { "const": "reversal", "type": "string" } ] }, "timestamp": { "format": "date-time", "type": "string" }, "summary": { "description": "Human-readable one-line description of the event", "type": "string" }, "details": { "description": "Event-type-specific fields", "type": "object", "patternProperties": { "^(.*)$": {} } }, "source": { "description": "The transaction this event belongs to, when the timeline is unified across a payment and its refunds/reversals", "type": "object", "required": [ "kind", "transaction_id", "transaction_number" ], "properties": { "kind": { "anyOf": [ { "const": "payment", "type": "string" }, { "const": "refund", "type": "string" }, { "const": "reversal", "type": "string" } ] }, "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" } } } } } } } } } }, "search_AmountFilter": { "title": "Amount Filter", "description": "Amount filter with range operations", "examples": [ { "gte": 100, "lte": 1000 }, { "gt": 500 }, { "between": [ 100, 1000 ] } ], "additionalProperties": false, "type": "object", "properties": { "gt": { "minimum": 0, "description": "Greater than this amount", "examples": [ 100 ], "type": "number" }, "lt": { "minimum": 0, "description": "Less than this amount", "examples": [ 1000 ], "type": "number" }, "gte": { "minimum": 0, "description": "Greater than or equal to this amount", "examples": [ 100 ], "type": "number" }, "lte": { "minimum": 0, "description": "Less than or equal to this amount", "examples": [ 1000 ], "type": "number" }, "between": { "minItems": 2, "maxItems": 2, "description": "Amount range [min, max]", "examples": [ [ 100, 1000 ] ], "type": "array", "items": { "minimum": 0, "type": "number" } } } }, "search_StatusFilter": { "title": "Status Filter", "description": "Status filter — use eq for single status, in for multiple", "examples": [ { "eq": "completed" }, { "in": [ "completed", "failed" ] } ], "minProperties": 1, "type": "object", "properties": { "eq": { "enum": [ "completed", "failed", "cancelled", "pending", "processing", "error", "refunding", "refunding_stuck", "refunding_failed", "partially_refunded", "fully_refunded" ], "description": "Exact match for transaction status", "examples": [ "completed" ], "type": "string" }, "in": { "minItems": 1, "description": "Match any of the specified statuses", "examples": [ [ "completed", "failed" ] ], "type": "array", "items": { "enum": [ "completed", "failed", "cancelled", "pending", "processing", "error", "refunding", "refunding_stuck", "refunding_failed", "partially_refunded", "fully_refunded" ], "type": "string" } } } }, "search_TransactionTypeFilter": { "title": "Transaction Type Filter", "description": "Transaction type filter — use eq for single type, in for multiple", "examples": [ { "eq": "payment" }, { "in": [ "payment", "refund" ] } ], "minProperties": 1, "type": "object", "properties": { "eq": { "enum": [ "payment", "refund" ], "description": "Exact match for transaction type", "examples": [ "payment" ], "type": "string" }, "in": { "minItems": 1, "description": "Match any of the specified transaction types", "examples": [ [ "payment", "refund" ] ], "type": "array", "items": { "enum": [ "payment", "refund" ], "type": "string" } } } }, "search_StringContainsFilter": { "title": "String Contains Filter", "description": "String contains filter for partial text matching", "examples": [ { "contains": "gmail" }, { "contains": "test" } ], "type": "object", "required": [ "contains" ], "properties": { "contains": { "minLength": 1, "maxLength": 255, "description": "Text to search for within the field", "examples": [ "gmail", "test", "john" ], "type": "string" } } }, "search_UUIDFilter": { "title": "UUID Filter", "description": "UUID filter for exact matching of payment request IDs", "examples": [ { "eq": "123e4567-e89b-12d3-a456-426614174000" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "format": "uuid", "description": "Exact match for payment request ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } }, "search_ExactStringFilter": { "title": "Exact String Filter", "description": "Exact string filter for payment tokens", "examples": [ { "eq": "tok_abc123def456" }, { "eq": "tok_xyz789ghi012" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "minLength": 1, "maxLength": 255, "description": "Exact match for payment token", "examples": [ "tok_abc123def456", "tok_xyz789ghi012" ], "type": "string" } } }, "search_DateFilter": { "title": "Date Filter", "description": "Date filter with range operations", "examples": [ { "eq": "2024-06-02T00:00:00Z" }, { "gte": "2024-01-01T00:00:00Z" }, { "between": [ "2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z" ] } ], "type": "object", "properties": { "eq": { "format": "date-time", "description": "Exact date match (matches entire day if time is 00:00:00)", "examples": [ "2024-06-02T00:00:00Z", "2024-06-02" ], "type": "string" }, "gte": { "format": "date-time", "description": "Greater than or equal to this date", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "lte": { "format": "date-time", "description": "Less than or equal to this date", "examples": [ "2024-12-31T23:59:59Z" ], "type": "string" }, "between": { "minItems": 2, "maxItems": 2, "description": "Date range [start, end]", "examples": [ [ "2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z" ] ], "type": "array", "items": { "format": "date-time", "type": "string" } } } }, "search_CurrencyFilter": { "title": "Currency Filter", "description": "Currency filter for exact matching of ISO currency codes", "additionalProperties": false, "type": "object", "required": [ "eq" ], "properties": { "eq": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "search_OrderIdFilter": { "title": "Order ID Filter", "description": "Order ID filter for partial text matching", "examples": [ { "contains": "c16d" }, { "contains": "ORDER-123" } ], "additionalProperties": false, "type": "object", "required": [ "contains" ], "properties": { "contains": { "minLength": 1, "maxLength": 255, "description": "Text to search for within order ID", "examples": [ "c16d", "ORDER-123", "2025" ], "type": "string" } } }, "search_CurrencyTotal": { "title": "Currency Total", "description": "Total amount for a specific currency", "type": "object", "required": [ "currency", "total_amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "total_amount": { "description": "Raw total amount (e.g., 2299.15)", "examples": [ 3034, 534, 2034.5, 10000.15 ], "type": "number" } } }, "search_SortField": { "title": "Sort Field", "description": "Sort field configuration for transaction search", "examples": [ { "field": "created_at", "direction": "desc" }, { "field": "amount", "direction": "asc" }, { "field": "status", "direction": "desc" } ], "type": "object", "required": [ "field", "direction" ], "properties": { "field": { "enum": [ "created_at", "updated_at", "amount", "converted_amount", "status", "transaction_type" ], "description": "Field to sort by", "examples": [ "created_at", "amount", "status" ], "type": "string" }, "direction": { "enum": [ "asc", "desc" ], "description": "Sort direction", "examples": [ "desc", "asc" ], "type": "string" } } }, "search_Pagination": { "title": "Search Pagination", "description": "Pagination parameters for transaction search", "examples": [ { "page": 1, "limit": 25 }, { "page": 2, "limit": 50 }, { "limit": 10 }, { "page": 3 } ], "type": "object", "properties": { "page": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 5 ], "type": "number" }, "limit": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50, 100 ], "type": "number" } } }, "search_Request": { "title": "Transaction Search Request", "description": "Phase 1 transaction search with currency totals and enhanced filtering", "examples": [ { "search": { "amount": { "gte": 1000, "lte": 5000 }, "status": { "eq": "completed" }, "customer_email": { "contains": "gmail" } }, "pagination": { "page": 1, "limit": 25 }, "sort": [ { "field": "created_at", "direction": "desc" } ] }, { "search": { "transaction_type": { "eq": "payment" }, "created_at": { "gte": "2024-01-01T00:00:00Z" } }, "pagination": { "page": 1, "limit": 50 }, "sort": [ { "field": "amount", "direction": "desc" }, { "field": "created_at", "direction": "asc" } ] }, { "search": { "currency": { "eq": "EUR" }, "order_id": { "contains": "ORDER" }, "status": { "eq": "completed" } }, "pagination": { "page": 1, "limit": 25 }, "sort": [ { "field": "created_at", "direction": "desc" } ] } ], "type": "object", "properties": { "search": { "description": "Search criteria for filtering transactions", "additionalProperties": false, "type": "object", "properties": { "id": { "title": "UUID Filter", "description": "UUID filter for exact matching of payment request IDs", "examples": [ { "eq": "123e4567-e89b-12d3-a456-426614174000" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "format": "uuid", "description": "Exact match for payment request ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } }, "amount": { "title": "Amount Filter", "description": "Amount filter with range operations", "examples": [ { "gte": 100, "lte": 1000 }, { "gt": 500 }, { "between": [ 100, 1000 ] } ], "additionalProperties": false, "type": "object", "properties": { "gt": { "minimum": 0, "description": "Greater than this amount", "examples": [ 100 ], "type": "number" }, "lt": { "minimum": 0, "description": "Less than this amount", "examples": [ 1000 ], "type": "number" }, "gte": { "minimum": 0, "description": "Greater than or equal to this amount", "examples": [ 100 ], "type": "number" }, "lte": { "minimum": 0, "description": "Less than or equal to this amount", "examples": [ 1000 ], "type": "number" }, "between": { "minItems": 2, "maxItems": 2, "description": "Amount range [min, max]", "examples": [ [ 100, 1000 ] ], "type": "array", "items": { "minimum": 0, "type": "number" } } } }, "status": { "title": "Status Filter", "description": "Status filter — use eq for single status, in for multiple", "examples": [ { "eq": "completed" }, { "in": [ "completed", "failed" ] } ], "minProperties": 1, "type": "object", "properties": { "eq": { "enum": [ "completed", "failed", "cancelled", "pending", "processing", "error", "refunding", "refunding_stuck", "refunding_failed", "partially_refunded", "fully_refunded" ], "description": "Exact match for transaction status", "examples": [ "completed" ], "type": "string" }, "in": { "minItems": 1, "description": "Match any of the specified statuses", "examples": [ [ "completed", "failed" ] ], "type": "array", "items": { "enum": [ "completed", "failed", "cancelled", "pending", "processing", "error", "refunding", "refunding_stuck", "refunding_failed", "partially_refunded", "fully_refunded" ], "type": "string" } } } }, "transaction_type": { "title": "Transaction Type Filter", "description": "Transaction type filter — use eq for single type, in for multiple", "examples": [ { "eq": "payment" }, { "in": [ "payment", "refund" ] } ], "minProperties": 1, "type": "object", "properties": { "eq": { "enum": [ "payment", "refund" ], "description": "Exact match for transaction type", "examples": [ "payment" ], "type": "string" }, "in": { "minItems": 1, "description": "Match any of the specified transaction types", "examples": [ [ "payment", "refund" ] ], "type": "array", "items": { "enum": [ "payment", "refund" ], "type": "string" } } } }, "payment_request_id": { "title": "UUID Filter", "description": "UUID filter for exact matching of payment request IDs", "examples": [ { "eq": "123e4567-e89b-12d3-a456-426614174000" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "format": "uuid", "description": "Exact match for payment request ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } }, "payment_token": { "title": "Exact String Filter", "description": "Exact string filter for payment tokens", "examples": [ { "eq": "tok_abc123def456" }, { "eq": "tok_xyz789ghi012" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "minLength": 1, "maxLength": 255, "description": "Exact match for payment token", "examples": [ "tok_abc123def456", "tok_xyz789ghi012" ], "type": "string" } } }, "customer_email": { "title": "String Contains Filter", "description": "String contains filter for partial text matching", "examples": [ { "contains": "gmail" }, { "contains": "test" } ], "type": "object", "required": [ "contains" ], "properties": { "contains": { "minLength": 1, "maxLength": 255, "description": "Text to search for within the field", "examples": [ "gmail", "test", "john" ], "type": "string" } } }, "created_at": { "title": "Date Filter", "description": "Date filter with range operations", "examples": [ { "eq": "2024-06-02T00:00:00Z" }, { "gte": "2024-01-01T00:00:00Z" }, { "between": [ "2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z" ] } ], "type": "object", "properties": { "eq": { "format": "date-time", "description": "Exact date match (matches entire day if time is 00:00:00)", "examples": [ "2024-06-02T00:00:00Z", "2024-06-02" ], "type": "string" }, "gte": { "format": "date-time", "description": "Greater than or equal to this date", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "lte": { "format": "date-time", "description": "Less than or equal to this date", "examples": [ "2024-12-31T23:59:59Z" ], "type": "string" }, "between": { "minItems": 2, "maxItems": 2, "description": "Date range [start, end]", "examples": [ [ "2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z" ] ], "type": "array", "items": { "format": "date-time", "type": "string" } } } }, "currency": { "title": "Currency Filter", "description": "Currency filter for exact matching of ISO currency codes", "additionalProperties": false, "type": "object", "required": [ "eq" ], "properties": { "eq": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "order_id": { "title": "Order ID Filter", "description": "Order ID filter for partial text matching", "examples": [ { "contains": "c16d" }, { "contains": "ORDER-123" } ], "additionalProperties": false, "type": "object", "required": [ "contains" ], "properties": { "contains": { "minLength": 1, "maxLength": 255, "description": "Text to search for within order ID", "examples": [ "c16d", "ORDER-123", "2025" ], "type": "string" } } }, "payout_batch_id": { "title": "UUID Filter", "description": "UUID filter for exact matching of payment request IDs", "examples": [ { "eq": "123e4567-e89b-12d3-a456-426614174000" } ], "type": "object", "required": [ "eq" ], "properties": { "eq": { "format": "uuid", "description": "Exact match for payment request ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" } } } } }, "pagination": { "title": "Search Pagination", "description": "Pagination parameters for transaction search", "examples": [ { "page": 1, "limit": 25 }, { "page": 2, "limit": 50 }, { "limit": 10 }, { "page": 3 } ], "type": "object", "properties": { "page": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 5 ], "type": "number" }, "limit": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50, 100 ], "type": "number" } } }, "sort": { "maxItems": 2, "description": "Sort criteria (max 2 fields for Phase 1)", "type": "array", "items": { "title": "Sort Field", "description": "Sort field configuration for transaction search", "examples": [ { "field": "created_at", "direction": "desc" }, { "field": "amount", "direction": "asc" }, { "field": "status", "direction": "desc" } ], "type": "object", "required": [ "field", "direction" ], "properties": { "field": { "enum": [ "created_at", "updated_at", "amount", "converted_amount", "status", "transaction_type" ], "description": "Field to sort by", "examples": [ "created_at", "amount", "status" ], "type": "string" }, "direction": { "enum": [ "asc", "desc" ], "description": "Sort direction", "examples": [ "desc", "asc" ], "type": "string" } } } }, "include_all_statuses": { "default": false, "description": "When true, includes all transaction statuses (including in-progress states like fee_paid, converted). Useful for debugging. Default: false (only shows received, completed, failed).", "examples": [ true, false ], "type": "boolean" } } }, "search_Metadata": { "description": "Metadata about the search operation", "type": "object", "required": [ "filters_applied", "sort_applied", "query_execution_time", "total_records_scanned" ], "properties": { "filters_applied": { "description": "List of filters that were applied", "type": "array", "items": { "type": "string" } }, "sort_applied": { "description": "Sort criteria that were applied", "type": "array", "items": { "title": "Sort Field", "description": "Sort field configuration for transaction search", "examples": [ { "field": "created_at", "direction": "desc" }, { "field": "amount", "direction": "asc" }, { "field": "status", "direction": "desc" } ], "type": "object", "required": [ "field", "direction" ], "properties": { "field": { "enum": [ "created_at", "updated_at", "amount", "converted_amount", "status", "transaction_type" ], "description": "Field to sort by", "examples": [ "created_at", "amount", "status" ], "type": "string" }, "direction": { "enum": [ "asc", "desc" ], "description": "Sort direction", "examples": [ "desc", "asc" ], "type": "string" } } } }, "query_execution_time": { "description": "Query execution time in milliseconds", "type": "number" }, "total_records_scanned": { "description": "Total number of records scanned", "type": "number" } } }, "fee_Schema": { "title": "Fee", "description": "Fee information", "additionalProperties": false, "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "created_at", "updated_at", "settlement_status" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the fee", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "amount": { "description": "The amount of the fee", "examples": [ 1, 0.2 ], "type": "number" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the fee", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_type": { "enum": [ "percentage", "fixed" ], "description": "The type of fee (percentage or fixed)", "examples": [ "percentage" ], "type": "string" }, "rate_type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee" ], "description": "The type of rate used to calculate the fee", "examples": [ "domestic_percent_fee" ], "type": "string" }, "rate_value": { "description": "The value of the rate used to calculate the fee", "examples": [ 1, 0.2 ], "type": "number" }, "rate_unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate used to calculate the fee", "examples": [ "%" ], "type": "string" }, "rate_base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate was applied", "examples": [ "gross_amount" ], "type": "string" }, "notes": { "description": "Optional notes about the fee", "examples": [ "Standard domestic fee" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the fee was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the fee was last updated", "type": "string" }, "settlement_status": { "enum": [ "pending", "invoiced", "settled", "failed" ], "description": "The settlement status of the fee", "examples": [ "pending" ], "type": "string" }, "invoice_id": { "format": "uuid", "description": "The ID of the invoice this fee is included in", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "settled_at": { "format": "date-time", "description": "When the fee was settled", "type": "string" } } }, "fee_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Fee", "description": "Fee information", "additionalProperties": false, "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "created_at", "updated_at", "settlement_status" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the fee", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "amount": { "description": "The amount of the fee", "examples": [ 1, 0.2 ], "type": "number" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the fee", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_type": { "enum": [ "percentage", "fixed" ], "description": "The type of fee (percentage or fixed)", "examples": [ "percentage" ], "type": "string" }, "rate_type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee" ], "description": "The type of rate used to calculate the fee", "examples": [ "domestic_percent_fee" ], "type": "string" }, "rate_value": { "description": "The value of the rate used to calculate the fee", "examples": [ 1, 0.2 ], "type": "number" }, "rate_unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate used to calculate the fee", "examples": [ "%" ], "type": "string" }, "rate_base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate was applied", "examples": [ "gross_amount" ], "type": "string" }, "notes": { "description": "Optional notes about the fee", "examples": [ "Standard domestic fee" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the fee was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the fee was last updated", "type": "string" }, "settlement_status": { "enum": [ "pending", "invoiced", "settled", "failed" ], "description": "The settlement status of the fee", "examples": [ "pending" ], "type": "string" }, "invoice_id": { "format": "uuid", "description": "The ID of the invoice this fee is included in", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "settled_at": { "format": "date-time", "description": "When the fee was settled", "type": "string" } } } } }, "fee_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "List of fees", "type": "array", "items": { "title": "Fee", "description": "Fee information", "additionalProperties": false, "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "created_at", "updated_at", "settlement_status" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the fee", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "amount": { "description": "The amount of the fee", "examples": [ 1, 0.2 ], "type": "number" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the fee", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_type": { "enum": [ "percentage", "fixed" ], "description": "The type of fee (percentage or fixed)", "examples": [ "percentage" ], "type": "string" }, "rate_type": { "enum": [ "domestic_percent_fee", "fixed_transaction_fee" ], "description": "The type of rate used to calculate the fee", "examples": [ "domestic_percent_fee" ], "type": "string" }, "rate_value": { "description": "The value of the rate used to calculate the fee", "examples": [ 1, 0.2 ], "type": "number" }, "rate_unit": { "enum": [ "%", "currency" ], "description": "The unit of the rate used to calculate the fee", "examples": [ "%" ], "type": "string" }, "rate_base": { "enum": [ "gross_amount", "gbp", "eur", "usd" ], "description": "The base on which the rate was applied", "examples": [ "gross_amount" ], "type": "string" }, "notes": { "description": "Optional notes about the fee", "examples": [ "Standard domestic fee" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the fee was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the fee was last updated", "type": "string" }, "settlement_status": { "enum": [ "pending", "invoiced", "settled", "failed" ], "description": "The settlement status of the fee", "examples": [ "pending" ], "type": "string" }, "invoice_id": { "format": "uuid", "description": "The ID of the invoice this fee is included in", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "settled_at": { "format": "date-time", "description": "When the fee was settled", "type": "string" } } } } } }, "feeAccount_Schema": { "title": "Fee Account", "description": "Fee account configuration for cross-border payments", "type": "object", "required": [ "id", "currency", "provider", "provider_account_id", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier of the fee account", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "description": "Cross-border provider", "examples": [ "transfermate" ], "type": "string" }, "provider_account_id": { "description": "Provider account identifier", "examples": [ "TM_EUR_FEE_001" ], "type": "string" }, "iban": { "description": "International Bank Account Number", "examples": [ "IE64IRCE92050112345678" ], "type": "string" }, "swift": { "description": "SWIFT/BIC code", "examples": [ "IRCEGB2L" ], "type": "string" }, "account_number": { "description": "Account number", "examples": [ "12345678" ], "type": "string" }, "routing_number": { "description": "Routing number (for US accounts)", "examples": [ "021000021" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Creation timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Last update timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } }, "feeAccount_Response": { "title": "Fee Account Response", "description": "Response containing fee account data", "additionalProperties": false, "examples": [ { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "TRANSFERMATE", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" } } ], "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Fee Account", "description": "Fee account configuration for cross-border payments", "type": "object", "required": [ "id", "currency", "provider", "provider_account_id", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier of the fee account", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "description": "Cross-border provider", "examples": [ "transfermate" ], "type": "string" }, "provider_account_id": { "description": "Provider account identifier", "examples": [ "TM_EUR_FEE_001" ], "type": "string" }, "iban": { "description": "International Bank Account Number", "examples": [ "IE64IRCE92050112345678" ], "type": "string" }, "swift": { "description": "SWIFT/BIC code", "examples": [ "IRCEGB2L" ], "type": "string" }, "account_number": { "description": "Account number", "examples": [ "12345678" ], "type": "string" }, "routing_number": { "description": "Routing number (for US accounts)", "examples": [ "021000021" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Creation timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Last update timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } }, "feeAccount_WithBalanceResponse": { "title": "Fee Account With Balance Response", "description": "Response containing a fee account plus its live balance", "additionalProperties": false, "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Fee Account With Balance", "description": "Fee account configuration plus its live global-account balance", "type": "object", "required": [ "id", "currency", "provider", "provider_account_id", "created_at", "updated_at", "balance" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier of the fee account", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "description": "Cross-border provider", "examples": [ "transfermate" ], "type": "string" }, "provider_account_id": { "description": "Provider account identifier", "examples": [ "TM_EUR_FEE_001" ], "type": "string" }, "iban": { "description": "International Bank Account Number", "examples": [ "IE64IRCE92050112345678" ], "type": "string" }, "swift": { "description": "SWIFT/BIC code", "examples": [ "IRCEGB2L" ], "type": "string" }, "account_number": { "description": "Account number", "examples": [ "12345678" ], "type": "string" }, "routing_number": { "description": "Routing number (for US accounts)", "examples": [ "021000021" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Creation timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Last update timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" }, "balance": { "description": "Live global-account balance, in the fee account's own currency", "examples": [ "12345.67" ], "type": "string" } } } } }, "feeAccount_ListResponse": { "title": "Fee Account List Response", "description": "Response containing list of fee accounts", "additionalProperties": false, "examples": [ { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "TRANSFERMATE", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "currency": "GBP", "provider": "TRANSFERMATE", "provider_account_id": "TM_GBP_FEE_001", "iban": "GB82WEST12345698765432", "swift": "WESTGB2L", "account_number": "87654321", "created_at": "2024-01-15T10:35:00.000Z", "updated_at": "2024-01-15T10:35:00.000Z" } ] } ], "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "List of fee accounts", "examples": [ [ { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "transfermate", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "currency": "GBP", "provider": "transfermate", "provider_account_id": "TM_GBP_FEE_001", "iban": "GB82WEST12345698765432", "swift": "WESTGB2L", "account_number": "87654321", "created_at": "2024-01-15T10:35:00.000Z", "updated_at": "2024-01-15T10:35:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "currency": "USD", "provider": "transfermate", "provider_account_id": "TM_USD_FEE_001", "account_number": "9876543210", "routing_number": "021000021", "created_at": "2024-01-15T10:40:00.000Z", "updated_at": "2024-01-15T10:40:00.000Z" } ] ], "type": "array", "items": { "title": "Fee Account", "description": "Fee account configuration for cross-border payments", "type": "object", "required": [ "id", "currency", "provider", "provider_account_id", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier of the fee account", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "description": "Cross-border provider", "examples": [ "transfermate" ], "type": "string" }, "provider_account_id": { "description": "Provider account identifier", "examples": [ "TM_EUR_FEE_001" ], "type": "string" }, "iban": { "description": "International Bank Account Number", "examples": [ "IE64IRCE92050112345678" ], "type": "string" }, "swift": { "description": "SWIFT/BIC code", "examples": [ "IRCEGB2L" ], "type": "string" }, "account_number": { "description": "Account number", "examples": [ "12345678" ], "type": "string" }, "routing_number": { "description": "Routing number (for US accounts)", "examples": [ "021000021" ], "type": "string" }, "created_at": { "format": "date-time", "description": "Creation timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Last update timestamp", "examples": [ "2024-01-15T10:30:00.000Z" ], "type": "string" } } } } } }, "feeAccount_ListQuery": { "title": "List Fee Accounts Query", "description": "Query parameters for listing fee accounts", "additionalProperties": false, "type": "object", "properties": { "provider": { "description": "Filter by cross-border provider", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" } } }, "feeAccount_CreateRequest": { "title": "Create Fee Account Request", "description": "Request to create a new fee account for a currency", "additionalProperties": false, "type": "object", "required": [ "currency" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency code for the fee account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } }, "refundSession_Schema": { "title": "Refund Session", "description": "Refund session information", "additionalProperties": false, "type": "object", "required": [ "id", "payment_id", "amount", "currency", "platform", "status", "created_at", "updated_at" ], "properties": { "id": { "description": "Refund session ID", "examples": [ "JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "gid": { "description": "Global identifier", "examples": [ "gid://shopify/RefundSession/JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "payment_id": { "description": "Original payment ID", "examples": [ "rSOX4QcIGECb4ZEydY8GgMTfO" ], "type": "string" }, "amount": { "description": "Refund amount", "examples": [ "1.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "merchant_locale": { "description": "Merchant locale", "examples": [ "en" ], "type": "string" }, "platform": { "description": "Platform initiating the refund", "examples": [ "shopify" ], "anyOf": [ { "const": "shopify", "type": "string" }, { "const": "woocommerce", "type": "string" } ] }, "proposed_at": { "description": "When the refund was proposed", "examples": [ "2025-02-21T11:17:05Z" ], "type": "string" }, "test": { "description": "Whether this is a test refund", "examples": [ true ], "type": "boolean" }, "status": { "description": "Status of the refund session", "examples": [ "pending", "completed", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the refund session was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the refund session was last updated", "type": "string" } } }, "refundSession_Input": { "type": "object", "required": [ "payment_id", "amount", "currency", "platform" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "id": { "description": "Shopify refund session ID", "examples": [ "JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "gid": { "description": "Global identifier", "examples": [ "gid://shopify/RefundSession/JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "payment_id": { "description": "Original payment ID", "examples": [ "rSOX4QcIGECb4ZEydY8GgMTfO" ], "type": "string" }, "amount": { "description": "Refund amount", "examples": [ "1.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "merchant_locale": { "description": "Merchant locale", "examples": [ "en" ], "type": "string" }, "platform": { "description": "Platform initiating the refund", "examples": [ "shopify" ], "anyOf": [ { "const": "shopify", "type": "string" }, { "const": "woocommerce", "type": "string" } ] }, "proposed_at": { "description": "When the refund was proposed", "examples": [ "2025-02-21T11:17:05Z" ], "type": "string" }, "test": { "description": "Whether this is a test refund", "examples": [ true ], "type": "boolean" } } }, "refundSession_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Refund Session", "description": "Refund session information", "additionalProperties": false, "type": "object", "required": [ "id", "payment_id", "amount", "currency", "platform", "status", "created_at", "updated_at" ], "properties": { "id": { "description": "Refund session ID", "examples": [ "JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "gid": { "description": "Global identifier", "examples": [ "gid://shopify/RefundSession/JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "payment_id": { "description": "Original payment ID", "examples": [ "rSOX4QcIGECb4ZEydY8GgMTfO" ], "type": "string" }, "amount": { "description": "Refund amount", "examples": [ "1.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "merchant_locale": { "description": "Merchant locale", "examples": [ "en" ], "type": "string" }, "platform": { "description": "Platform initiating the refund", "examples": [ "shopify" ], "anyOf": [ { "const": "shopify", "type": "string" }, { "const": "woocommerce", "type": "string" } ] }, "proposed_at": { "description": "When the refund was proposed", "examples": [ "2025-02-21T11:17:05Z" ], "type": "string" }, "test": { "description": "Whether this is a test refund", "examples": [ true ], "type": "boolean" }, "status": { "description": "Status of the refund session", "examples": [ "pending", "completed", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the refund session was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the refund session was last updated", "type": "string" } } } } }, "refundSession_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Refund Session", "description": "Refund session information", "additionalProperties": false, "type": "object", "required": [ "id", "payment_id", "amount", "currency", "platform", "status", "created_at", "updated_at" ], "properties": { "id": { "description": "Refund session ID", "examples": [ "JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "gid": { "description": "Global identifier", "examples": [ "gid://shopify/RefundSession/JM1YXF4yUe0vmo-FHsgVK3ZC" ], "type": "string" }, "payment_id": { "description": "Original payment ID", "examples": [ "rSOX4QcIGECb4ZEydY8GgMTfO" ], "type": "string" }, "amount": { "description": "Refund amount", "examples": [ "1.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "merchant_locale": { "description": "Merchant locale", "examples": [ "en" ], "type": "string" }, "platform": { "description": "Platform initiating the refund", "examples": [ "shopify" ], "anyOf": [ { "const": "shopify", "type": "string" }, { "const": "woocommerce", "type": "string" } ] }, "proposed_at": { "description": "When the refund was proposed", "examples": [ "2025-02-21T11:17:05Z" ], "type": "string" }, "test": { "description": "Whether this is a test refund", "examples": [ true ], "type": "boolean" }, "status": { "description": "Status of the refund session", "examples": [ "pending", "completed", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the refund session was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the refund session was last updated", "type": "string" } } } } } }, "merchant_MultiAccountSettingUpdate": { "title": "Merchant Multi-Account Setting Update", "description": "Input for updating the merchant multi-account setting", "additionalProperties": false, "type": "object", "required": [ "allowed" ], "properties": { "allowed": { "description": "The desired state for the multi-account setting", "examples": [ true, false ], "type": "boolean" } } }, "merchant_RefundRetentionRateUpdate": { "title": "Merchant Refund Retention Rate Update", "description": "Input for updating the merchant refund retention rate", "additionalProperties": false, "type": "object", "required": [ "refund_retention_rate" ], "properties": { "refund_retention_rate": { "description": "The refund retention rate as a decimal string between 0 and 1 (e.g. \"0.05\" for 5%)", "examples": [ "0.05" ], "type": "string" } } }, "merchantTestData_Options": { "title": "Test Data Options", "description": "Options for test data generation", "additionalProperties": false, "type": "object", "properties": { "paymentRequestCount": { "minimum": 1, "maximum": 150, "default": 120, "description": "Number of payment requests to generate", "examples": [ 120, 50, 100, 150 ], "type": "integer" }, "customerCount": { "minimum": 1, "maximum": 20, "default": 15, "description": "Number of unique customers to create/use", "examples": [ 15, 8, 20 ], "type": "integer" }, "dateRangeInDays": { "minimum": 1, "maximum": 730, "default": 730, "description": "Spread transactions over this many days (up to 2 years)", "examples": [ 730, 365, 180, 90 ], "type": "integer" }, "includeRefunds": { "default": true, "description": "Whether to include refund transactions", "examples": [ true, false ], "type": "boolean" }, "includeFailures": { "default": true, "description": "Whether to include failed and cancelled transactions", "examples": [ true, false ], "type": "boolean" }, "scenarioProfile": { "default": "standard", "description": "Predefined scenario profile", "examples": [ "standard", "high-volume", "cross-border", "failure-testing" ], "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high-volume", "type": "string" }, { "const": "cross-border", "type": "string" }, { "const": "failure-testing", "type": "string" } ] }, "includePayouts": { "default": false, "description": "Whether to generate payout batches from cross-border transactions", "examples": [ true, false ], "type": "boolean" } } }, "merchantTestData_Request": { "title": "Merchant Test Data Request", "description": "Request body for generating test data for a merchant", "additionalProperties": false, "type": "object", "properties": { "options": { "title": "Test Data Options", "description": "Options for test data generation", "additionalProperties": false, "type": "object", "properties": { "paymentRequestCount": { "minimum": 1, "maximum": 150, "default": 120, "description": "Number of payment requests to generate", "examples": [ 120, 50, 100, 150 ], "type": "integer" }, "customerCount": { "minimum": 1, "maximum": 20, "default": 15, "description": "Number of unique customers to create/use", "examples": [ 15, 8, 20 ], "type": "integer" }, "dateRangeInDays": { "minimum": 1, "maximum": 730, "default": 730, "description": "Spread transactions over this many days (up to 2 years)", "examples": [ 730, 365, 180, 90 ], "type": "integer" }, "includeRefunds": { "default": true, "description": "Whether to include refund transactions", "examples": [ true, false ], "type": "boolean" }, "includeFailures": { "default": true, "description": "Whether to include failed and cancelled transactions", "examples": [ true, false ], "type": "boolean" }, "scenarioProfile": { "default": "standard", "description": "Predefined scenario profile", "examples": [ "standard", "high-volume", "cross-border", "failure-testing" ], "anyOf": [ { "const": "standard", "type": "string" }, { "const": "high-volume", "type": "string" }, { "const": "cross-border", "type": "string" }, { "const": "failure-testing", "type": "string" } ] }, "includePayouts": { "default": false, "description": "Whether to generate payout batches from cross-border transactions", "examples": [ true, false ], "type": "boolean" } } } } }, "merchantTestData_Summary": { "title": "Test Data Summary", "description": "Summary of test data generation", "additionalProperties": false, "examples": [ { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s", "payoutBatchesCreated": 3 }, { "merchantId": "123e4567-e89b-12d3-a456-426614174000", "paymentRequestsCreated": 50, "transactionsCreated": 50, "customersCreated": 8, "timeElapsed": "2.3s" } ], "type": "object", "required": [ "merchantId", "paymentRequestsCreated", "transactionsCreated", "customersCreated", "timeElapsed" ], "properties": { "merchantId": { "format": "uuid", "description": "The merchant ID for which test data was generated", "examples": [ "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "paymentRequestsCreated": { "description": "Number of payment requests created", "examples": [ 120, 50, 100 ], "type": "integer" }, "transactionsCreated": { "description": "Number of transactions created", "examples": [ 120, 50, 100 ], "type": "integer" }, "customersCreated": { "description": "Number of customers created", "examples": [ 15, 8, 12 ], "type": "integer" }, "timeElapsed": { "description": "Time taken to generate test data", "examples": [ "3.2s", "2.3s", "1.5s" ], "type": "string" }, "payoutBatchesCreated": { "description": "Number of payout batches created (only when includePayouts is true)", "examples": [ 3, 2, 0 ], "type": "integer" } } }, "merchantTestData_Details": { "title": "Test Data Details", "description": "Detailed breakdown of generated test data", "additionalProperties": false, "examples": [ { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } }, { "paymentRequestsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "transactionsByType": { "payment": 50, "refund": 0 }, "transactionsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "amountDistribution": { "small": 20, "medium": 20, "large": 10 }, "currencyDistribution": { "EUR": 25, "GBP": 13, "USD": 8, "DKK": 4 } } ], "type": "object", "required": [ "paymentRequestsByStatus", "transactionsByType", "transactionsByStatus", "amountDistribution", "currencyDistribution" ], "properties": { "paymentRequestsByStatus": { "description": "Breakdown of payment requests by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed payment requests", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending payment requests", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed payment requests", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled payment requests", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "transactionsByType": { "description": "Breakdown of transactions by type", "additionalProperties": false, "examples": [ { "payment": 50, "refund": 0 }, { "payment": 25, "refund": 3 } ], "type": "object", "required": [ "payment", "refund" ], "properties": { "payment": { "description": "Number of payment transactions", "examples": [ 50, 25, 35 ], "type": "integer" }, "refund": { "description": "Number of refund transactions", "examples": [ 0, 5, 2 ], "type": "integer" } } }, "transactionsByStatus": { "description": "Breakdown of transactions by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed transactions", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending transactions", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed transactions", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled transactions", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "amountDistribution": { "description": "Distribution of transaction amounts", "additionalProperties": false, "examples": [ { "small": 20, "medium": 20, "large": 10 }, { "small": 10, "medium": 10, "large": 5 } ], "type": "object", "required": [ "small", "medium", "large" ], "properties": { "small": { "description": "Number of small amount transactions (10-100)", "examples": [ 20, 10, 15 ], "type": "integer" }, "medium": { "description": "Number of medium amount transactions (100-1000)", "examples": [ 20, 10, 15 ], "type": "integer" }, "large": { "description": "Number of large amount transactions (1000+)", "examples": [ 10, 5, 8 ], "type": "integer" } } }, "currencyDistribution": { "description": "Number of transactions per currency code", "examples": [ { "EUR": 40, "GBP": 7, "USD": 3 }, { "EUR": 38, "GBP": 8, "USD": 4 } ], "type": "object", "patternProperties": { "^(.*)$": { "type": "integer" } } } } }, "merchantTestData_Data": { "title": "Merchant Test Data", "description": "Test data generation result", "additionalProperties": false, "examples": [ { "message": "Test data generated successfully for merchant", "summary": { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s" }, "details": { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } } } ], "type": "object", "required": [ "message", "summary", "details" ], "properties": { "message": { "description": "Success message", "examples": [ "Test data generated successfully for merchant" ], "type": "string" }, "summary": { "title": "Test Data Summary", "description": "Summary of test data generation", "additionalProperties": false, "examples": [ { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s", "payoutBatchesCreated": 3 }, { "merchantId": "123e4567-e89b-12d3-a456-426614174000", "paymentRequestsCreated": 50, "transactionsCreated": 50, "customersCreated": 8, "timeElapsed": "2.3s" } ], "type": "object", "required": [ "merchantId", "paymentRequestsCreated", "transactionsCreated", "customersCreated", "timeElapsed" ], "properties": { "merchantId": { "format": "uuid", "description": "The merchant ID for which test data was generated", "examples": [ "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "paymentRequestsCreated": { "description": "Number of payment requests created", "examples": [ 120, 50, 100 ], "type": "integer" }, "transactionsCreated": { "description": "Number of transactions created", "examples": [ 120, 50, 100 ], "type": "integer" }, "customersCreated": { "description": "Number of customers created", "examples": [ 15, 8, 12 ], "type": "integer" }, "timeElapsed": { "description": "Time taken to generate test data", "examples": [ "3.2s", "2.3s", "1.5s" ], "type": "string" }, "payoutBatchesCreated": { "description": "Number of payout batches created (only when includePayouts is true)", "examples": [ 3, 2, 0 ], "type": "integer" } } }, "details": { "title": "Test Data Details", "description": "Detailed breakdown of generated test data", "additionalProperties": false, "examples": [ { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } }, { "paymentRequestsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "transactionsByType": { "payment": 50, "refund": 0 }, "transactionsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "amountDistribution": { "small": 20, "medium": 20, "large": 10 }, "currencyDistribution": { "EUR": 25, "GBP": 13, "USD": 8, "DKK": 4 } } ], "type": "object", "required": [ "paymentRequestsByStatus", "transactionsByType", "transactionsByStatus", "amountDistribution", "currencyDistribution" ], "properties": { "paymentRequestsByStatus": { "description": "Breakdown of payment requests by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed payment requests", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending payment requests", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed payment requests", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled payment requests", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "transactionsByType": { "description": "Breakdown of transactions by type", "additionalProperties": false, "examples": [ { "payment": 50, "refund": 0 }, { "payment": 25, "refund": 3 } ], "type": "object", "required": [ "payment", "refund" ], "properties": { "payment": { "description": "Number of payment transactions", "examples": [ 50, 25, 35 ], "type": "integer" }, "refund": { "description": "Number of refund transactions", "examples": [ 0, 5, 2 ], "type": "integer" } } }, "transactionsByStatus": { "description": "Breakdown of transactions by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed transactions", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending transactions", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed transactions", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled transactions", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "amountDistribution": { "description": "Distribution of transaction amounts", "additionalProperties": false, "examples": [ { "small": 20, "medium": 20, "large": 10 }, { "small": 10, "medium": 10, "large": 5 } ], "type": "object", "required": [ "small", "medium", "large" ], "properties": { "small": { "description": "Number of small amount transactions (10-100)", "examples": [ 20, 10, 15 ], "type": "integer" }, "medium": { "description": "Number of medium amount transactions (100-1000)", "examples": [ 20, 10, 15 ], "type": "integer" }, "large": { "description": "Number of large amount transactions (1000+)", "examples": [ 10, 5, 8 ], "type": "integer" } } }, "currencyDistribution": { "description": "Number of transactions per currency code", "examples": [ { "EUR": 40, "GBP": 7, "USD": 3 }, { "EUR": 38, "GBP": 8, "USD": 4 } ], "type": "object", "patternProperties": { "^(.*)$": { "type": "integer" } } } } } } }, "merchantTestData_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant Test Data", "description": "Test data generation result", "additionalProperties": false, "examples": [ { "message": "Test data generated successfully for merchant", "summary": { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s" }, "details": { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } } } ], "type": "object", "required": [ "message", "summary", "details" ], "properties": { "message": { "description": "Success message", "examples": [ "Test data generated successfully for merchant" ], "type": "string" }, "summary": { "title": "Test Data Summary", "description": "Summary of test data generation", "additionalProperties": false, "examples": [ { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s", "payoutBatchesCreated": 3 }, { "merchantId": "123e4567-e89b-12d3-a456-426614174000", "paymentRequestsCreated": 50, "transactionsCreated": 50, "customersCreated": 8, "timeElapsed": "2.3s" } ], "type": "object", "required": [ "merchantId", "paymentRequestsCreated", "transactionsCreated", "customersCreated", "timeElapsed" ], "properties": { "merchantId": { "format": "uuid", "description": "The merchant ID for which test data was generated", "examples": [ "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "paymentRequestsCreated": { "description": "Number of payment requests created", "examples": [ 120, 50, 100 ], "type": "integer" }, "transactionsCreated": { "description": "Number of transactions created", "examples": [ 120, 50, 100 ], "type": "integer" }, "customersCreated": { "description": "Number of customers created", "examples": [ 15, 8, 12 ], "type": "integer" }, "timeElapsed": { "description": "Time taken to generate test data", "examples": [ "3.2s", "2.3s", "1.5s" ], "type": "string" }, "payoutBatchesCreated": { "description": "Number of payout batches created (only when includePayouts is true)", "examples": [ 3, 2, 0 ], "type": "integer" } } }, "details": { "title": "Test Data Details", "description": "Detailed breakdown of generated test data", "additionalProperties": false, "examples": [ { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } }, { "paymentRequestsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "transactionsByType": { "payment": 50, "refund": 0 }, "transactionsByStatus": { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, "amountDistribution": { "small": 20, "medium": 20, "large": 10 }, "currencyDistribution": { "EUR": 25, "GBP": 13, "USD": 8, "DKK": 4 } } ], "type": "object", "required": [ "paymentRequestsByStatus", "transactionsByType", "transactionsByStatus", "amountDistribution", "currencyDistribution" ], "properties": { "paymentRequestsByStatus": { "description": "Breakdown of payment requests by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed payment requests", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending payment requests", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed payment requests", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled payment requests", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "transactionsByType": { "description": "Breakdown of transactions by type", "additionalProperties": false, "examples": [ { "payment": 50, "refund": 0 }, { "payment": 25, "refund": 3 } ], "type": "object", "required": [ "payment", "refund" ], "properties": { "payment": { "description": "Number of payment transactions", "examples": [ 50, 25, 35 ], "type": "integer" }, "refund": { "description": "Number of refund transactions", "examples": [ 0, 5, 2 ], "type": "integer" } } }, "transactionsByStatus": { "description": "Breakdown of transactions by status", "additionalProperties": false, "examples": [ { "completed": 35, "pending": 8, "failed": 5, "cancelled": 2 }, { "completed": 18, "pending": 4, "failed": 2, "cancelled": 1 } ], "type": "object", "required": [ "completed", "pending", "failed", "cancelled" ], "properties": { "completed": { "description": "Number of completed transactions", "examples": [ 35, 25, 18 ], "type": "integer" }, "pending": { "description": "Number of pending transactions", "examples": [ 8, 4, 6 ], "type": "integer" }, "failed": { "description": "Number of failed transactions", "examples": [ 5, 2, 3 ], "type": "integer" }, "cancelled": { "description": "Number of cancelled transactions", "examples": [ 2, 1, 1 ], "type": "integer" } } }, "amountDistribution": { "description": "Distribution of transaction amounts", "additionalProperties": false, "examples": [ { "small": 20, "medium": 20, "large": 10 }, { "small": 10, "medium": 10, "large": 5 } ], "type": "object", "required": [ "small", "medium", "large" ], "properties": { "small": { "description": "Number of small amount transactions (10-100)", "examples": [ 20, 10, 15 ], "type": "integer" }, "medium": { "description": "Number of medium amount transactions (100-1000)", "examples": [ 20, 10, 15 ], "type": "integer" }, "large": { "description": "Number of large amount transactions (1000+)", "examples": [ 10, 5, 8 ], "type": "integer" } } }, "currencyDistribution": { "description": "Number of transactions per currency code", "examples": [ { "EUR": 40, "GBP": 7, "USD": 3 }, { "EUR": 38, "GBP": 8, "USD": 4 } ], "type": "object", "patternProperties": { "^(.*)$": { "type": "integer" } } } } } } } } }, "paymentScheme_Schema": { "title": "Payment Scheme", "description": "Payment scheme information", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_default", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "The human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco", "Faster Payments" ], "type": "string" }, "is_default": { "description": "Whether this is the default payment scheme for the country", "examples": [ true, false ], "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme should be shown as a separate payment option in the UI", "examples": [ false, true ], "type": "boolean" } } }, "paymentScheme_List": { "title": "Payment Schemes List", "description": "List of payment schemes", "additionalProperties": false, "type": "object", "required": [ "payment_schemes" ], "properties": { "payment_schemes": { "description": "List of available payment schemes for the country", "type": "array", "items": { "title": "Payment Scheme", "description": "Payment scheme information", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_default", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "The human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco", "Faster Payments" ], "type": "string" }, "is_default": { "description": "Whether this is the default payment scheme for the country", "examples": [ true, false ], "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme should be shown as a separate payment option in the UI", "examples": [ false, true ], "type": "boolean" } } } } } }, "paymentScheme_DiscoveryQuery": { "required": [ "country" ], "additionalProperties": false, "title": "Payment Scheme Discovery Query", "description": "Query parameters for discovering payment schemes", "type": "object", "properties": { "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } }, "paymentScheme_DiscoveryResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Payment Schemes List", "description": "List of payment schemes", "additionalProperties": false, "type": "object", "required": [ "payment_schemes" ], "properties": { "payment_schemes": { "description": "List of available payment schemes for the country", "type": "array", "items": { "title": "Payment Scheme", "description": "Payment scheme information", "additionalProperties": false, "type": "object", "required": [ "id", "type", "name", "is_default", "additional_payment_method" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the payment scheme", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "name": { "description": "The human-readable name of the payment scheme", "examples": [ "SEPA Credit Transfer", "Multibanco", "Faster Payments" ], "type": "string" }, "is_default": { "description": "Whether this is the default payment scheme for the country", "examples": [ true, false ], "type": "boolean" }, "additional_payment_method": { "description": "Whether this scheme should be shown as a separate payment option in the UI", "examples": [ false, true ], "type": "boolean" } } } } } } } }, "paymentScheme_CountryError": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "description": "Error codes from country validation", "anyOf": [ { "const": "INVALID_COUNTRY_CODE_FORMAT", "type": "string" }, { "const": "INVALID_COUNTRY_CODE", "type": "string" }, { "const": "COUNTRY_NOT_DOMESTIC_ACTIVATED", "type": "string" }, { "const": "COUNTRY_NOT_CROSS_BORDER_ACTIVATED", "type": "string" }, { "const": "COUNTRY_NOT_ACTIVATED", "type": "string" } ] }, "message": { "description": "Human-readable error message", "examples": [ "Invalid country code format provided for payment scheme discovery", "Country code not found for payment scheme discovery: XX", "Country XX is not activated for payments (payment scheme discovery)" ], "type": "string" } } } } }, "bankAccountPaymentScheme_UpdateRequest": { "title": "Bank Account Payment Scheme Update Request", "description": "Request body for updating payment schemes on a bank account", "additionalProperties": false, "type": "object", "required": [ "supported_payment_schemes" ], "properties": { "supported_payment_schemes": { "description": "Array of payment schemes to update/merge. Only specified schemes are modified, existing schemes not mentioned are preserved.", "examples": [ [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": true } ], [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": false }, { "type": "MULTIBANCO", "is_active": true } ] ], "minItems": 1, "maxItems": 10, "type": "array", "items": { "title": "Payment Scheme Update Input", "description": "Payment scheme configuration for bank account updates", "additionalProperties": false, "type": "object", "required": [ "type" ], "properties": { "type": { "title": "Payment Scheme Type", "description": "The type of payment scheme", "examples": [ "SEPA_CREDIT_TRANSFER", "MULTIBANCO", "FASTER_PAYMENTS", "DANISH_DOMESTIC_CREDIT_TRANSFER", "BECS", "ACH" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "BECS", "type": "string" }, { "const": "ACH", "type": "string" } ] }, "is_active": { "description": "Whether this account should actively receive payments for this scheme. Defaults to false if not specified.", "type": "boolean" } } } } } }, "shopifyOrder_Input": { "type": "object", "required": [ "orderData" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "orderData": { "additionalProperties": true, "description": "Shopify order data object", "examples": [ { "order_id": "12345", "total": "100.00" } ], "type": "object", "properties": {} } } }, "shopifyOrder_BulkInput": { "type": "object", "required": [ "orders" ], "properties": { "merchant_id": { "format": "uuid", "description": "Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "orders": { "description": "Array of Shopify order data objects", "examples": [ [ { "order_id": "12345", "total": "100.00" } ] ], "type": "array", "items": { "additionalProperties": true, "description": "Shopify order data object", "type": "object", "properties": {} } } } }, "shopifyOrder_Response": { "title": "Shopify Order Response", "description": "Response for creating a Shopify order", "type": "object", "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": true, "description": "Shopify order data", "type": "object", "properties": {} } } }, "shopifyOrder_ListResponse": { "title": "Shopify Orders List Response", "description": "Response for listing Shopify orders", "type": "object", "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "Array of Shopify orders", "type": "array", "items": { "additionalProperties": true, "description": "Shopify order data", "type": "object", "properties": {} } } } }, "crossBorderEnrollment_Enrollment": { "title": "Cross-Border Enrollment", "description": "Cross-border payment provider enrollment information for a merchant", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the cross-border enrollment", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "provider": { "title": "Cross-Border Provider", "description": "The cross-border payment provider instance name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "status": { "title": "Cross-Border Enrollment Status", "description": "The current status of the cross-border enrollment process", "examples": [ "awaiting_details", "awaiting_verification", "verified" ], "anyOf": [ { "const": "awaiting_details", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "verified", "type": "string" } ] }, "created_at": { "format": "date-time", "description": "The timestamp when the enrollment was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the enrollment was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "supported_currencies": { "description": "List of supported currencies derived from virtual merchant bank accounts", "examples": [ [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] ], "type": "array", "items": { "title": "Supported Currency", "description": "Currency support status for cross-border payments", "additionalProperties": false, "type": "object", "required": [ "currency", "status" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "status": { "description": "The status of the currency support", "examples": [ "active", "inactive" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] } } } } } }, "crossBorderEnrollment_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Cross-Border Enrollment", "description": "Cross-border payment provider enrollment information for a merchant", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the cross-border enrollment", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "provider": { "title": "Cross-Border Provider", "description": "The cross-border payment provider instance name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "status": { "title": "Cross-Border Enrollment Status", "description": "The current status of the cross-border enrollment process", "examples": [ "awaiting_details", "awaiting_verification", "verified" ], "anyOf": [ { "const": "awaiting_details", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "verified", "type": "string" } ] }, "created_at": { "format": "date-time", "description": "The timestamp when the enrollment was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the enrollment was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "supported_currencies": { "description": "List of supported currencies derived from virtual merchant bank accounts", "examples": [ [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] ], "type": "array", "items": { "title": "Supported Currency", "description": "Currency support status for cross-border payments", "additionalProperties": false, "type": "object", "required": [ "currency", "status" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "status": { "description": "The status of the currency support", "examples": [ "active", "inactive" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] } } } } } } } }, "crossBorderEnrollment_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Cross-Border Enrollment", "description": "Cross-border payment provider enrollment information for a merchant", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the cross-border enrollment", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "provider": { "title": "Cross-Border Provider", "description": "The cross-border payment provider instance name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "status": { "title": "Cross-Border Enrollment Status", "description": "The current status of the cross-border enrollment process", "examples": [ "awaiting_details", "awaiting_verification", "verified" ], "anyOf": [ { "const": "awaiting_details", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "verified", "type": "string" } ] }, "created_at": { "format": "date-time", "description": "The timestamp when the enrollment was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the enrollment was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "supported_currencies": { "description": "List of supported currencies derived from virtual merchant bank accounts", "examples": [ [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] ], "type": "array", "items": { "title": "Supported Currency", "description": "Currency support status for cross-border payments", "additionalProperties": false, "type": "object", "required": [ "currency", "status" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "status": { "description": "The status of the currency support", "examples": [ "active", "inactive" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] } } } } } } } } }, "crossBorderEnrollment_Status": { "title": "Cross-Border Enrollment Status", "description": "The current status of the cross-border enrollment process", "examples": [ "awaiting_details", "awaiting_verification", "verified" ], "anyOf": [ { "const": "awaiting_details", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "verified", "type": "string" } ] }, "crossBorderEnrollment_Provider": { "title": "Cross-Border Provider", "description": "The cross-border payment provider instance name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "crossBorderEnrollment_EnableInput": { "title": "Enable Enrollment Input", "description": "Request body for enabling cross-border enrollment", "additionalProperties": false, "type": "object", "required": [ "provider" ], "properties": { "provider": { "description": "The cross-border provider to enroll with.", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" } } }, "crossBorderEnrollment_UpdateStatusInput": { "title": "Update Enrollment Status Input", "description": "Request body for updating cross-border enrollment status", "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "description": "The new status for the enrollment. Use \"verified\" to check with provider and update if verified.", "examples": [ "awaiting_verification", "verified" ], "anyOf": [ { "const": "awaiting_verification", "type": "string" }, { "const": "verified", "type": "string" } ] } } }, "crossBorderEnrollment_SetupAccountsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "Success message", "examples": [ "Merchant accounts setup completed successfully" ], "type": "string" } } } } }, "countryConfig_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "title": "CountryConfigResponseData", "description": "Full configuration for a country including payment schemes", "type": "object", "required": [ "name", "iso2", "config", "payment_schemes" ], "properties": { "name": { "description": "Full country name", "examples": [ "Germany", "Australia", "Denmark" ], "type": "string" }, "iso2": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "short": { "description": "Short custom code for internal usage", "examples": [ "gb", "de" ], "type": "string" }, "grouping": { "description": "Regional grouping", "examples": [ "EU", "APAC", "NA" ], "type": "string" }, "config": { "title": "CountryConfigData", "description": "Configuration rules for a specific country", "additionalProperties": false, "type": "object", "required": [ "phone_data" ], "properties": { "phone_data": { "additionalProperties": false, "type": "object", "required": [ "countryCode" ], "properties": { "countryCode": { "description": "International phone country code", "examples": [ "44", "61", "1" ], "type": "string" }, "phoneFormat": { "description": "Default phone mask format", "examples": [ ".... ......", "(...) ...-...." ], "type": "string" }, "hasTrunkPrefix": { "description": "The trunk prefix, if there is one for the country", "examples": [ 0, 1 ], "type": "number" }, "patterns": { "description": "Regex-based mapping of phone prefix - format pattern", "examples": [ { "/^4/": "... ... ...", "default": ". .... ...." } ], "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } } } }, "postal_code": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "company_number": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "vat": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "tax_id": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "entity_structure": { "description": "List of supported legal entity types in this country", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "value" ], "properties": { "label": { "description": "Entity structure type label", "examples": [ "Private Limited Company (LTD)", "LLC" ], "type": "string" }, "value": { "description": "Internal enum value representing the legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "fields": { "description": "Fields required depending on entity structure", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "type", "required" ], "properties": { "type": { "description": "Additional field required for this structure", "examples": [ "company_number", "vat" ], "type": "string" }, "required": { "description": "Whether the field is mandatory", "examples": [ true, false ], "type": "boolean" } } } } } } }, "required_address_lines": { "description": "Fields required when submitting an address", "examples": [ [ "address_line1", "city", "postal_code" ] ], "type": "array", "items": { "type": "string" } }, "state_province": { "description": "List of supported states/provinces", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "reviewLabel", "value" ], "properties": { "label": { "description": "Full state/province name", "examples": [ "New South Wales", "Bavaria" ], "type": "string" }, "reviewLabel": { "description": "Short display label used in reviews", "examples": [ "NSW", "BY" ], "type": "string" }, "value": { "description": "Stored value for the state/province", "examples": [ "New South Wales", "Bavaria" ], "type": "string" } } } } } }, "payment_schemes": { "description": "List of available payment schemes", "type": "array", "items": { "title": "CountryPaymentScheme", "description": "Payment scheme configuration for a country", "additionalProperties": false, "type": "object", "required": [ "type", "name", "fields" ], "properties": { "type": { "description": "Payment scheme type", "examples": [ "FASTER_PAYMENTS" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "ACH", "type": "string" }, { "const": "BECS", "type": "string" } ] }, "name": { "description": "Payment scheme name", "examples": [ "Faster Payments" ], "type": "string" }, "fields": { "description": "Input fields required for this scheme in this country", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "min", "max", "pattern", "placeholder", "required", "type" ], "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" }, "type": { "description": "Internal field type (company_number, vat, tax_id, etc.)", "examples": [ "company_number", "tax_id" ], "type": "string" } } } } } } } } } } }, "countryConfig_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "description": "List of country configurations", "type": "array", "items": { "additionalProperties": false, "title": "CountryConfigResponseData", "description": "Full configuration for a country including payment schemes", "type": "object", "required": [ "name", "iso2", "config", "payment_schemes" ], "properties": { "name": { "description": "Full country name", "examples": [ "Germany", "Australia", "Denmark" ], "type": "string" }, "iso2": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "short": { "description": "Short custom code for internal usage", "examples": [ "gb", "de" ], "type": "string" }, "grouping": { "description": "Regional grouping", "examples": [ "EU", "APAC", "NA" ], "type": "string" }, "config": { "title": "CountryConfigData", "description": "Configuration rules for a specific country", "additionalProperties": false, "type": "object", "required": [ "phone_data" ], "properties": { "phone_data": { "additionalProperties": false, "type": "object", "required": [ "countryCode" ], "properties": { "countryCode": { "description": "International phone country code", "examples": [ "44", "61", "1" ], "type": "string" }, "phoneFormat": { "description": "Default phone mask format", "examples": [ ".... ......", "(...) ...-...." ], "type": "string" }, "hasTrunkPrefix": { "description": "The trunk prefix, if there is one for the country", "examples": [ 0, 1 ], "type": "number" }, "patterns": { "description": "Regex-based mapping of phone prefix - format pattern", "examples": [ { "/^4/": "... ... ...", "default": ". .... ...." } ], "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } } } }, "postal_code": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "company_number": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "vat": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "tax_id": { "additionalProperties": false, "type": "object", "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "format": { "description": "Display mask for digits-only fields; \".\" marks an input slot, any other character is a literal separator inserted automatically (e.g. \"..-.......\")", "examples": [ "..-......." ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" } } }, "entity_structure": { "description": "List of supported legal entity types in this country", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "value" ], "properties": { "label": { "description": "Entity structure type label", "examples": [ "Private Limited Company (LTD)", "LLC" ], "type": "string" }, "value": { "description": "Internal enum value representing the legal structure of the company", "examples": [ "limited_liability_company" ], "anyOf": [ { "const": "limited_liability_company", "type": "string" }, { "const": "private_limited_company", "type": "string" }, { "const": "public_limited_company", "type": "string" }, { "const": "general_partnership", "type": "string" }, { "const": "limited_liability_partnership", "type": "string" }, { "const": "limited_partnership", "type": "string" }, { "const": "limited_liability_entrep_company", "type": "string" }, { "const": "joint_stock_company", "type": "string" }, { "const": "single_member_llc", "type": "string" }, { "const": "multi_member_llc", "type": "string" }, { "const": "private_partnership", "type": "string" }, { "const": "private_corporation", "type": "string" }, { "const": "public_company", "type": "string" } ] }, "fields": { "description": "Fields required depending on entity structure", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "type", "required" ], "properties": { "type": { "description": "Additional field required for this structure", "examples": [ "company_number", "vat" ], "type": "string" }, "required": { "description": "Whether the field is mandatory", "examples": [ true, false ], "type": "boolean" } } } } } } }, "required_address_lines": { "description": "Fields required when submitting an address", "examples": [ [ "address_line1", "city", "postal_code" ] ], "type": "array", "items": { "type": "string" } }, "state_province": { "description": "List of supported states/provinces", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "reviewLabel", "value" ], "properties": { "label": { "description": "Full state/province name", "examples": [ "New South Wales", "Bavaria" ], "type": "string" }, "reviewLabel": { "description": "Short display label used in reviews", "examples": [ "NSW", "BY" ], "type": "string" }, "value": { "description": "Stored value for the state/province", "examples": [ "New South Wales", "Bavaria" ], "type": "string" } } } } } }, "payment_schemes": { "description": "List of available payment schemes", "type": "array", "items": { "title": "CountryPaymentScheme", "description": "Payment scheme configuration for a country", "additionalProperties": false, "type": "object", "required": [ "type", "name", "fields" ], "properties": { "type": { "description": "Payment scheme type", "examples": [ "FASTER_PAYMENTS" ], "anyOf": [ { "const": "SEPA_CREDIT_TRANSFER", "type": "string" }, { "const": "MULTIBANCO", "type": "string" }, { "const": "DANISH_DOMESTIC_CREDIT_TRANSFER", "type": "string" }, { "const": "FASTER_PAYMENTS", "type": "string" }, { "const": "BACS", "type": "string" }, { "const": "ACH", "type": "string" }, { "const": "BECS", "type": "string" } ] }, "name": { "description": "Payment scheme name", "examples": [ "Faster Payments" ], "type": "string" }, "fields": { "description": "Input fields required for this scheme in this country", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "label", "min", "max", "pattern", "placeholder", "required", "type" ], "properties": { "label": { "description": "Label", "examples": [ "Postal Code", "VAT number" ], "type": "string" }, "min": { "description": "Minimum allowed length", "examples": [ 4, 8 ], "type": "number" }, "max": { "description": "Maximum allowed length", "examples": [ 8, 11 ], "type": "number" }, "pattern": { "description": "Regex validation pattern", "examples": [ "^[A-Z0-9]{8}$", "^GB[0-9]{9}$" ], "type": "string" }, "placeholder": { "description": "Example placeholder shown to users", "examples": [ "SW1A 1AA", "GB123123123" ], "type": "string" }, "required": { "description": "Indicates if the field is mandatory", "examples": [ true, false ], "type": "boolean" }, "type": { "description": "Internal field type (company_number, vat, tax_id, etc.)", "examples": [ "company_number", "tax_id" ], "type": "string" } } } } } } } } } } } }, "devMerchant_ModeFlipResult": { "title": "Dev: Merchant Mode Flip Result", "description": "Result of a dev-only `promote-to-live` / `revert-to-sandbox` operation: how many payment_request rows were re-flagged alongside the merchant itself.", "type": "object", "required": [ "merchantId", "previousMode", "newMode", "paymentRequestsAffected" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "previousMode": { "description": "Merchant operating mode", "anyOf": [ { "const": "live", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "newMode": { "description": "Merchant operating mode", "anyOf": [ { "const": "live", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "paymentRequestsAffected": { "description": "Number of payment_request rows whose flags were updated", "type": "integer" } } }, "devMerchant_ModeFlipResponse": { "title": "Dev: Merchant Mode Flip Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Dev: Merchant Mode Flip Result", "description": "Result of a dev-only `promote-to-live` / `revert-to-sandbox` operation: how many payment_request rows were re-flagged alongside the merchant itself.", "type": "object", "required": [ "merchantId", "previousMode", "newMode", "paymentRequestsAffected" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "previousMode": { "description": "Merchant operating mode", "anyOf": [ { "const": "live", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "newMode": { "description": "Merchant operating mode", "anyOf": [ { "const": "live", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "paymentRequestsAffected": { "description": "Number of payment_request rows whose flags were updated", "type": "integer" } } } } }, "devMerchant_SimulateRefundTopUpInput": { "title": "Dev: Simulate Refund Account Top-up Input", "additionalProperties": false, "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "exclusiveMinimum": 0, "description": "Decimal amount to credit (account currency)", "examples": [ 250, 3.2 ], "type": "number" }, "currency": { "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency of the merchant refund account to credit", "examples": [ "GBP", "EUR", "USD" ], "type": "string" }, "reference": { "description": "Payer reference shown on the activity row", "type": "string" }, "payer": { "description": "Payer display name shown on the activity row", "type": "string" }, "description": { "description": "Free-text description", "type": "string" }, "provider": { "description": "Optional provider name to scope the top-up to (e.g. \"transfermate\" vs \"fake-transfermate\" on envs where both are fake-backed).", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" } } }, "devMerchant_SimulateRefundTopUpResult": { "title": "Dev: Simulate Refund Account Top-up Result", "type": "object", "required": [ "merchantId", "bankAccountId", "userBankId", "currency", "amount" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "bankAccountId": { "format": "uuid", "type": "string" }, "userBankId": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "reference": { "type": "string" } } }, "devMerchant_SimulateRefundTopUpResponse": { "title": "Dev: Simulate Refund Account Top-up Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Dev: Simulate Refund Account Top-up Result", "type": "object", "required": [ "merchantId", "bankAccountId", "userBankId", "currency", "amount" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "bankAccountId": { "format": "uuid", "type": "string" }, "userBankId": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string" }, "reference": { "type": "string" } } } } }, "devMerchant_ResetEnrollmentResult": { "title": "Dev: Reset Cross-Border Enrollment Result", "type": "object", "required": [ "merchantId", "provider", "bankAccountsDeleted", "feeBeneficiariesDeleted", "enrollmentsDeleted" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "bankAccountsDeleted": { "type": "integer" }, "feeBeneficiariesDeleted": { "type": "integer" }, "enrollmentsDeleted": { "type": "integer" } } }, "devMerchant_ResetEnrollmentResponse": { "title": "Dev: Reset Cross-Border Enrollment Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Dev: Reset Cross-Border Enrollment Result", "type": "object", "required": [ "merchantId", "provider", "bankAccountsDeleted", "feeBeneficiariesDeleted", "enrollmentsDeleted" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "bankAccountsDeleted": { "type": "integer" }, "feeBeneficiariesDeleted": { "type": "integer" }, "enrollmentsDeleted": { "type": "integer" } } } } }, "devMerchant_ClearRefundActivityInput": { "title": "Dev: Clear Refund Account Activity Input", "additionalProperties": false, "type": "object", "properties": { "currency": { "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency to scope the clear. Omit to clear every refund account.", "type": "string" } } }, "devMerchant_ClearRefundActivityResult": { "title": "Dev: Clear Refund Account Activity Result", "type": "object", "required": [ "merchantId", "cleared" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "cleared": { "type": "array", "items": { "type": "object", "required": [ "bankAccountId", "currency", "deleted" ], "properties": { "bankAccountId": { "format": "uuid", "type": "string" }, "currency": { "type": "string" }, "deleted": { "type": "integer" } } } } } }, "devMerchant_ClearRefundActivityResponse": { "title": "Dev: Clear Refund Account Activity Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Dev: Clear Refund Account Activity Result", "type": "object", "required": [ "merchantId", "cleared" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "cleared": { "type": "array", "items": { "type": "object", "required": [ "bankAccountId", "currency", "deleted" ], "properties": { "bankAccountId": { "format": "uuid", "type": "string" }, "currency": { "type": "string" }, "deleted": { "type": "integer" } } } } } } } }, "payout_Batch": { "title": "Payout Batch", "description": "A batch of transactions to be paid out to a merchant", "type": "object", "required": [ "id", "payment_reference", "merchant_id", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant ID for this payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440001" ], "type": "string" }, "source_account_id": { "format": "uuid", "description": "ID of the receiving bank account used as the source for this payout", "examples": [ "550e8400-e29b-41d4-a716-446655440002" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "retention_reference": { "description": "Payment reference for the retention transfer", "examples": [ "QKM1ABC2DEF34G-RET" ], "type": "string" }, "retention_tm_transaction_id": { "description": "TransferMate transaction ID for the retention transfer", "examples": [ "TM-87654321" ], "type": "string" }, "tm_transaction_id": { "description": "TransferMate transaction ID for the payout", "examples": [ "TM-12345678" ], "type": "string" }, "error_message": { "description": "Error message if the payout failed", "examples": [ "Settlement account not found" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the payout batch was last updated", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" } } }, "payout_BatchResponse": { "title": "Payout Batch Response", "description": "Response containing a single payout batch", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Payout Batch", "description": "A batch of transactions to be paid out to a merchant", "type": "object", "required": [ "id", "payment_reference", "merchant_id", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant ID for this payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440001" ], "type": "string" }, "source_account_id": { "format": "uuid", "description": "ID of the receiving bank account used as the source for this payout", "examples": [ "550e8400-e29b-41d4-a716-446655440002" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "retention_reference": { "description": "Payment reference for the retention transfer", "examples": [ "QKM1ABC2DEF34G-RET" ], "type": "string" }, "retention_tm_transaction_id": { "description": "TransferMate transaction ID for the retention transfer", "examples": [ "TM-87654321" ], "type": "string" }, "tm_transaction_id": { "description": "TransferMate transaction ID for the payout", "examples": [ "TM-12345678" ], "type": "string" }, "error_message": { "description": "Error message if the payout failed", "examples": [ "Settlement account not found" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the payout batch was last updated", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" } } } } }, "payout_BatchListResponse": { "title": "Payout Batch List Response", "description": "Response containing a list of payout batches", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Payout Batch", "description": "A batch of transactions to be paid out to a merchant", "type": "object", "required": [ "id", "payment_reference", "merchant_id", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant ID for this payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440001" ], "type": "string" }, "source_account_id": { "format": "uuid", "description": "ID of the receiving bank account used as the source for this payout", "examples": [ "550e8400-e29b-41d4-a716-446655440002" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "retention_reference": { "description": "Payment reference for the retention transfer", "examples": [ "QKM1ABC2DEF34G-RET" ], "type": "string" }, "retention_tm_transaction_id": { "description": "TransferMate transaction ID for the retention transfer", "examples": [ "TM-87654321" ], "type": "string" }, "tm_transaction_id": { "description": "TransferMate transaction ID for the payout", "examples": [ "TM-12345678" ], "type": "string" }, "error_message": { "description": "Error message if the payout failed", "examples": [ "Settlement account not found" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "When the payout batch was last updated", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" } } } } } }, "payout_UpdateStatusInput": { "title": "Update Payout Batch Status Input", "description": "Request body for updating payout batch status", "type": "object", "required": [ "status" ], "properties": { "status": { "description": "Target status for the payout batch (only COMPLETED is allowed)", "examples": [ "completed" ], "const": "completed", "type": "string" } } }, "payout_MerchantBatch": { "title": "Merchant Payout Batch", "description": "A payout batch as visible to the merchant (excludes internal fields)", "type": "object", "required": [ "id", "payment_reference", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" } } }, "payout_MerchantBatchResponse": { "title": "Merchant Payout Batch Response", "description": "Response containing a single merchant-facing payout batch", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Merchant Payout Batch", "description": "A payout batch as visible to the merchant (excludes internal fields)", "type": "object", "required": [ "id", "payment_reference", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" } } } } }, "payout_MerchantBatchListResponse": { "title": "Merchant Payout Batch List Response", "description": "Response containing a list of merchant-facing payout batches", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Merchant Payout Batch", "description": "A payout batch as visible to the merchant (excludes internal fields)", "type": "object", "required": [ "id", "payment_reference", "status", "currency", "gross_amount", "fees_total", "net_amount", "transaction_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the payout batch", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "payment_reference": { "description": "Short payment reference code for the payout batch", "examples": [ "QKM1ABC2DEF34G" ], "type": "string" }, "status": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payout", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "gross_amount": { "description": "Total transaction amount before fees, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1395.94" ], "type": "string" }, "fees_total": { "description": "Total fees deducted, in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "14.00" ], "type": "string" }, "net_amount": { "description": "Net amount after fees (gross_amount - fees_total), in the payout currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions included in this payout", "examples": [ 5 ], "type": "number" }, "payout_amount": { "description": "Amount transferred to the settlement account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1111.10" ], "type": "string" }, "retained_amount": { "description": "Amount retained for the refund account", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "123.46" ], "type": "string" }, "retention_rate": { "description": "Retention rate applied (e.g. 0.1000 for 10%)", "pattern": "^\\d+\\.\\d{4}$", "examples": [ "0.1000" ], "type": "string" }, "executed_at": { "format": "date-time", "description": "When the payout was executed", "examples": [ "2024-01-15T10:30:00Z" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the payout batch was created", "examples": [ "2024-01-15T10:00:00Z" ], "type": "string" } } } } } }, "invoice_Status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "invoice_PaymentMethod": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "invoice_Payment": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "invoice_FxRate": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } }, "invoice_Invoice": { "title": "Invoice", "description": "A claim over a set of fees billed to a merchant", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "issued_by_user_id", "paid_at", "voided_at", "voided_reason", "voided_by_user_id", "notes", "created_by_user_id", "created_at", "updated_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "description": "Per-merchant monthly sequence (e.g. INV-202605-000123)", "examples": [ "INV-202605-000001" ], "type": "string" }, "payment_reference": { "description": "12-character payment reference for bank statements", "examples": [ "QK7L2M9X4P0R" ], "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "description": "UTC period start (inclusive)", "type": "string" }, "period_end": { "format": "date", "description": "UTC period end (exclusive)", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid. Use this instead of deriving outstanding client-side.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions claimed by this invoice", "examples": [ 42 ], "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "issued_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voided_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } }, "invoice_Response": { "title": "Invoice Response", "description": "Response containing a single invoice", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invoice", "description": "A claim over a set of fees billed to a merchant", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "issued_by_user_id", "paid_at", "voided_at", "voided_reason", "voided_by_user_id", "notes", "created_by_user_id", "created_at", "updated_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "description": "Per-merchant monthly sequence (e.g. INV-202605-000123)", "examples": [ "INV-202605-000001" ], "type": "string" }, "payment_reference": { "description": "12-character payment reference for bank statements", "examples": [ "QK7L2M9X4P0R" ], "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "description": "UTC period start (inclusive)", "type": "string" }, "period_end": { "format": "date", "description": "UTC period end (exclusive)", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid. Use this instead of deriving outstanding client-side.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions claimed by this invoice", "examples": [ 42 ], "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "issued_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voided_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } } } }, "invoice_ListResponse": { "title": "Invoice List Response", "description": "Response containing a list of invoices", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Invoice", "description": "A claim over a set of fees billed to a merchant", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "issued_by_user_id", "paid_at", "voided_at", "voided_reason", "voided_by_user_id", "notes", "created_by_user_id", "created_at", "updated_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "description": "Per-merchant monthly sequence (e.g. INV-202605-000123)", "examples": [ "INV-202605-000001" ], "type": "string" }, "payment_reference": { "description": "12-character payment reference for bank statements", "examples": [ "QK7L2M9X4P0R" ], "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "description": "UTC period start (inclusive)", "type": "string" }, "period_end": { "format": "date", "description": "UTC period end (exclusive)", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid. Use this instead of deriving outstanding client-side.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "description": "Number of transactions claimed by this invoice", "examples": [ 42 ], "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "issued_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "voided_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voided_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } } } } }, "invoice_CustomerInvoice": { "title": "Customer Invoice", "description": "Invoice visible to a merchant customer", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "paid_at", "created_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "payment_reference": { "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "type": "string" }, "period_end": { "format": "date", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } }, "invoice_CustomerResponse": { "title": "Customer Invoice Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Customer Invoice", "description": "Invoice visible to a merchant customer", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "paid_at", "created_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "payment_reference": { "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "type": "string" }, "period_end": { "format": "date", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } } } }, "invoice_CustomerListResponse": { "title": "Customer Invoice List Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Customer Invoice", "description": "Invoice visible to a merchant customer", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "paid_at", "created_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "payment_reference": { "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "type": "string" }, "period_end": { "format": "date", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } } } } }, "invoice_DocumentBundle": { "title": "Invoice Document Bundle", "description": "JSON form of the rendered invoice document — line items, totals, parties.", "type": "object", "required": [ "invoice", "line_items", "currency_subtotals", "grand_total_minor", "grand_total_is_estimate", "merchant", "issuer", "fee_account", "fx_rates" ], "properties": { "invoice": { "title": "Customer Invoice", "description": "Invoice visible to a merchant customer", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "paid_at", "created_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "payment_reference": { "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "type": "string" }, "period_end": { "format": "date", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } }, "line_items": { "type": "array", "items": { "title": "Invoice Line Item", "type": "object", "required": [ "transaction_id", "transaction_number", "transaction_created_at", "deposit_amount_minor", "deposit_currency", "payout_currency", "exchange_rate", "fee_amount_minor", "fee_currency", "fee_rate_type", "fee_rate_value", "fee_rate_unit" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "transaction_created_at": { "format": "date-time", "type": "string" }, "deposit_amount_minor": { "type": "number" }, "deposit_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the deposit", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payout_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency Quidkey paid the merchant in", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "exchange_rate": { "description": "Stored exchange rate at transaction time (1.0 for same-currency)", "type": "number" }, "fee_amount_minor": { "description": "Fee in its original currency (minor units)", "type": "number" }, "fee_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the fee", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_rate_type": { "type": "string" }, "fee_rate_value": { "type": "number" }, "fee_rate_unit": { "type": "string" } } } }, "currency_subtotals": { "type": "array", "items": { "title": "Invoice Currency Subtotal", "type": "object", "required": [ "source_currency", "subtotal_source_minor", "subtotal_invoice_minor", "rate", "rate_source", "rate_captured_at", "rate_fetched_at", "rate_provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency being subtotalled", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "subtotal_source_minor": { "type": "number" }, "subtotal_invoice_minor": { "description": "Null when the rate could not be resolved (DRAFT + FX provider unavailable)", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rate_source": { "anyOf": [ { "const": "same_currency", "type": "string" }, { "const": "stored", "type": "string" }, { "const": "snapshot", "type": "string" }, { "const": "estimate", "type": "string" }, { "const": "pending", "type": "string" } ] }, "rate_captured_at": { "description": "Provider's data-freshness timestamp (rate age)", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rate_fetched_at": { "description": "When our service called the FX provider to lock this rate", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rate_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "grand_total_minor": { "description": "Null when any subtotal could not be converted", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "grand_total_is_estimate": { "description": "True when one or more subtotals used a render-time live rate (DRAFT)", "type": "boolean" }, "merchant": { "title": "Invoice Merchant Snapshot", "type": "object", "required": [ "id", "name", "address_lines" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "address_lines": { "type": "array", "items": { "type": "string" } } } }, "issuer": { "title": "Invoice Issuer", "type": "object", "required": [ "name", "address_lines", "country", "vat_number", "contact_email", "contact_url" ], "properties": { "name": { "type": "string" }, "address_lines": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact_email": { "type": "string" }, "contact_url": { "type": "string" } } }, "fee_account": { "anyOf": [ { "title": "Invoice Fee Account", "type": "object", "required": [ "currency", "provider" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Account currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "type": "string" }, "account_holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iban": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "swift": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routing_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bsb": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "fx_rates": { "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } }, "invoice_DocumentBundleResponse": { "title": "Invoice Document Bundle Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invoice Document Bundle", "description": "JSON form of the rendered invoice document — line items, totals, parties.", "type": "object", "required": [ "invoice", "line_items", "currency_subtotals", "grand_total_minor", "grand_total_is_estimate", "merchant", "issuer", "fee_account", "fx_rates" ], "properties": { "invoice": { "title": "Customer Invoice", "description": "Invoice visible to a merchant customer", "type": "object", "required": [ "id", "invoice_number", "payment_reference", "merchant_id", "status", "currency", "period_start", "period_end", "total_amount", "amount_paid", "outstanding_amount", "transaction_count", "due_date", "issued_at", "paid_at", "created_at", "payments", "fx_rates" ], "properties": { "id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "payment_reference": { "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the invoice", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "period_start": { "format": "date", "type": "string" }, "period_end": { "format": "date", "type": "string" }, "total_amount": { "description": "Gross billable fees in invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "amount_paid": { "description": "Sum of recorded invoice payments", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "0.00" ], "type": "string" }, "outstanding_amount": { "description": "Server-computed total_amount − amount_paid.", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "transaction_count": { "type": "number" }, "due_date": { "anyOf": [ { "format": "date", "type": "string" }, { "type": "null" } ] }, "issued_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "payments": { "type": "array", "items": { "title": "Invoice Payment", "description": "A payment recorded against an invoice", "type": "object", "required": [ "id", "amount", "currency", "payment_method", "external_reference", "paid_at", "recorded_by_user_id", "recorded_at", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "125.00" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the payment", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "How a payment against an invoice was recorded", "examples": [ "manual_bank_transfer" ], "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "immediately_settled", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference or similar correlation key; null for system-inserted", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "type": "string" }, "recorded_by_user_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "recorded_at": { "format": "date-time", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "fx_rates": { "description": "FX rate snapshot captured at issue time, one row per source currency", "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } }, "line_items": { "type": "array", "items": { "title": "Invoice Line Item", "type": "object", "required": [ "transaction_id", "transaction_number", "transaction_created_at", "deposit_amount_minor", "deposit_currency", "payout_currency", "exchange_rate", "fee_amount_minor", "fee_currency", "fee_rate_type", "fee_rate_value", "fee_rate_unit" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "transaction_created_at": { "format": "date-time", "type": "string" }, "deposit_amount_minor": { "type": "number" }, "deposit_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the deposit", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payout_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency Quidkey paid the merchant in", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "exchange_rate": { "description": "Stored exchange rate at transaction time (1.0 for same-currency)", "type": "number" }, "fee_amount_minor": { "description": "Fee in its original currency (minor units)", "type": "number" }, "fee_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the fee", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_rate_type": { "type": "string" }, "fee_rate_value": { "type": "number" }, "fee_rate_unit": { "type": "string" } } } }, "currency_subtotals": { "type": "array", "items": { "title": "Invoice Currency Subtotal", "type": "object", "required": [ "source_currency", "subtotal_source_minor", "subtotal_invoice_minor", "rate", "rate_source", "rate_captured_at", "rate_fetched_at", "rate_provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency being subtotalled", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "subtotal_source_minor": { "type": "number" }, "subtotal_invoice_minor": { "description": "Null when the rate could not be resolved (DRAFT + FX provider unavailable)", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "rate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rate_source": { "anyOf": [ { "const": "same_currency", "type": "string" }, { "const": "stored", "type": "string" }, { "const": "snapshot", "type": "string" }, { "const": "estimate", "type": "string" }, { "const": "pending", "type": "string" } ] }, "rate_captured_at": { "description": "Provider's data-freshness timestamp (rate age)", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rate_fetched_at": { "description": "When our service called the FX provider to lock this rate", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "rate_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "grand_total_minor": { "description": "Null when any subtotal could not be converted", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "grand_total_is_estimate": { "description": "True when one or more subtotals used a render-time live rate (DRAFT)", "type": "boolean" }, "merchant": { "title": "Invoice Merchant Snapshot", "type": "object", "required": [ "id", "name", "address_lines" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "address_lines": { "type": "array", "items": { "type": "string" } } } }, "issuer": { "title": "Invoice Issuer", "type": "object", "required": [ "name", "address_lines", "country", "vat_number", "contact_email", "contact_url" ], "properties": { "name": { "type": "string" }, "address_lines": { "type": "array", "items": { "type": "string" } }, "country": { "type": "string" }, "vat_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact_email": { "type": "string" }, "contact_url": { "type": "string" } } }, "fee_account": { "anyOf": [ { "title": "Invoice Fee Account", "type": "object", "required": [ "currency", "provider" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Account currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "provider": { "type": "string" }, "account_holder_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "iban": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "swift": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "routing_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bsb": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "fx_rates": { "type": "array", "items": { "title": "Invoice FX Rate", "type": "object", "required": [ "source_currency", "rate", "captured_at", "fetched_at", "provider" ], "properties": { "source_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The fee currency the rate converts FROM", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "rate": { "description": "Multiplier applied to convert from source_currency to the invoice currency", "examples": [ "0.85120000" ], "type": "string" }, "captured_at": { "format": "date-time", "description": "Provider's data-freshness timestamp (rate age)", "type": "string" }, "fetched_at": { "description": "When our service called the FX provider to lock this rate. Null for rows created before this column existed.", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "provider": { "examples": [ "openexchangerates" ], "type": "string" } } } } } } } }, "invoice_CreateInput": { "title": "Create Invoice Input", "description": "Request body for POST /admin/invoices", "type": "object", "required": [ "merchant_id", "period_start", "period_end", "currency" ], "properties": { "merchant_id": { "format": "uuid", "type": "string" }, "period_start": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, inclusive", "type": "string" }, "period_end": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, exclusive", "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO-4217 invoice currency (defaults to merchant home currency)", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "invoice_UpdateStatusInput": { "title": "Update Invoice Status Input", "description": "Request body for PUT /admin/invoices/:id/status", "type": "object", "required": [ "status" ], "properties": { "status": { "description": "Target status. `paid` is not allowed — it falls out automatically when payments cover the total", "anyOf": [ { "const": "issued", "type": "string" }, { "const": "void", "type": "string" } ] }, "reason": { "description": "Required when status=void", "minLength": 1, "type": "string" } } }, "invoice_RecordPaymentInput": { "title": "Record Invoice Payment Input", "description": "Request body for POST /admin/invoices/:id/payments", "type": "object", "required": [ "amount", "currency", "payment_method", "paid_at" ], "properties": { "amount": { "description": "Payment amount in the invoice currency", "pattern": "^-?\\d+\\.\\d{2}$", "examples": [ "1234.56" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Must match the invoice currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_method": { "description": "manual_bank_transfer for received funds; issue_credit for admin write-offs (requires `notes`)", "anyOf": [ { "const": "manual_bank_transfer", "type": "string" }, { "const": "issue_credit", "type": "string" } ] }, "external_reference": { "description": "Bank statement reference; idempotency key per (invoice_id, external_reference)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paid_at": { "format": "date-time", "description": "When the funds actually moved", "type": "string" }, "notes": { "description": "Required when payment_method=issue_credit (the reason)", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "invoice_ListQuery": { "title": "List Invoices Query", "type": "object", "properties": { "merchant_id": { "format": "uuid", "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "period_start_from": { "format": "date", "type": "string" }, "period_start_to": { "format": "date", "type": "string" }, "limit": { "description": "Page size (1-200, default 50)", "pattern": "^[1-9]\\d{0,2}$", "type": "string" }, "offset": { "pattern": "^\\d+$", "type": "string" } } }, "invoice_CustomerListQuery": { "title": "Customer List Invoices Query", "type": "object", "properties": { "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] } } }, "invoice_ClaimablePreviewQuery": { "title": "Claimable Preview Query", "type": "object", "required": [ "merchant_id", "period_start", "period_end" ], "properties": { "merchant_id": { "format": "uuid", "type": "string" }, "period_start": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, inclusive", "type": "string" }, "period_end": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, exclusive", "type": "string" } } }, "invoice_ClaimablePreview": { "title": "Claimable Preview", "type": "object", "required": [ "transaction_count", "fee_totals_by_currency", "transactions", "truncated", "conflicts" ], "properties": { "transaction_count": { "description": "Total eligible transactions in the window (not capped by the sample list)", "type": "number" }, "fee_totals_by_currency": { "type": "array", "items": { "title": "Claimable Preview Currency Total", "type": "object", "required": [ "currency", "total_minor", "transaction_count" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Fee currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "total_minor": { "type": "number" }, "transaction_count": { "type": "number" } } } }, "transactions": { "description": "Sample of up to 500 eligible transactions; truncated=true when more exist", "type": "array", "items": { "title": "Claimable Preview Transaction", "type": "object", "required": [ "transaction_id", "transaction_number", "created_at", "deposit_amount_minor", "deposit_currency", "fee_total_minor", "fee_currency" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deposit_amount_minor": { "type": "number" }, "deposit_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the deposit", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_total_minor": { "description": "Sum of positive fees on this transaction, in fee_currency", "type": "number" }, "fee_currency": { "description": "Null when the transaction has no positive fees", "anyOf": [ { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the fee total", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, { "type": "null" } ] } } } }, "truncated": { "type": "boolean" }, "conflicts": { "description": "Invoices that already own transactions in this window", "type": "array", "items": { "title": "Claimable Preview Conflict", "type": "object", "required": [ "invoice_id", "invoice_number", "status", "transaction_count" ], "properties": { "invoice_id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "transaction_count": { "type": "number" } } } } } }, "invoice_ClaimablePreviewResponse": { "title": "Claimable Preview Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Claimable Preview", "type": "object", "required": [ "transaction_count", "fee_totals_by_currency", "transactions", "truncated", "conflicts" ], "properties": { "transaction_count": { "description": "Total eligible transactions in the window (not capped by the sample list)", "type": "number" }, "fee_totals_by_currency": { "type": "array", "items": { "title": "Claimable Preview Currency Total", "type": "object", "required": [ "currency", "total_minor", "transaction_count" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Fee currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "total_minor": { "type": "number" }, "transaction_count": { "type": "number" } } } }, "transactions": { "description": "Sample of up to 500 eligible transactions; truncated=true when more exist", "type": "array", "items": { "title": "Claimable Preview Transaction", "type": "object", "required": [ "transaction_id", "transaction_number", "created_at", "deposit_amount_minor", "deposit_currency", "fee_total_minor", "fee_currency" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "deposit_amount_minor": { "type": "number" }, "deposit_currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the deposit", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "fee_total_minor": { "description": "Sum of positive fees on this transaction, in fee_currency", "type": "number" }, "fee_currency": { "description": "Null when the transaction has no positive fees", "anyOf": [ { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Currency of the fee total", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, { "type": "null" } ] } } } }, "truncated": { "type": "boolean" }, "conflicts": { "description": "Invoices that already own transactions in this window", "type": "array", "items": { "title": "Claimable Preview Conflict", "type": "object", "required": [ "invoice_id", "invoice_number", "status", "transaction_count" ], "properties": { "invoice_id": { "format": "uuid", "type": "string" }, "invoice_number": { "type": "string" }, "status": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "transaction_count": { "type": "number" } } } } } } } }, "user_User": { "title": "User", "description": "User information with role assignments", "additionalProperties": false, "type": "object", "required": [ "id", "email", "created_at", "updated_at", "role_assignments" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "email": { "format": "email", "description": "The email address of the user", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "default_partner_id": { "format": "uuid", "description": "Default partner context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "default_merchant_id": { "format": "uuid", "description": "Default merchant context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "role_assignments": { "description": "Roles assigned to this user", "type": "array", "items": { "title": "Role Assignment", "description": "A role assigned to a user", "additionalProperties": false, "type": "object", "required": [ "id", "role", "created_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the role assignment", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the role was assigned", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } }, "user_Input": { "title": "User Input", "description": "User creation input", "additionalProperties": false, "type": "object", "required": [ "email" ], "properties": { "email": { "format": "email", "description": "User email address", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "default_partner_id": { "format": "uuid", "description": "Default partner context", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "default_merchant_id": { "format": "uuid", "description": "Default merchant context", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "roles": { "description": "Initial roles to assign to the user", "type": "array", "items": { "description": "Role string in format \"scopeType:roleName:scopeId\"", "examples": [ "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" } } } }, "user_Response": { "title": "User Response", "description": "Response containing a single user", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "User", "description": "User information with role assignments", "additionalProperties": false, "type": "object", "required": [ "id", "email", "created_at", "updated_at", "role_assignments" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "email": { "format": "email", "description": "The email address of the user", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "default_partner_id": { "format": "uuid", "description": "Default partner context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "default_merchant_id": { "format": "uuid", "description": "Default merchant context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "role_assignments": { "description": "Roles assigned to this user", "type": "array", "items": { "title": "Role Assignment", "description": "A role assigned to a user", "additionalProperties": false, "type": "object", "required": [ "id", "role", "created_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the role assignment", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the role was assigned", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } } } }, "user_ListResponse": { "title": "Users List Response", "description": "Response containing a list of users", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "User", "description": "User information with role assignments", "additionalProperties": false, "type": "object", "required": [ "id", "email", "created_at", "updated_at", "role_assignments" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "email": { "format": "email", "description": "The email address of the user", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name of the user", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name of the user", "examples": [ "Doe" ], "type": "string" }, "default_partner_id": { "format": "uuid", "description": "Default partner context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "default_merchant_id": { "format": "uuid", "description": "Default merchant context for the user", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the user", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "role_assignments": { "description": "Roles assigned to this user", "type": "array", "items": { "title": "Role Assignment", "description": "A role assigned to a user", "additionalProperties": false, "type": "object", "required": [ "id", "role", "created_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the role assignment", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the role was assigned", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } } } } }, "user_RoleAssignment": { "title": "Role Assignment", "description": "A role assigned to a user", "additionalProperties": false, "type": "object", "required": [ "id", "role", "created_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the role assignment", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the role was assigned", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } }, "user_RoleAssignmentInput": { "title": "Role Assignment Input", "description": "Input for assigning a role to a user", "additionalProperties": false, "type": "object", "required": [ "role" ], "properties": { "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" } } }, "user_RoleAssignmentResponse": { "title": "Role Assignment Response", "description": "Response containing a role assignment", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Role Assignment", "description": "A role assigned to a user", "additionalProperties": false, "type": "object", "required": [ "id", "role", "created_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the role assignment", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "role": { "description": "Role in format \"scopeType:roleName\" or \"scopeType:roleName:scopeId\"", "examples": [ "global:admin", "partner:admin:123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the role was assigned", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } }, "user_SuccessMessage": { "title": "Success Message Response", "description": "Response with a success message", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "message" ], "properties": { "message": { "description": "Success message", "examples": [ "User deleted successfully" ], "type": "string" } } } } }, "user_UpdateProfile": { "title": "Update Profile", "description": "Input for updating the current user profile", "additionalProperties": false, "type": "object", "properties": { "first_name": { "minLength": 1, "maxLength": 100, "description": "First name", "examples": [ "John" ], "type": "string" }, "last_name": { "minLength": 1, "maxLength": 100, "description": "Last name", "examples": [ "Doe" ], "type": "string" } } }, "user_ProfileResponse": { "title": "Profile Response", "description": "Response containing user profile", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Profile", "description": "User profile information", "additionalProperties": false, "type": "object", "required": [ "id", "email", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "User ID", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "email": { "format": "email", "description": "User email", "examples": [ "user@example.com" ], "type": "string" }, "first_name": { "description": "First name", "examples": [ "John" ], "type": "string" }, "last_name": { "description": "Last name", "examples": [ "Doe" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "Last update date", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } }, "adminProviderStatus_Detail": { "title": "Admin Provider Status Detail", "description": "Admin-only provider status detail including raw payload", "type": "object", "required": [ "id", "payment_request_id", "provider_request_id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "processed_at", "signature_valid", "event_id", "event_type", "processing_error", "raw_payload" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "signature_valid": { "type": "boolean" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processing_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_payload": { "description": "Raw payload received from the payment provider", "type": "object", "patternProperties": { "^(.*)$": {} } } } }, "adminProviderStatus_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "title": "Admin Provider Status Detail", "description": "Admin-only provider status detail including raw payload", "type": "object", "required": [ "id", "payment_request_id", "provider_request_id", "source", "provider_name", "provider_status", "processing_status", "provider_updated_at", "created_at", "observed_at", "processed_at", "signature_valid", "event_id", "event_type", "processing_error", "raw_payload" ], "properties": { "id": { "format": "uuid", "type": "string" }, "payment_request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "provider_request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "webhook", "polling", "finalization", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed", "conflict", "stale" ], "type": "string" }, "provider_updated_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "observed_at": { "format": "date-time", "type": "string" }, "processed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "signature_valid": { "type": "boolean" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processing_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_payload": { "description": "Raw payload received from the payment provider", "type": "object", "patternProperties": { "^(.*)$": {} } } } } } }, "adminTransfermate_GlobalAccountDetailsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "is_successful", "messages", "data" ], "properties": { "is_successful": { "type": "boolean" }, "messages": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "page": { "type": "number" }, "pages_count": { "type": "number" }, "records_per_page": { "type": "number" }, "total_records": { "type": "number" }, "data": { "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } }, "adminTransfermate_TransactionSummaryResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "is_successful", "messages", "transactions", "metadata" ], "properties": { "is_successful": { "type": "boolean" }, "messages": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "page": { "type": "number" }, "pages_count": { "type": "number" }, "records_per_page": { "type": "number" }, "total_records": { "type": "number" }, "transactions": { "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } } }, "metadata": { "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } }, "adminTransfermate_GlobalAccountByUserBankIdResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "resolved", "tm" ], "properties": { "resolved": { "type": "object", "required": [ "merchantId", "bankAccountId", "provider", "userBankId" ], "properties": { "merchantId": { "format": "uuid", "type": "string" }, "bankAccountId": { "format": "uuid", "type": "string" }, "provider": { "type": "string" }, "userBankId": { "type": "number" } } }, "tm": { "type": "object", "required": [ "is_successful", "messages", "data" ], "properties": { "is_successful": { "type": "boolean" }, "messages": { "type": "object", "patternProperties": { "^(.*)$": {} } }, "page": { "type": "number" }, "pages_count": { "type": "number" }, "records_per_page": { "type": "number" }, "total_records": { "type": "number" }, "data": { "type": "array", "items": { "type": "object", "patternProperties": { "^(.*)$": {} } } } } } } } } }, "bankAccountTransactions_Query": { "title": "Bank Account Transactions Query", "description": "Query parameters for bank-account transactions listing", "additionalProperties": false, "type": "object", "properties": { "date_from": { "format": "date", "description": "Filter from date (ISO 8601 YYYY-MM-DD)", "examples": [ "2026-04-01" ], "type": "string" }, "date_to": { "format": "date", "description": "Filter to date (ISO 8601 YYYY-MM-DD)", "examples": [ "2026-04-30" ], "type": "string" }, "page": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "type": "integer" }, "limit": { "default": 50, "description": "Rows per page (provider-limited)", "anyOf": [ { "const": 10, "type": "number" }, { "const": 20, "type": "number" }, { "const": 50, "type": "number" }, { "const": 100, "type": "number" } ] }, "direction": { "description": "Filter to money in or money out only. Omit for both.", "anyOf": [ { "const": "in", "type": "string" }, { "const": "out", "type": "string" } ] } } }, "bankAccountTransactions_Row": { "title": "Bank Account Transaction Row", "additionalProperties": false, "type": "object", "required": [ "date", "direction", "amount", "currency", "beneficiary", "running_balance", "transaction_type", "status", "web_transaction_id" ], "properties": { "date": { "description": "Transaction date (ISO 8601)", "type": "string" }, "direction": { "description": "Whether money moved into (\"in\") or out of (\"out\") the account", "anyOf": [ { "const": "in", "type": "string" }, { "const": "out", "type": "string" } ] }, "amount": { "description": "Absolute amount as a decimal string in the account currency", "examples": [ "2.00", "3.20" ], "type": "string" }, "currency": { "description": "ISO 4217 currency code", "type": "string" }, "beneficiary": { "description": "For Money In: the merchant the account belongs to. For Money Out: the customer being refunded (resolved via the linked Quidkey transaction).", "type": "string" }, "running_balance": { "description": "Running balance after this entry (decimal string)", "type": "string" }, "transaction_type": { "description": "Provider transaction type (Wire, ACH, ...)", "type": "string" }, "status": { "description": "Provider-reported status", "type": "string" }, "web_transaction_id": { "description": "Provider transaction id", "type": "string" }, "related_transaction_id": { "description": "Linked Quidkey Transaction id (for money-out rows)", "type": "string" }, "related_transaction_number": { "description": "Linked Quidkey Transaction.transaction_number for deep-link", "type": "string" } } }, "bankAccountTransactions_ListResponse": { "title": "Bank Account Transactions List Response", "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Bank Account Transaction Row", "additionalProperties": false, "type": "object", "required": [ "date", "direction", "amount", "currency", "beneficiary", "running_balance", "transaction_type", "status", "web_transaction_id" ], "properties": { "date": { "description": "Transaction date (ISO 8601)", "type": "string" }, "direction": { "description": "Whether money moved into (\"in\") or out of (\"out\") the account", "anyOf": [ { "const": "in", "type": "string" }, { "const": "out", "type": "string" } ] }, "amount": { "description": "Absolute amount as a decimal string in the account currency", "examples": [ "2.00", "3.20" ], "type": "string" }, "currency": { "description": "ISO 4217 currency code", "type": "string" }, "beneficiary": { "description": "For Money In: the merchant the account belongs to. For Money Out: the customer being refunded (resolved via the linked Quidkey transaction).", "type": "string" }, "running_balance": { "description": "Running balance after this entry (decimal string)", "type": "string" }, "transaction_type": { "description": "Provider transaction type (Wire, ACH, ...)", "type": "string" }, "status": { "description": "Provider-reported status", "type": "string" }, "web_transaction_id": { "description": "Provider transaction id", "type": "string" }, "related_transaction_id": { "description": "Linked Quidkey Transaction id (for money-out rows)", "type": "string" }, "related_transaction_number": { "description": "Linked Quidkey Transaction.transaction_number for deep-link", "type": "string" } } } }, "pagination": { "title": "Pagination Metadata", "description": "Metadata for paginated responses", "additionalProperties": false, "type": "object", "required": [ "total", "page", "limit", "totalPages", "hasNextPage", "hasPreviousPage" ], "properties": { "total": { "description": "Total number of items", "examples": [ 150 ], "type": "integer" }, "page": { "description": "Current page number", "examples": [ 1 ], "type": "integer" }, "limit": { "description": "Number of items per page", "examples": [ 25 ], "type": "integer" }, "totalPages": { "description": "Total number of pages", "examples": [ 6 ], "type": "integer" }, "hasNextPage": { "description": "Whether there is a next page", "examples": [ true ], "type": "boolean" }, "hasPreviousPage": { "description": "Whether there is a previous page", "examples": [ false ], "type": "boolean" } } } } }, "adminMerchantWebhookDelivery_Detail": { "title": "Admin Merchant Webhook Delivery Detail", "description": "Admin-only merchant webhook delivery detail including request/response payloads", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at", "request_payload", "response_body" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_id": { "format": "uuid", "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "request_payload": { "description": "The payload we sent to the merchant", "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "response_body": { "description": "Response body from merchant endpoint (truncated to 1KB)", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "adminMerchantWebhookDelivery_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "title": "Admin Merchant Webhook Delivery Detail", "description": "Admin-only merchant webhook delivery detail including request/response payloads", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "payment_provider_status_id", "webhook_url", "platform", "event_type", "status", "response_status_code", "duration_ms", "created_at", "request_payload", "response_body" ], "properties": { "id": { "format": "uuid", "type": "string" }, "transaction_id": { "format": "uuid", "type": "string" }, "merchant_id": { "format": "uuid", "type": "string" }, "payment_provider_status_id": { "description": "Optional ID of the PaymentProviderStatus event that triggered this delivery", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "webhook_url": { "description": "The URL the webhook was sent to", "type": "string" }, "platform": { "description": "Platform type", "enum": [ "embedded", "shopify", "woocommerce" ], "type": "string" }, "event_type": { "description": "Event type sent", "examples": [ "quidkey.payment_request.succeeded", "payment.success" ], "type": "string" }, "status": { "description": "Delivery status", "enum": [ "delivered", "failed" ], "type": "string" }, "response_status_code": { "description": "HTTP response status code from merchant endpoint", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "description": "Error message if delivery failed", "type": "string" }, "duration_ms": { "description": "Request duration in milliseconds", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "request_payload": { "description": "The payload we sent to the merchant", "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "response_body": { "description": "Response body from merchant endpoint (truncated to 1KB)", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "adminMerchantWebhookDelivery_ResendResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "new_delivery_id", "status", "response_status_code", "duration_ms" ], "properties": { "new_delivery_id": { "format": "uuid", "type": "string" }, "status": { "anyOf": [ { "const": "delivered", "type": "string" }, { "const": "failed", "type": "string" } ] }, "response_status_code": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error_message": { "type": "string" } } } } }, "onboarding_Report": { "title": "MerchantOnboardingReport", "description": "Onboarding readiness report for all providers", "additionalProperties": false, "type": "object", "required": [ "merchant_id", "providers" ], "properties": { "merchant_id": { "format": "uuid", "description": "The merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "providers": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "mode", "status", "requirements", "depends_on", "can_enroll" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "mode": { "description": "Provider operating mode", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "status": { "description": "Overall readiness status for this provider", "anyOf": [ { "const": "not_applicable", "type": "string" }, { "const": "not_ready", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "enrolling", "type": "string" }, { "const": "onboarded", "type": "string" } ] }, "requirements": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "code", "label", "met" ], "properties": { "code": { "description": "Requirement identifier", "examples": [ "LEGAL_ENTITY_EXISTS" ], "type": "string" }, "label": { "description": "Human-readable label", "examples": [ "Legal entity attached" ], "type": "string" }, "met": { "description": "Whether the requirement is met", "examples": [ true ], "type": "boolean" }, "blocker": { "description": "Reason the requirement is not met", "examples": [ "Merchant must have a legal entity" ], "type": "string" }, "problems": { "description": "Specific field-level problems", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field", "message" ], "properties": { "field": { "description": "The field that has the problem", "examples": [ "company_name" ], "type": "string" }, "message": { "description": "Description of the problem", "examples": [ "Company name is required" ], "type": "string" }, "value": { "description": "The problematic value" } } } } } } }, "depends_on": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "satisfied" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "satisfied": { "description": "Whether the dependency is satisfied", "examples": [ true ], "type": "boolean" } } } }, "can_enroll": { "description": "Whether the merchant can enroll with this provider right now", "examples": [ false ], "type": "boolean" } } } } } }, "onboarding_ReadinessResponse": { "title": "OnboardingReadinessResponse", "description": "Response containing the onboarding readiness report", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "MerchantOnboardingReport", "description": "Onboarding readiness report for all providers", "additionalProperties": false, "type": "object", "required": [ "merchant_id", "providers" ], "properties": { "merchant_id": { "format": "uuid", "description": "The merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "providers": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "mode", "status", "requirements", "depends_on", "can_enroll" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "mode": { "description": "Provider operating mode", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "status": { "description": "Overall readiness status for this provider", "anyOf": [ { "const": "not_applicable", "type": "string" }, { "const": "not_ready", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "enrolling", "type": "string" }, { "const": "onboarded", "type": "string" } ] }, "requirements": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "code", "label", "met" ], "properties": { "code": { "description": "Requirement identifier", "examples": [ "LEGAL_ENTITY_EXISTS" ], "type": "string" }, "label": { "description": "Human-readable label", "examples": [ "Legal entity attached" ], "type": "string" }, "met": { "description": "Whether the requirement is met", "examples": [ true ], "type": "boolean" }, "blocker": { "description": "Reason the requirement is not met", "examples": [ "Merchant must have a legal entity" ], "type": "string" }, "problems": { "description": "Specific field-level problems", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field", "message" ], "properties": { "field": { "description": "The field that has the problem", "examples": [ "company_name" ], "type": "string" }, "message": { "description": "Description of the problem", "examples": [ "Company name is required" ], "type": "string" }, "value": { "description": "The problematic value" } } } } } } }, "depends_on": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "satisfied" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "satisfied": { "description": "Whether the dependency is satisfied", "examples": [ true ], "type": "boolean" } } } }, "can_enroll": { "description": "Whether the merchant can enroll with this provider right now", "examples": [ false ], "type": "boolean" } } } } } } } }, "onboarding_ProviderReadinessResponse": { "title": "ProviderReadinessResponse", "description": "Response containing a single provider readiness result", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "provider", "mode", "status", "requirements", "depends_on", "can_enroll" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "mode": { "description": "Provider operating mode", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "status": { "description": "Overall readiness status for this provider", "anyOf": [ { "const": "not_applicable", "type": "string" }, { "const": "not_ready", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "enrolling", "type": "string" }, { "const": "onboarded", "type": "string" } ] }, "requirements": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "code", "label", "met" ], "properties": { "code": { "description": "Requirement identifier", "examples": [ "LEGAL_ENTITY_EXISTS" ], "type": "string" }, "label": { "description": "Human-readable label", "examples": [ "Legal entity attached" ], "type": "string" }, "met": { "description": "Whether the requirement is met", "examples": [ true ], "type": "boolean" }, "blocker": { "description": "Reason the requirement is not met", "examples": [ "Merchant must have a legal entity" ], "type": "string" }, "problems": { "description": "Specific field-level problems", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field", "message" ], "properties": { "field": { "description": "The field that has the problem", "examples": [ "company_name" ], "type": "string" }, "message": { "description": "Description of the problem", "examples": [ "Company name is required" ], "type": "string" }, "value": { "description": "The problematic value" } } } } } } }, "depends_on": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "satisfied" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "satisfied": { "description": "Whether the dependency is satisfied", "examples": [ true ], "type": "boolean" } } } }, "can_enroll": { "description": "Whether the merchant can enroll with this provider right now", "examples": [ false ], "type": "boolean" } } } } }, "onboarding_UpdateStatusInput": { "additionalProperties": false, "title": "UpdateOnboardingStatusInput", "type": "object", "required": [ "status" ], "properties": { "status": { "description": "The target state: 'enrolling' to start enrollment, 'onboarded' to complete it.", "anyOf": [ { "const": "enrolling", "type": "string" }, { "const": "onboarded", "type": "string" } ] } } }, "onboarding_ProviderListResponse": { "title": "ProviderListResponse", "description": "Response containing all registered onboarding providers", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "provider", "mode", "dependencies", "requirements", "supports_enrollment", "supports_completion" ], "properties": { "provider": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" }, "mode": { "description": "Provider operating mode", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "dependencies": { "description": "Providers that must be onboarded first", "type": "array", "items": { "description": "Provider identifier", "examples": [ "quidkey" ], "type": "string" } }, "requirements": { "description": "Requirements for this provider", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "code", "label" ], "properties": { "code": { "description": "Requirement identifier", "examples": [ "LEGAL_ENTITY_EXISTS" ], "type": "string" }, "label": { "description": "Human-readable label", "examples": [ "Legal entity attached" ], "type": "string" } } } }, "supports_enrollment": { "description": "Whether this provider supports the enrollment step", "type": "boolean" }, "supports_completion": { "description": "Whether this provider supports the completion step", "type": "boolean" } } } } } } } }, "goLive_Report": { "title": "GoLiveReport", "description": "Merchant-facing go-live status report", "additionalProperties": false, "type": "object", "required": [ "status", "steps", "progress", "celebration_pending" ], "properties": { "status": { "description": "Overall go-live status for the merchant", "anyOf": [ { "const": "in_progress", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "live", "type": "string" } ] }, "steps": { "description": "Ordered list of go-live steps with their statuses", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "key", "label", "status" ], "properties": { "key": { "description": "Step identifier", "examples": [ "business_information" ], "type": "string" }, "label": { "description": "Human-readable step label", "examples": [ "Complete business information" ], "type": "string" }, "status": { "description": "Status of a go-live step", "anyOf": [ { "const": "not_started", "type": "string" }, { "const": "incomplete", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "action_needed", "type": "string" } ] }, "hint": { "description": "Guidance text shown when step is not complete", "examples": [ "Some business details are still missing" ], "type": "string" } } } }, "progress": { "additionalProperties": false, "type": "object", "required": [ "completed", "total", "percentage" ], "properties": { "completed": { "description": "Number of completed steps", "examples": [ 2 ], "type": "integer" }, "total": { "description": "Total number of steps", "examples": [ 4 ], "type": "integer" }, "percentage": { "description": "Weighted progress percentage (0-100). Pending steps get partial credit.", "minimum": 0, "maximum": 100, "examples": [ 75 ], "type": "integer" } } }, "celebration_pending": { "description": "True when merchant just went live and celebration has not been shown yet", "examples": [ false ], "type": "boolean" } } }, "goLive_Response": { "title": "GoLiveResponse", "description": "Response containing the go-live status report", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "GoLiveReport", "description": "Merchant-facing go-live status report", "additionalProperties": false, "type": "object", "required": [ "status", "steps", "progress", "celebration_pending" ], "properties": { "status": { "description": "Overall go-live status for the merchant", "anyOf": [ { "const": "in_progress", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "live", "type": "string" } ] }, "steps": { "description": "Ordered list of go-live steps with their statuses", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "key", "label", "status" ], "properties": { "key": { "description": "Step identifier", "examples": [ "business_information" ], "type": "string" }, "label": { "description": "Human-readable step label", "examples": [ "Complete business information" ], "type": "string" }, "status": { "description": "Status of a go-live step", "anyOf": [ { "const": "not_started", "type": "string" }, { "const": "incomplete", "type": "string" }, { "const": "complete", "type": "string" }, { "const": "awaiting_verification", "type": "string" }, { "const": "action_needed", "type": "string" } ] }, "hint": { "description": "Guidance text shown when step is not complete", "examples": [ "Some business details are still missing" ], "type": "string" } } } }, "progress": { "additionalProperties": false, "type": "object", "required": [ "completed", "total", "percentage" ], "properties": { "completed": { "description": "Number of completed steps", "examples": [ 2 ], "type": "integer" }, "total": { "description": "Total number of steps", "examples": [ 4 ], "type": "integer" }, "percentage": { "description": "Weighted progress percentage (0-100). Pending steps get partial credit.", "minimum": 0, "maximum": 100, "examples": [ 75 ], "type": "integer" } } }, "celebration_pending": { "description": "True when merchant just went live and celebration has not been shown yet", "examples": [ false ], "type": "boolean" } } } } }, "paymentLink_CreateInput": { "additionalProperties": false, "type": "object", "required": [ "order" ], "properties": { "merchant_id": { "format": "uuid", "description": "Required for Partner authentication, forbidden for Merchant authentication", "type": "string" }, "order": { "additionalProperties": false, "type": "object", "required": [ "amount", "currency", "payment_reference" ], "properties": { "amount": { "minimum": 1, "examples": [ 1000 ], "description": "Amount in minor units (e.g., cents)", "type": "integer" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "payment_reference": { "maxLength": 18, "examples": [ "Invoice #123" ], "description": "Up to 18 chars, appears on customer bank statement", "type": "string" }, "order_id": { "examples": [ "ORD-123456" ], "description": "Merchant's order identifier", "type": "string" }, "locale": { "default": "en", "examples": [ "en", "pt", "es" ], "description": "BCP-47 locale tag", "type": "string" }, "test_transaction": { "examples": [ true ], "description": "Flag to force sandbox mode", "type": "boolean" } } }, "metadata": { "description": "Optional metadata to attach to the payment link", "type": "object", "patternProperties": { "^(.*)$": {} } }, "redirect_urls": { "additionalProperties": false, "type": "object", "required": [ "success_url", "failure_url" ], "properties": { "success_url": { "format": "uri", "maxLength": 2048, "description": "URL to redirect customer to after successful payment (HTTPS required in production)", "examples": [ "https://example.com/payment/success" ], "type": "string" }, "failure_url": { "format": "uri", "maxLength": 2048, "description": "URL to redirect customer to after failed payment (HTTPS required in production)", "examples": [ "https://example.com/payment/failure" ], "type": "string" } } } } }, "paymentLink_CreateResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "link_id", "payment_link_url", "expires_at", "status" ], "properties": { "link_id": { "format": "uuid", "description": "Internal payment link identifier (for reference only)", "type": "string" }, "payment_link_url": { "format": "uri", "description": "Full URL to share with customer. Contains a secure 64-char hex token (not the link_id). Token is only returned once.", "examples": [ "https://core.quidkey.com/payment-link/a1b2c3d4e5f6..." ], "type": "string" }, "expires_at": { "format": "date-time", "description": "ISO 8601 timestamp when link expires", "type": "string" }, "status": { "enum": [ "active" ], "description": "Payment link status", "type": "string" } } } } }, "paymentLink_DetailsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "status", "link_type", "merchant", "partner_branding", "order", "locale", "allowed_countries", "default_customer_country" ], "properties": { "status": { "enum": [ "active", "used", "expired", "cancelled" ], "description": "Current status of the payment link", "type": "string" }, "link_type": { "enum": [ "single_use", "reusable" ], "description": "Payment link type", "type": "string" }, "merchant": { "type": "object", "required": [ "brand_name", "uri", "branding" ], "properties": { "brand_name": { "description": "Merchant brand name", "type": "string" }, "uri": { "description": "Merchant URI identifier", "type": "string" }, "branding": { "anyOf": [ { "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, "partner_branding": { "anyOf": [ { "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "order": { "type": "object", "required": [ "amount", "currency", "payment_reference" ], "properties": { "amount": { "description": "Amount in minor units", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "type": "string" }, "payment_reference": { "description": "Payment reference", "type": "string" } } }, "locale": { "description": "Locale for the payment link", "type": "string" }, "allowed_countries": { "description": "Countries the customer can pay from", "type": "array", "items": { "type": "object", "required": [ "code", "name" ], "properties": { "code": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Payer country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "name": { "description": "Country name", "type": "string" } } } }, "default_customer_country": { "description": "Suggested default for the customer country selector, derived from the link currency. Null when the currency is shared across multiple countries (e.g. EUR) or the derived country is not in allowed_countries.", "anyOf": [ { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, { "type": "null" } ] } } } } }, "paymentLink_ConfirmInput": { "additionalProperties": false, "type": "object", "required": [ "customer" ], "properties": { "customer": { "title": "Payment Customer Input", "description": "Customer information for payment flows", "additionalProperties": false, "type": "object", "required": [ "name", "email", "phone", "country" ], "properties": { "name": { "minLength": 1, "description": "Full name of the customer", "examples": [ "John Doe" ], "type": "string" }, "email": { "format": "email", "description": "Email address of the customer", "examples": [ "john@example.com" ], "type": "string" }, "phone": { "minLength": 3, "description": "E.164-formatted phone number", "examples": [ "+351960123456" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" } } } } }, "paymentLink_ConfirmResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "payment_token", "expires_in" ], "properties": { "payment_token": { "pattern": "^ptok_", "description": "Payment token for loading embedded iframe", "examples": [ "ptok_550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "expires_in": { "minimum": 0, "maximum": 900, "description": "Token expiry in seconds", "examples": [ 900 ], "type": "integer" } } } } }, "paymentLink_ListQuery": { "additionalProperties": false, "type": "object", "properties": { "page": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 3 ], "type": "integer" }, "limit": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50 ], "type": "integer" }, "sort": { "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")", "examples": [ "created_at:desc", "amount:asc", "updated_at:desc" ], "type": "string" }, "status": { "enum": [ "active", "used", "expired", "cancelled" ], "description": "Payment link status", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Filter by merchant ID (admin/partner only)", "type": "string" }, "search": { "description": "Search by payment reference or order ID", "type": "string" } } }, "paymentLink_ListResponse": { "title": "Payment Link List Response", "description": "Paginated response with metadata", "additionalProperties": false, "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "merchant", "amount", "currency", "payment_reference", "order_id", "status", "link_type", "views_count", "first_viewed_at", "expires_at", "created_at", "transaction_id" ], "properties": { "id": { "format": "uuid", "type": "string" }, "merchant": { "type": "object", "required": [ "id", "brand_name" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brand_name": { "type": "string" } } }, "amount": { "description": "Amount in decimal format (e.g. \"10.00\")", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "type": "string" }, "payment_reference": { "type": "string" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "used", "expired", "cancelled" ], "description": "Payment link status", "type": "string" }, "link_type": { "enum": [ "single_use", "reusable" ], "type": "string" }, "views_count": { "type": "integer" }, "first_viewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expires_at": { "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "transaction_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] } } } }, "pagination": { "title": "Pagination Metadata", "description": "Metadata for paginated responses", "additionalProperties": false, "type": "object", "required": [ "total", "page", "limit", "totalPages", "hasNextPage", "hasPreviousPage" ], "properties": { "total": { "description": "Total number of items", "examples": [ 150 ], "type": "integer" }, "page": { "description": "Current page number", "examples": [ 1 ], "type": "integer" }, "limit": { "description": "Number of items per page", "examples": [ 25 ], "type": "integer" }, "totalPages": { "description": "Total number of pages", "examples": [ 6 ], "type": "integer" }, "hasNextPage": { "description": "Whether there is a next page", "examples": [ true ], "type": "boolean" }, "hasPreviousPage": { "description": "Whether there is a previous page", "examples": [ false ], "type": "boolean" } } } } }, "paymentLink_DetailResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "id", "merchant", "amount", "currency", "payment_reference", "order_id", "status", "link_type", "views_count", "first_viewed_at", "expires_at", "created_at", "transaction_id", "locale", "metadata", "payment_link_url", "redirect_urls" ], "properties": { "id": { "format": "uuid", "type": "string" }, "merchant": { "type": "object", "required": [ "id", "brand_name" ], "properties": { "id": { "format": "uuid", "type": "string" }, "brand_name": { "type": "string" } } }, "amount": { "description": "Amount in decimal format (e.g. \"10.00\")", "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "type": "string" }, "payment_reference": { "type": "string" }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "active", "used", "expired", "cancelled" ], "description": "Payment link status", "type": "string" }, "link_type": { "enum": [ "single_use", "reusable" ], "type": "string" }, "views_count": { "type": "integer" }, "first_viewed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expires_at": { "format": "date-time", "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "transaction_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "locale": { "type": "string" }, "metadata": { "anyOf": [ { "type": "object", "patternProperties": { "^(.*)$": {} } }, { "type": "null" } ] }, "payment_link_url": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "redirect_urls": { "anyOf": [ { "additionalProperties": false, "type": "object", "required": [ "success_url", "failure_url" ], "properties": { "success_url": { "format": "uri", "maxLength": 2048, "description": "URL to redirect customer to after successful payment (HTTPS required in production)", "examples": [ "https://example.com/payment/success" ], "type": "string" }, "failure_url": { "format": "uri", "maxLength": 2048, "description": "URL to redirect customer to after failed payment (HTTPS required in production)", "examples": [ "https://example.com/payment/failure" ], "type": "string" } } }, { "type": "null" } ] } } } } }, "paymentLink_ReceivableCurrenciesResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "currencies" ], "properties": { "currencies": { "type": "array", "items": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Receivable currency", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" } } } } } }, "crossBorderRefund_CreateRequest": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "description": "Refund amount in the customer currency", "examples": [ 100, 50.5 ], "minimum": 0.01, "type": "number" }, "reason": { "description": "Optional reason for the refund", "examples": [ "Customer request", "Duplicate payment", "Service not provided" ], "maxLength": 255, "type": "string" }, "target_status": { "description": "Target status for the refund. Defaults to RECEIVED (no transition). Use COMPLETED to create and execute the refund in one call.", "examples": [ "received", "completed" ], "anyOf": [ { "const": "received", "type": "string" }, { "const": "completed", "type": "string" } ] } } }, "crossBorderRefund_RefundableAmount": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Maximum refundable amount as a decimal string", "examples": [ "100.00", "75.50" ], "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "examples": [ "EUR", "GBP", "USD" ], "type": "string" } } }, "crossBorderRefund_RefundableAmountResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Maximum refundable amount as a decimal string", "examples": [ "100.00", "75.50" ], "type": "string" }, "currency": { "description": "Currency code (ISO 4217)", "examples": [ "EUR", "GBP", "USD" ], "type": "string" } } } } }, "crossBorderRefund_PathParams": { "type": "object", "required": [ "merchantId", "transactionId" ], "properties": { "merchantId": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "transactionId": { "format": "uuid", "description": "Original transaction ID", "type": "string" } } }, "crossBorderRefund_RefundReadinessResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "resolvable", "problems", "payout" ], "properties": { "resolvable": { "description": "True when the refund payout details resolve with no outstanding problems", "type": "boolean" }, "problems": { "description": "Outstanding problems preventing the refund; empty when resolvable", "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "payout": { "description": "Resolved payout details, or null when bank details could not be resolved", "anyOf": [ { "type": "object", "required": [ "currency", "country", "account_masked", "bic_resolved" ], "properties": { "currency": { "description": "Resolved payout currency (ISO 4217)", "examples": [ "EUR", "GBP" ], "type": "string" }, "country": { "description": "Resolved payout country (ISO 3166-1 alpha-2)", "examples": [ "DE", "GB" ], "type": "string" }, "account_masked": { "description": "Masked customer account identifier (last 4 shown)", "examples": [ "****3000" ], "type": "string" }, "bic_resolved": { "description": "Whether a BIC/SWIFT code was resolved for the payout account", "type": "boolean" } } }, { "type": "null" } ] } } } } }, "transaction_RefundListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "required": [ "id", "transaction_number", "amount", "currency", "transaction_type", "status", "cross_border", "deposit_country", "payout_country", "payout_currency", "exchange_rate", "converted_amount", "payout_at", "payout_batch_id", "test", "created_at", "updated_at", "settled_at", "platform", "refund_status", "can_refund", "payment_request" ], "properties": { "id": { "type": "string" }, "transaction_number": { "type": "string" }, "amount": { "description": "Transaction amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "transaction_type": { "enum": [ "payment", "refund", "reversal" ], "type": "string" }, "status": { "enum": [ "pending", "received", "fee_paid", "converted", "completed", "failed", "cancelled", "error", "unknown" ], "type": "string" }, "cross_border": { "type": "boolean" }, "deposit_country": { "type": "string" }, "payout_country": { "type": "string" }, "payout_currency": { "anyOf": [ { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, { "type": "null" } ] }, "exchange_rate": { "anyOf": [ { "description": "FX rate applied for cross-border conversion", "type": "number" }, { "type": "null" } ] }, "converted_amount": { "anyOf": [ { "description": "Amount in payout currency after FX conversion", "type": "number" }, { "type": "null" } ] }, "payout_at": { "anyOf": [ { "format": "date-time", "description": "When the payout settled", "type": "string" }, { "type": "null" } ] }, "payout_batch_id": { "anyOf": [ { "format": "uuid", "description": "ID of the payout batch this transaction belongs to", "type": "string" }, { "type": "null" } ] }, "test": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "enum": [ "shopify", "woocommerce", "embedded", "payment_link" ], "type": "string" }, { "type": "null" } ] }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "description": "Error code identifying the problem", "type": "string" }, "message": { "description": "Human-readable description of the problem", "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "target_status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "refund_status": { "description": "Current refund status for payment transactions", "anyOf": [ { "const": "refunding", "type": "string" }, { "const": "refunding_stuck", "type": "string" }, { "const": "refunding_failed", "type": "string" }, { "const": "partially_refunded", "type": "string" }, { "const": "fully_refunded", "type": "string" }, { "type": "null" } ] }, "can_refund": { "description": "Whether a refund can be initiated for this transaction", "type": "boolean" }, "payment_request": { "anyOf": [ { "type": "object", "required": [ "id", "order_id", "customer", "payment_token" ], "properties": { "id": { "format": "uuid", "type": "string" }, "order_id": { "description": "Merchant order ID", "examples": [ "ORD-2025-00123", "ORDER-456" ], "type": "string" }, "customer": { "anyOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" } } }, { "type": "null" } ] }, "payment_token": { "description": "Payment token", "examples": [ "tok_abc123def456" ], "type": "string" } } }, { "type": "null" } ] }, "fees": { "type": "object", "required": [ "total", "currency", "items" ], "properties": { "total": { "description": "Total fees in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "currency", "fee_type", "rate_type", "rate_value", "rate_unit", "rate_base", "notes", "settlement_status", "invoice_id", "settled_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "amount": { "description": "Fee amount in decimal format", "type": "number" }, "currency": { "type": "object", "required": [ "code", "symbol", "name", "minor_unit" ], "properties": { "code": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "symbol": { "description": "Currency symbol", "examples": [ "€", "£", "$" ], "type": "string" }, "name": { "description": "Currency name", "examples": [ "Euro", "British Pound", "US Dollar" ], "type": "string" }, "minor_unit": { "description": "Number of decimal places", "examples": [ 2 ], "type": "number" } } }, "fee_type": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "string" }, "rate_unit": { "type": "string" }, "rate_base": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_status": { "type": "string" }, "invoice_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } } } } } }, "customerBankAccount_Account": { "title": "Customer Bank Account", "description": "Customer bank account information for refund payouts", "additionalProperties": false, "type": "object", "required": [ "id", "currency", "country", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the customer bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account", "examples": [ "DE89370400440532013000" ], "type": "string" }, "account_number": { "description": "The account number of the bank account", "examples": [ "11223344" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (UK)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (US)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (Australia)", "examples": [ "062-000" ], "type": "string" }, "bic": { "description": "The BIC/SWIFT code of the bank account", "examples": [ "MARKDEF1100" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } }, "customerBankAccount_Input": { "title": "Customer Bank Account Input", "description": "Customer bank account creation/update input", "additionalProperties": false, "type": "object", "required": [ "account_holder_name", "currency", "country" ], "properties": { "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith" ], "type": "string" }, "customer_id": { "format": "uuid", "description": "The customer who owns this bank account. Required when minting accounts outside the Flinks-linking flow.", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "account_type": { "description": "US ACH account type", "examples": [ "checking" ], "anyOf": [ { "const": "checking", "type": "string" }, { "const": "savings", "type": "string" } ] }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account", "examples": [ "DE89370400440532013000" ], "type": "string" }, "account_number": { "description": "The account number of the bank account", "examples": [ "11223344" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (UK)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (US)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (Australia)", "examples": [ "062-000" ], "type": "string" }, "bic": { "description": "The BIC/SWIFT code of the bank account", "examples": [ "MARKDEF1100" ], "type": "string" } } }, "customerBankAccount_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Customer Bank Account", "description": "Customer bank account information for refund payouts", "additionalProperties": false, "type": "object", "required": [ "id", "currency", "country", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the customer bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account", "examples": [ "DE89370400440532013000" ], "type": "string" }, "account_number": { "description": "The account number of the bank account", "examples": [ "11223344" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (UK)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (US)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (Australia)", "examples": [ "062-000" ], "type": "string" }, "bic": { "description": "The BIC/SWIFT code of the bank account", "examples": [ "MARKDEF1100" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } }, "customerBankAccount_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Customer Bank Account", "description": "Customer bank account information for refund payouts", "additionalProperties": false, "type": "object", "required": [ "id", "currency", "country", "status", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the customer bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency of the bank account", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the bank account", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "status": { "description": "The status of the bank account", "examples": [ "active" ], "type": "string" }, "account_holder_name": { "description": "Name of the account holder", "examples": [ "John Smith" ], "type": "string" }, "iban": { "description": "The IBAN of the bank account", "examples": [ "DE89370400440532013000" ], "type": "string" }, "account_number": { "description": "The account number of the bank account", "examples": [ "11223344" ], "type": "string" }, "sort_code": { "description": "The sort code of the bank account (UK)", "examples": [ "123456" ], "type": "string" }, "routing_number": { "description": "The routing number of the bank account (US)", "examples": [ "123456789" ], "type": "string" }, "bban": { "description": "Basic Bank Account Number (e.g., Norway)", "examples": [ "86011117947" ], "type": "string" }, "plusgiro_number": { "description": "PlusGiro number (Sweden)", "examples": [ "41054685" ], "type": "string" }, "bsb": { "description": "Bank State Branch code (Australia)", "examples": [ "062-000" ], "type": "string" }, "bic": { "description": "The BIC/SWIFT code of the bank account", "examples": [ "MARKDEF1100" ], "type": "string" }, "created_at": { "format": "date-time", "description": "The creation date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The last update date of the bank account", "examples": [ "2024-03-19T12:00:00Z" ], "type": "string" } } } } } }, "deliveryReport_Input": { "title": "Delivery Report Input", "description": "Report from an external adapter about a finalization call to the external platform", "type": "object", "required": [ "platform", "finalization_type", "status" ], "properties": { "platform": { "description": "Platform that performed the finalization", "examples": [ "shopify", "woocommerce", "custom" ], "type": "string" }, "finalization_type": { "description": "Type of finalization performed", "examples": [ "payment_resolved", "payment_rejected", "refund_resolved", "refund_rejected" ], "type": "string" }, "external_reference": { "description": "External platform reference ID (e.g., Shopify GID)", "examples": [ "gid://shopify/PaymentSession/abc123" ], "type": "string" }, "request_payload": { "description": "The payload sent to the external platform", "type": "object", "patternProperties": { "^(.*)$": {} } }, "response": { "description": "The response received from the external platform", "type": "object", "patternProperties": { "^(.*)$": {} } }, "status": { "description": "Whether the finalization call succeeded or failed", "anyOf": [ { "const": "success", "type": "string" }, { "const": "failure", "type": "string" } ] }, "http_status": { "description": "HTTP status code from the external platform", "examples": [ 200, 400, 500 ], "type": "number" }, "duration_ms": { "description": "How long the finalization call took in milliseconds", "examples": [ 150, 342, 1200 ], "type": "number" }, "payment_provider_status_id": { "format": "uuid", "description": "Correlation ID linking to the PaymentProviderStatus that triggered this", "type": "string" } } }, "deliveryReport_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "format": "uuid", "type": "string" }, "message": { "type": "string" } } } } }, "invitation_Invitation": { "title": "Invitation", "description": "An invitation to join a partner or merchant with a specific role", "additionalProperties": false, "type": "object", "required": [ "id", "email", "scope_type", "scope_id", "role", "status", "expires_at", "invited_by_user_id", "accepted_at", "accepted_by_user_id", "last_sent_at", "send_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Invitation ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "The scope this invitation grants access to", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_id": { "format": "uuid", "description": "Partner or merchant ID the invitation is for", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "role": { "description": "Role to grant upon acceptance (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" }, { "const": "revoked", "type": "string" }, { "const": "expired", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "invited_by_user_id": { "description": "User ID of the person who created this invitation (null if user was deleted)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "accepted_at": { "description": "When the invitation was accepted", "examples": [ null ], "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "accepted_by_user_id": { "description": "User ID of the person who accepted", "examples": [ null ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "last_sent_at": { "format": "date-time", "description": "When the invitation email was last sent", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "send_count": { "description": "Number of times the invitation email has been sent", "examples": [ 1 ], "type": "number" }, "created_at": { "format": "date-time", "description": "When the invitation was created", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" } } }, "invitation_InvitationWithLink": { "title": "Invitation With Link", "description": "Invitation with one-time link (returned on create/resend only)", "type": "object", "required": [ "id", "email", "scope_type", "scope_id", "role", "status", "expires_at", "invited_by_user_id", "accepted_at", "accepted_by_user_id", "last_sent_at", "send_count", "created_at", "invitation_link" ], "properties": { "id": { "format": "uuid", "description": "Invitation ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "The scope this invitation grants access to", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_id": { "format": "uuid", "description": "Partner or merchant ID the invitation is for", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "role": { "description": "Role to grant upon acceptance (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" }, { "const": "revoked", "type": "string" }, { "const": "expired", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "invited_by_user_id": { "description": "User ID of the person who created this invitation (null if user was deleted)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "accepted_at": { "description": "When the invitation was accepted", "examples": [ null ], "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "accepted_by_user_id": { "description": "User ID of the person who accepted", "examples": [ null ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "last_sent_at": { "format": "date-time", "description": "When the invitation email was last sent", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "send_count": { "description": "Number of times the invitation email has been sent", "examples": [ 1 ], "type": "number" }, "created_at": { "format": "date-time", "description": "When the invitation was created", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "invitation_link": { "format": "uri", "description": "One-time invitation link (only returned on create/resend, not stored server-side)", "examples": [ "https://console.example.com/invitations/accept?token=abc123..." ], "type": "string" } } }, "invitation_CreateBody": { "title": "Create Invitation Body", "description": "Request body for creating an invitation", "additionalProperties": false, "type": "object", "required": [ "email", "role" ], "properties": { "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "role": { "description": "Role to grant (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" } } }, "invitation_AcceptBody": { "title": "Accept Invitation Body", "description": "Request body for accepting an invitation", "additionalProperties": false, "type": "object", "required": [ "token" ], "properties": { "token": { "description": "Raw invitation token from the email link", "examples": [ "a1b2c3d4e5f6..." ], "type": "string" } } }, "invitation_Preview": { "title": "Invitation Preview", "description": "Minimal invitation preview — safe for unauthenticated display", "additionalProperties": false, "type": "object", "required": [ "email", "scope_type", "scope_name", "role", "expires_at", "status" ], "properties": { "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "Scope type of the invitation", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_name": { "description": "Display name of the partner or merchant", "examples": [ "Acme Corp" ], "type": "string" }, "role": { "description": "Role that will be granted", "examples": [ "admin" ], "type": "string" }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "type": "string" } } }, "invitation_AcceptResult": { "title": "Invitation Accept Result", "description": "Result of accepting an invitation", "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "description": "Result of the accept operation: \"accepted\" for new role, \"already_granted\" if user already has the role", "examples": [ "accepted" ], "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "already_granted", "type": "string" } ] } } }, "invitation_Response": { "title": "Invitation Response", "description": "Response containing a single invitation", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invitation", "description": "An invitation to join a partner or merchant with a specific role", "additionalProperties": false, "type": "object", "required": [ "id", "email", "scope_type", "scope_id", "role", "status", "expires_at", "invited_by_user_id", "accepted_at", "accepted_by_user_id", "last_sent_at", "send_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Invitation ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "The scope this invitation grants access to", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_id": { "format": "uuid", "description": "Partner or merchant ID the invitation is for", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "role": { "description": "Role to grant upon acceptance (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" }, { "const": "revoked", "type": "string" }, { "const": "expired", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "invited_by_user_id": { "description": "User ID of the person who created this invitation (null if user was deleted)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "accepted_at": { "description": "When the invitation was accepted", "examples": [ null ], "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "accepted_by_user_id": { "description": "User ID of the person who accepted", "examples": [ null ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "last_sent_at": { "format": "date-time", "description": "When the invitation email was last sent", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "send_count": { "description": "Number of times the invitation email has been sent", "examples": [ 1 ], "type": "number" }, "created_at": { "format": "date-time", "description": "When the invitation was created", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" } } } } }, "invitation_WithLinkResponse": { "title": "Invitation With Link Response", "description": "Response containing an invitation with one-time link (create/resend)", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invitation With Link", "description": "Invitation with one-time link (returned on create/resend only)", "type": "object", "required": [ "id", "email", "scope_type", "scope_id", "role", "status", "expires_at", "invited_by_user_id", "accepted_at", "accepted_by_user_id", "last_sent_at", "send_count", "created_at", "invitation_link" ], "properties": { "id": { "format": "uuid", "description": "Invitation ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "The scope this invitation grants access to", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_id": { "format": "uuid", "description": "Partner or merchant ID the invitation is for", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "role": { "description": "Role to grant upon acceptance (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" }, { "const": "revoked", "type": "string" }, { "const": "expired", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "invited_by_user_id": { "description": "User ID of the person who created this invitation (null if user was deleted)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "accepted_at": { "description": "When the invitation was accepted", "examples": [ null ], "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "accepted_by_user_id": { "description": "User ID of the person who accepted", "examples": [ null ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "last_sent_at": { "format": "date-time", "description": "When the invitation email was last sent", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "send_count": { "description": "Number of times the invitation email has been sent", "examples": [ 1 ], "type": "number" }, "created_at": { "format": "date-time", "description": "When the invitation was created", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "invitation_link": { "format": "uri", "description": "One-time invitation link (only returned on create/resend, not stored server-side)", "examples": [ "https://console.example.com/invitations/accept?token=abc123..." ], "type": "string" } } } } }, "invitation_ListResponse": { "title": "Invitation List Response", "description": "Response containing a list of invitations", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Invitation", "description": "An invitation to join a partner or merchant with a specific role", "additionalProperties": false, "type": "object", "required": [ "id", "email", "scope_type", "scope_id", "role", "status", "expires_at", "invited_by_user_id", "accepted_at", "accepted_by_user_id", "last_sent_at", "send_count", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Invitation ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "The scope this invitation grants access to", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_id": { "format": "uuid", "description": "Partner or merchant ID the invitation is for", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "role": { "description": "Role to grant upon acceptance (e.g. admin, admin-read-only)", "examples": [ "admin" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" }, { "const": "revoked", "type": "string" }, { "const": "expired", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "invited_by_user_id": { "description": "User ID of the person who created this invitation (null if user was deleted)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "accepted_at": { "description": "When the invitation was accepted", "examples": [ null ], "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "accepted_by_user_id": { "description": "User ID of the person who accepted", "examples": [ null ], "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "last_sent_at": { "format": "date-time", "description": "When the invitation email was last sent", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" }, "send_count": { "description": "Number of times the invitation email has been sent", "examples": [ 1 ], "type": "number" }, "created_at": { "format": "date-time", "description": "When the invitation was created", "examples": [ "2026-02-05T12:00:00.000Z" ], "type": "string" } } } } } }, "invitation_PreviewResponse": { "title": "Invitation Preview Response", "description": "Response containing an invitation preview", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invitation Preview", "description": "Minimal invitation preview — safe for unauthenticated display", "additionalProperties": false, "type": "object", "required": [ "email", "scope_type", "scope_name", "role", "expires_at", "status" ], "properties": { "email": { "format": "email", "description": "Invitee email address", "examples": [ "invitee@example.com" ], "type": "string" }, "scope_type": { "description": "Scope type of the invitation", "examples": [ "partner" ], "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "scope_name": { "description": "Display name of the partner or merchant", "examples": [ "Acme Corp" ], "type": "string" }, "role": { "description": "Role that will be granted", "examples": [ "admin" ], "type": "string" }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "examples": [ "2026-02-12T00:00:00.000Z" ], "type": "string" }, "status": { "description": "Current status of the invitation", "examples": [ "pending" ], "type": "string" } } } } }, "invitation_AcceptResponse": { "title": "Invitation Accept Response", "description": "Response from accepting an invitation", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Invitation Accept Result", "description": "Result of accepting an invitation", "additionalProperties": false, "type": "object", "required": [ "status" ], "properties": { "status": { "description": "Result of the accept operation: \"accepted\" for new role, \"already_granted\" if user already has the role", "examples": [ "accepted" ], "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "already_granted", "type": "string" } ] } } } } }, "invitation_ListQuery": { "title": "Invitation List Query", "description": "Query parameters for listing invitations", "additionalProperties": false, "type": "object", "properties": { "status": { "description": "Filter invitations by status (default: pending)", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "all", "type": "string" } ] } } }, "accountInformation_CreateSessionInput": { "title": "Create Account Information Session Input", "description": "Request body for creating an account information (bank linking) session", "additionalProperties": false, "type": "object", "properties": { "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Bank account country to link. Currently only US is supported for account verification.", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "redirect_url": { "format": "uri", "description": "URL to redirect the user after completing the provider flow", "examples": [ "https://dashboard.example.com/bank-accounts/linked" ], "type": "string" }, "include_holder_identity": { "description": "Include account holder identity (name, address, email, phone)", "default": false, "type": "boolean" }, "include_transactions": { "description": "Include transaction history", "default": false, "type": "boolean" }, "transaction_days": { "description": "Transaction history period in days", "default": 90, "anyOf": [ { "const": 90, "type": "number" }, { "const": 365, "type": "number" } ] }, "include_statements": { "description": "Include PDF bank statements", "default": false, "type": "boolean" }, "statement_count": { "description": "Number of statements to retrieve", "minimum": 1, "maximum": 12, "default": 1, "type": "number" } } }, "accountInformation_CreateSessionResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "session_id", "verification_token", "expires_at" ], "properties": { "session_id": { "format": "uuid", "description": "Session ID for internal use (polling status, confirm accounts)", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "verification_token": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "Secure token for building public verification URLs. Only returned once, never stored. Use this in verification link URLs (not session_id).", "examples": [ "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" ], "type": "string" }, "expires_at": { "format": "date-time", "description": "When the session expires", "examples": [ "2024-03-19T13:30:00Z" ], "type": "string" } } } } }, "accountInformation_Session": { "title": "Account Information Session", "description": "Account information session details", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider_name", "status", "connect_url", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant that owns this session", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "provider_name": { "description": "Provider name (e.g. flinks)", "examples": [ "flinks" ], "type": "string" }, "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "connect_url": { "format": "uri", "description": "Provider connect URL (for pending sessions)", "type": "string" }, "redirect_url": { "format": "uri", "description": "Client redirect URL after completion", "type": "string" }, "expires_at": { "format": "date-time", "description": "When the session expires", "type": "string" }, "requested_data_types": { "additionalProperties": false, "type": "object", "required": [ "account_identity", "holder_identity", "transaction_history", "statements" ], "properties": { "account_identity": { "type": "boolean" }, "holder_identity": { "type": "boolean" }, "transaction_history": { "type": "boolean" }, "statements": { "type": "boolean" } } }, "retrieved_accounts": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "provider_account_id", "account_number_masked", "account_type", "institution_name", "currency", "country" ], "properties": { "provider_account_id": { "type": "string" }, "account_number_masked": { "type": "string" }, "account_type": { "type": "string" }, "holder_name": { "type": "string" }, "institution_name": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" } } } }, "error_message": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } }, "accountInformation_SessionResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Account Information Session", "description": "Account information session details", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider_name", "status", "connect_url", "expires_at", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant that owns this session", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "provider_name": { "description": "Provider name (e.g. flinks)", "examples": [ "flinks" ], "type": "string" }, "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "connect_url": { "format": "uri", "description": "Provider connect URL (for pending sessions)", "type": "string" }, "redirect_url": { "format": "uri", "description": "Client redirect URL after completion", "type": "string" }, "expires_at": { "format": "date-time", "description": "When the session expires", "type": "string" }, "requested_data_types": { "additionalProperties": false, "type": "object", "required": [ "account_identity", "holder_identity", "transaction_history", "statements" ], "properties": { "account_identity": { "type": "boolean" }, "holder_identity": { "type": "boolean" }, "transaction_history": { "type": "boolean" }, "statements": { "type": "boolean" } } }, "retrieved_accounts": { "type": "array", "items": { "additionalProperties": true, "type": "object", "required": [ "provider_account_id", "account_number_masked", "account_type", "institution_name", "currency", "country" ], "properties": { "provider_account_id": { "type": "string" }, "account_number_masked": { "type": "string" }, "account_type": { "type": "string" }, "holder_name": { "type": "string" }, "institution_name": { "type": "string" }, "currency": { "type": "string" }, "country": { "type": "string" } } } }, "error_message": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } }, "accountInformation_RedirectQuery": { "title": "Account Information Redirect Query", "description": "Query parameters for account information redirect endpoint", "additionalProperties": true, "type": "object", "required": [ "token" ], "properties": { "token": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "Verification token (embedded in provider redirect URL when creating session)", "type": "string" }, "LoginId": { "description": "Flinks login ID returned after user completes flow", "type": "string" }, "loginId": { "description": "Flinks login ID (lowercase variant)", "type": "string" } } }, "accountInformation_ConfirmAccountsInput": { "title": "Confirm Accounts Input", "description": "Request body for confirming selected accounts from an account information session", "additionalProperties": false, "type": "object", "required": [ "selected_account_ids" ], "properties": { "selected_account_ids": { "minItems": 1, "description": "At least one account must be selected", "type": "array", "items": { "description": "Provider account IDs from retrieved_accounts to create as bank accounts", "examples": [ [ "acc-123", "acc-456" ] ], "type": "string" } } } }, "accountInformation_ConfirmAccountsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "created", "skipped" ], "properties": { "created": { "description": "Bank accounts created from selected accounts", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "account_number_masked", "routing_number", "currency", "country", "status", "account_type", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Bank account ID", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "account_number_masked": { "description": "Masked account number (e.g. ****7890)", "examples": [ "****7890" ], "type": "string" }, "routing_number": { "description": "US routing number (9 digits)", "examples": [ "021000021" ], "type": "string" }, "currency": { "description": "Currency code", "examples": [ "USD" ], "type": "string" }, "country": { "description": "Country code", "examples": [ "US" ], "type": "string" }, "status": { "description": "Account status", "examples": [ "active" ], "type": "string" }, "account_type": { "description": "Account type", "examples": [ "owned" ], "type": "string" }, "created_at": { "format": "date-time", "description": "When the account was created", "type": "string" } } } }, "skipped": { "description": "Provider account IDs skipped (duplicates)", "type": "array", "items": { "type": "string" } } } } } }, "accountInformation_VerificationDetailsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Verification Details", "description": "Public verification session details for the consent page", "additionalProperties": false, "type": "object", "required": [ "status", "connect_url", "expires_at", "merchant", "options" ], "properties": { "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "connect_url": { "description": "Provider connect URL for the iframe", "type": "string" }, "expires_at": { "format": "date-time", "description": "When the session expires", "type": "string" }, "merchant": { "additionalProperties": false, "type": "object", "required": [ "name" ], "properties": { "name": { "description": "Merchant legal name", "examples": [ "Acme Corp" ], "type": "string" }, "brand_name": { "description": "Merchant brand/display name", "examples": [ "Acme Store" ], "type": "string" } } }, "options": { "additionalProperties": false, "type": "object", "required": [ "include_holder_identity", "include_transactions", "include_statements" ], "properties": { "include_holder_identity": { "description": "Whether holder identity (name, address) is requested", "type": "boolean" }, "include_transactions": { "description": "Whether transaction history is requested", "type": "boolean" }, "transaction_days": { "description": "Number of days of transaction history", "examples": [ 90 ], "type": "number" }, "include_statements": { "description": "Whether PDF statements are requested", "type": "boolean" }, "statement_count": { "description": "Number of statements requested", "examples": [ 1 ], "type": "number" } } } } } } }, "accountInformation_ActivateVerificationResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "connect_url" ], "properties": { "connect_url": { "description": "Fresh provider connect URL for the iframe", "examples": [ "https://connect.example.com/v2/?authorizeToken=..." ], "type": "string" } } } } }, "accountInformation_ExpireSessionsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "expired_count" ], "properties": { "expired_count": { "description": "Number of sessions expired", "type": "number" } } } } }, "accountInformation_ListSessionsQuery": { "title": "List Sessions Query", "description": "Query parameters for listing account information sessions", "additionalProperties": false, "type": "object", "properties": { "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "limit": { "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of sessions to return", "type": "integer" }, "cursor": { "description": "Cursor for pagination (opaque string from previous response)", "type": "string" } } }, "accountInformation_ListSessionsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "sessions", "next_cursor" ], "properties": { "sessions": { "type": "array", "items": { "title": "Session Summary", "description": "Account information session summary for list responses", "additionalProperties": false, "type": "object", "required": [ "id", "status", "created_at", "expires_at", "verification_url" ], "properties": { "id": { "format": "uuid", "description": "Session ID", "type": "string" }, "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "requested_data_types": { "additionalProperties": false, "type": "object", "required": [ "account_identity", "holder_identity", "transaction_history", "statements" ], "properties": { "account_identity": { "type": "boolean" }, "holder_identity": { "type": "boolean" }, "transaction_history": { "type": "boolean" }, "statements": { "type": "boolean" } } }, "verification_url": { "description": "Copyable verification URL (only available for pending sessions)", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "next_cursor": { "description": "Cursor for the next page, or null if no more results", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "accountInformation_CancelSessionResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Session Summary", "description": "Account information session summary for list responses", "additionalProperties": false, "type": "object", "required": [ "id", "status", "created_at", "expires_at", "verification_url" ], "properties": { "id": { "format": "uuid", "description": "Session ID", "type": "string" }, "status": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "requested_data_types": { "additionalProperties": false, "type": "object", "required": [ "account_identity", "holder_identity", "transaction_history", "statements" ], "properties": { "account_identity": { "type": "boolean" }, "holder_identity": { "type": "boolean" }, "transaction_history": { "type": "boolean" }, "statements": { "type": "boolean" } } }, "verification_url": { "description": "Copyable verification URL (only available for pending sessions)", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "accountInformationProviderStatus_Event": { "title": "Account Information Provider Status Event", "description": "Provider status event summary for account information sessions", "additionalProperties": false, "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "redirect", "webhook", "polling", "system", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" } } }, "accountInformationProviderStatus_ListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Account Information Provider Status Event", "description": "Provider status event summary for account information sessions", "additionalProperties": false, "type": "object", "required": [ "id", "source", "provider_name", "provider_status", "processing_status", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "source": { "enum": [ "redirect", "webhook", "polling", "system", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "processing_error": { "type": "string" } } } } } }, "adminAccountInformationProviderStatus_Detail": { "title": "Admin Account Information Provider Status Detail", "description": "Admin-only account information provider status detail including raw payload", "type": "object", "required": [ "id", "account_information_session_id", "merchant_bank_account_id", "source", "provider_name", "provider_status", "processing_status", "created_at", "updated_at", "event_id", "event_type", "processing_error", "raw_payload" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_information_session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_bank_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "redirect", "webhook", "polling", "system", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processing_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_payload": { "description": "Raw payload received from account information provider", "type": "object", "patternProperties": { "^(.*)$": {} } } } }, "adminAccountInformationProviderStatus_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Admin Account Information Provider Status Detail", "description": "Admin-only account information provider status detail including raw payload", "type": "object", "required": [ "id", "account_information_session_id", "merchant_bank_account_id", "source", "provider_name", "provider_status", "processing_status", "created_at", "updated_at", "event_id", "event_type", "processing_error", "raw_payload" ], "properties": { "id": { "format": "uuid", "type": "string" }, "account_information_session_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_bank_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "redirect", "webhook", "polling", "system", "admin" ], "type": "string" }, "provider_name": { "type": "string" }, "provider_status": { "type": "string" }, "processing_status": { "enum": [ "received", "processed", "ignored", "failed" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processing_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_payload": { "description": "Raw payload received from account information provider", "type": "object", "patternProperties": { "^(.*)$": {} } } } } } }, "branding_Branding": { "title": "Branding Info", "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "branding_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "anyOf": [ { "title": "Branding Info", "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] } } }, "branding_Update": { "title": "Branding Update", "additionalProperties": false, "type": "object", "properties": { "primary_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ] } } }, "branding_PartnerUpdate": { "title": "Partner Branding Update", "additionalProperties": false, "type": "object", "properties": { "primary_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "branding_ExtractResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "logo_url", "icon_url", "primary_color", "secondary_color", "confidence" ], "properties": { "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "type": "number" } } } } }, "shareholderInvitation_ShareholderInvitation": { "title": "Shareholder Invitation", "description": "An invitation for a shareholder to complete KYC onboarding", "additionalProperties": false, "type": "object", "required": [ "id", "email", "merchant_id", "shareholder_type", "shareholder_country_iso2", "status", "expires_at", "accepted_at", "opened_at", "current_step", "current_step_name", "steps_completed", "core_shareholder_id", "invited_by_user_id", "created_at", "display_status", "total_steps" ], "properties": { "id": { "format": "uuid", "description": "Shareholder invitation ID", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant this invitation belongs to", "type": "string" }, "shareholder_type": { "description": "Type of shareholder (individual)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareholder_country_iso2": { "description": "Country ISO2 code set during onboarding", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "Current status of the invitation", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "accepted_at": { "description": "When the invitation was accepted", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "opened_at": { "description": "When the invitation link was first opened", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_step": { "description": "Current wizard step (0-3)", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Array of completed step numbers", "type": "array", "items": { "type": "number" } }, "core_shareholder_id": { "description": "ID of the shareholder created in Core (set after step 1)", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "invited_by_user_id": { "description": "User ID of the person who created this invitation", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the invitation was created", "type": "string" }, "display_status": { "description": "Computed display status for UI", "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "filling_details", "type": "string" }, { "const": "invite_created", "type": "string" }, { "const": "invite_sent", "type": "string" } ] }, "total_steps": { "description": "Total number of wizard steps", "type": "number" } } }, "shareholderInvitation_WithLink": { "title": "Shareholder Invitation With Link", "description": "Shareholder invitation with onboarding link", "type": "object", "required": [ "id", "email", "merchant_id", "shareholder_type", "shareholder_country_iso2", "status", "expires_at", "accepted_at", "opened_at", "current_step", "current_step_name", "steps_completed", "core_shareholder_id", "invited_by_user_id", "created_at", "display_status", "total_steps", "invitation_link" ], "properties": { "id": { "format": "uuid", "description": "Shareholder invitation ID", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant this invitation belongs to", "type": "string" }, "shareholder_type": { "description": "Type of shareholder (individual)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareholder_country_iso2": { "description": "Country ISO2 code set during onboarding", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "Current status of the invitation", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "accepted_at": { "description": "When the invitation was accepted", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "opened_at": { "description": "When the invitation link was first opened", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_step": { "description": "Current wizard step (0-3)", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Array of completed step numbers", "type": "array", "items": { "type": "number" } }, "core_shareholder_id": { "description": "ID of the shareholder created in Core (set after step 1)", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "invited_by_user_id": { "description": "User ID of the person who created this invitation", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the invitation was created", "type": "string" }, "display_status": { "description": "Computed display status for UI", "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "filling_details", "type": "string" }, { "const": "invite_created", "type": "string" }, { "const": "invite_sent", "type": "string" } ] }, "total_steps": { "description": "Total number of wizard steps", "type": "number" }, "invitation_link": { "description": "Invitation link for the shareholder to complete onboarding", "type": "string" }, "email_sent": { "description": "Whether the invitation email was successfully sent", "type": "boolean" } } }, "shareholderInvitation_CreateBody": { "title": "Create Shareholder Invitation Body", "description": "Request body for creating a shareholder invitation", "additionalProperties": false, "type": "object", "required": [ "email" ], "properties": { "email": { "format": "email", "description": "Email address of the shareholder to invite", "type": "string" }, "send_email": { "description": "Whether to email the invitation now. Defaults to true when omitted.", "type": "boolean" } } }, "shareholderInvitation_Preview": { "title": "Shareholder Invitation Preview", "description": "Minimal preview for unauthenticated display", "additionalProperties": false, "type": "object", "required": [ "merchant_name", "email", "status", "current_step", "current_step_name", "steps_completed", "total_steps", "expires_at", "merchant_country_iso2" ], "properties": { "merchant_name": { "description": "Display name of the merchant", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "status": { "description": "Current status", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "current_step": { "description": "Current wizard step", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Completed steps", "type": "array", "items": { "type": "number" } }, "total_steps": { "description": "Total number of wizard steps", "type": "number" }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "merchant_country_iso2": { "description": "Merchant country ISO2 for preselection", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "shareholderInvitation_SubmitStepBody": { "title": "Submit Step Body", "description": "Request body for submitting a wizard step. The payload field accepts step-specific data; per-step validation is applied using Step1PayloadSchema/Step2PayloadSchema.", "additionalProperties": false, "type": "object", "required": [ "token", "step" ], "properties": { "token": { "description": "Raw invitation token", "type": "string" }, "step": { "description": "Step number being submitted (0, 1, or 2)", "type": "number" }, "payload": { "description": "Step-specific payload data. Step 0: no payload. Step 1: validated against Step1PayloadSchema (legal_entity + ownership_details). Step 2: validated against Step2PayloadSchema (legal_entity with citizenship + residency_address). Per-step schema validation is enforced before processing." } } }, "shareholderInvitation_SubmitStepResult": { "title": "Submit Step Result", "description": "Result of submitting a wizard step", "additionalProperties": false, "type": "object", "required": [ "next_step" ], "properties": { "next_step": { "description": "Next step to display, or null if complete", "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, "shareholderInvitation_Response": { "title": "Shareholder Invitation Response", "description": "Response containing a single shareholder invitation", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Shareholder Invitation", "description": "An invitation for a shareholder to complete KYC onboarding", "additionalProperties": false, "type": "object", "required": [ "id", "email", "merchant_id", "shareholder_type", "shareholder_country_iso2", "status", "expires_at", "accepted_at", "opened_at", "current_step", "current_step_name", "steps_completed", "core_shareholder_id", "invited_by_user_id", "created_at", "display_status", "total_steps" ], "properties": { "id": { "format": "uuid", "description": "Shareholder invitation ID", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant this invitation belongs to", "type": "string" }, "shareholder_type": { "description": "Type of shareholder (individual)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareholder_country_iso2": { "description": "Country ISO2 code set during onboarding", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "Current status of the invitation", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "accepted_at": { "description": "When the invitation was accepted", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "opened_at": { "description": "When the invitation link was first opened", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_step": { "description": "Current wizard step (0-3)", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Array of completed step numbers", "type": "array", "items": { "type": "number" } }, "core_shareholder_id": { "description": "ID of the shareholder created in Core (set after step 1)", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "invited_by_user_id": { "description": "User ID of the person who created this invitation", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the invitation was created", "type": "string" }, "display_status": { "description": "Computed display status for UI", "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "filling_details", "type": "string" }, { "const": "invite_created", "type": "string" }, { "const": "invite_sent", "type": "string" } ] }, "total_steps": { "description": "Total number of wizard steps", "type": "number" } } } } }, "shareholderInvitation_WithLinkResponse": { "title": "Shareholder Invitation With Link Response", "description": "Response containing a shareholder invitation with link", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Shareholder Invitation With Link", "description": "Shareholder invitation with onboarding link", "type": "object", "required": [ "id", "email", "merchant_id", "shareholder_type", "shareholder_country_iso2", "status", "expires_at", "accepted_at", "opened_at", "current_step", "current_step_name", "steps_completed", "core_shareholder_id", "invited_by_user_id", "created_at", "display_status", "total_steps", "invitation_link" ], "properties": { "id": { "format": "uuid", "description": "Shareholder invitation ID", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant this invitation belongs to", "type": "string" }, "shareholder_type": { "description": "Type of shareholder (individual)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareholder_country_iso2": { "description": "Country ISO2 code set during onboarding", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "Current status of the invitation", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "accepted_at": { "description": "When the invitation was accepted", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "opened_at": { "description": "When the invitation link was first opened", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_step": { "description": "Current wizard step (0-3)", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Array of completed step numbers", "type": "array", "items": { "type": "number" } }, "core_shareholder_id": { "description": "ID of the shareholder created in Core (set after step 1)", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "invited_by_user_id": { "description": "User ID of the person who created this invitation", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the invitation was created", "type": "string" }, "display_status": { "description": "Computed display status for UI", "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "filling_details", "type": "string" }, { "const": "invite_created", "type": "string" }, { "const": "invite_sent", "type": "string" } ] }, "total_steps": { "description": "Total number of wizard steps", "type": "number" }, "invitation_link": { "description": "Invitation link for the shareholder to complete onboarding", "type": "string" }, "email_sent": { "description": "Whether the invitation email was successfully sent", "type": "boolean" } } } } }, "shareholderInvitation_ListResponse": { "title": "Shareholder Invitation List Response", "description": "Response containing a list of shareholder invitations", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Shareholder Invitation", "description": "An invitation for a shareholder to complete KYC onboarding", "additionalProperties": false, "type": "object", "required": [ "id", "email", "merchant_id", "shareholder_type", "shareholder_country_iso2", "status", "expires_at", "accepted_at", "opened_at", "current_step", "current_step_name", "steps_completed", "core_shareholder_id", "invited_by_user_id", "created_at", "display_status", "total_steps" ], "properties": { "id": { "format": "uuid", "description": "Shareholder invitation ID", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "merchant_id": { "format": "uuid", "description": "Merchant this invitation belongs to", "type": "string" }, "shareholder_type": { "description": "Type of shareholder (individual)", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareholder_country_iso2": { "description": "Country ISO2 code set during onboarding", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "description": "Current status of the invitation", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "accepted_at": { "description": "When the invitation was accepted", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "opened_at": { "description": "When the invitation link was first opened", "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "current_step": { "description": "Current wizard step (0-3)", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Array of completed step numbers", "type": "array", "items": { "type": "number" } }, "core_shareholder_id": { "description": "ID of the shareholder created in Core (set after step 1)", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "invited_by_user_id": { "description": "User ID of the person who created this invitation", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the invitation was created", "type": "string" }, "display_status": { "description": "Computed display status for UI", "anyOf": [ { "const": "accepted", "type": "string" }, { "const": "filling_details", "type": "string" }, { "const": "invite_created", "type": "string" }, { "const": "invite_sent", "type": "string" } ] }, "total_steps": { "description": "Total number of wizard steps", "type": "number" } } } } } }, "shareholderInvitation_PreviewResponse": { "title": "Shareholder Invitation Preview Response", "description": "Response containing a shareholder invitation preview", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Shareholder Invitation Preview", "description": "Minimal preview for unauthenticated display", "additionalProperties": false, "type": "object", "required": [ "merchant_name", "email", "status", "current_step", "current_step_name", "steps_completed", "total_steps", "expires_at", "merchant_country_iso2" ], "properties": { "merchant_name": { "description": "Display name of the merchant", "type": "string" }, "email": { "format": "email", "description": "Invitee email address", "type": "string" }, "status": { "description": "Current status", "anyOf": [ { "const": "pending", "type": "string" }, { "const": "accepted", "type": "string" } ] }, "current_step": { "description": "Current wizard step", "type": "number" }, "current_step_name": { "description": "Name of the current step (consent, basic_info, address, or complete)", "type": "string" }, "steps_completed": { "description": "Completed steps", "type": "array", "items": { "type": "number" } }, "total_steps": { "description": "Total number of wizard steps", "type": "number" }, "expires_at": { "format": "date-time", "description": "When this invitation expires", "type": "string" }, "merchant_country_iso2": { "description": "Merchant country ISO2 for preselection", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "shareholderInvitation_SubmitStepResponse": { "title": "Submit Step Response", "description": "Response from submitting a wizard step", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Submit Step Result", "description": "Result of submitting a wizard step", "additionalProperties": false, "type": "object", "required": [ "next_step" ], "properties": { "next_step": { "description": "Next step to display, or null if complete", "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } }, "merchantRegistration_Input": { "title": "Merchant Registration Input", "description": "Self-service merchant registration input", "additionalProperties": false, "type": "object", "required": [ "brand_name", "uri", "category_code", "clientEvidence" ], "properties": { "brand_name": { "description": "The brand name of the merchant", "examples": [ "My Store" ], "type": "string" }, "uri": { "description": "The URI of the merchant's website (protocol optional, will be normalized)", "examples": [ "my-store.com", "https://my-store.com" ], "type": "string" }, "category_code": { "description": "The merchant category code (MCC)", "examples": [ "4816" ], "type": "string" }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "clientEvidence": { "additionalProperties": false, "type": "object", "required": [ "consented_agreements", "checkbox_language" ], "properties": { "checkout_page_version": { "description": "APP_COMMIT_SHA the page was built from", "examples": [ "a1b2c3d" ], "type": "string" }, "timezone": { "description": "Browser IANA timezone", "examples": [ "Europe/Dublin" ], "type": "string" }, "fingerprint": { "description": "FingerprintJS visitor id if available", "type": "string" }, "consented_agreements": { "description": "One entry per required consent kind for the current acceptance", "minItems": 1, "examples": [ [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "kind", "agreement_id" ], "properties": { "kind": { "description": "AgreementKind literal", "type": "string" }, "agreement_id": { "format": "uuid", "type": "string" } } } }, "checkbox_language": { "description": "Rendered text of each checkbox the user ticked", "examples": [ [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] ], "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "checkbox_id", "rendered_text", "covers_kinds" ], "properties": { "checkbox_id": { "type": "string" }, "rendered_text": { "type": "string" }, "covers_kinds": { "type": "array", "items": { "type": "string" } } } } } } } } }, "merchantRegistration_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "merchant", "access_token", "refresh_token", "token_type", "expires_in" ], "properties": { "merchant": { "title": "Merchant", "description": "Merchant information", "additionalProperties": false, "type": "object", "required": [ "id", "brand_name", "uri", "category_code", "activation_status", "mode", "multi_account_setting", "refund_retention_rate", "client_id", "has_client_secret" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "brand_name": { "description": "The brand name of the merchant", "examples": [ "Example Brand" ], "type": "string" }, "uri": { "format": "uri", "description": "The URI of the merchant's website", "examples": [ "https://example-merchant.com" ], "type": "string" }, "category_code": { "description": "The merchant category code", "examples": [ "4816" ], "type": "string" }, "activation_status": { "description": "The activation status of the merchant", "examples": [ "active" ], "anyOf": [ { "const": "active", "type": "string" }, { "const": "inactive", "type": "string" } ] }, "mode": { "description": "The mode of the merchant", "examples": [ "live" ], "anyOf": [ { "const": "sandbox", "type": "string" }, { "const": "live", "type": "string" } ] }, "country": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The country of the merchant", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "settlement_currency": { "description": "The merchant's effective billing/settlement currency, derived from their settlement bank account (with a country fallback). Null when it can't be resolved. Populated by GET /merchants/:id only; absent from list responses.", "examples": [ "EUR", "GBP" ], "anyOf": [ { "minLength": 3, "maxLength": 3, "type": "string" }, { "type": "null" } ] }, "multi_account_setting": { "description": "The multi-account setting of the merchant", "examples": [ true, false ], "type": "boolean" }, "refund_retention_rate": { "description": "The proportion of settled funds retained to cover potential refunds. Null means the global default is used.", "anyOf": [ { "description": "The refund retention rate as a decimal (e.g. \"0.0500\" for 5%)", "examples": [ "0.0500" ], "type": "string" }, { "type": "null" } ] }, "client_id": { "description": "The client ID of the merchant", "examples": [ "merchant_123" ], "type": "string" }, "has_client_secret": { "description": "Whether a client secret is set for this merchant", "examples": [ true ], "type": "boolean" }, "account_owners": { "description": "The account owners associated with this merchant", "examples": [ [] ], "type": "array", "items": { "title": "Merchant Account Owner", "description": "Information about a merchant account owner", "additionalProperties": false, "type": "object", "required": [ "id", "full_name", "email", "is_primary", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the account owner", "examples": [ "123e4567-e89b-12d3-a456-426614174002" ], "type": "string" }, "full_name": { "description": "The full name of the account owner", "examples": [ "John Doe" ], "maxLength": 255, "type": "string" }, "email": { "format": "email", "description": "The email address of the account owner", "examples": [ "john.doe@example.com" ], "maxLength": 255, "type": "string" }, "phone_number": { "description": "The phone number in format: country_code;number (e.g., 44;7395236209)", "examples": [ "44;7395236209" ], "pattern": "^[0-9]{1,4};[0-9]{6,15}$", "type": "string" }, "role": { "description": "The role of the account owner within the organization", "examples": [ "Owner", "Director", "Manager" ], "maxLength": 100, "type": "string" }, "is_primary": { "description": "Whether this account owner is the primary contact", "examples": [ true, false ], "type": "boolean" }, "created_at": { "format": "date-time", "description": "The timestamp when the account owner was created", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" }, "updated_at": { "format": "date-time", "description": "The timestamp when the account owner was last updated", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } } } } } }, "access_token": { "description": "New access token with merchant:admin role", "type": "string" }, "refresh_token": { "description": "New refresh token", "type": "string" }, "token_type": { "const": "Bearer", "type": "string" }, "expires_in": { "description": "Token expiry in seconds", "type": "number" } } } } }, "resolutionLink_PathParams": { "type": "object", "required": [ "merchantId", "transactionId" ], "properties": { "merchantId": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "transactionId": { "format": "uuid", "description": "Original transaction ID", "type": "string" } } }, "resolutionLink_SendBody": { "type": "object", "required": [ "email" ], "properties": { "email": { "format": "email", "description": "Customer email address", "type": "string" }, "skip_email": { "description": "If true, creates link without sending email (for copy/paste)", "type": "boolean" } } }, "resolutionLink_SendResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "id", "email", "expires_at", "invite_link" ], "properties": { "id": { "format": "uuid", "type": "string" }, "email": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "invite_link": { "type": "string" } } } } }, "resolutionLink_GetResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "invite_link" ], "properties": { "invite_link": { "type": "string" } } } } }, "resolutionLink_ResendBody": { "type": "object", "properties": { "email": { "format": "email", "description": "Optional new customer email address", "type": "string" } } }, "resolutionLink_ResendResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "email", "expires_at" ], "properties": { "email": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" } } } } }, "resolutionLink_PreviewQuery": { "type": "object", "required": [ "token" ], "properties": { "token": { "minLength": 10, "description": "Resolution link token", "type": "string" } } }, "resolutionLink_PreviewResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "transaction_id", "merchant_brand_name", "customer_email", "problems", "expires_at", "deposit_country", "refund_amount", "refund_currency_code", "refund_currency_symbol" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "merchant_brand_name": { "type": "string" }, "customer_email": { "type": "string" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "code", "message", "label", "is_resolvable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "label": { "description": "Display label for the problem", "type": "string" }, "is_resolvable": { "description": "Whether the problem can be resolved by providing additional data", "type": "boolean" } } } }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "deposit_country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refund_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "refund_currency_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refund_currency_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "resolutionLink_TokenUpdateSuccess": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } }, "adminPostProcessorLog_Log": { "title": "Post-Processor Log", "description": "A TransferMate post-processor log entry", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "action", "status", "from_currency", "to_currency", "amount", "converted_amount", "exchange_rate", "tm_transaction_id", "reference", "error_message", "source_account_id", "source_account_type", "destination_account_id", "destination_account_type", "reason", "performed_by_user_id", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Log entry ID", "type": "string" }, "transaction_id": { "description": "Associated transaction ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_id": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "action": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "status": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "from_currency": { "description": "Source currency code", "examples": [ "EUR" ], "type": "string" }, "to_currency": { "description": "Destination currency code", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Transfer amount", "examples": [ "100.00" ], "type": "string" }, "converted_amount": { "description": "Converted amount after FX", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchange_rate": { "description": "Exchange rate applied", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tm_transaction_id": { "description": "TransferMate transaction ID", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "description": "Payment reference", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_message": { "description": "Error message if failed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_account_id": { "description": "Source account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source_account_type": { "description": "Type of source account", "anyOf": [ { "description": "Type of source account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "destination_account_id": { "description": "Destination account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "description": "Type of destination account", "anyOf": [ { "description": "Type of destination account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" }, { "const": "CUSTOMER_BANK_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "reason": { "description": "Reason for manual transfer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "performed_by_user_id": { "description": "User who performed the manual transfer", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the log entry was created", "type": "string" } } }, "adminPostProcessorLog_Response": { "title": "Post-Processor Log Response", "description": "Response containing a single post-processor log entry", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Post-Processor Log", "description": "A TransferMate post-processor log entry", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "action", "status", "from_currency", "to_currency", "amount", "converted_amount", "exchange_rate", "tm_transaction_id", "reference", "error_message", "source_account_id", "source_account_type", "destination_account_id", "destination_account_type", "reason", "performed_by_user_id", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Log entry ID", "type": "string" }, "transaction_id": { "description": "Associated transaction ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_id": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "action": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "status": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "from_currency": { "description": "Source currency code", "examples": [ "EUR" ], "type": "string" }, "to_currency": { "description": "Destination currency code", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Transfer amount", "examples": [ "100.00" ], "type": "string" }, "converted_amount": { "description": "Converted amount after FX", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchange_rate": { "description": "Exchange rate applied", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tm_transaction_id": { "description": "TransferMate transaction ID", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "description": "Payment reference", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_message": { "description": "Error message if failed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_account_id": { "description": "Source account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source_account_type": { "description": "Type of source account", "anyOf": [ { "description": "Type of source account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "destination_account_id": { "description": "Destination account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "description": "Type of destination account", "anyOf": [ { "description": "Type of destination account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" }, { "const": "CUSTOMER_BANK_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "reason": { "description": "Reason for manual transfer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "performed_by_user_id": { "description": "User who performed the manual transfer", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the log entry was created", "type": "string" } } } } }, "adminPostProcessorLog_ListResponse": { "title": "Post-Processor Log List Response", "description": "Paginated response with metadata", "additionalProperties": false, "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Post-Processor Log", "description": "A TransferMate post-processor log entry", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "action", "status", "from_currency", "to_currency", "amount", "converted_amount", "exchange_rate", "tm_transaction_id", "reference", "error_message", "source_account_id", "source_account_type", "destination_account_id", "destination_account_type", "reason", "performed_by_user_id", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Log entry ID", "type": "string" }, "transaction_id": { "description": "Associated transaction ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_id": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "action": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "status": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "from_currency": { "description": "Source currency code", "examples": [ "EUR" ], "type": "string" }, "to_currency": { "description": "Destination currency code", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Transfer amount", "examples": [ "100.00" ], "type": "string" }, "converted_amount": { "description": "Converted amount after FX", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchange_rate": { "description": "Exchange rate applied", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tm_transaction_id": { "description": "TransferMate transaction ID", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "description": "Payment reference", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_message": { "description": "Error message if failed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_account_id": { "description": "Source account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source_account_type": { "description": "Type of source account", "anyOf": [ { "description": "Type of source account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "destination_account_id": { "description": "Destination account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "description": "Type of destination account", "anyOf": [ { "description": "Type of destination account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" }, { "const": "CUSTOMER_BANK_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "reason": { "description": "Reason for manual transfer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "performed_by_user_id": { "description": "User who performed the manual transfer", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the log entry was created", "type": "string" } } } }, "pagination": { "title": "Pagination Metadata", "description": "Metadata for paginated responses", "additionalProperties": false, "type": "object", "required": [ "total", "page", "limit", "totalPages", "hasNextPage", "hasPreviousPage" ], "properties": { "total": { "description": "Total number of items", "examples": [ 150 ], "type": "integer" }, "page": { "description": "Current page number", "examples": [ 1 ], "type": "integer" }, "limit": { "description": "Number of items per page", "examples": [ 25 ], "type": "integer" }, "totalPages": { "description": "Total number of pages", "examples": [ 6 ], "type": "integer" }, "hasNextPage": { "description": "Whether there is a next page", "examples": [ true ], "type": "boolean" }, "hasPreviousPage": { "description": "Whether there is a previous page", "examples": [ false ], "type": "boolean" } } } } }, "adminPostProcessorLog_ListQuery": { "title": "Post-Processor Log List Query", "description": "Query parameters for listing post-processor logs", "type": "object", "properties": { "page": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 3 ], "type": "integer" }, "limit": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50 ], "type": "integer" }, "sort": { "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")", "examples": [ "created_at:desc", "amount:asc", "updated_at:desc" ], "type": "string" }, "merchant_id": { "format": "uuid", "description": "Filter by merchant ID", "type": "string" }, "action": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "status": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "from_date": { "format": "date-time", "description": "Filter logs created after this date", "type": "string" }, "to_date": { "format": "date-time", "description": "Filter logs created before this date", "type": "string" } } }, "adminPostProcessorLog_IdParams": { "type": "object", "required": [ "logId" ], "properties": { "logId": { "format": "uuid", "description": "Post-processor log ID", "type": "string" } } }, "adminPostProcessorLog_ManualTransferInput": { "title": "Manual Transfer Input", "description": "Request body for creating a manual transfer", "type": "object", "required": [ "reference", "source_account_id", "source_account_type", "destination_account_id", "destination_account_type", "amount", "reason" ], "properties": { "reference": { "minLength": 8, "pattern": "^[^0TtBb]", "description": "Unique payment reference (used as TransferMate client_transaction_id)", "examples": [ "QKMT-20240601-001" ], "type": "string" }, "source_account_id": { "format": "uuid", "description": "Source account ID (a merchant bank account or a fee account)", "type": "string" }, "source_account_type": { "description": "Type of source account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" } ] }, "destination_account_id": { "format": "uuid", "description": "Destination account ID", "type": "string" }, "destination_account_type": { "description": "Type of destination account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" }, { "const": "CUSTOMER_BANK_ACCOUNT", "type": "string" } ] }, "amount": { "description": "Amount to transfer (in source currency)", "examples": [ "100.00" ], "type": "string" }, "reason": { "description": "Reason for the manual transfer", "examples": [ "Correcting misrouted funds" ], "type": "string" } } }, "adminPostProcessorLog_ManualTransferResponse": { "title": "Manual Transfer Response", "description": "Response containing the created manual transfer log entry", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Post-Processor Log", "description": "A TransferMate post-processor log entry", "type": "object", "required": [ "id", "transaction_id", "merchant_id", "action", "status", "from_currency", "to_currency", "amount", "converted_amount", "exchange_rate", "tm_transaction_id", "reference", "error_message", "source_account_id", "source_account_type", "destination_account_id", "destination_account_type", "reason", "performed_by_user_id", "created_at" ], "properties": { "id": { "format": "uuid", "description": "Log entry ID", "type": "string" }, "transaction_id": { "description": "Associated transaction ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "merchant_id": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "action": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "status": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "from_currency": { "description": "Source currency code", "examples": [ "EUR" ], "type": "string" }, "to_currency": { "description": "Destination currency code", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "description": "Transfer amount", "examples": [ "100.00" ], "type": "string" }, "converted_amount": { "description": "Converted amount after FX", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchange_rate": { "description": "Exchange rate applied", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tm_transaction_id": { "description": "TransferMate transaction ID", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "description": "Payment reference", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "error_message": { "description": "Error message if failed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_account_id": { "description": "Source account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "source_account_type": { "description": "Type of source account", "anyOf": [ { "description": "Type of source account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "destination_account_id": { "description": "Destination account ID", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "destination_account_type": { "description": "Type of destination account", "anyOf": [ { "description": "Type of destination account", "anyOf": [ { "const": "MERCHANT_BANK_ACCOUNT", "type": "string" }, { "const": "FEE_ACCOUNT", "type": "string" }, { "const": "CUSTOMER_BANK_ACCOUNT", "type": "string" } ] }, { "type": "null" } ] }, "reason": { "description": "Reason for manual transfer", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "performed_by_user_id": { "description": "User who performed the manual transfer", "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "description": "When the log entry was created", "type": "string" } } } } }, "dashboard_Summary": { "additionalProperties": false, "title": "Dashboard Summary", "type": "object", "required": [ "scope", "period", "period_days", "transactions", "volume_by_currency", "fees_by_currency", "next_payout_by_currency" ], "properties": { "scope": { "description": "The resolved scope for this dashboard response", "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "period": { "description": "The time period for this dashboard response", "anyOf": [ { "const": "30d", "type": "string" }, { "const": "60d", "type": "string" }, { "const": "all", "type": "string" } ] }, "period_days": { "description": "Number of days in the current period (null for all-time)", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "comparison_period": { "additionalProperties": false, "type": "object", "required": [ "start", "end" ], "properties": { "start": { "format": "date-time", "description": "Start of the comparison period", "type": "string" }, "end": { "format": "date-time", "description": "End of the comparison period", "type": "string" } } }, "partners": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "description": "All-time total count", "type": "integer" }, "new_in_period": { "description": "New entities in the selected period (omitted for all-time)", "type": "integer" } } }, "merchants": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "description": "All-time total count", "type": "integer" }, "new_in_period": { "description": "New entities in the selected period (omitted for all-time)", "type": "integer" } } }, "transactions": { "additionalProperties": false, "type": "object", "required": [ "count" ], "properties": { "count": { "description": "Transaction count in current period", "type": "integer" }, "previous_count": { "description": "Transaction count in previous period (omitted for all-time)", "type": "integer" } } }, "volume_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Current period decimal amount", "type": "string" }, "previous_amount": { "description": "Previous period decimal amount (omitted for all-time)", "type": "string" } } } }, "fees_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Current period decimal amount", "type": "string" }, "previous_amount": { "description": "Previous period decimal amount (omitted for all-time)", "type": "string" } } } }, "next_payout_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Decimal amount as string (e.g. \"1234.56\")", "type": "string" } } } } } }, "dashboard_SummaryResponse": { "title": "Dashboard Summary Response", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "title": "Dashboard Summary", "type": "object", "required": [ "scope", "period", "period_days", "transactions", "volume_by_currency", "fees_by_currency", "next_payout_by_currency" ], "properties": { "scope": { "description": "The resolved scope for this dashboard response", "anyOf": [ { "const": "global", "type": "string" }, { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" } ] }, "period": { "description": "The time period for this dashboard response", "anyOf": [ { "const": "30d", "type": "string" }, { "const": "60d", "type": "string" }, { "const": "all", "type": "string" } ] }, "period_days": { "description": "Number of days in the current period (null for all-time)", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "comparison_period": { "additionalProperties": false, "type": "object", "required": [ "start", "end" ], "properties": { "start": { "format": "date-time", "description": "Start of the comparison period", "type": "string" }, "end": { "format": "date-time", "description": "End of the comparison period", "type": "string" } } }, "partners": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "description": "All-time total count", "type": "integer" }, "new_in_period": { "description": "New entities in the selected period (omitted for all-time)", "type": "integer" } } }, "merchants": { "additionalProperties": false, "type": "object", "required": [ "total" ], "properties": { "total": { "description": "All-time total count", "type": "integer" }, "new_in_period": { "description": "New entities in the selected period (omitted for all-time)", "type": "integer" } } }, "transactions": { "additionalProperties": false, "type": "object", "required": [ "count" ], "properties": { "count": { "description": "Transaction count in current period", "type": "integer" }, "previous_count": { "description": "Transaction count in previous period (omitted for all-time)", "type": "integer" } } }, "volume_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Current period decimal amount", "type": "string" }, "previous_amount": { "description": "Previous period decimal amount (omitted for all-time)", "type": "string" } } } }, "fees_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Current period decimal amount", "type": "string" }, "previous_amount": { "description": "Previous period decimal amount (omitted for all-time)", "type": "string" } } } }, "next_payout_by_currency": { "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "amount": { "description": "Decimal amount as string (e.g. \"1234.56\")", "type": "string" } } } } } } } }, "providerConfiguration_Config": { "title": "Provider Configuration", "description": "A merchant provider configuration (credentials masked)", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider_name", "has_credentials", "active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the provider configuration", "type": "string" }, "merchant_id": { "format": "uuid", "description": "The merchant this configuration belongs to", "type": "string" }, "provider_name": { "description": "Payment provider name (e.g. fumopay, tink)", "type": "string" }, "has_credentials": { "description": "Whether encrypted credentials have been stored", "type": "boolean" }, "active": { "description": "Whether this provider configuration is active", "type": "boolean" }, "created_at": { "format": "date-time", "description": "When the configuration was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the configuration was last updated", "type": "string" } } }, "providerConfiguration_Input": { "title": "Provider Configuration Input", "description": "Input for creating or updating a provider configuration", "additionalProperties": false, "type": "object", "required": [ "provider_name", "credentials" ], "properties": { "provider_name": { "description": "Payment provider name", "type": "string" }, "credentials": { "description": "Provider-specific credential key/value pairs", "type": "object", "patternProperties": { "^(.*)$": { "type": "string" } } } } }, "providerConfiguration_Response": { "title": "Provider Configuration Response", "description": "Response containing a single provider configuration", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Provider Configuration", "description": "A merchant provider configuration (credentials masked)", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider_name", "has_credentials", "active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the provider configuration", "type": "string" }, "merchant_id": { "format": "uuid", "description": "The merchant this configuration belongs to", "type": "string" }, "provider_name": { "description": "Payment provider name (e.g. fumopay, tink)", "type": "string" }, "has_credentials": { "description": "Whether encrypted credentials have been stored", "type": "boolean" }, "active": { "description": "Whether this provider configuration is active", "type": "boolean" }, "created_at": { "format": "date-time", "description": "When the configuration was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the configuration was last updated", "type": "string" } } } } }, "providerConfiguration_ListResponse": { "title": "Provider Configuration List Response", "description": "Response containing a list of provider configurations", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Provider Configuration", "description": "A merchant provider configuration (credentials masked)", "additionalProperties": false, "type": "object", "required": [ "id", "merchant_id", "provider_name", "has_credentials", "active", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "description": "The unique identifier of the provider configuration", "type": "string" }, "merchant_id": { "format": "uuid", "description": "The merchant this configuration belongs to", "type": "string" }, "provider_name": { "description": "Payment provider name (e.g. fumopay, tink)", "type": "string" }, "has_credentials": { "description": "Whether encrypted credentials have been stored", "type": "boolean" }, "active": { "description": "Whether this provider configuration is active", "type": "boolean" }, "created_at": { "format": "date-time", "description": "When the configuration was created", "type": "string" }, "updated_at": { "format": "date-time", "description": "When the configuration was last updated", "type": "string" } } } } } }, "providerConfiguration_DeleteResponse": { "title": "Provider Configuration Delete Response", "description": "Response after deleting a provider configuration", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "description": "Whether the configuration was deleted", "type": "boolean" } } } } }, "providerConfiguration_PaymentProvider": { "title": "Payment Provider", "description": "A payment provider with country coverage information", "additionalProperties": false, "type": "object", "required": [ "name", "countries" ], "properties": { "name": { "description": "Payment provider name", "type": "string" }, "countries": { "description": "Countries where this provider operates", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "country_code", "is_default" ], "properties": { "country_code": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country where the provider operates", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "is_default": { "description": "Whether this provider is the default for the country", "type": "boolean" } } } }, "partners_using": { "description": "Number of partners using this provider (admin only)", "type": "integer" } } }, "providerConfiguration_ProvidersListResponse": { "title": "Payment Providers List Response", "description": "Response containing a list of payment providers", "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Payment Provider", "description": "A payment provider with country coverage information", "additionalProperties": false, "type": "object", "required": [ "name", "countries" ], "properties": { "name": { "description": "Payment provider name", "type": "string" }, "countries": { "description": "Countries where this provider operates", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "country_code", "is_default" ], "properties": { "country_code": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Country where the provider operates", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "is_default": { "description": "Whether this provider is the default for the country", "type": "boolean" } } } }, "partners_using": { "description": "Number of partners using this provider (admin only)", "type": "integer" } } } } } }, "straddleWebhook_SuccessResponse": { "title": "Straddle Webhook Success Response", "additionalProperties": false, "type": "object", "required": [ "received" ], "properties": { "received": { "examples": [ true ], "type": "boolean" } } }, "agreement_CurrentAgreementsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "agreements" ], "properties": { "agreements": { "type": "array", "items": { "title": "Agreement Entry", "additionalProperties": false, "type": "object", "required": [ "id", "kind", "version", "url" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for this Agreement row — echoed in consent submissions", "type": "string" }, "kind": { "description": "The kind of legal agreement", "anyOf": [ { "const": "quidkey_privacy", "type": "string" }, { "const": "quidkey_tos", "type": "string" }, { "const": "merchant_tos", "type": "string" }, { "const": "merchant_dpa", "type": "string" }, { "const": "merchant_prohibited_use", "type": "string" }, { "const": "merchant_pricing_plan", "type": "string" }, { "const": "merchant_bank_debit_authorization", "type": "string" }, { "const": "merchant_nacha_acknowledgment", "type": "string" }, { "const": "third_party_provider_agreements", "type": "string" }, { "const": "transfermate_authorization", "type": "string" }, { "const": "straddle_psa", "type": "string" }, { "const": "ach_authorization", "type": "string" } ] }, "version": { "format": "date", "description": "The semantic version (date) of this agreement", "examples": [ "2026-04-22" ], "type": "string" }, "url": { "format": "uri", "description": "Absolute URL where the versioned agreement is hosted", "examples": [ "https://app.quidkey.com/legal/ach-authorization-2026-04-22" ], "type": "string" } } } } } } } }, "agreement_MerchantAgreementRecordsListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "type": "array", "items": { "title": "Merchant Agreement Record", "additionalProperties": false, "type": "object", "required": [ "id", "agreement_id", "agreement_kind", "agreement_kind_label", "agreement_url_snapshot", "accepted_at", "evidence_record_id" ], "properties": { "id": { "format": "uuid", "description": "Unique identifier for the agreement record", "type": "string" }, "agreement_id": { "format": "uuid", "description": "The versioned Agreement this record references", "type": "string" }, "agreement_kind": { "description": "The kind of legal agreement", "anyOf": [ { "const": "quidkey_privacy", "type": "string" }, { "const": "quidkey_tos", "type": "string" }, { "const": "merchant_tos", "type": "string" }, { "const": "merchant_dpa", "type": "string" }, { "const": "merchant_prohibited_use", "type": "string" }, { "const": "merchant_pricing_plan", "type": "string" }, { "const": "merchant_bank_debit_authorization", "type": "string" }, { "const": "merchant_nacha_acknowledgment", "type": "string" }, { "const": "third_party_provider_agreements", "type": "string" }, { "const": "transfermate_authorization", "type": "string" }, { "const": "straddle_psa", "type": "string" }, { "const": "ach_authorization", "type": "string" } ] }, "agreement_kind_label": { "description": "Human-readable label for the agreement kind", "examples": [ "Quidkey Merchant Terms" ], "type": "string" }, "agreement_url_snapshot": { "format": "uri", "description": "URL the merchant saw at the time of acceptance", "type": "string" }, "accepted_at": { "format": "date-time", "description": "Timestamp at which the agreement was accepted", "type": "string" }, "evidence_record_id": { "format": "uuid", "description": "Evidence record that captures the acceptance event", "type": "string" } } } } } }, "evidence_Response": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "additionalProperties": false, "type": "object", "required": [ "id", "event_type", "event_version", "action", "subject_type", "subject_id", "actor", "evidence", "artifacts", "context_payment_request_id", "context_payment_link_id", "context_customer_bank_account_id", "context_merchant_id", "correlation_id", "context_extra", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "event_type": { "type": "string" }, "event_version": { "type": "string" }, "action": { "type": "string" }, "subject_type": { "type": "string" }, "subject_id": { "format": "uuid", "type": "string" }, "actor": { "additionalProperties": true, "type": "object", "properties": {} }, "evidence": { "additionalProperties": true, "type": "object", "properties": {} }, "artifacts": { "additionalProperties": true, "type": "object", "properties": {} }, "context_payment_request_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "context_payment_link_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "context_customer_bank_account_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "context_merchant_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "correlation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "context_extra": { "anyOf": [ { "additionalProperties": true, "type": "object", "properties": {} }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/api/v1/admin/partners": { "post": { "tags": [ "Partners", "Admin" ], "summary": "Create a new partner", "description": "Create a new partner", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partner_CreateResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Barclaycard", "email": "argo@barclaycard.com", "client_id": "partner_123", "client_secret": "secret_abc123" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Partner creation input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partner_Input" }, "example": { "name": "Barclaycard", "email": "argo@barclaycard.com", "website": "barclaycard.com" } } } } }, "get": { "tags": [ "Partners", "Admin" ], "summary": "Get all partners", "description": "Get all partners", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "email", "client_id", "has_client_secret", "website", "created_at", "updated_at" ], "properties": { "id": { "format": "uuid", "type": "string" }, "name": { "type": "string" }, "email": { "format": "email", "type": "string" }, "client_id": { "format": "uuid", "type": "string" }, "has_client_secret": { "type": "boolean" }, "website": { "anyOf": [ { "format": "uri", "type": "string" }, { "type": "null" } ] }, "created_at": { "format": "date-time", "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/admin/partners/{id}": { "get": { "tags": [ "Partners", "Admin" ], "summary": "Get a partner by ID", "description": "Get a partner by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partner_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Barclaycard", "email": "argo@barclaycard.com", "client_id": "partner_123", "client_secret": "$2b$10$...", "has_client_secret": true, "website": "https://transfermate.com", "payment_providers": { "GB": "fumopay" }, "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the partner", "type": "string" }, "description": "The unique identifier of the partner" } ] }, "put": { "tags": [ "Partners", "Admin" ], "summary": "Update a partner by ID", "description": "Update a partner by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partner_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Barclaycard", "email": "argo@barclaycard.com", "client_id": "partner_123", "client_secret": "$2b$10$...", "has_client_secret": true, "website": "https://transfermate.com", "payment_providers": { "GB": "fumopay" }, "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the partner", "type": "string" }, "description": "The unique identifier of the partner" } ], "requestBody": { "required": true, "description": "Partner update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/partner_Update" }, "example": { "name": "BarclayCard International", "email": "argo.international@barclaycard.com", "website": "barclaycard-international.com", "payment_providers": { "GB": "fumopay" } } } } } } }, "/api/v1/admin/partners/{id}/generate-secret": { "post": { "tags": [ "Partners", "Admin" ], "summary": "Generate a new client secret for a partner", "description": "Generate a new client secret for a partner", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "client_secret" ], "properties": { "client_secret": { "description": "The generated client secret", "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the partner", "type": "string" }, "description": "The unique identifier of the partner" } ] } }, "/api/v1/admin/partners/{id}/revoke-secret": { "post": { "tags": [ "Partners", "Admin" ], "summary": "Revoke the client secret for a partner", "description": "Revoke the client secret for a partner", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "description": "Success message", "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the partner", "type": "string" }, "description": "The unique identifier of the partner" } ] } }, "/api/v1/merchants/register": { "post": { "tags": [ "Merchants" ], "summary": "Self-service merchant registration for users with global:user role", "description": "Self-service merchant registration for users with global:user role", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRegistration_Response" }, "example": { "success": true, "data": { "merchant": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] }, "token_type": "Bearer" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Self-service merchant registration input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRegistration_Input" }, "example": { "brand_name": "My Store", "uri": "my-store.com", "category_code": "4816", "country": "GB", "clientEvidence": { "checkout_page_version": "a1b2c3d", "timezone": "Europe/Dublin", "consented_agreements": [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ], "checkbox_language": [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] } } } } } } }, "/api/v1/merchants": { "post": { "tags": [ "Merchants" ], "summary": "Create a new merchant", "description": "Create a new merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Merchant creation input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Input" }, "example": { "partner_id": "550e8400-e29b-41d4-a716-446655440000", "brand_name": "Example Brand", "uri": "example-merchant.com", "category_code": "4816", "country": "GB", "account_owner": { "full_name": "John Doe", "email": "john.doe@example.com", "phone_number": "44;7395236209", "role": "Owner" } } } } } }, "get": { "tags": [ "Merchants" ], "summary": "Get all merchants", "description": "Get all merchants", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partner_id", "in": "query", "required": false, "schema": { "format": "uuid", "description": "Filter merchants by partner ID. Required for admin tokens without partner context.", "type": "string" }, "description": "Filter merchants by partner ID. Required for admin tokens without partner context." } ] } }, "/api/v1/merchants/{id}": { "get": { "tags": [ "Merchants" ], "summary": "Get a merchant by ID", "description": "Get a merchant by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] }, "put": { "tags": [ "Merchants" ], "summary": "Update a merchant by ID", "description": "Update a merchant by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Merchant update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Update" }, "example": { "brand_name": "Updated Example Brand", "uri": "updated-example-merchant.com", "category_code": "4816", "country": "GB" } } } } } }, "/api/v1/merchants/{id}/generate-secret": { "post": { "tags": [ "Merchants" ], "summary": "Generate a client secret for a merchant", "description": "Generate a client secret for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_GenerateClientSecretResponse" }, "example": { "success": true, "data": { "client_secret": "secret_123abc" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{id}/revoke-secret": { "post": { "tags": [ "Merchants" ], "summary": "Revoke a client secret for a merchant", "description": "Revoke a client secret for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_RevokeClientSecretResponse" }, "example": { "success": true, "data": { "message": "Client secret successfully revoked" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{id}/activation-status": { "patch": { "tags": [ "Merchants" ], "summary": "Update the activation status of a merchant", "description": "Update the activation status of a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Merchant activation status update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_ActivationStatusUpdate" }, "example": { "activation_status": "active" } } } } } }, "/api/v1/merchants/{id}/mode": { "patch": { "tags": [ "Merchants" ], "summary": "Update the mode of a merchant (live/sandbox)", "description": "Update the mode of a merchant (live/sandbox)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Merchant mode update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_ModeUpdate" }, "example": { "mode": "live" } } } } } }, "/api/v1/merchants/{id}/settings/multi-account": { "patch": { "tags": [ "Merchants" ], "summary": "Update the multi-account allowed setting for a merchant", "description": "Update the multi-account allowed setting for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Input for updating the merchant multi-account setting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_MultiAccountSettingUpdate" }, "example": { "allowed": true } } } } } }, "/api/v1/merchants/{id}/refund-retention-rate": { "put": { "tags": [ "Merchants" ], "summary": "Update the refund retention rate for a merchant", "description": "Update the refund retention rate for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "brand_name": "Example Brand", "uri": "https://example-merchant.com", "category_code": "4816", "activation_status": "active", "mode": "live", "country": "GB", "settlement_currency": "EUR", "multi_account_setting": true, "refund_retention_rate": "0.0500", "client_id": "merchant_123", "has_client_secret": true, "account_owners": [] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Input for updating the merchant refund retention rate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchant_RefundRetentionRateUpdate" }, "example": { "refund_retention_rate": "0.05" } } } } } }, "/api/v1/webhooks": { "post": { "tags": [ "Webhook" ], "summary": "Register or update a merchant webhook URL", "description": "Register or update a merchant webhook URL", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_Response" }, "example": { "success": true, "data": { "webhook_url": "https://example.com/webhook", "message": "Webhook URL successfully configured" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Webhook configuration input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "webhook_url": "https://example.com/webhook" } } } } } }, "/api/v1/webhooks/secret": { "post": { "tags": [ "Webhook" ], "summary": "Generate a webhook signing secret for the authenticated merchant", "description": "Generate a webhook signing secret for the authenticated merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_GenerateWebhookSecretResponse" }, "example": { "success": true, "data": { "webhook_secret": "whsec_a1b2c3d4e5f6…" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Input for webhook secret operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_SecretInput" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "/api/v1/webhooks/secret/revoke": { "post": { "tags": [ "Webhook" ], "summary": "Revoke the current webhook signing secret", "description": "Revoke the current webhook signing secret", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_RevokeWebhookSecretResponse" }, "example": { "success": true, "data": { "message": "Webhook secret successfully revoked" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Input for webhook secret operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook_SecretInput" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "/api/v1/merchants/{id}/legal-entities": { "post": { "tags": [ "Legal Entities" ], "summary": "Create a legal entity for a merchant", "description": "Create a legal entity for a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Legal entity creation input (includes Nacha acknowledgment evidence) - either company or individual", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_CreateInput" } } } } }, "get": { "tags": [ "Legal Entities" ], "summary": "Get a legal entity for a merchant", "description": "Get a legal entity for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] }, "put": { "tags": [ "Legal Entities" ], "summary": "Update a legal entity for a merchant", "description": "Update a legal entity for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Legal entity update input - either company or individual with partial updates allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Patch" } } } } }, "patch": { "tags": [ "Legal Entities" ], "summary": "Partially update a legal entity for a merchant", "description": "Partially update a legal entity for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Legal entity update input - either company or individual with partial updates allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Patch" } } } } } }, "/api/v1/admin/legal-entities/{id}/verify": { "patch": { "tags": [ "Legal Entities", "Admin" ], "summary": "Verify a legal entity", "description": "Verify a legal entity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/legalEntity_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the legal entity", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the legal entity" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "required": [ "verification_status" ], "type": "object", "properties": { "verification_status": { "description": "The new verification status for the legal entity", "examples": [ "verified", "rejected", "pending_verification", "more_information_required" ], "anyOf": [ { "const": "verified", "type": "string" }, { "const": "rejected", "type": "string" }, { "const": "pending_verification", "type": "string" }, { "const": "more_information_required", "type": "string" } ] } } }, "example": { "verification_status": "verified" } } } } } }, "/api/v1/merchants/{merchantId}/shareholders": { "post": { "tags": [ "Legal Entities" ], "summary": "Create a shareholder for a Merchant Legal Entity", "description": "Create a shareholder for a Merchant Legal Entity", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Shareholder creation input (full payload)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Input" }, "example": { "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "get": { "tags": [ "Legal Entities" ], "summary": "Get shareholders for a Merchant Legal Entity", "description": "Get shareholders for a Merchant Legal Entity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/shareholders/{shareholderId}": { "get": { "tags": [ "Legal Entities" ], "summary": "Get a shareholder for a Merchant Legal Entity", "description": "Get a shareholder for a Merchant Legal Entity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the shareholder" } ] }, "put": { "tags": [ "Legal Entities" ], "summary": "Update a shareholder for a Merchant Legal Entity", "description": "Update a shareholder for a Merchant Legal Entity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the shareholder" } ], "requestBody": { "required": true, "description": "Shareholder update input with partial updates supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Update" }, "example": { "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "patch": { "tags": [ "Legal Entities" ], "summary": "Partially update a shareholder for a Merchant Legal Entity", "description": "Partially update a shareholder for a Merchant Legal Entity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the shareholder" } ], "requestBody": { "required": true, "description": "Partial update for shareholder - all fields optional. Use this for incremental updates like adding ID details for cross-border.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_Patch" }, "example": { "ownership_details": { "ownership_share": 25, "ownership_roles": [ "owner", "director" ], "id_type": "passport", "id_number": "AB123456", "id_issue_country": "GB" } } } } } }, "delete": { "tags": [ "Legal Entities" ], "summary": "Delete a shareholder from a Merchant Legal Entity. Also removes associated documents and the holder legal entity if no longer referenced.", "description": "Delete a shareholder from a Merchant Legal Entity. Also removes associated documents and the holder legal entity if no longer referenced.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholder_DeleteResponse" }, "example": { "success": true, "data": { "deleted": true } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder to delete", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the shareholder to delete" } ] } }, "/api/v1/merchants/{id}/bank-accounts": { "post": { "tags": [ "Merchant Bank Accounts" ], "summary": "Create a bank account for a merchant", "description": "Create a bank account for a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Merchant bank account creation input (direct-debit authorization evidence required for user-auth callers)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_CreateInput" }, "example": { "account_number": "11223344", "currency": "GBP", "country": "GB", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bank_id": "123e4567-e89b-12d3-a456-426614174002", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": true } ], "client_evidence": { "checkout_page_version": "a1b2c3d", "timezone": "Europe/Dublin", "consented_agreements": [ { "kind": "merchant_tos", "agreement_id": "00000000-0000-0000-0000-000000000001" }, { "kind": "quidkey_privacy", "agreement_id": "00000000-0000-0000-0000-000000000002" }, { "kind": "merchant_dpa", "agreement_id": "00000000-0000-0000-0000-000000000003" }, { "kind": "merchant_prohibited_use", "agreement_id": "00000000-0000-0000-0000-000000000004" }, { "kind": "merchant_pricing_plan", "agreement_id": "00000000-0000-0000-0000-000000000005" }, { "kind": "third_party_provider_agreements", "agreement_id": "00000000-0000-0000-0000-000000000006" }, { "kind": "transfermate_authorization", "agreement_id": "00000000-0000-0000-0000-000000000007" } ], "checkbox_language": [ { "checkbox_id": "consent-quidkey", "rendered_text": "I confirm I am an authorized representative of this business and agree to Quidkey's …", "covers_kinds": [ "merchant_tos", "quidkey_privacy", "merchant_dpa", "merchant_prohibited_use", "merchant_pricing_plan", "third_party_provider_agreements" ] }, { "checkbox_id": "consent-transfermate", "rendered_text": "I confirm by ticking this box I authorise Quidkey to view and enter transactions with TransferMate on my behalf …", "covers_kinds": [ "transfermate_authorization" ] } ] } } } } } }, "get": { "tags": [ "Merchant Bank Accounts" ], "summary": "Get all bank accounts for a merchant (active and inactive). Optionally filter by currency query param.", "description": "Get all bank accounts for a merchant (active and inactive). Optionally filter by currency query param.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "currency", "in": "query", "required": false, "schema": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Optional currency code (ISO 4217) to filter active accounts", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "description": "Optional currency code (ISO 4217) to filter active accounts" }, { "name": "roles", "in": "query", "required": false, "schema": { "description": "Filter by account role(s). Defaults to settlement if not specified.", "examples": [ [ "settlement" ], [ "receiving", "refund" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "description": "Filter by account role(s). Defaults to settlement if not specified." }, { "name": "include_balance", "in": "query", "required": false, "schema": { "description": "Include balance for accounts that support it (requires additional API calls)", "default": false, "type": "boolean" }, "description": "Include balance for accounts that support it (requires additional API calls)" } ] } }, "/api/v1/merchants/{id}/bank-accounts/active": { "get": { "tags": [ "Merchant Bank Accounts" ], "summary": "Get active bank account(s) for a merchant. Optionally filter by currency query param.", "description": "Get active bank account(s) for a merchant. Optionally filter by currency query param.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "currency", "in": "query", "required": false, "schema": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "Optional currency code (ISO 4217) to filter active accounts", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "description": "Optional currency code (ISO 4217) to filter active accounts" }, { "name": "roles", "in": "query", "required": false, "schema": { "description": "Filter by account role(s). Defaults to settlement if not specified.", "examples": [ [ "settlement" ], [ "receiving", "refund" ] ], "type": "array", "items": { "description": "The purpose an account serves", "examples": [ "settlement" ], "anyOf": [ { "const": "receiving", "type": "string" }, { "const": "settlement", "type": "string" }, { "const": "refund", "type": "string" } ] } }, "description": "Filter by account role(s). Defaults to settlement if not specified." }, { "name": "include_balance", "in": "query", "required": false, "schema": { "description": "Include balance for accounts that support it (requires additional API calls)", "default": false, "type": "boolean" }, "description": "Include balance for accounts that support it (requires additional API calls)" } ] } }, "/api/v1/bank-accounts/{bankAccountId}/deactivate": { "put": { "tags": [ "Merchant Bank Accounts" ], "summary": "Deactivate a specific bank account", "description": "Deactivate a specific bank account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the bank account to deactivate", "examples": [ "ef84a547-8956-460e-a4a3-9d313da5efca" ], "type": "string" }, "description": "The unique identifier of the bank account to deactivate" } ] } }, "/api/v1/bank-accounts/{bankAccountId}/transactions": { "get": { "tags": [ "Merchant Bank Accounts" ], "summary": "List transactions for a bank account (money in / money out). Currently supported only for refund accounts; other roles return 404. Supports JSON (paginated) and xlsx/csv exports via Accept header.", "description": "List transactions for a bank account (money in / money out). Currently supported only for refund accounts; other roles return 404. Supports JSON (paginated) and xlsx/csv exports via Accept header.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankAccountTransactions_ListResponse" }, "example": { "success": true, "data": [ { "direction": "in", "amount": "2.00" } ], "pagination": { "total": 150, "page": 1, "limit": 25, "totalPages": 6, "hasNextPage": true, "hasPreviousPage": false } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "502": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error502" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Bank account ID", "type": "string" }, "description": "Bank account ID" }, { "name": "date_from", "in": "query", "required": false, "schema": { "format": "date", "description": "Filter from date (ISO 8601 YYYY-MM-DD)", "examples": [ "2026-04-01" ], "type": "string" }, "description": "Filter from date (ISO 8601 YYYY-MM-DD)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "format": "date", "description": "Filter to date (ISO 8601 YYYY-MM-DD)", "examples": [ "2026-04-30" ], "type": "string" }, "description": "Filter to date (ISO 8601 YYYY-MM-DD)" }, { "name": "page", "in": "query", "required": false, "schema": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "type": "integer" }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "description": "Rows per page (provider-limited)", "anyOf": [ { "const": 10, "type": "number" }, { "const": 20, "type": "number" }, { "const": 50, "type": "number" }, { "const": 100, "type": "number" } ] }, "description": "Rows per page (provider-limited)" }, { "name": "direction", "in": "query", "required": false, "schema": { "description": "Filter to money in or money out only. Omit for both.", "anyOf": [ { "const": "in", "type": "string" }, { "const": "out", "type": "string" } ] }, "description": "Filter to money in or money out only. Omit for both." } ] } }, "/api/v1/admin/bank-accounts/{bankAccountId}/balance": { "put": { "tags": [ "Merchant Bank Accounts", "Admin" ], "summary": "Set the balance on a fake-transfermate account (admin only)", "description": "Set the balance on a fake-transfermate account (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the bank account", "examples": [ "ef84a547-8956-460e-a4a3-9d313da5efca" ], "type": "string" }, "description": "The unique identifier of the bank account" } ], "requestBody": { "required": true, "description": "Input for setting refund account balance in sandbox mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_SetBalanceInput" }, "example": { "balance": "1000.00" } } } } } }, "/api/v1/bank-accounts/{bankAccountId}/payment-schemes": { "put": { "tags": [ "Merchant Bank Account Payment Schemes" ], "summary": "Update/merge payment schemes for a specific bank account. Only modifies specified schemes, preserves existing ones not mentioned.", "description": "Update/merge payment schemes for a specific bank account. Only modifies specified schemes, preserves existing ones not mentioned.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "account_number": "11223344", "currency": "GBP", "country": "GB", "status": "active", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "iban": "DE89370400440532013000", "bic": "MARKDEF1100", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "account_holder_name": "John Smith", "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer" } ], "roles": [ "receiving", "settlement" ], "balance": "1234.56" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the bank account", "examples": [ "ef84a547-8956-460e-a4a3-9d313da5efca" ], "type": "string" }, "description": "The unique identifier of the bank account" } ], "requestBody": { "required": true, "description": "Request body for updating payment schemes on a bank account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankAccountPaymentScheme_UpdateRequest" }, "example": { "supported_payment_schemes": [ { "type": "SEPA_CREDIT_TRANSFER", "is_active": true } ] } } } } } }, "/api/v1/payment-schemes": { "get": { "tags": [ "Payment Schemes" ], "summary": "Get available payment schemes for a specific country", "description": "Get available payment schemes for a specific country", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentScheme_DiscoveryResponse" }, "example": { "success": true, "data": { "payment_schemes": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "type": "SEPA_CREDIT_TRANSFER", "name": "SEPA Credit Transfer", "is_default": true, "additional_payment_method": false } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentScheme_CountryError" }, "example": { "success": false, "error": { "code": "INVALID_COUNTRY_CODE_FORMAT", "message": "Invalid country code format provided for payment scheme discovery" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentScheme_CountryError" }, "example": { "success": false, "error": { "code": "INVALID_COUNTRY_CODE_FORMAT", "message": "Invalid country code format provided for payment scheme discovery" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "description": "ISO 3166-1 alpha-2 country code" } ] } }, "/api/v1/countries/config/{iso2}": { "get": { "tags": [ "Countries" ], "summary": "Get a full CountryConfig by ISO2 country code", "description": "Get a full CountryConfig by ISO2 country code", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/countryConfig_Response" }, "example": { "success": true, "data": { "name": "Germany", "iso2": "GB", "short": "gb", "grouping": "EU", "config": { "phone_data": { "countryCode": "44", "phoneFormat": ".... ......", "hasTrunkPrefix": 0, "patterns": { "/^4/": "... ... ...", "default": ". .... ...." } }, "postal_code": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "company_number": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "vat": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "tax_id": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "entity_structure": [ { "label": "Private Limited Company (LTD)", "value": "limited_liability_company", "fields": [ { "type": "company_number", "required": true } ] } ], "required_address_lines": [ "address_line1", "city", "postal_code" ], "state_province": [ { "label": "New South Wales", "reviewLabel": "NSW", "value": "New South Wales" } ] }, "payment_schemes": [ { "type": "FASTER_PAYMENTS", "name": "Faster Payments", "fields": [ { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "required": true, "type": "company_number" } ] } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "iso2", "in": "path", "required": true, "schema": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "description": "ISO 3166-1 alpha-2 country code" } ] } }, "/api/v1/countries/config": { "get": { "tags": [ "Countries" ], "summary": "Get a list of all available CountryConfig records", "description": "Get a list of all available CountryConfig records", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/countryConfig_ListResponse" }, "example": { "success": true, "data": [ { "name": "Germany", "iso2": "GB", "short": "gb", "grouping": "EU", "config": { "phone_data": { "countryCode": "44", "phoneFormat": ".... ......", "hasTrunkPrefix": 0, "patterns": { "/^4/": "... ... ...", "default": ". .... ...." } }, "postal_code": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "company_number": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "vat": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "tax_id": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "entity_structure": [ { "label": "Private Limited Company (LTD)", "value": "limited_liability_company", "fields": [ { "type": "company_number", "required": true } ] } ], "required_address_lines": [ "address_line1", "city", "postal_code" ], "state_province": [ { "label": "New South Wales", "reviewLabel": "NSW", "value": "New South Wales" } ] }, "payment_schemes": [ { "type": "FASTER_PAYMENTS", "name": "Faster Payments", "fields": [ { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "required": true, "type": "company_number" } ] } ] } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/public/countries/config": { "get": { "tags": [ "Countries" ], "summary": "Get a list of all available CountryConfig records (public, no auth required)", "description": "Get a list of all available CountryConfig records (public, no auth required)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/countryConfig_ListResponse" }, "example": { "success": true, "data": [ { "name": "Germany", "iso2": "GB", "short": "gb", "grouping": "EU", "config": { "phone_data": { "countryCode": "44", "phoneFormat": ".... ......", "hasTrunkPrefix": 0, "patterns": { "/^4/": "... ... ...", "default": ". .... ...." } }, "postal_code": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "company_number": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "vat": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "tax_id": { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "format": "..-.......", "required": true }, "entity_structure": [ { "label": "Private Limited Company (LTD)", "value": "limited_liability_company", "fields": [ { "type": "company_number", "required": true } ] } ], "required_address_lines": [ "address_line1", "city", "postal_code" ], "state_province": [ { "label": "New South Wales", "reviewLabel": "NSW", "value": "New South Wales" } ] }, "payment_schemes": [ { "type": "FASTER_PAYMENTS", "name": "Faster Payments", "fields": [ { "label": "Postal Code", "min": 4, "max": 8, "pattern": "^[A-Z0-9]{8}$", "placeholder": "SW1A 1AA", "required": true, "type": "company_number" } ] } ] } ] } } } } } } }, "/api/v1/merchants/{id}/documents": { "post": { "tags": [ "Merchant Documents" ], "summary": "Upload a document for a merchant. Requires multipart/form-data with fields: file (binary) and documentType (string)", "description": "Upload a document for a merchant. Requires multipart/form-data with fields: file (binary) and documentType (string)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document_UploadResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "CERTIFICATE_OF_INCORPORATION", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Multipart form data for document upload", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/document_UploadRequest" } } } } }, "get": { "tags": [ "Merchant Documents" ], "summary": "List all documents for a merchant (metadata only)", "description": "List all documents for a merchant (metadata only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/document_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "certificate_of_incorporation", "fileName": "certificate.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "documentType": "business_proof_of_address", "fileName": "utility_bill.pdf", "uploadedAt": "2024-01-16T14:20:00.000Z" }, { "id": "770e8400-e29b-41d4-a716-446655440002", "documentType": "memorandum_and_articles", "fileName": "memorandum.pdf", "uploadedAt": "2024-01-17T09:15:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/shareholders/{shareholderId}/documents": { "post": { "tags": [ "Shareholder Documents" ], "summary": "Upload a document for a shareholder. Requires multipart/form-data with fields: file (binary) and documentType (string)", "description": "Upload a document for a shareholder. Requires multipart/form-data with fields: file (binary) and documentType (string)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderDocument_UploadResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "PROOF_OF_ADDRESS", "fileName": "proof_of_address.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "description": "The unique identifier of the shareholder" } ], "requestBody": { "required": true, "description": "Multipart form data for shareholder document upload", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/shareholderDocument_UploadRequest" } } } } }, "get": { "tags": [ "Shareholder Documents" ], "summary": "List all documents for a shareholder (metadata only)", "description": "List all documents for a shareholder (metadata only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderDocument_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "documentType": "PROOF_OF_ADDRESS", "fileName": "proof_of_address.pdf", "uploadedAt": "2024-01-15T10:30:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "shareholderId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the shareholder", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "description": "The unique identifier of the shareholder" } ] } }, "/api/v1/payment-requests": { "post": { "tags": [ "Payments" ], "summary": "Create a new payment request", "description": "Create a new payment request", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentRequest_Response" }, "example": { "success": true, "data": { "payment_link": "https://example.com/pay/abc123" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Payment request input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentRequest_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone_number": "07123456789" }, "billingAddress": { "address_line1": "12 West Common Drive", "address_line2": "Flat 1", "apartment": "Apt 5B", "city": "London", "state_province": "Greater London", "country": "GB", "postal_code": "SE1 1AA", "company_name": "Acme Ltd" }, "amount": 19.99, "currency": "GBP", "payment_reference": "ORDER123", "order_id": "1140", "locale": "en_GB", "platform": "WooCommerce", "device_type": "mobile", "external_payment_request_id": "u0nwmSrNntjIWozmNslK5Tlq", "test_transaction": false, "group": "rZNvy+1jH6Z+BcPqA5U5BSIcnUavBha3C63xBalm+xE=", "gid": "gid://shopify/PaymentSession/u0nwmSrNntjIWozmNslK5Tlq", "selected_bank_id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd", "session_id": "4B2dxmle3vGgimS4deUX3+2PgLF2+/0ZWnNsNSZcgdU=", "success_url_redirect": "https://storename.com/success", "fail_url_redirect": "https://storename.com/failure", "simulation": { "straddle": { "customer_outcome": "standard", "paykey_outcome": "standard", "charge_outcome": "standard", "balance_check": "required" }, "flinks": { "outcome": "happy", "mfa": "skip" } } } } } } } }, "/api/v1/payment-requests:redirect": { "post": { "tags": [ "Payments" ], "summary": "Create a payment request via the redirect (Pay by Bank) flow", "description": "Create a payment request via the redirect (Pay by Bank) flow", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/redirectPaymentRequest_Response" }, "example": { "success": true, "data": { "redirect_url": "https://example.com/redirect" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Strict input parameters for the redirect (Pay by Bank) payment request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/redirectPaymentRequest_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "customer": { "name": "John Doe", "email": "john.doe@example.com", "phone_number": "+447123456789" }, "billing_address": { "address_line1": "12 West Common Drive", "address_line2": "Flat 1", "apartment": "Apt 5B", "city": "London", "state_province": "Greater London", "country": "GB", "postal_code": "SE1 1AA", "company_name": "Acme Ltd" }, "amount": 1999, "currency": "GBP", "payment_reference": "ORDER123", "order_id": "1140", "locale": "en_GB", "success_url_redirect": "https://storename.com/success", "fail_url_redirect": "https://storename.com/failure", "test_transaction": false, "selected_bank_id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd", "simulation": { "straddle": { "customer_outcome": "standard", "paykey_outcome": "standard", "charge_outcome": "standard", "balance_check": "required" }, "flinks": { "outcome": "happy", "mfa": "skip" } } } } } } } }, "/api/v1/payment-initiation/{paymentRequestId}": { "post": { "tags": [ "Payments" ], "summary": "Initiate a payment for a specific payment request with selected bank", "description": "Initiate a payment for a specific payment request with selected bank", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentInitiation_Response" }, "example": { "success": true, "data": { "order_id": "123" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the payment request", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the payment request" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentInitiation_Input" }, "example": { "bankId": "123e4567-e89b-12d3-a456-426614174000", "paymentScheme": null } } } } } }, "/api/v1/callback": { "get": { "tags": [ "Payments" ], "summary": "Handle payment callback from Tink", "description": "Handle payment callback from Tink", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "HTML response for the callback page", "examples": [ "..." ], "type": "string" }, "example": "..." } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/api/v1/payments/{paymentRequestId}/status": { "get": { "tags": [ "Payments" ], "summary": "Check payment status (public, keyed by provider request id). Returns a minimal, PII-free status view used by the embedded checkout page.", "description": "Check payment status (public, keyed by provider request id). Returns a minimal, PII-free status view used by the embedded checkout page.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentStatus_CustomerResponse" }, "example": { "status": "pending", "amount": "1000", "currency": "GBP", "order_id": "1140" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The paymentRequestId parameter" } ] } }, "/api/v1/merchants/{merchantId}/payment-requests/{paymentRequestId}/status": { "get": { "tags": [ "Payments" ], "summary": "Check the status of one of the merchant's payment requests by internal id. Documented fallback for missed webhooks.", "description": "Check the status of one of the merchant's payment requests by internal id. Documented fallback for missed webhooks.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentStatus_MerchantResponse" }, "example": { "success": true, "data": { "status": "pending", "amount": "1000", "currency": "GBP" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The paymentRequestId parameter" } ] } }, "/api/v1/payment-requests/{paymentRequestId}/status": { "get": { "tags": [ "Payments" ], "summary": "Check the status of one of your payment requests by id. Documented fallback for missed webhooks.", "description": "Check the status of one of your payment requests by id. Documented fallback for missed webhooks.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentStatus_MerchantResponse" }, "example": { "success": true, "data": { "status": "pending", "amount": "1000", "currency": "GBP" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "paymentRequestId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The paymentRequestId parameter" } ] } }, "/api/v1/payment-links": { "get": { "tags": [ "Payment Links" ], "summary": "List payment links with context-aware access control", "description": "List payment links with context-aware access control", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_ListResponse" }, "example": { "success": true, "pagination": { "total": 150, "page": 1, "limit": 25, "totalPages": 6, "hasNextPage": true, "hasPreviousPage": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 3 ], "type": "integer" }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50 ], "type": "integer" }, "description": "Number of items per page (max 100)" }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")", "examples": [ "created_at:desc", "amount:asc", "updated_at:desc" ], "type": "string" }, "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")" }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "active", "used", "expired", "cancelled" ], "description": "Payment link status", "type": "string" }, "description": "Payment link status" }, { "name": "merchant_id", "in": "query", "required": false, "schema": { "format": "uuid", "description": "Filter by merchant ID (admin/partner only)", "type": "string" }, "description": "Filter by merchant ID (admin/partner only)" }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Search by payment reference or order ID", "type": "string" }, "description": "Search by payment reference or order ID" } ] }, "post": { "tags": [ "Payment Links" ], "summary": "Create a new payment link (Partner or Merchant authentication)", "description": "Create a new payment link (Partner or Merchant authentication)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_CreateResponse" }, "example": { "success": true, "data": { "payment_link_url": "https://core.quidkey.com/payment-link/a1b2c3d4e5f6..." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_CreateInput" }, "example": { "order": { "amount": 1000, "currency": "GBP", "payment_reference": "Invoice #123", "order_id": "ORD-123456", "locale": "en", "test_transaction": true }, "redirect_urls": { "success_url": "https://example.com/payment/success", "failure_url": "https://example.com/payment/failure" } } } } } } }, "/api/v1/payment-links/receivable-currencies": { "get": { "tags": [ "Payment Links" ], "summary": "Get currencies the merchant can receive payments in", "description": "Get currencies the merchant can receive payments in", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_ReceivableCurrenciesResponse" }, "example": { "success": true, "data": { "currencies": [ "GBP" ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "query", "required": false, "schema": { "format": "uuid", "description": "Merchant ID (required for Partner auth)", "type": "string" }, "description": "Merchant ID (required for Partner auth)" } ] } }, "/api/v1/payment-links/{id}": { "get": { "tags": [ "Payment Links" ], "summary": "Get payment link details by ID", "description": "Get payment link details by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_DetailResponse" }, "example": { "success": true, "data": { "redirect_urls": { "success_url": "https://example.com/payment/success", "failure_url": "https://example.com/payment/failure" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Payment link ID", "type": "string" }, "description": "Payment link ID" } ] } }, "/api/v1/payment-links/{token}/details": { "get": { "tags": [ "Payment Links" ], "summary": "Get payment link details (public endpoint). Uses secure token for lookup.", "description": "Get payment link details (public endpoint). Uses secure token for lookup.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_DetailsResponse" }, "example": { "success": true, "data": { "allowed_countries": [ { "code": "GB" } ], "default_customer_country": "GB" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "The secure token from the payment link URL (64-char hex)", "examples": [ "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" ], "type": "string" }, "description": "The secure token from the payment link URL (64-char hex)" } ] } }, "/api/v1/payment-links/{token}/confirm": { "post": { "tags": [ "Payment Links" ], "summary": "Confirm payment link and create payment request (public endpoint). Uses secure token for lookup.", "description": "Confirm payment link and create payment request (public endpoint). Uses secure token for lookup.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_ConfirmResponse" }, "example": { "success": true, "data": { "payment_token": "ptok_550e8400-e29b-41d4-a716-446655440000", "expires_in": 900 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "The secure token from the payment link URL (64-char hex)", "examples": [ "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" ], "type": "string" }, "description": "The secure token from the payment link URL (64-char hex)" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentLink_ConfirmInput" }, "example": { "customer": { "name": "John Doe", "email": "john@example.com", "phone": "+351960123456", "country": "GB" } } } } } } }, "/api/v1/embedded": { "get": { "tags": [ "Embedded" ], "summary": "Serve the Quidkey iframe bootstrap HTML", "description": "Serve the Quidkey iframe bootstrap HTML", "responses": {} } }, "/api/v1/embedded/html": { "get": { "tags": [ "Embedded" ], "summary": "Server-side rendered HTML fragment for bank selection", "description": "Server-side rendered HTML fragment for bank selection", "responses": {} } }, "/api/v1/embedded/payment-requests": { "post": { "tags": [ "Embedded" ], "summary": "Create a payment request and return a payment_token for iframe flow", "description": "Create a payment request and return a payment_token for iframe flow", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedPaymentRequest_Response" }, "example": { "success": true, "data": { "payment_token": "ptok_efghijklm...", "expires_in": 900 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedPaymentRequest_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "customer": { "name": "John Doe", "email": "john@example.com", "phone": "+351960123456", "country": "GB" }, "order": { "order_id": "ORD-123456", "amount": 9300, "currency": "GBP", "payment_reference": "Barcelona Tryp", "locale": "en-GB", "test_transaction": true, "rewards": { "extra_rewards": 150, "total_rewards": 300, "description": "Loyalty bonus + base rewards" } }, "device_type": "ios", "billing_address": { "address_line1": "12 West Common Drive", "address_line2": "Flat 1", "apartment": "Apt 5B", "city": "London", "state_province": "Greater London", "country": "GB", "postal_code": "SE1 1AA", "company_name": "Acme Ltd" }, "simulation": { "straddle": { "customer_outcome": "standard", "paykey_outcome": "standard", "charge_outcome": "standard", "balance_check": "required" }, "flinks": { "outcome": "happy", "mfa": "skip" } }, "redirect_urls": { "success_url": "https://tryp.com/checkout/success", "failure_url": "https://tryp.com/checkout/error" }, "webhook_endpoints": [ "wizzair-prod" ] } } } } }, "patch": { "tags": [ "Embedded" ], "summary": "Update an embedded payment request (amount and/or rewards) before payment initiation", "description": "Update an embedded payment request (amount and/or rewards) before payment initiation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedPaymentRequestUpdate_Response" }, "example": { "success": true, "data": { "payment_token": "ptok_abcd1234", "amount": 1530, "rewards": { "extra_rewards": 150, "total_rewards": 300, "description": "Updated loyalty bonus" }, "expires_in": 750 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedPaymentRequestUpdate_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "payment_token": "ptok_abcd1234", "amount": 1530, "rewards": { "extra_rewards": 150, "total_rewards": 300, "description": "Updated loyalty bonus" } } } } } } }, "/api/v1/embedded/flinks-session": { "post": { "tags": [ "Embedded" ], "summary": "Create a Flinks Connect session for the embedded payment flow", "description": "Create a Flinks Connect session for the embedded payment flow", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedFlinksSession_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedFlinksSession_Input" }, "example": { "institution_id": 42 } } } } } }, "/api/v1/embedded/flinks-redirect": { "get": { "tags": [ "Embedded" ], "summary": "Handle Flinks redirect after bank authentication, create CustomerBankAccount", "description": "Handle Flinks redirect after bank authentication, create CustomerBankAccount", "responses": {} } }, "/api/v1/embedded/flinks-session/{sessionId}/cancel": { "post": { "tags": [ "Embedded" ], "summary": "Cancel a Flinks Connect session abandoned by the customer in the iframe", "description": "Cancel a Flinks Connect session abandoned by the customer in the iframe", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedFlinksSession_Cancel_Response" }, "example": { "success": true, "data": { "status": "cancelled" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/embeddedFlinksSession_Cancel_Input" }, "example": { "reason": "user_closed" } } } } } }, "/api/v1/embedded/payment-initiation": { "post": { "tags": [ "Embedded" ], "summary": "Initiate a payment for an embedded flow using payment_token (query or body) and selected bank", "description": "Initiate a payment for an embedded flow using payment_token (query or body) and selected bank", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentInitiation_Response" }, "example": { "success": true, "data": { "order_id": "123" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paymentInitiation_Input" }, "example": { "bankId": "123e4567-e89b-12d3-a456-426614174000", "paymentScheme": null } } } } } }, "/api/v1/straddle-payment": { "get": { "tags": [ "Payment" ], "summary": "Render full-page US bank payment flow (Flinks + Straddle)", "description": "Render full-page US bank payment flow (Flinks + Straddle)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" } } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" } } } } } } }, "parameters": [ { "name": "payment_token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The payment_token parameter" } ] } }, "/api/v1/merchants/{id}/transactions": { "post": { "tags": [ "Transactions" ], "summary": "Search transactions for a merchant with filtering and sorting", "description": "Search transactions for a merchant with filtering and sorting", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_SearchResponse" }, "example": { "data": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "target_status": "pending", "refund_status": "refunding", "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "target_status": "pending", "refund_status": "refunding", "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "target_status": "pending", "refund_status": "refunding", "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } ], "search_metadata": { "sort_applied": [ { "field": "created_at", "direction": "desc" } ] }, "totals": [ { "currency": "EUR", "total_amount": 3034 }, { "currency": "GBP", "total_amount": 534 }, { "currency": "DKK", "total_amount": 2034 } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Phase 1 transaction search with currency totals and enhanced filtering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_Request" }, "example": { "search": { "amount": { "gte": 1000, "lte": 5000 }, "status": { "eq": "completed" }, "customer_email": { "contains": "gmail" } }, "pagination": { "page": 1, "limit": 25 }, "sort": [ { "field": "created_at", "direction": "desc" } ] } } } } } }, "/api/v1/transactions/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Get a transaction by ID", "description": "Get a transaction by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_Response" }, "example": { "data": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the transaction" } ] } }, "/api/v1/transactions/{id}/refunds": { "get": { "tags": [ "Transactions" ], "summary": "List all refunds for a transaction", "description": "List all refunds for a transaction", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_RefundListResponse" }, "example": { "data": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "target_status": "pending", "refund_status": "refunding", "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the transaction" } ] } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/status": { "put": { "tags": [ "Transactions" ], "summary": "Update transaction status to trigger async fee payment or currency conversion", "description": "Update transaction status to trigger async fee payment or currency conversion", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_UpdateStatusResponse" }, "example": { "data": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the transaction" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_UpdateStatusInput" }, "example": { "status": "received" } } } } } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/billing-address": { "put": { "tags": [ "Transactions" ], "summary": "Update billing address for a transaction", "description": "Update billing address for a transaction", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_UpdateBillingAddressResponse" }, "example": { "data": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the transaction" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_UpdateBillingAddressInput" }, "example": { "billing_address": { "address_line1": "12 West Common Drive", "address_line2": "Flat 1", "apartment": "Apt 5B", "city": "London", "state_province": "Greater London", "country": "GB", "postal_code": "SE1 1AA", "company_name": "Acme Ltd" } } } } } } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/customer-bank-account": { "put": { "tags": [ "Transactions" ], "summary": "Link a customer bank account to a transaction for refund payouts", "description": "Link a customer bank account to a transaction for refund payouts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_Response" }, "example": { "data": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the transaction" } ], "requestBody": { "required": true, "description": "Customer bank account creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Input" }, "example": { "account_holder_name": "John Smith", "customer_id": "123e4567-e89b-12d3-a456-426614174002", "account_type": "checking", "currency": "GBP", "country": "GB", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100" } } } } } }, "/api/v1/transactions/{transactionId}/delivery-reports": { "post": { "tags": [ "Transactions" ], "summary": "Create a delivery report from an external adapter (Shopify, WooCommerce, etc.) for observability", "description": "Create a delivery report from an external adapter (Shopify, WooCommerce, etc.) for observability", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deliveryReport_Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "description": "The transaction number (not UUID)", "examples": [ "TXN-2026-00123" ], "type": "string" }, "description": "The transaction number (not UUID)" } ], "requestBody": { "required": true, "description": "Report from an external adapter about a finalization call to the external platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/deliveryReport_Input" }, "example": { "platform": "shopify", "finalization_type": "payment_resolved", "external_reference": "gid://shopify/PaymentSession/abc123", "status": "success", "http_status": 200, "duration_ms": 150 } } } } } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/refunds": { "post": { "tags": [ "Transactions" ], "summary": "Create a cross-border refund for a transaction", "description": "Create a cross-border refund for a transaction", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_Response" }, "example": { "data": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "target_status": "pending", "refund_status": "refunding", "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the original transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the original transaction" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderRefund_CreateRequest" }, "example": { "amount": 100, "reason": "Customer request", "target_status": "received" } } } } }, "get": { "tags": [ "Transactions" ], "summary": "List all refunds for a transaction", "description": "List all refunds for a transaction", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_RefundListResponse" }, "example": { "data": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "target_status": "pending", "refund_status": "refunding", "payment_request": { "order_id": "ORD-2025-00123", "payment_token": "tok_abc123def456" }, "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the original transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the original transaction" } ] } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/refundable-amount": { "get": { "tags": [ "Transactions" ], "summary": "Get the maximum refundable amount for a transaction", "description": "Get the maximum refundable amount for a transaction", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderRefund_RefundableAmountResponse" }, "example": { "data": { "amount": "100.00", "currency": "EUR" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the original transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the original transaction" } ] } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/refund-readiness": { "get": { "tags": [ "Transactions" ], "summary": "Check whether a refund's payout details can be resolved for a transaction (read-only)", "description": "Check whether a refund's payout details can be resolved for a transaction (read-only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderRefund_RefundReadinessResponse" }, "example": { "data": { "payout": { "currency": "EUR", "country": "DE", "account_masked": "****3000" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the original transaction", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the original transaction" } ] } }, "/api/v1/transactions/{transactionId}/billing-address": { "put": { "tags": [ "Transaction Updates (Token)" ], "summary": "Update billing address for a transaction (authenticated via resolution token)", "description": "Update billing address for a transaction (authenticated via resolution token)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_TokenUpdateSuccess" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "type": "string" }, "description": "The unique identifier of the transaction" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_UpdateBillingAddressInput" }, "example": { "billing_address": { "address_line1": "12 West Common Drive", "address_line2": "Flat 1", "apartment": "Apt 5B", "city": "London", "state_province": "Greater London", "country": "GB", "postal_code": "SE1 1AA", "company_name": "Acme Ltd" } } } } } } }, "/api/v1/transactions/{transactionId}/customer-bank-account": { "put": { "tags": [ "Transaction Updates (Token)" ], "summary": "Link customer bank account to a transaction (authenticated via resolution token)", "description": "Link customer bank account to a transaction (authenticated via resolution token)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_TokenUpdateSuccess" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "type": "string" }, "description": "The unique identifier of the transaction" } ], "requestBody": { "required": true, "description": "Customer bank account creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Input" }, "example": { "account_holder_name": "John Smith", "customer_id": "123e4567-e89b-12d3-a456-426614174002", "account_type": "checking", "currency": "GBP", "country": "GB", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100" } } } } } }, "/api/v1/transactions/{transactionId}/resolution/complete": { "post": { "tags": [ "Transaction Updates (Token)" ], "summary": "Mark resolution link as completed after customer submits fixes", "description": "Mark resolution link as completed after customer submits fixes", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_TokenUpdateSuccess" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the transaction", "type": "string" }, "description": "The unique identifier of the transaction" } ] } }, "/api/v1/admin/transactions/{transactionId}/update-and-resend": { "post": { "tags": [ "Transactions", "Admin" ], "summary": "Update transaction status and resend webhook (admin only). Use this when payment status changed after initial callback.", "description": "Update transaction status and resend webhook (admin only). Use this when payment status changed after initial callback.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "transaction_id", "transaction_number", "old_status", "new_status", "old_webhook_status", "new_webhook_status", "webhook_sent" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "old_status": { "type": "string" }, "new_status": { "type": "string" }, "old_webhook_status": { "type": "string" }, "new_webhook_status": { "type": "string" }, "webhook_sent": { "type": "boolean" }, "webhook_error": { "type": "string" } } } } }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Transaction ID", "type": "string" }, "description": "Transaction ID" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "required": [ "status" ], "type": "object", "properties": { "status": { "description": "New transaction status", "examples": [ "completed" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "received", "type": "string" }, { "const": "fee_paid", "type": "string" }, { "const": "converted", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "cancelled", "type": "string" }, { "const": "error", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "status_message": { "description": "Optional status message", "examples": [ "Payment completed after bank confirmation" ], "type": "string" } } }, "example": { "status": "completed", "status_message": "Payment completed after bank confirmation" } } } } } }, "/api/v1/admin/transactions/{transactionId}": { "get": { "tags": [ "Transactions", "Admin" ], "summary": "Get full internal detail for a transaction (admin/debug): merchant, payment-request and provider references, fees, refunds/reversals, and an optional unified event timeline.", "description": "Get full internal detail for a transaction (admin/debug): merchant, payment-request and provider references, fees, refunds/reversals, and an optional unified event timeline.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction_AdminDetailResponse" }, "example": { "data": { "transaction": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "refund_status": "refunding", "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] }, "merchant_webhook_deliveries": [ { "event_type": "quidkey.payment_request.succeeded" } ], "refunds": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "refund_status": "refunding", "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ], "reversals": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "payout_currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "refund_status": "refunding", "fees": { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 }, "items": [ { "currency": { "code": "GBP", "symbol": "€", "name": "Euro", "minor_unit": 2 } } ] } } ] }, "timeline": [ { "type": "provider_status", "source": { "kind": "payment" } } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Transaction ID", "type": "string" }, "description": "Transaction ID" }, { "name": "include_timeline", "in": "query", "required": false, "schema": { "default": false, "description": "Include the unified, event-ordered timeline across the payment and its refunds/reversals", "type": "boolean" }, "description": "Include the unified, event-ordered timeline across the payment and its refunds/reversals" }, { "name": "include_payloads", "in": "query", "required": false, "schema": { "default": false, "description": "Include raw webhook/provider payloads in timeline event details", "type": "boolean" }, "description": "Include raw webhook/provider payloads in timeline event details" } ] } }, "/api/v1/admin/transactions/{transactionId}/calculate-fees": { "post": { "tags": [ "Transactions", "Admin" ], "summary": "Calculate fees for a transaction that is missing them. Use force=true to recalculate (deletes existing PENDING fees first).", "description": "Calculate fees for a transaction that is missing them. Use force=true to recalculate (deletes existing PENDING fees first).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "examples": [ true ], "type": "boolean" }, "data": { "type": "object", "required": [ "transaction_id", "transaction_number", "fees_calculated", "fees" ], "properties": { "transaction_id": { "format": "uuid", "type": "string" }, "transaction_number": { "type": "string" }, "fees_calculated": { "type": "number" }, "fees": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "amount", "currency", "rate_type", "rate_value", "notes" ], "properties": { "id": { "format": "uuid", "type": "string" }, "type": { "type": "string" }, "amount": { "description": "Fee amount in decimal", "type": "number" }, "currency": { "type": "string" }, "rate_type": { "type": "string" }, "rate_value": { "type": "number" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } } }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "422": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error422" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Transaction ID", "type": "string" }, "description": "Transaction ID" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "description": "Delete existing PENDING fees and recalculate. Fails if any fees are invoiced or settled.", "type": "boolean" } } } } } } } }, "/api/v1/refund-session": { "post": { "tags": [ "Refunds" ], "summary": "Create a refund session", "description": "Create a refund session", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refundSession_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "id": "JM1YXF4yUe0vmo-FHsgVK3ZC", "gid": "gid://shopify/RefundSession/JM1YXF4yUe0vmo-FHsgVK3ZC", "payment_id": "rSOX4QcIGECb4ZEydY8GgMTfO", "amount": "1.00", "currency": "GBP", "merchant_locale": "en", "platform": "shopify", "proposed_at": "2025-02-21T11:17:05Z", "test": true } } } } } }, "/api/v1/bank-predictions": { "post": { "tags": [ "Bank Predictions" ], "summary": "Predict banks for a customer based on their contact information", "description": "Predict banks for a customer based on their contact information", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankPrediction_Response" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankPrediction_Request" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "customer_country": "GB", "phone_number": "+447395263205", "email": "customer@example.com", "payment_request_id": "123e4567-e89b-12d3-a456-426614174000", "session_id": "wca23456789abcdef" } } } } } }, "/api/v1/admin/customers": { "post": { "tags": [ "Customers", "Admin" ], "summary": "Create a new customer", "description": "Create a new customer", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Customer creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_Input" }, "example": { "name": "John Doe", "email": "john.doe@example.com", "phone_number": "+491234567890" } } } } } }, "/api/v1/admin/customers/{customerId}": { "get": { "tags": [ "Customers", "Admin" ], "summary": "Retrieve a customer by ID", "description": "Retrieve a customer by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the customer", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the customer" } ] }, "put": { "tags": [ "Customers", "Admin" ], "summary": "Update a customer by ID", "description": "Update a customer by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the customer", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the customer" } ], "requestBody": { "required": true, "description": "Customer creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer_Input" }, "example": { "name": "John Doe", "email": "john.doe@example.com", "phone_number": "+491234567890" } } } } } }, "/api/v1/merchants/{merchantId}/customer-bank-accounts": { "post": { "tags": [ "Customer Bank Accounts" ], "summary": "Create a customer bank account for refund payouts", "description": "Create a customer bank account for refund payouts", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "currency": "GBP", "country": "GB", "status": "active", "account_holder_name": "John Smith", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Customer bank account creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Input" }, "example": { "account_holder_name": "John Smith", "customer_id": "123e4567-e89b-12d3-a456-426614174002", "account_type": "checking", "currency": "GBP", "country": "GB", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100" } } } } }, "get": { "tags": [ "Customer Bank Accounts" ], "summary": "List all customer bank accounts for a merchant", "description": "List all customer bank accounts for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "currency": "GBP", "country": "GB", "status": "active", "account_holder_name": "John Smith", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/customer-bank-accounts/{id}": { "get": { "tags": [ "Customer Bank Accounts" ], "summary": "Get a customer bank account by ID", "description": "Get a customer bank account by ID", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "currency": "GBP", "country": "GB", "status": "active", "account_holder_name": "John Smith", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the customer bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "description": "The unique identifier of the customer bank account" } ] }, "put": { "tags": [ "Customer Bank Accounts" ], "summary": "Update a customer bank account", "description": "Update a customer bank account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "currency": "GBP", "country": "GB", "status": "active", "account_holder_name": "John Smith", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the customer bank account", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "description": "The unique identifier of the customer bank account" } ], "requestBody": { "required": true, "description": "Customer bank account creation/update input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customerBankAccount_Input" }, "example": { "account_holder_name": "John Smith", "customer_id": "123e4567-e89b-12d3-a456-426614174002", "account_type": "checking", "currency": "GBP", "country": "GB", "iban": "DE89370400440532013000", "account_number": "11223344", "sort_code": "123456", "routing_number": "123456789", "bban": "86011117947", "plusgiro_number": "41054685", "bsb": "062-000", "bic": "MARKDEF1100" } } } } } }, "/api/v1/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Get current user identity, context, available contexts, and effective permissions", "description": "Get current user identity, context, available contexts, and effective permissions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authMe_Response" }, "example": { "success": true, "data": { "subject_type": "user", "id": "550e8400-e29b-41d4-a716-446655440000", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "current_context": { "type": "partner", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp" }, "available_contexts": [ { "type": "partner", "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Acme Corp", "roles": [ "admin" ] } ], "effective_roles": [ "partner:admin:550e8400-e29b-41d4-a716-446655440000" ], "permissions": [ "merchants:list" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/api/v1/oauth2/token": { "post": { "tags": [ "Auth" ], "summary": "Issue a new access token", "description": "Issue a new access token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_TokenResponse" }, "example": { "success": true, "data": { "access_token": "example_access_token_xyz789", "refresh_token": "example_refresh_token_abc123", "token_type": "Bearer", "expires_in": 900 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_Error401OrChallenge" } } } } }, "requestBody": { "required": true, "description": "Request token with given grant type - client_credentials, magic_code, google_id_token, or refresh_token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_TokenRequest" } } } } } }, "/api/v1/oauth2/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh an existing access token", "description": "Refresh an existing access token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_TokenResponse" }, "example": { "success": true, "data": { "access_token": "example_access_token_xyz789", "refresh_token": "example_refresh_token_abc123", "token_type": "Bearer", "expires_in": 900 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_RefreshTokenRequest" }, "example": { "refresh_token": "refresh_token_abc123" } } } } } }, "/api/v1/oauth2/healthcheck": { "post": { "tags": [ "Auth" ], "summary": "Check the health of the authentication service", "description": "Check the health of the authentication service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_HealthcheckResponse" }, "example": { "success": true, "data": { "token": "example_token_xyz123", "isExpired": false } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_HealthcheckRequest" }, "example": { "token": "example_token_xyz123" } } } } } }, "/api/v1/banks/top": { "get": { "tags": [ "Banks" ], "summary": "Retrieve the curated top banks for a market. `country` selects the market; optional `currency` filters further; `limit` caps the result count. Public and cacheable at the market level.", "description": "Retrieve the curated top banks for a market. `country` selects the market; optional `currency` filters further; `limit` caps the result count. Public and cacheable at the market level.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_TopBanksResponse" }, "example": { "success": true, "data": { "banks": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "websiteUrl": "https://www.santander.co.uk", "topInMarket": true } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "description": "The market / country code (ISO 3166-1 alpha-2)", "examples": [ "GB" ], "type": "string" }, "description": "The market / country code (ISO 3166-1 alpha-2)" }, { "name": "currency", "in": "query", "required": false, "schema": { "description": "Optional currency filter (ISO 4217)", "examples": [ "GBP" ], "type": "string" }, "description": "Optional currency filter (ISO 4217)" }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 50, "description": "Maximum number of banks to return", "examples": [ 3 ], "type": "integer" }, "description": "Maximum number of banks to return" } ] } }, "/api/v1/banks/top/{market}": { "get": { "tags": [ "Banks" ], "summary": "Retrieve the top banks for a specific market", "description": "Retrieve the top banks for a specific market", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "websiteUrl": "https://www.santander.co.uk", "topInMarket": true } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "description": "The market code (e.g., GB, DE)", "examples": [ "GB" ], "type": "string" }, "description": "The market code (e.g., GB, DE)" } ] } }, "/api/v1/admin/banks/top/{market}": { "put": { "tags": [ "Banks", "Admin" ], "summary": "Update the status of top banks for a specific market", "description": "Update the status of top banks for a specific market", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bank_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "websiteUrl": "https://www.santander.co.uk", "topInMarket": true } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "description": "The market code (e.g., GB, DE)", "examples": [ "GB" ], "type": "string" }, "description": "The market code (e.g., GB, DE)" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "required": [ "bankNames", "topInMarket" ], "type": "object", "properties": { "bankNames": { "type": "array", "items": { "description": "List of bank names to update", "examples": [ "Santander", "Barclays" ], "type": "string" } }, "topInMarket": { "description": "Whether these banks should be marked as top in the market", "examples": [ true ], "type": "boolean" } } }, "example": { "bankNames": [ "Santander" ], "topInMarket": true } } } } } }, "/api/v1/banks/{market}": { "get": { "tags": [ "Banks" ], "summary": "Retrieve banks for a specific market. Without query params returns the default list for the market. With `q` performs a substring match on bank name; `provider` further scopes to a provider configuration; `limit` caps results (default 20, max 50).", "description": "Retrieve banks for a specific market. Without query params returns the default list for the market. With `q` performs a substring match on bank name; `provider` further scopes to a provider configuration; `limit` caps results (default 20, max 50).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "description": "Indicates if the request was successful", "examples": [ true ], "type": "boolean" }, "data": { "title": "Bank", "description": "A financial institution", "additionalProperties": false, "type": "object", "properties": { "id": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "123e4567-e89b-12d3-a456-426614174001" ], "type": "string" }, "name": { "description": "The name of the bank", "examples": [ "Santander" ], "type": "string" }, "market": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "The market of the bank", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "currency": { "pattern": "^[A-Za-z]{3}$", "minLength": 3, "maxLength": 3, "description": "The currency supported by the bank", "examples": [ "GBP", "USD", "EUR", "JPY" ], "type": "string" }, "displayName": { "description": "The display name of the bank", "examples": [ "Santander" ], "type": "string" }, "logoUrl": { "description": "Displayable logo URL. Prefers the bank's native logo; falls back to a logos.dev URL derived from websiteUrl. Empty string when neither is available.", "examples": [ "https://example.com/logo.png", "https://img.logo.dev/chase.com?token=..." ], "type": "string" }, "websiteUrl": { "description": "The bank's website URL (the logos.dev fallback source for logoUrl).", "examples": [ "https://www.santander.co.uk" ], "type": "string" }, "topInMarket": { "description": "Indicates if the bank is top in the market", "examples": [ true ], "type": "boolean" } } } } } }, "example": [ { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "websiteUrl": "https://www.santander.co.uk", "topInMarket": true } } ] } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "market", "in": "path", "required": true, "schema": { "description": "The market code (e.g., GB, DE, US)", "examples": [ "GB" ], "type": "string" }, "description": "The market code (e.g., GB, DE, US)" }, { "name": "q", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 100, "description": "Case-insensitive substring match on bank name", "examples": [ "chase" ], "type": "string" }, "description": "Case-insensitive substring match on bank name" }, { "name": "provider", "in": "query", "required": false, "schema": { "description": "Restrict results to banks tied to this payment provider. Account-info providers (e.g. Flinks) are addressed via the payment provider that routes through them (e.g. straddle / straddle_sandbox).", "anyOf": [ { "const": "tink", "type": "string" }, { "const": "fumopay", "type": "string" }, { "const": "fumopay_sandbox", "type": "string" }, { "const": "sandbox", "type": "string" }, { "const": "straddle", "type": "string" }, { "const": "straddle_sandbox", "type": "string" } ] }, "description": "Restrict results to banks tied to this payment provider. Account-info providers (e.g. Flinks) are addressed via the payment provider that routes through them (e.g. straddle / straddle_sandbox)." }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 50, "default": 20, "description": "Maximum number of results (default 20)", "examples": [ 20 ], "type": "integer" }, "description": "Maximum number of results (default 20)" } ] } }, "/api/v1/banks/initialize": { "post": { "tags": [ "Banks" ], "summary": "Initialize banks in the system", "description": "Initialize banks in the system", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "description": "Success message", "examples": [ "Banks initialized successfully" ], "type": "string" } } }, "example": { "message": "Banks initialized successfully" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "description": "Providers to initialize. If omitted, all providers run.", "examples": [ [ "tink" ], [ "fumopay" ], [ "flinks" ] ], "type": "array", "items": { "anyOf": [ { "const": "tink", "type": "string" }, { "const": "fumopay", "type": "string" }, { "const": "flinks", "type": "string" } ] } } } }, "example": { "providers": [ "tink" ] } } } } } }, "/api/v1/bank-selection": { "get": { "tags": [ "Banks" ], "summary": "Render bank selection page with predicted and market banks", "description": "Render bank selection page with predicted and market banks", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" } } } } } } }, "parameters": [ { "name": "paymentRequestId", "in": "query", "required": true, "schema": { "description": "The payment request ID", "format": "uuid", "type": "string" }, "description": "The payment request ID" } ] } }, "/api/v1/admin/banks/{bankId}/status": { "put": { "tags": [ "Banks", "Admin" ], "summary": "Update bank activation status (admin only)", "description": "Update bank activation status (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankActivation_Response" }, "example": { "success": true, "data": { "bank": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Santander", "market": "GB", "currency": "GBP", "isActive": true, "previousStatus": false }, "message": "Bank activated successfully" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "The unique identifier of the bank" } ], "requestBody": { "required": true, "description": "Input for updating bank activation status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankActivation_Input" }, "example": { "isActive": true } } } } }, "get": { "tags": [ "Banks", "Admin" ], "summary": "Get bank status and details (admin only)", "description": "Get bank status and details (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankActivation_StatusResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "topInMarket": true, "isActive": true, "tinkProvider": { "id": "tink-provider-123", "popular": true }, "providers": [ { "name": "tink", "popular": true } ], "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the bank", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "The unique identifier of the bank" } ] } }, "/api/v1/admin/banks": { "get": { "tags": [ "Banks", "Admin" ], "summary": "Get all banks with their activation status (admin only)", "description": "Get all banks with their activation status (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bankActivation_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Santander", "market": "GB", "currency": "GBP", "displayName": "Santander", "logoUrl": "https://example.com/logo.png", "topInMarket": true, "isActive": true, "tinkProvider": { "id": "tink-provider-123", "popular": true }, "providers": [ { "name": "tink", "popular": true } ], "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "pattern": "^[A-Za-z]{2}$", "minLength": 2, "maxLength": 2, "description": "Filter by market (optional)", "examples": [ "GB", "US", "FR", "DE" ], "type": "string" }, "description": "Filter by market (optional)" }, { "name": "isActive", "in": "query", "required": false, "schema": { "description": "Filter by activation status (optional)", "examples": [ "true" ], "type": "string" }, "description": "Filter by activation status (optional)" } ] } }, "/api/v1/seeds/run-seeds": { "post": { "tags": [ "Seeds" ], "summary": "Run database seed scripts", "description": "Run database seed scripts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/seed_Response" }, "example": { "success": true, "data": { "message": "Seeds created successfully" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/api/v1/seeds/merchant/{merchantId}/test-data": { "post": { "tags": [ "Seeds" ], "summary": "Generate test payment requests and transactions for a specific merchant", "description": "Generate test payment requests and transactions for a specific merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantTestData_Response" }, "example": { "success": true, "data": { "message": "Test data generated successfully for merchant", "summary": { "merchantId": "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "paymentRequestsCreated": 120, "transactionsCreated": 120, "customersCreated": 15, "timeElapsed": "5.5s" }, "details": { "paymentRequestsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "transactionsByType": { "payment": 120, "refund": 0 }, "transactionsByStatus": { "completed": 84, "pending": 18, "failed": 12, "cancelled": 6 }, "amountDistribution": { "small": 48, "medium": 48, "large": 24 }, "currencyDistribution": { "EUR": 60, "GBP": 30, "USD": 18, "DKK": 12 } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The merchant ID to generate test data for", "examples": [ "934eef9d-2ea7-4a83-9646-cb8ecdc54947", "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The merchant ID to generate test data for" } ], "requestBody": { "required": true, "description": "Request body for generating test data for a merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantTestData_Request" }, "example": { "options": { "paymentRequestCount": 120, "customerCount": 15, "dateRangeInDays": 730, "includeRefunds": true, "includeFailures": true, "scenarioProfile": "standard", "includePayouts": true } } } } } } }, "/api/v1/admin/default-rates/active": { "get": { "tags": [ "Default Rates", "Admin" ], "summary": "Retrieve currently active default rates", "description": "Retrieve currently active default rates", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/defaultRates_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/admin/default-rates/history": { "get": { "tags": [ "Default Rates", "Admin" ], "summary": "Retrieve history of all default rates", "description": "Retrieve history of all default rates", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/defaultRates_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/admin/default-rates": { "post": { "tags": [ "Default Rates", "Admin" ], "summary": "Create new default rates", "description": "Create new default rates", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/defaultRates_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Default rates creation input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/defaultRates_Input" }, "example": { "rates": [ { "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "notes": "Standard domestic percentage fee" }, { "type": "fixed_transaction_fee", "value": 0.2, "unit": "currency", "base": "gbp", "notes": "Standard fixed GBP fee" }, { "type": "fixed_transaction_fee", "value": 0.27, "unit": "currency", "base": "eur", "notes": "Standard fixed EUR fee" } ] } } } } } }, "/api/v1/admin/merchants/{merchantId}/rates/active": { "get": { "tags": [ "Merchant Rates", "Admin" ], "summary": "Retrieve active rates for a merchant", "description": "Retrieve active rates for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRates_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174002", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "merchantId": "123e4567-e89b-12d3-a456-426614174000", "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/admin/merchants/{merchantId}/rates/history": { "get": { "tags": [ "Merchant Rates", "Admin" ], "summary": "Retrieve rate history for a merchant", "description": "Retrieve rate history for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRates_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174002", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "merchantId": "123e4567-e89b-12d3-a456-426614174000", "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/admin/merchants/{merchantId}/rates": { "post": { "tags": [ "Merchant Rates", "Admin" ], "summary": "Create custom rates for a merchant", "description": "Create custom rates for a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRates_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174002", "version": "v1-2024-01-13T15:00:00Z", "is_active": true, "merchantId": "123e4567-e89b-12d3-a456-426614174000", "created_by": "system_seed", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "rates": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "defaultRatesId": "123e4567-e89b-12d3-a456-426614174001", "merchantRatesId": "123e4567-e89b-12d3-a456-426614174001", "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "conversion_currencies": { "source": "EUR", "destination": "GBP" }, "notes": "Standard domestic fee" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Merchant rates creation input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/merchantRates_Input" }, "example": { "rates": [ { "type": "domestic_percent_fee", "value": 1, "unit": "%", "base": "gross_amount", "notes": "Standard domestic percentage fee" }, { "type": "fixed_transaction_fee", "value": 0.2, "unit": "currency", "base": "gbp", "notes": "Standard fixed GBP fee" }, { "type": "fixed_transaction_fee", "value": 0.27, "unit": "currency", "base": "eur", "notes": "Standard fixed EUR fee" } ] } } } } } }, "/api/v1/shopify-orders": { "post": { "tags": [ "Shopify Orders" ], "summary": "Create a Shopify order for a merchant", "description": "Create a Shopify order for a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shopifyOrder_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shopifyOrder_Input" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "orderData": { "order_id": "12345", "total": "100.00" } } } } } }, "get": { "tags": [ "Shopify Orders" ], "summary": "Get all Shopify orders for a merchant", "description": "Get all Shopify orders for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shopifyOrder_ListResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/shopify-orders/bulk": { "post": { "tags": [ "Shopify Orders" ], "summary": "Create multiple Shopify orders for a merchant", "description": "Create multiple Shopify orders for a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shopifyOrder_ListResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shopifyOrder_BulkInput" }, "example": { "merchant_id": "550e8400-e29b-41d4-a716-446655440000", "orders": [ { "order_id": "12345", "total": "100.00" } ] } } } } } }, "/api/v1/merchants/{merchantId}/cross-border-enrollments": { "post": { "tags": [ "CrossBorder" ], "summary": "Enable cross-border payments for a merchant with a specific provider", "description": "Enable cross-border payments for a merchant with a specific provider", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "provider": "transfermate", "status": "awaiting_details", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "supported_currencies": [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ], "requestBody": { "required": true, "description": "Request body for enabling cross-border enrollment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_EnableInput" }, "example": { "provider": "transfermate" } } } } }, "get": { "tags": [ "CrossBorder" ], "summary": "List all cross-border enrollments for a merchant", "description": "List all cross-border enrollments for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "provider": "transfermate", "status": "awaiting_details", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "supported_currencies": [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/cross-border-enrollments/{provider}": { "get": { "tags": [ "CrossBorder" ], "summary": "Get cross-border enrollment status for a specific provider", "description": "Get cross-border enrollment status for a specific provider", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "provider": "transfermate", "status": "awaiting_details", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "supported_currencies": [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "provider", "in": "path", "required": true, "schema": { "description": "The cross-border provider name", "examples": [ "transfermate" ], "type": "string" }, "description": "The cross-border provider name" } ] } }, "/api/v1/merchants/{merchantId}/cross-border-enrollments/{provider}/status": { "put": { "tags": [ "CrossBorder" ], "summary": "Update cross-border enrollment status for a specific provider", "description": "Update cross-border enrollment status for a specific provider", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "provider": "transfermate", "status": "awaiting_details", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "supported_currencies": [ { "currency": "USD", "status": "active" }, { "currency": "EUR", "status": "active" }, { "currency": "GBP", "status": "inactive" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "provider", "in": "path", "required": true, "schema": { "description": "The cross-border provider name", "examples": [ "transfermate" ], "type": "string" }, "description": "The cross-border provider name" } ], "requestBody": { "required": true, "description": "Request body for updating cross-border enrollment status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_UpdateStatusInput" }, "example": { "status": "awaiting_verification" } } } } } }, "/api/v1/merchants/{merchantId}/cross-border-enrollments/{provider}/setup-accounts": { "post": { "tags": [ "CrossBorder" ], "summary": "Setup verified merchant accounts (beneficiary and virtual accounts)", "description": "Setup verified merchant accounts (beneficiary and virtual accounts)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/crossBorderEnrollment_SetupAccountsResponse" }, "example": { "success": true, "data": { "message": "Merchant accounts setup completed successfully" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "provider", "in": "path", "required": true, "schema": { "description": "The cross-border provider name", "examples": [ "transfermate" ], "type": "string" }, "description": "The cross-border provider name" } ] } }, "/api/v1/admin/fee-accounts/{provider}": { "post": { "tags": [ "Admin" ], "summary": "Create a fee account for a currency by activating a global account with the provider", "description": "Create a fee account for a currency by activating a global account with the provider", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feeAccount_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "TRANSFERMATE", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "description": "Cross-border provider name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "description": "Cross-border provider name" } ], "requestBody": { "required": true, "description": "Request to create a new fee account for a currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feeAccount_CreateRequest" }, "example": { "currency": "GBP" } } } } }, "get": { "tags": [ "Admin" ], "summary": "List fee accounts for a specific provider", "description": "List fee accounts for a specific provider", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feeAccount_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "TRANSFERMATE", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "currency": "GBP", "provider": "TRANSFERMATE", "provider_account_id": "TM_GBP_FEE_001", "iban": "GB82WEST12345698765432", "swift": "WESTGB2L", "account_number": "87654321", "created_at": "2024-01-15T10:35:00.000Z", "updated_at": "2024-01-15T10:35:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "description": "Cross-border provider name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "description": "Cross-border provider name" } ] } }, "/api/v1/admin/fee-accounts": { "get": { "tags": [ "Admin" ], "summary": "List all fee accounts configured for cross-border payments", "description": "List all fee accounts configured for cross-border payments", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feeAccount_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "EUR", "provider": "TRANSFERMATE", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z" }, { "id": "660e8400-e29b-41d4-a716-446655440001", "currency": "GBP", "provider": "TRANSFERMATE", "provider_account_id": "TM_GBP_FEE_001", "iban": "GB82WEST12345698765432", "swift": "WESTGB2L", "account_number": "87654321", "created_at": "2024-01-15T10:35:00.000Z", "updated_at": "2024-01-15T10:35:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "description": "Filter by cross-border provider", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "description": "Filter by cross-border provider" } ] } }, "/api/v1/admin/fee-accounts/{provider}/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get a single fee account including its live global-account balance", "description": "Get a single fee account including its live global-account balance", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/feeAccount_WithBalanceResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "currency": "GBP", "provider": "transfermate", "provider_account_id": "TM_EUR_FEE_001", "iban": "IE64IRCE92050112345678", "swift": "IRCEGB2L", "account_number": "12345678", "routing_number": "021000021", "created_at": "2024-01-15T10:30:00.000Z", "updated_at": "2024-01-15T10:30:00.000Z", "balance": "12345.67" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "description": "Cross-border provider name", "examples": [ "transfermate", "fake-transfermate" ], "type": "string" }, "description": "Cross-border provider name" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Fee account ID", "type": "string" }, "description": "Fee account ID" } ] } }, "/api/v1/webhooks/transfermate": { "post": { "tags": [ "Webhooks" ], "summary": "Handle TransferMate webhook events", "description": "Handle TransferMate webhook events", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transfermateWebhook_SuccessResponse" }, "example": { "event_id": "3511e175-ab2c-40ec-ba5d-49e466c86328", "customer_id": "80812345", "event_code": "6" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "TransferMate webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transfermateWebhook_Input" }, "example": { "event_id": "3511e175-ab2c-40ec-ba5d-49e466c86328", "customer_id": "80812345", "event_code": "6" } } } } } }, "/api/v1/admin/bank-accounts/{bankAccountId}/transfermate/global-account-details": { "get": { "tags": [ "Admin", "TransferMate" ], "summary": "Get raw TransferMate global account details for a bank account (admin only)", "description": "Get raw TransferMate global account details for a bank account (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminTransfermate_GlobalAccountDetailsResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "502": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error502" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant bank account ID", "type": "string" }, "description": "Merchant bank account ID" }, { "name": "date_from", "in": "query", "required": false, "schema": { "description": "Filter from date (ISO 8601)", "type": "string" }, "description": "Filter from date (ISO 8601)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "description": "Filter to date (ISO 8601)", "type": "string" }, "description": "Filter to date (ISO 8601)" }, { "name": "items_per_page", "in": "query", "required": false, "schema": { "description": "Items per page", "anyOf": [ { "const": "10", "type": "string" }, { "const": "20", "type": "string" }, { "const": "50", "type": "string" }, { "const": "100", "type": "string" } ] }, "description": "Items per page" }, { "name": "p_number", "in": "query", "required": false, "schema": { "description": "Page number", "type": "string" }, "description": "Page number" }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "description": "Filter by transaction ID", "type": "string" }, "description": "Filter by transaction ID" } ] } }, "/api/v1/admin/transfermate/global-accounts/{userBankId}/details": { "get": { "tags": [ "Admin", "TransferMate" ], "summary": "Debug-only: fetch raw TransferMate global account details by raw user_bank_id (resolves the owning merchant via provider_metadata to authenticate). Use when you only have a user_bank_id from a webhook/TM dashboard and don't know the QK bank account ID. Returns 404 if no QK bank account owns that user_bank_id.", "description": "Debug-only: fetch raw TransferMate global account details by raw user_bank_id (resolves the owning merchant via provider_metadata to authenticate). Use when you only have a user_bank_id from a webhook/TM dashboard and don't know the QK bank account ID. Returns 404 if no QK bank account owns that user_bank_id.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminTransfermate_GlobalAccountByUserBankIdResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "502": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error502" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "userBankId", "in": "path", "required": true, "schema": { "pattern": "^\\d+$", "description": "Raw TransferMate user_bank_id", "type": "string" }, "description": "Raw TransferMate user_bank_id" }, { "name": "provider", "in": "query", "required": false, "schema": { "description": "Cross-border provider name (default 'transfermate')", "type": "string" }, "description": "Cross-border provider name (default 'transfermate')" }, { "name": "date_from", "in": "query", "required": false, "schema": { "description": "Filter from date (ISO 8601)", "type": "string" }, "description": "Filter from date (ISO 8601)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "description": "Filter to date (ISO 8601)", "type": "string" }, "description": "Filter to date (ISO 8601)" }, { "name": "items_per_page", "in": "query", "required": false, "schema": { "description": "Items per page", "anyOf": [ { "const": "10", "type": "string" }, { "const": "20", "type": "string" }, { "const": "50", "type": "string" }, { "const": "100", "type": "string" } ] }, "description": "Items per page" }, { "name": "p_number", "in": "query", "required": false, "schema": { "description": "Page number", "type": "string" }, "description": "Page number" }, { "name": "transaction_id", "in": "query", "required": false, "schema": { "description": "Filter by transaction ID", "type": "string" }, "description": "Filter by transaction ID" } ] } }, "/api/v1/admin/bank-accounts/{bankAccountId}/transfermate/transaction-summary": { "get": { "tags": [ "Admin", "TransferMate" ], "summary": "Get raw TransferMate transaction summary for a bank account (admin only)", "description": "Get raw TransferMate transaction summary for a bank account (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminTransfermate_TransactionSummaryResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "502": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error502" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant bank account ID", "type": "string" }, "description": "Merchant bank account ID" }, { "name": "currency_from", "in": "query", "required": false, "schema": { "description": "Filter by source currency", "type": "string" }, "description": "Filter by source currency" }, { "name": "ref_number", "in": "query", "required": false, "schema": { "description": "Filter by reference number", "type": "string" }, "description": "Filter by reference number" }, { "name": "reconciliation_id", "in": "query", "required": false, "schema": { "description": "Filter by reconciliation ID", "type": "string" }, "description": "Filter by reconciliation ID" }, { "name": "date_from", "in": "query", "required": false, "schema": { "description": "Filter from date (ISO 8601)", "type": "string" }, "description": "Filter from date (ISO 8601)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "description": "Filter to date (ISO 8601)", "type": "string" }, "description": "Filter to date (ISO 8601)" }, { "name": "transactions_statuses", "in": "query", "required": false, "schema": { "description": "Comma-separated payment statuses", "type": "string" }, "description": "Comma-separated payment statuses" }, { "name": "client_transaction_id", "in": "query", "required": false, "schema": { "description": "Filter by client transaction ID", "type": "string" }, "description": "Filter by client transaction ID" }, { "name": "p_number", "in": "query", "required": false, "schema": { "description": "Page number", "type": "string" }, "description": "Page number" } ] } }, "/api/v1/admin/manual-transfers": { "post": { "tags": [ "Admin", "TransferMate" ], "summary": "Create a manual transfer between accounts (admin only)", "description": "Create a manual transfer between accounts (admin only)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminPostProcessorLog_ManualTransferResponse" }, "example": { "success": true, "data": { "action": "FEE_TRANSFER", "status": "INITIATED", "from_currency": "EUR", "amount": "100.00", "source_account_type": "MERCHANT_BANK_ACCOUNT", "destination_account_type": "MERCHANT_BANK_ACCOUNT" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body for creating a manual transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminPostProcessorLog_ManualTransferInput" }, "example": { "reference": "QKMT-20240601-001", "source_account_type": "MERCHANT_BANK_ACCOUNT", "destination_account_type": "MERCHANT_BANK_ACCOUNT", "amount": "100.00", "reason": "Correcting misrouted funds" } } } } } }, "/api/v1/webhooks/tink": { "post": { "tags": [ "Webhooks" ], "summary": "Handle Tink Events v2 webhook notifications", "description": "Handle Tink Events v2 webhook notifications", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/tinkWebhook_SuccessResponse" }, "example": { "success": true, "event_id": "evt-123456", "action": "updated", "duplicate": false, "conflict": false } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/api/v1/webhooks/fumopay": { "post": { "tags": [ "Webhooks" ], "summary": "Handle FumoPay webhook notifications", "description": "Handle FumoPay webhook notifications", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "received" ], "properties": { "received": { "type": "boolean" } } } } } } } } }, "/api/v1/callback/fumopay": { "get": { "tags": [ "Payments" ], "summary": "Handle FumoPay payment callback redirect", "description": "Handle FumoPay payment callback redirect", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "HTML response for the callback page", "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "payment_request_id", "in": "query", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The payment_request_id parameter" } ] } }, "/api/v1/admin/merchants/{merchantId}/payouts": { "post": { "tags": [ "Payout", "Admin" ], "summary": "Create a new payout batch for all CONVERTED cross-border transactions", "description": "Create a new payout batch for all CONVERTED cross-border transactions", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_BatchResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "merchant_id": "550e8400-e29b-41d4-a716-446655440001", "source_account_id": "550e8400-e29b-41d4-a716-446655440002", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "retention_reference": "QKM1ABC2DEF34G-RET", "retention_tm_transaction_id": "TM-87654321", "tm_transaction_id": "TM-12345678", "error_message": "Settlement account not found", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" } ] }, "get": { "tags": [ "Payout", "Admin" ], "summary": "List payout batches for a merchant", "description": "List payout batches for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_BatchListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "merchant_id": "550e8400-e29b-41d4-a716-446655440001", "source_account_id": "550e8400-e29b-41d4-a716-446655440002", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "retention_reference": "QKM1ABC2DEF34G-RET", "retention_tm_transaction_id": "TM-87654321", "tm_transaction_id": "TM-12345678", "error_message": "Settlement account not found", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "description": "Status of the payout batch" } ] } }, "/api/v1/admin/merchants/{merchantId}/payouts/{payoutBatchId}": { "get": { "tags": [ "Payout", "Admin" ], "summary": "Get details of a payout batch", "description": "Get details of a payout batch", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_BatchResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "merchant_id": "550e8400-e29b-41d4-a716-446655440001", "source_account_id": "550e8400-e29b-41d4-a716-446655440002", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "retention_reference": "QKM1ABC2DEF34G-RET", "retention_tm_transaction_id": "TM-87654321", "tm_transaction_id": "TM-12345678", "error_message": "Settlement account not found", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "payoutBatchId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the payout batch", "type": "string" }, "description": "The unique identifier of the payout batch" } ] } }, "/api/v1/admin/merchants/{merchantId}/payouts/{payoutBatchId}/status": { "put": { "tags": [ "Payout", "Admin" ], "summary": "Execute a payout batch by setting status to COMPLETED", "description": "Execute a payout batch by setting status to COMPLETED", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_BatchResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "merchant_id": "550e8400-e29b-41d4-a716-446655440001", "source_account_id": "550e8400-e29b-41d4-a716-446655440002", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "retention_reference": "QKM1ABC2DEF34G-RET", "retention_tm_transaction_id": "TM-87654321", "tm_transaction_id": "TM-12345678", "error_message": "Settlement account not found", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "payoutBatchId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the payout batch", "type": "string" }, "description": "The unique identifier of the payout batch" } ], "requestBody": { "required": true, "description": "Request body for updating payout batch status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_UpdateStatusInput" }, "example": { "status": "completed" } } } } } }, "/api/v1/merchants/{merchantId}/payouts": { "get": { "tags": [ "Payout" ], "summary": "List payout batches for the authenticated merchant", "description": "List payout batches for the authenticated merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_MerchantBatchListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Status of the payout batch", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "processing", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" } ] }, "description": "Status of the payout batch" } ] } }, "/api/v1/merchants/{merchantId}/payouts/{payoutBatchId}": { "get": { "tags": [ "Payout" ], "summary": "Get details of a payout batch for the authenticated merchant", "description": "Get details of a payout batch for the authenticated merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/payout_MerchantBatchResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "payment_reference": "QKM1ABC2DEF34G", "status": "pending", "currency": "GBP", "gross_amount": "1395.94", "fees_total": "14.00", "net_amount": "1234.56", "transaction_count": 5, "payout_amount": "1111.10", "retained_amount": "123.46", "retention_rate": "0.1000", "executed_at": "2024-01-15T10:30:00Z", "created_at": "2024-01-15T10:00:00Z" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "payoutBatchId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the payout batch", "type": "string" }, "description": "The unique identifier of the payout batch" } ] } }, "/api/v1/admin/invoices": { "post": { "tags": [ "Invoice", "Admin" ], "summary": "Create a draft invoice for a merchant over a (period, currency) window. Claims eligible transactions atomically; pre-settled fees produce an immediately_settled payment row.", "description": "Create a draft invoice for a merchant over a (period, currency) window. Claims eligible transactions atomically; pre-settled fees produce an immediately_settled payment row.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_Response" }, "example": { "success": true, "data": { "invoice_number": "INV-202605-000001", "payment_reference": "QK7L2M9X4P0R", "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "transaction_count": 42, "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "422": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error422" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "Request body for POST /admin/invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_CreateInput" }, "example": { "currency": "GBP" } } } } }, "get": { "tags": [ "Invoice", "Admin" ], "summary": "List invoices across all billables with optional filters", "description": "List invoices across all billables with optional filters", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_ListResponse" }, "example": { "success": true, "data": [ { "invoice_number": "INV-202605-000001", "payment_reference": "QK7L2M9X4P0R", "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "transaction_count": 42, "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "query", "required": false, "schema": { "format": "uuid", "type": "string" }, "description": "The merchant_id parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "description": "Lifecycle status of the invoice" }, { "name": "period_start_from", "in": "query", "required": false, "schema": { "format": "date", "type": "string" }, "description": "The period_start_from parameter" }, { "name": "period_start_to", "in": "query", "required": false, "schema": { "format": "date", "type": "string" }, "description": "The period_start_to parameter" }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Page size (1-200, default 50)", "pattern": "^[1-9]\\d{0,2}$", "type": "string" }, "description": "Page size (1-200, default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "pattern": "^\\d+$", "type": "string" }, "description": "The offset parameter" } ] } }, "/api/v1/admin/invoices/claimable": { "get": { "tags": [ "Invoice", "Admin" ], "summary": "Preview claimable transactions for a (merchant, period) window. Uses the same eligibility predicate as create; surfaces conflicts when other invoices already own rows in the window. Used by the Create-invoice form to validate the window before submit.", "description": "Preview claimable transactions for a (merchant, period) window. Uses the same eligibility predicate as create; surfaces conflicts when other invoices already own rows in the window. Used by the Create-invoice form to validate the window before submit.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_ClaimablePreviewResponse" }, "example": { "success": true, "data": { "fee_totals_by_currency": [ { "currency": "GBP" } ], "transactions": [ { "deposit_currency": "GBP", "fee_currency": "GBP" } ], "conflicts": [ { "status": "issued" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchant_id", "in": "query", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchant_id parameter" }, { "name": "period_start", "in": "query", "required": true, "schema": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, inclusive", "type": "string" }, "description": "UTC date, inclusive" }, { "name": "period_end", "in": "query", "required": true, "schema": { "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC date, exclusive", "type": "string" }, "description": "UTC date, exclusive" } ] } }, "/api/v1/admin/invoices/{invoiceId}": { "get": { "tags": [ "Invoice", "Admin" ], "summary": "Get details of an invoice (any billable type)", "description": "Get details of an invoice (any billable type)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_Response" }, "example": { "success": true, "data": { "invoice_number": "INV-202605-000001", "payment_reference": "QK7L2M9X4P0R", "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "transaction_count": 42, "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Unique identifier of the invoice", "type": "string" }, "description": "Unique identifier of the invoice" } ] } }, "/api/v1/admin/invoices/{invoiceId}/document": { "get": { "tags": [ "Invoice", "Admin" ], "summary": "Returns the JSON document bundle that drives the PDF/CSV renderers — line items, per-currency subtotals, fee account, issuer block, FX snapshots. Powers the Console preview.", "description": "Returns the JSON document bundle that drives the PDF/CSV renderers — line items, per-currency subtotals, fee account, issuer block, FX snapshots. Powers the Console preview.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_DocumentBundleResponse" }, "example": { "success": true, "data": { "invoice": { "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] }, "line_items": [ { "deposit_currency": "GBP", "payout_currency": "GBP", "fee_currency": "GBP" } ], "currency_subtotals": [ { "source_currency": "GBP", "rate_source": "same_currency" } ], "fee_account": { "currency": "GBP" }, "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The invoiceId parameter" } ] } }, "/api/v1/admin/invoices/{invoiceId}/status": { "put": { "tags": [ "Invoice", "Admin" ], "summary": "Update invoice status. ISSUED issues a draft (auto-PAID if already covered by pre-settled fees); VOID releases the claimed transactions and reverts fees to PENDING (refused if any invoice_payment rows exist). `paid` is never set directly.", "description": "Update invoice status. ISSUED issues a draft (auto-PAID if already covered by pre-settled fees); VOID releases the claimed transactions and reverts fees to PENDING (refused if any invoice_payment rows exist). `paid` is never set directly.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_Response" }, "example": { "success": true, "data": { "invoice_number": "INV-202605-000001", "payment_reference": "QK7L2M9X4P0R", "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "transaction_count": 42, "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The invoiceId parameter" } ], "requestBody": { "required": true, "description": "Request body for PUT /admin/invoices/:id/status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_UpdateStatusInput" }, "example": { "status": "issued" } } } } } }, "/api/v1/admin/invoices/{invoiceId}/payments": { "post": { "tags": [ "Invoice", "Admin" ], "summary": "Record a payment or pre-issue credit against an invoice. payment_method=manual_bank_transfer requires ISSUED (records received funds); issue_credit allowed on DRAFT or ISSUED (write-off / pre-issue discount, requires `notes`). Idempotent on (invoice_id, external_reference).", "description": "Record a payment or pre-issue credit against an invoice. payment_method=manual_bank_transfer requires ISSUED (records received funds); issue_credit allowed on DRAFT or ISSUED (write-off / pre-issue discount, requires `notes`). Idempotent on (invoice_id, external_reference).", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_Response" }, "example": { "success": true, "data": { "invoice_number": "INV-202605-000001", "payment_reference": "QK7L2M9X4P0R", "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "transaction_count": 42, "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The invoiceId parameter" } ], "requestBody": { "required": true, "description": "Request body for POST /admin/invoices/:id/payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_RecordPaymentInput" }, "example": { "amount": "1234.56", "currency": "GBP", "payment_method": "manual_bank_transfer" } } } } } }, "/api/v1/merchants/{merchantId}/invoices": { "get": { "tags": [ "Invoice" ], "summary": "List the merchant's invoices (drafts are hidden — customers see ISSUED+ only)", "description": "List the merchant's invoices (drafts are hidden — customers see ISSUED+ only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_CustomerListResponse" }, "example": { "success": true, "data": [ { "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Lifecycle status of the invoice", "examples": [ "issued" ], "anyOf": [ { "const": "draft", "type": "string" }, { "const": "issued", "type": "string" }, { "const": "paid", "type": "string" }, { "const": "void", "type": "string" } ] }, "description": "Lifecycle status of the invoice" } ] } }, "/api/v1/merchants/{merchantId}/invoices/{invoiceId}": { "get": { "tags": [ "Invoice" ], "summary": "Get an invoice billed to the merchant", "description": "Get an invoice billed to the merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_CustomerResponse" }, "example": { "success": true, "data": { "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The invoiceId parameter" } ] } }, "/api/v1/merchants/{merchantId}/invoices/{invoiceId}/document": { "get": { "tags": [ "Invoice" ], "summary": "Returns the JSON document bundle for a merchant invoice — line items, subtotals, fee account, issuer. Same 404 rules as the detail endpoint (cross-tenant, draft, never-issued).", "description": "Returns the JSON document bundle for a merchant invoice — line items, subtotals, fee account, issuer. Same 404 rules as the detail endpoint (cross-tenant, draft, never-issued).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice_DocumentBundleResponse" }, "example": { "success": true, "data": { "invoice": { "status": "issued", "currency": "GBP", "total_amount": "1234.56", "amount_paid": "0.00", "outstanding_amount": "1234.56", "payments": [ { "amount": "125.00", "currency": "GBP", "payment_method": "manual_bank_transfer" } ], "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] }, "line_items": [ { "deposit_currency": "GBP", "payout_currency": "GBP", "fee_currency": "GBP" } ], "currency_subtotals": [ { "source_currency": "GBP", "rate_source": "same_currency" } ], "fee_account": { "currency": "GBP" }, "fx_rates": [ { "source_currency": "GBP", "rate": "0.85120000", "provider": "openexchangerates" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "invoiceId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The invoiceId parameter" } ] } }, "/api/v1/admin/dev/merchants/{merchantId}/promote-to-live": { "post": { "tags": [ "Merchants", "Admin", "Dev" ], "summary": "Dev-only: flip a sandbox merchant to live mode and re-flag every one of its payment_requests as live (test_transaction=false, provider_environment=live). Refused in production. Idempotent.", "description": "Dev-only: flip a sandbox merchant to live mode and re-flag every one of its payment_requests as live (test_transaction=false, provider_environment=live). Refused in production. Idempotent.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_ModeFlipResponse" }, "example": { "success": true, "data": { "previousMode": "live", "newMode": "live" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ] } }, "/api/v1/admin/dev/merchants/{merchantId}/revert-to-sandbox": { "post": { "tags": [ "Merchants", "Admin", "Dev" ], "summary": "Dev-only: revert a merchant back to sandbox mode and re-flag every one of its payment_requests as test. Refused in production. Idempotent.", "description": "Dev-only: revert a merchant back to sandbox mode and re-flag every one of its payment_requests as test. Refused in production. Idempotent.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_ModeFlipResponse" }, "example": { "success": true, "data": { "previousMode": "live", "newMode": "live" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ] } }, "/api/v1/admin/dev/merchants/{merchantId}/cross-border-enrollments/{provider}/reset": { "post": { "tags": [ "Merchants", "Admin", "Dev" ], "summary": "Dev-only: tear down the merchant's cross-border enrollment + every virtual account from a fake provider. Use after `/admin/reset` on the fake provider so core can re-enroll cleanly. Refused in production or if the provider is not registered as fake.", "description": "Dev-only: tear down the merchant's cross-border enrollment + every virtual account from a fake provider. Use after `/admin/reset` on the fake provider so core can re-enroll cleanly. Refused in production or if the provider is not registered as fake.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_ResetEnrollmentResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The provider parameter" } ] } }, "/api/v1/admin/dev/merchants/{merchantId}/refund-account/clear-activity": { "post": { "tags": [ "Merchants", "Admin", "Dev" ], "summary": "Dev-only: wipe all transactions on the merchant's fake-provider refund account and reset its balance to 0. Use for a clean demo slate without tearing down enrollment. Refused in production or for non-fake providers.", "description": "Dev-only: wipe all transactions on the merchant's fake-provider refund account and reset its balance to 0. Use for a clean demo slate without tearing down enrollment. Refused in production or for non-fake providers.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_ClearRefundActivityResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_ClearRefundActivityInput" } } } } } }, "/api/v1/admin/dev/merchants/{merchantId}/refund-account/simulate-top-up": { "post": { "tags": [ "Merchants", "Admin", "Dev" ], "summary": "Dev-only: simulate an inbound wire onto the merchant refund account via the merchant's fake cross-border provider. Refused in production. Refused if the merchant is not enrolled with a fake provider, so it can never trigger a real TransferMate call.", "description": "Dev-only: simulate an inbound wire onto the merchant refund account via the merchant's fake cross-border provider. Refused in production. Refused if the merchant is not enrolled with a fake provider, so it can never trigger a real TransferMate call.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_SimulateRefundTopUpResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/devMerchant_SimulateRefundTopUpInput" }, "example": { "amount": 250, "currency": "GBP", "provider": "transfermate" } } } } } }, "/api/v1/users/register": { "post": { "tags": [ "Users" ], "summary": "Register a new user account", "description": "Register a new user account", "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_Error401OrChallenge" } } } } }, "requestBody": { "required": true, "description": "Registration request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/auth_RegisterRequest" }, "example": { "email": "user@example.com", "first_name": "John", "last_name": "Doe" } } } } } }, "/api/v1/users/me": { "patch": { "tags": [ "Users" ], "summary": "Update the authenticated user's own profile (name fields)", "description": "Update the authenticated user's own profile (name fields)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_ProfileResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "updated_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Input for updating the current user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_UpdateProfile" }, "example": { "first_name": "John", "last_name": "Doe" } } } } } }, "/api/v1/partners/{partnerId}/users": { "get": { "tags": [ "Users" ], "summary": "List users who have role assignments at this partner", "description": "List users who have role assignments at this partner", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "role_assignments": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The partnerId parameter" } ] } }, "/api/v1/merchants/{merchantId}/users": { "get": { "tags": [ "Users" ], "summary": "List users who have role assignments at this merchant", "description": "List users who have role assignments at this merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "role_assignments": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ] } }, "/api/v1/users": { "get": { "tags": [ "Users" ], "summary": "List all users with their role assignments", "description": "List all users with their role assignments", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_ListResponse" }, "example": { "success": true, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "role_assignments": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } ] } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Users" ], "summary": "Create a new user", "description": "Create a new user", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "role_assignments": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "description": "User creation input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_Input" }, "example": { "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "roles": [ "partner:admin:123e4567-e89b-12d3-a456-426614174001" ] } } } } } }, "/api/v1/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get a user by ID with their role assignments", "description": "Get a user by ID with their role assignments", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_Response" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "default_partner_id": "123e4567-e89b-12d3-a456-426614174001", "default_merchant_id": "123e4567-e89b-12d3-a456-426614174001", "created_at": "2024-03-19T12:00:00Z", "updated_at": "2024-03-19T12:00:00Z", "role_assignments": [ { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The user ID", "type": "string" }, "description": "The user ID" } ] }, "delete": { "tags": [ "Users" ], "summary": "Delete a user and all their role assignments", "description": "Delete a user and all their role assignments", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_SuccessMessage" }, "example": { "success": true, "data": { "message": "User deleted successfully" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The user ID", "type": "string" }, "description": "The user ID" } ] } }, "/api/v1/users/{id}/roles": { "post": { "tags": [ "Users" ], "summary": "Assign a role to a user", "description": "Assign a role to a user", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_RoleAssignmentResponse" }, "example": { "success": true, "data": { "id": "123e4567-e89b-12d3-a456-426614174001", "role": "global:admin", "created_at": "2024-03-19T12:00:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The user ID", "type": "string" }, "description": "The user ID" } ], "requestBody": { "required": true, "description": "Input for assigning a role to a user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_RoleAssignmentInput" }, "example": { "role": "global:admin" } } } } } }, "/api/v1/users/{id}/roles/{assignmentId}": { "delete": { "tags": [ "Users" ], "summary": "Revoke a role assignment from a user", "description": "Revoke a role assignment from a user", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_SuccessMessage" }, "example": { "success": true, "data": { "message": "User deleted successfully" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The user ID", "type": "string" }, "description": "The user ID" }, { "name": "assignmentId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The role assignment ID", "type": "string" }, "description": "The role assignment ID" } ] } }, "/api/v1/admin/provider-status-events/{id}": { "get": { "tags": [ "Admin", "Provider Status" ], "summary": "Get provider status event details including raw payload (admin only)", "description": "Get provider status event details including raw payload (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminProviderStatus_Response" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Provider status event ID", "type": "string" }, "description": "Provider status event ID" } ] } }, "/api/v1/admin/merchant-webhook-deliveries/{id}": { "get": { "tags": [ "Admin", "Webhooks" ], "summary": "Get merchant webhook delivery details including request payload and response body (admin only)", "description": "Get merchant webhook delivery details including request payload and response body (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminMerchantWebhookDelivery_Response" }, "example": { "data": { "event_type": "quidkey.payment_request.succeeded" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant webhook delivery ID", "type": "string" }, "description": "Merchant webhook delivery ID" } ] } }, "/api/v1/admin/webhook-deliveries/{deliveryId}/resend": { "post": { "tags": [ "Admin", "Webhooks" ], "summary": "Resend a webhook by delivery ID (replay stored payload; admin only)", "description": "Resend a webhook by delivery ID (replay stored payload; admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminMerchantWebhookDelivery_ResendResponse" }, "example": { "data": { "status": "delivered" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant webhook delivery ID", "type": "string" }, "description": "Merchant webhook delivery ID" } ] } }, "/api/v1/partners/{partnerId}/invitations": { "post": { "tags": [ "Partner Invitations" ], "summary": "Create an invitation for a user to join a partner", "description": "Create an invitation for a user to join a partner", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_WithLinkResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z", "invitation_link": "https://console.example.com/invitations/accept?token=abc123..." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The partnerId parameter" } ], "requestBody": { "required": true, "description": "Request body for creating an invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_CreateBody" }, "example": { "email": "invitee@example.com", "role": "admin" } } } } }, "get": { "tags": [ "Partner Invitations" ], "summary": "List invitations for a partner", "description": "List invitations for a partner", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The partnerId parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Filter invitations by status (default: pending)", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "all", "type": "string" } ] }, "description": "Filter invitations by status (default: pending)" } ] } }, "/api/v1/partners/{partnerId}/invitations/{id}/resend": { "post": { "tags": [ "Partner Invitations" ], "summary": "Resend a pending partner invitation", "description": "Resend a pending partner invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_WithLinkResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z", "invitation_link": "https://console.example.com/invitations/accept?token=abc123..." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The partnerId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/partners/{partnerId}/invitations/{id}": { "delete": { "tags": [ "Partner Invitations" ], "summary": "Revoke a pending partner invitation", "description": "Revoke a pending partner invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The partnerId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{merchantId}/invitations": { "post": { "tags": [ "Merchant Invitations" ], "summary": "Create an invitation for a user to join a merchant", "description": "Create an invitation for a user to join a merchant", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_WithLinkResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z", "invitation_link": "https://console.example.com/invitations/accept?token=abc123..." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ], "requestBody": { "required": true, "description": "Request body for creating an invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_CreateBody" }, "example": { "email": "invitee@example.com", "role": "admin" } } } } }, "get": { "tags": [ "Merchant Invitations" ], "summary": "List invitations for a merchant", "description": "List invitations for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_ListResponse" }, "example": { "success": true, "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Filter invitations by status (default: pending)", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "all", "type": "string" } ] }, "description": "Filter invitations by status (default: pending)" } ] } }, "/api/v1/merchants/{merchantId}/invitations/{id}/resend": { "post": { "tags": [ "Merchant Invitations" ], "summary": "Resend a pending merchant invitation", "description": "Resend a pending merchant invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_WithLinkResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z", "invitation_link": "https://console.example.com/invitations/accept?token=abc123..." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{merchantId}/invitations/{id}": { "delete": { "tags": [ "Merchant Invitations" ], "summary": "Revoke a pending merchant invitation", "description": "Revoke a pending merchant invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_Response" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "email": "invitee@example.com", "scope_type": "partner", "scope_id": "550e8400-e29b-41d4-a716-446655440000", "role": "admin", "status": "pending", "expires_at": "2026-02-12T00:00:00.000Z", "invited_by_user_id": "550e8400-e29b-41d4-a716-446655440000", "accepted_at": null, "accepted_by_user_id": null, "last_sent_at": "2026-02-05T12:00:00.000Z", "send_count": 1, "created_at": "2026-02-05T12:00:00.000Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/user-invitations/preview": { "get": { "tags": [ "User Invitations" ], "summary": "Preview an invitation (public — used from the email link)", "description": "Preview an invitation (public — used from the email link)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_PreviewResponse" }, "example": { "success": true, "data": { "email": "invitee@example.com", "scope_type": "partner", "scope_name": "Acme Corp", "role": "admin", "expires_at": "2026-02-12T00:00:00.000Z", "status": "pending" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "description": "Raw invitation token from the email link", "type": "string" }, "description": "Raw invitation token from the email link" } ] } }, "/api/v1/user-invitations/accept": { "post": { "tags": [ "User Invitations" ], "summary": "Accept an invitation (requires authentication, email must match)", "description": "Accept an invitation (requires authentication, email must match)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_AcceptResponse" }, "example": { "success": true, "data": { "status": "accepted" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body for accepting an invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invitation_AcceptBody" }, "example": { "token": "a1b2c3d4e5f6..." } } } } } }, "/api/v1/merchants/{id}/account-information/sessions": { "post": { "tags": [ "Account Information" ], "summary": "Create an account information (bank linking) session. Returns connect_url for provider UI and session_id for polling/redirect.", "description": "Create an account information (bank linking) session. Returns connect_url for provider UI and session_id for polling/redirect.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_CreateSessionResponse" }, "example": { "success": true, "data": { "session_id": "550e8400-e29b-41d4-a716-446655440000", "verification_token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", "expires_at": "2024-03-19T13:30:00Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "description": "Request body for creating an account information (bank linking) session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_CreateSessionInput" }, "example": { "country": "GB", "redirect_url": "https://dashboard.example.com/bank-accounts/linked", "transaction_days": 90 } } } } }, "get": { "tags": [ "Account Information" ], "summary": "List account information sessions with optional status filter and cursor pagination.", "description": "List account information sessions with optional status filter and cursor pagination.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_ListSessionsResponse" }, "example": { "success": true, "data": { "sessions": [ { "status": "pending" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Current session status", "examples": [ "pending" ], "anyOf": [ { "const": "pending", "type": "string" }, { "const": "completed", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "expired", "type": "string" }, { "const": "cancelled", "type": "string" } ] }, "description": "Current session status" }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "default": 20, "description": "Maximum number of sessions to return", "type": "integer" }, "description": "Maximum number of sessions to return" }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor for pagination (opaque string from previous response)", "type": "string" }, "description": "Cursor for pagination (opaque string from previous response)" } ] } }, "/api/v1/merchants/{id}/account-information/sessions/{sessionId}/confirm": { "post": { "tags": [ "Account Information" ], "summary": "Confirm selected accounts from a completed session; creates merchant bank account records. Returns created (masked) and skipped (duplicate) provider account IDs.", "description": "Confirm selected accounts from a completed session; creates merchant bank account records. Returns created (masked) and skipped (duplicate) provider account IDs.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_ConfirmAccountsResponse" }, "example": { "success": true, "data": { "created": [ { "account_number_masked": "****7890", "routing_number": "021000021", "currency": "USD", "country": "US", "status": "active", "account_type": "owned" } ] } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "Session ID" } ], "requestBody": { "required": true, "description": "Request body for confirming selected accounts from an account information session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_ConfirmAccountsInput" }, "example": { "selected_account_ids": [ [ "acc-123", "acc-456" ] ] } } } } } }, "/api/v1/merchants/{id}/account-information/sessions/{sessionId}/cancel": { "post": { "tags": [ "Account Information" ], "summary": "Cancel a pending verification session.", "description": "Cancel a pending verification session.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_CancelSessionResponse" }, "example": { "success": true, "data": { "status": "pending" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "Session ID" } ] } }, "/api/v1/merchants/{id}/account-information/sessions/{sessionId}": { "get": { "tags": [ "Account Information" ], "summary": "Get account information session status and details (including retrieved accounts when completed).", "description": "Get account information session status and details (including retrieved accounts when completed).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_SessionResponse" }, "example": { "success": true, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "provider_name": "flinks", "status": "pending" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "Session ID" } ] } }, "/api/v1/merchants/{id}/account-information/sessions/{sessionId}/provider-status-events": { "get": { "tags": [ "Account Information" ], "summary": "Get account information provider status event summaries for a session.", "description": "Get account information provider status event summaries for a session.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformationProviderStatus_ListResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Session ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "Session ID" } ] } }, "/api/v1/merchants/{id}/bank-accounts/{bankAccountId}/provider-status-events": { "get": { "tags": [ "Account Information" ], "summary": "Get account information provider status event summaries for a bank account.", "description": "Get account information provider status event summaries for a bank account.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformationProviderStatus_ListResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "Merchant ID" }, { "name": "bankAccountId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Bank account ID", "examples": [ "550e8400-e29b-41d4-a716-446655440000" ], "type": "string" }, "description": "Bank account ID" } ] } }, "/api/v1/account-information/redirect": { "get": { "tags": [ "Account Information" ], "summary": "Redirect URL for provider (e.g. Flinks) after user completes bank linking. Redirects to client redirect_url with status.", "description": "Redirect URL for provider (e.g. Flinks) after user completes bank linking. Redirects to client redirect_url with status.", "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "Verification token (embedded in provider redirect URL when creating session)", "type": "string" }, "description": "Verification token (embedded in provider redirect URL when creating session)" }, { "name": "LoginId", "in": "query", "required": false, "schema": { "description": "Flinks login ID returned after user completes flow", "type": "string" }, "description": "Flinks login ID returned after user completes flow" }, { "name": "loginId", "in": "query", "required": false, "schema": { "description": "Flinks login ID (lowercase variant)", "type": "string" }, "description": "Flinks login ID (lowercase variant)" } ] } }, "/api/v1/account-verification/{token}/activate": { "post": { "tags": [ "Account Information" ], "summary": "Activate a verification session by generating a fresh provider connect URL. Called when the user clicks \"Connect Bank Account\" on the consent page.", "description": "Activate a verification session by generating a fresh provider connect URL. Called when the user clicks \"Connect Bank Account\" on the consent page.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_ActivateVerificationResponse" }, "example": { "success": true, "data": { "connect_url": "https://connect.example.com/v2/?authorizeToken=..." } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "The secure verification token from the verification link URL (64-char hex)", "examples": [ "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" ], "type": "string" }, "description": "The secure verification token from the verification link URL (64-char hex)" } ] } }, "/api/v1/account-verification/{token}/details": { "get": { "tags": [ "Account Information" ], "summary": "Get verification session details for the public verification page. Uses secure token for lookup (not session ID). Returns merchant info, requested data types, and connect URL.", "description": "Get verification session details for the public verification page. Uses secure token for lookup (not session ID). Returns merchant info, requested data types, and connect URL.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_VerificationDetailsResponse" }, "example": { "success": true, "data": { "status": "pending", "merchant": { "name": "Acme Corp", "brand_name": "Acme Store" }, "options": { "transaction_days": 90, "statement_count": 1 } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "minLength": 64, "maxLength": 64, "pattern": "^[a-f0-9]{64}$", "description": "The secure verification token from the verification link URL (64-char hex)", "examples": [ "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" ], "type": "string" }, "description": "The secure verification token from the verification link URL (64-char hex)" } ] } }, "/api/v1/admin/account-information/provider-status-events/{id}": { "get": { "tags": [ "Admin", "Account Information" ], "summary": "Get account information provider status event details including raw payload (admin only)", "description": "Get account information provider status event details including raw payload (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminAccountInformationProviderStatus_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Account information provider status event ID", "type": "string" }, "description": "Account information provider status event ID" } ] } }, "/api/v1/admin/account-information/expire-sessions": { "post": { "tags": [ "Admin", "Account Information" ], "summary": "Expire stale PENDING account information sessions past their TTL. Intended for scheduled cleanup (e.g., Cloud Scheduler every 5 minutes).", "description": "Expire stale PENDING account information sessions past their TTL. Intended for scheduled cleanup (e.g., Cloud Scheduler every 5 minutes).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountInformation_ExpireSessionsResponse" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/admin/post-processor-logs": { "get": { "tags": [ "Post-Processor Logs", "Admin" ], "summary": "List post-processor log entries with optional filters (admin only)", "description": "List post-processor log entries with optional filters (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminPostProcessorLog_ListResponse" }, "example": { "success": true, "data": [ { "action": "FEE_TRANSFER", "status": "INITIATED", "from_currency": "EUR", "amount": "100.00", "source_account_type": "MERCHANT_BANK_ACCOUNT", "destination_account_type": "MERCHANT_BANK_ACCOUNT" } ], "pagination": { "total": 150, "page": 1, "limit": 25, "totalPages": 6, "hasNextPage": true, "hasPreviousPage": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "minimum": 1, "default": 1, "description": "Page number (1-based)", "examples": [ 1, 2, 3 ], "type": "integer" }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 100, "default": 25, "description": "Number of items per page (max 100)", "examples": [ 10, 25, 50 ], "type": "integer" }, "description": "Number of items per page (max 100)" }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")", "examples": [ "created_at:desc", "amount:asc", "updated_at:desc" ], "type": "string" }, "description": "Sort field and direction (e.g., \"created_at:desc\", \"amount:asc\")" }, { "name": "merchant_id", "in": "query", "required": false, "schema": { "format": "uuid", "description": "Filter by merchant ID", "type": "string" }, "description": "Filter by merchant ID" }, { "name": "action", "in": "query", "required": false, "schema": { "description": "Type of post-processor action", "anyOf": [ { "const": "FEE_TRANSFER", "type": "string" }, { "const": "CURRENCY_CONVERSION", "type": "string" }, { "const": "PAYOUT", "type": "string" }, { "const": "REFUND_RETENTION", "type": "string" }, { "const": "MANUAL", "type": "string" } ] }, "description": "Type of post-processor action" }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Status of the post-processor log entry", "anyOf": [ { "const": "INITIATED", "type": "string" }, { "const": "COMPLETED", "type": "string" }, { "const": "FAILED", "type": "string" } ] }, "description": "Status of the post-processor log entry" }, { "name": "from_date", "in": "query", "required": false, "schema": { "format": "date-time", "description": "Filter logs created after this date", "type": "string" }, "description": "Filter logs created after this date" }, { "name": "to_date", "in": "query", "required": false, "schema": { "format": "date-time", "description": "Filter logs created before this date", "type": "string" }, "description": "Filter logs created before this date" } ] } }, "/api/v1/admin/post-processor-logs/{logId}": { "get": { "tags": [ "Post-Processor Logs", "Admin" ], "summary": "Get a single post-processor log entry by ID (admin only)", "description": "Get a single post-processor log entry by ID (admin only)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adminPostProcessorLog_Response" }, "example": { "success": true, "data": { "action": "FEE_TRANSFER", "status": "INITIATED", "from_currency": "EUR", "amount": "100.00", "source_account_type": "MERCHANT_BANK_ACCOUNT", "destination_account_type": "MERCHANT_BANK_ACCOUNT" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "logId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Post-processor log ID", "type": "string" }, "description": "Post-processor log ID" } ] } }, "/api/v1/webhooks/flinks": { "post": { "tags": [ "Webhooks" ], "summary": "Handle Flinks GetAccountsDetail webhook payloads", "description": "Handle Flinks GetAccountsDetail webhook payloads", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flinksWebhook_SuccessResponse" }, "example": { "data": { "action": "processed" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Flinks GetAccountsDetail payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/flinksWebhook_Input" }, "example": { "HttpStatusCode": 200, "RequestId": "22178382-31ee-485c-a750-c20929b6a344", "Login": { "Id": "5602459c-f6d0-4ca0-6750-08dccdcadcc0" }, "InstitutionName": "FlinksCapital", "InstitutionId": 14, "Institution": "FlinksCapital" } } } } } }, "/api/v1/partners/{id}/branding": { "get": { "tags": [ "Branding" ], "summary": "Get partner branding (logo, colors)", "description": "Get partner branding (logo, colors)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "put": { "tags": [ "Branding" ], "summary": "Update partner branding colors and website", "description": "Update partner branding colors and website", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_PartnerUpdate" } } } } } }, "/api/v1/partners/{id}/branding/logo": { "post": { "tags": [ "Branding" ], "summary": "Upload partner logo (multipart/form-data)", "description": "Upload partner logo (multipart/form-data)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "delete": { "tags": [ "Branding" ], "summary": "Remove partner logo", "description": "Remove partner logo", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/partners/{id}/branding/icon": { "post": { "tags": [ "Branding" ], "summary": "Upload partner icon (multipart/form-data)", "description": "Upload partner icon (multipart/form-data)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "delete": { "tags": [ "Branding" ], "summary": "Remove partner icon", "description": "Remove partner icon", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/partners/{id}/branding/extract": { "post": { "tags": [ "Branding" ], "summary": "Auto-extract branding from partner website using Firecrawl", "description": "Auto-extract branding from partner website using Firecrawl", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_ExtractResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{id}/branding": { "get": { "tags": [ "Branding" ], "summary": "Get merchant branding (logo, colors)", "description": "Get merchant branding (logo, colors)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "put": { "tags": [ "Branding" ], "summary": "Update merchant branding colors", "description": "Update merchant branding colors", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Update" } } } } } }, "/api/v1/merchants/{id}/branding/logo": { "post": { "tags": [ "Branding" ], "summary": "Upload merchant logo (multipart/form-data)", "description": "Upload merchant logo (multipart/form-data)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "delete": { "tags": [ "Branding" ], "summary": "Remove merchant logo", "description": "Remove merchant logo", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{id}/branding/icon": { "post": { "tags": [ "Branding" ], "summary": "Upload merchant icon (multipart/form-data)", "description": "Upload merchant icon (multipart/form-data)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] }, "delete": { "tags": [ "Branding" ], "summary": "Remove merchant icon", "description": "Remove merchant icon", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{id}/branding/extract": { "post": { "tags": [ "Branding" ], "summary": "Auto-extract branding from merchant URI using Firecrawl", "description": "Auto-extract branding from merchant URI using Firecrawl", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/branding_ExtractResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/providers": { "get": { "tags": [ "Onboarding" ], "summary": "List all registered onboarding providers with their requirements and config", "description": "List all registered onboarding providers with their requirements and config", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/onboarding_ProviderListResponse" }, "example": { "success": true, "data": { "providers": [ { "provider": "quidkey", "mode": "live", "dependencies": [ "quidkey" ], "requirements": [ { "code": "LEGAL_ENTITY_EXISTS", "label": "Legal entity attached" } ] } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/merchants/{merchantId}/onboarding": { "get": { "tags": [ "Onboarding" ], "summary": "Get onboarding readiness report for a merchant across all providers", "description": "Get onboarding readiness report for a merchant across all providers", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/onboarding_ReadinessResponse" }, "example": { "success": true, "data": { "merchant_id": "123e4567-e89b-12d3-a456-426614174000", "providers": [ { "provider": "quidkey", "mode": "live", "status": "not_applicable", "requirements": [ { "code": "LEGAL_ENTITY_EXISTS", "label": "Legal entity attached", "met": true, "blocker": "Merchant must have a legal entity", "problems": [ { "field": "company_name", "message": "Company name is required" } ] } ], "depends_on": [ { "provider": "quidkey", "satisfied": true } ], "can_enroll": false } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/onboarding/{provider}/status": { "put": { "tags": [ "Onboarding" ], "summary": "Update onboarding status for a merchant with a specific provider. Use 'enrolling' to start enrollment or 'onboarded' to complete it.", "description": "Update onboarding status for a merchant with a specific provider. Use 'enrolling' to start enrollment or 'onboarded' to complete it.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/onboarding_ProviderReadinessResponse" }, "example": { "success": true, "data": { "provider": "quidkey", "mode": "live", "status": "not_applicable", "requirements": [ { "code": "LEGAL_ENTITY_EXISTS", "label": "Legal entity attached", "met": true, "blocker": "Merchant must have a legal entity", "problems": [ { "field": "company_name", "message": "Company name is required" } ] } ], "depends_on": [ { "provider": "quidkey", "satisfied": true } ], "can_enroll": false } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" }, { "name": "provider", "in": "path", "required": true, "schema": { "description": "The provider name", "examples": [ "transfermate" ], "type": "string" }, "description": "The provider name" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/onboarding_UpdateStatusInput" }, "example": { "status": "enrolling" } } } } } }, "/api/v1/payment-providers": { "get": { "tags": [ "Provider Configuration" ], "summary": "List all payment providers with country coverage", "description": "List all payment providers with country coverage", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_ProvidersListResponse" }, "example": { "success": true, "data": [ { "countries": [ { "country_code": "GB" } ] } ] } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/merchants/{merchantId}/provider-configurations": { "post": { "tags": [ "Provider Configuration" ], "summary": "Create or update provider credentials for a merchant", "description": "Create or update provider credentials for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_Response" }, "example": { "success": true } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_Response" }, "example": { "success": true } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ], "requestBody": { "required": true, "description": "Input for creating or updating a provider configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_Input" } } } } }, "get": { "tags": [ "Provider Configuration" ], "summary": "List provider configurations for a merchant (credentials masked)", "description": "List provider configurations for a merchant (credentials masked)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_ListResponse" }, "example": { "success": true } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ] } }, "/api/v1/merchants/{merchantId}/provider-configurations/{providerName}": { "delete": { "tags": [ "Provider Configuration" ], "summary": "Delete provider configuration for a merchant", "description": "Delete provider configuration for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/providerConfiguration_DeleteResponse" }, "example": { "success": true } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "providerName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The providerName parameter" } ] } }, "/api/v1/merchants/{merchantId}/go-live": { "get": { "tags": [ "Go Live" ], "summary": "Get merchant-facing go-live status with steps and progress", "description": "Get merchant-facing go-live status with steps and progress", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/goLive_Response" }, "example": { "success": true, "data": { "status": "in_progress", "steps": [ { "key": "business_information", "label": "Complete business information", "status": "not_started", "hint": "Some business details are still missing" } ], "progress": { "completed": 2, "total": 4, "percentage": 75 }, "celebration_pending": false } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/go-live/celebrate": { "post": { "tags": [ "Go Live" ], "summary": "Mark the go-live celebration as shown for this merchant", "description": "Mark the go-live celebration as shown for this merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_BaseResponse" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "The unique identifier of the merchant", "examples": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "string" }, "description": "The unique identifier of the merchant" } ] } }, "/api/v1/merchants/{merchantId}/shareholder-invitations": { "post": { "tags": [ "Shareholder Invitations" ], "summary": "Create a shareholder invitation for KYC onboarding", "description": "Create a shareholder invitation for KYC onboarding", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_WithLinkResponse" }, "example": { "success": true, "data": { "status": "pending", "display_status": "accepted" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "409": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error409" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ], "requestBody": { "required": true, "description": "Request body for creating a shareholder invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_CreateBody" } } } } }, "get": { "tags": [ "Shareholder Invitations" ], "summary": "List all shareholder invitations for a merchant", "description": "List all shareholder invitations for a merchant", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_ListResponse" }, "example": { "success": true, "data": [ { "status": "pending", "display_status": "accepted" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" } ] } }, "/api/v1/merchants/{merchantId}/shareholder-invitations/{id}/resend": { "post": { "tags": [ "Shareholder Invitations" ], "summary": "Resend a shareholder invitation email", "description": "Resend a shareholder invitation email", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_WithLinkResponse" }, "example": { "success": true, "data": { "status": "pending", "display_status": "accepted" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{merchantId}/shareholder-invitations/{id}/link": { "post": { "tags": [ "Shareholder Invitations" ], "summary": "Get the invitation link for a shareholder invitation", "description": "Get the invitation link for a shareholder invitation", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_WithLinkResponse" }, "example": { "success": true, "data": { "status": "pending", "display_status": "accepted" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/merchants/{merchantId}/shareholder-invitations/{id}": { "delete": { "tags": [ "Shareholder Invitations" ], "summary": "Delete a shareholder invitation (and associated shareholder if created)", "description": "Delete a shareholder invitation (and associated shareholder if created)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_BaseResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The merchantId parameter" }, { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/shareholder-invitations/preview": { "get": { "tags": [ "Shareholder Invitations" ], "summary": "Preview a shareholder invitation (public, no auth required)", "description": "Preview a shareholder invitation (public, no auth required)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_PreviewResponse" }, "example": { "success": true, "data": { "status": "pending" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "description": "Raw invitation token", "type": "string" }, "description": "Raw invitation token" } ] } }, "/api/v1/shareholder-invitations/submit-step": { "post": { "tags": [ "Shareholder Invitations" ], "summary": "Submit a wizard step for shareholder onboarding (public, no auth required)", "description": "Submit a wizard step for shareholder onboarding (public, no auth required)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_SubmitStepResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "410": { "description": "Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error410" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "requestBody": { "required": true, "description": "Request body for submitting a wizard step. The payload field accepts step-specific data; per-step validation is applied using Step1PayloadSchema/Step2PayloadSchema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shareholderInvitation_SubmitStepBody" } } } } } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/resolution-link": { "post": { "tags": [ "Refund Resolution Links" ], "summary": "Create and optionally send a resolution link for a pending refund", "description": "Create and optionally send a resolution link for a pending refund", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_SendResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "description": "Merchant ID" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Original transaction ID", "type": "string" }, "description": "Original transaction ID" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_SendBody" } } } } } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/resolution-link/rotate": { "post": { "tags": [ "Refund Resolution Links" ], "summary": "Rotate token and get existing resolution link", "description": "Rotate token and get existing resolution link", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_GetResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "description": "Merchant ID" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Original transaction ID", "type": "string" }, "description": "Original transaction ID" } ] } }, "/api/v1/merchants/{merchantId}/transactions/{transactionId}/resolution-link/resend": { "post": { "tags": [ "Refund Resolution Links" ], "summary": "Resend resolution link email with rotated token", "description": "Resend resolution link email with rotated token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_ResendResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Merchant ID", "type": "string" }, "description": "Merchant ID" }, { "name": "transactionId", "in": "path", "required": true, "schema": { "format": "uuid", "description": "Original transaction ID", "type": "string" }, "description": "Original transaction ID" } ], "requestBody": { "required": true, "description": "Request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_ResendBody" } } } } } }, "/api/v1/transactions/resolution-preview": { "get": { "tags": [ "Refund Resolution Links" ], "summary": "Customer previews refund requirements via token", "description": "Customer previews refund requirements via token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/resolutionLink_PreviewResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "minLength": 10, "description": "Resolution link token", "type": "string" }, "description": "Resolution link token" } ] } }, "/api/v1/dashboard/summary": { "get": { "tags": [ "Dashboard" ], "summary": "Get dashboard summary with scope-aware KPI metrics", "description": "Get dashboard summary with scope-aware KPI metrics", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/dashboard_SummaryResponse" }, "example": { "success": true, "data": { "scope": "global", "period": "30d", "volume_by_currency": [ { "currency": "GBP" } ], "fees_by_currency": [ { "currency": "GBP" } ], "next_payout_by_currency": [ { "currency": "GBP" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "description": "Time period for KPI metrics (default: 30d)", "anyOf": [ { "const": "30d", "type": "string" }, { "const": "60d", "type": "string" }, { "const": "all", "type": "string" } ] }, "description": "Time period for KPI metrics (default: 30d)" } ] } }, "/api/v1/webhooks/straddle": { "post": { "tags": [ "Webhooks" ], "summary": "Handle Straddle webhook events", "description": "Handle Straddle webhook events", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/straddleWebhook_SuccessResponse" }, "example": { "received": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/internal/command-palette/search": { "get": { "tags": [ "Command Palette" ], "summary": "Permission-scoped search for the ⌘K command palette.", "description": "Permission-scoped search for the ⌘K command palette.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commandPalette_SearchResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error400" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "minLength": 1, "maxLength": 200, "description": "Search query", "type": "string" }, "description": "Search query" }, { "name": "type", "in": "query", "required": false, "schema": { "description": "Filter to a single entity type. Unknown values are rejected at validation rather than silently returning [].", "anyOf": [ { "const": "partner", "type": "string" }, { "const": "merchant", "type": "string" }, { "const": "payment-link", "type": "string" }, { "const": "payout", "type": "string" }, { "const": "transaction", "type": "string" }, { "const": "invoice", "type": "string" } ] }, "description": "Filter to a single entity type. Unknown values are rejected at validation rather than silently returning []." }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 20, "default": 5, "type": "integer" }, "description": "The limit parameter" } ] } }, "/internal/command-palette/reindex": { "post": { "tags": [ "Command Palette" ], "summary": "Admin-only: rebuild every command palette index from Postgres. Use after seeding or if indexes drift.", "description": "Admin-only: rebuild every command palette index from Postgres. Use after seeding or if indexes drift.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/commandPalette_ReindexResponse" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/legal/current-agreements": { "get": { "tags": [ "Legal" ], "summary": "List the current version URLs for Quidkey-hosted and Straddle legal agreements", "description": "List the current version URLs for Quidkey-hosted and Straddle legal agreements", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/agreement_CurrentAgreementsResponse" }, "example": { "success": true, "data": { "agreements": [ { "kind": "quidkey_privacy", "version": "2026-04-22", "url": "https://app.quidkey.com/legal/ach-authorization-2026-04-22" } ] } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error500" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } } } }, "/api/v1/admin/evidence/{id}": { "get": { "tags": [ "Evidence" ], "summary": "Fetch a single evidence record by id (admin debug)", "description": "Fetch a single evidence record by id (admin debug)", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/evidence_Response" }, "example": { "success": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "const": false, "type": "boolean" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "const": "EVIDENCE_NOT_FOUND", "type": "string" }, "message": { "examples": [ "Evidence not found" ], "type": "string" } } } } }, "example": { "success": false, "error": { "code": "EVIDENCE_NOT_FOUND", "message": "Evidence not found" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/admin/agreement-records/{id}/bundle": { "get": { "tags": [ "Agreement" ], "summary": "Download a markdown forensic bundle for an AgreementRecord — the legal acceptance plus the linked evidence detail.", "description": "Download a markdown forensic bundle for an AgreementRecord — the legal acceptance plus the linked evidence detail.", "responses": {}, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } }, "/api/v1/admin/merchants/{id}/agreement-records": { "get": { "tags": [ "Agreement", "Admin" ], "summary": "List merchant-level AgreementRecords the merchant has accepted, in the order they were signed. Excludes per-transaction records (e.g. customer ACH authorizations).", "description": "List merchant-level AgreementRecords the merchant has accepted, in the order they were signed. Excludes per-transaction records (e.g. customer ACH authorizations).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/agreement_MerchantAgreementRecordsListResponse" }, "example": { "success": true, "data": [ { "agreement_kind": "quidkey_privacy", "agreement_kind_label": "Quidkey Merchant Terms" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error401" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error403" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/shared_Error404" }, "example": { "success": false, "error": { "message": "Invalid input provided" } } } } } }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "The id parameter" } ] } } } }