{ "openapi": "3.1.0", "paths": { "/api/v1/healthz": { "get": { "operationId": "getHealthz", "summary": "Health check endpoint", "description": "Returns the current health status of the service. Used by load balancers and monitoring systems to verify service availability.", "parameters": [], "responses": { "200": { "description": "Service is healthy and operational", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthzDto" } } } }, "400": { "description": "Invalid request parameters" }, "500": { "description": "Service is unhealthy or experiencing issues" } }, "tags": [ "Health" ], "security": [ {} ] } }, "/api/v1/countries": { "get": { "operationId": "getCountries", "summary": "Get all countries", "description": "Retrieve a list of available countries with optional filtering by scope. The scope parameter controls which countries are returned: core (default) returns countries with full operational support, supported returns countries with document definitions, and all returns every country in the system.", "parameters": [ { "name": "operationalStatus", "required": false, "in": "query", "description": "Filter countries by operational status", "schema": { "enum": [ "ENABLED", "RESTRICTED", "BLOCKED" ], "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "Filter countries by scope: core (default) for countries with full support (AR, CL, CO, PE, MX, BR, US, BO), supported for countries with document definitions, all for every country in the system", "schema": { "enum": [ "core", "supported", "all", "onboarding" ], "type": "string" } } ], "responses": { "200": { "description": "Get countries based on the specified scope", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryResponseDto" } } } } }, "400": { "description": "Invalid request parameters" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/countries/{countrySymbol}/states": { "get": { "operationId": "getStates", "summary": "Get states by country", "description": "Retrieve all states/provinces for a specific country using the country symbol", "parameters": [ { "name": "countrySymbol", "required": true, "in": "path", "description": "Country symbol (ISO 3166-1 alpha-2 code, e.g., 'MX', 'US', 'CA')", "schema": { "example": "MX", "type": "string" } } ], "responses": { "200": { "description": "Get states by country", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StateResponseDto" } } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Country not found" }, "422": { "description": "Invalid country symbol format" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/countries/{countrySymbol}/states/{stateId}": { "get": { "operationId": "getStateById", "summary": "Get state by ID", "description": "Retrieve detailed information for a specific state within a country", "parameters": [ { "name": "countrySymbol", "required": true, "in": "path", "description": "Country symbol (ISO 3166-1 alpha-2 code, e.g., 'MX', 'US', 'CA')", "schema": { "example": "MX", "type": "string" } }, { "name": "stateId", "required": true, "in": "path", "description": "State identifier (e.g., '1', '25')", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "Get state by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Country or state not found" }, "422": { "description": "Invalid country symbol or state ID format" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/countries/{countrySymbol}/states/{stateId}/counties": { "get": { "operationId": "getCounties", "summary": "Get counties by state", "description": "Retrieve all counties/municipalities for a specific state within a country", "parameters": [ { "name": "countrySymbol", "required": true, "in": "path", "description": "Country symbol (ISO 3166-1 alpha-2 code, e.g., 'MX', 'US', 'CA')", "schema": { "example": "MX", "type": "string" } }, { "name": "stateId", "required": true, "in": "path", "description": "State identifier (e.g., '1', '25')", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "Get counties by state", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountyResponseDto" } } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Country or state not found" }, "422": { "description": "Invalid country symbol or state ID format" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/countries/{countrySymbol}/states/{stateId}/counties/{countyId}": { "get": { "operationId": "getCountyById", "summary": "Get county by ID", "description": "Retrieve detailed information for a specific county/municipality within a state and country", "parameters": [ { "name": "countrySymbol", "required": true, "in": "path", "description": "Country symbol (ISO 3166-1 alpha-2 code, e.g., 'MX', 'US', 'CA')", "schema": { "example": "MX", "type": "string" } }, { "name": "stateId", "required": true, "in": "path", "description": "State identifier (e.g., '1', '25')", "schema": { "example": "1", "type": "string" } }, { "name": "countyId", "required": true, "in": "path", "description": "County identifier (e.g., 'cnt_456', 'cnt_789')", "schema": { "example": "cnt_456", "type": "string" } } ], "responses": { "200": { "description": "Get county by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountyResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Country, state, or county not found" }, "422": { "description": "Invalid country symbol, state ID, or county ID format" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/banks": { "get": { "operationId": "getAvailableBanks", "summary": "Get available banks", "description": "\n Retrieve list of available banks. Returns sandbox data in non-production environments and production data in production environment.\n - When no countrySymbol is provided: returns all banks organized by country\n - When countrySymbol is provided: returns only banks for that specific country\n ", "parameters": [ { "name": "countrySymbol", "required": false, "in": "query", "description": "Filter banks by country symbol (ISO 3166-1 alpha-2 code)", "schema": { "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } } ], "responses": { "200": { "description": "Available banks", "content": { "application/json": { "schema": { "oneOf": [ { "description": "All banks organized by country (when no countrySymbol provided)", "$ref": "#/components/schemas/GenericCountryBanksDto" }, { "description": "Banks for specific country (when countrySymbol provided)", "type": "array", "items": { "$ref": "#/components/schemas/ValueDto" } } ] } } } }, "400": { "description": "Invalid request parameters (e.g., unsupported or malformed countrySymbol)" }, "404": { "description": "No banks available for the specified country" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/documents": { "get": { "operationId": "getAvailableDocuments", "summary": "Get available document types", "description": "Retrieve available document types and requirements per country for identity verification and compliance. The scope parameter controls which countries are included: core (default) returns documents for core countries only, supported returns documents for all countries with defined requirements, all returns documents for every country with dynamic fallback, and pre-onboarding returns documents from the CountryDocumentTypes table organized by entity type (PERSON/COMPANY). When countrySymbol is provided, returns documents for that specific country regardless of scope.", "parameters": [ { "name": "entityType", "required": false, "in": "query", "description": "Filter documents by entity type. Only applicable when scope is onboarding. If not provided, returns documents for all entity types.", "schema": { "enum": [ "PERSON", "COMPANY" ], "type": "string" } }, { "name": "countrySymbol", "required": false, "in": "query", "description": "Filter documents by country symbol(s) (ISO 3166-1 alpha-2 code). Accepts single value or multiple values (e.g., countrySymbol=CL&countrySymbol=AR). For onboarding scope, returns documents for specified countries. For other scopes with single country, returns documents for that country.", "schema": { "example": "CL", "type": "array", "items": {} } }, { "name": "scope", "required": false, "in": "query", "description": "Filter documents by scope: core (default) for core countries (AR, CL, CO, PE, MX, BR, US, BO), supported for all countries with document definitions, all for every country with dynamic fallback, pre-onboarding for documents from CountryDocumentTypes table", "schema": { "enum": [ "core", "supported", "all", "onboarding" ], "type": "string" } } ], "responses": { "200": { "description": "Get available documents per country based on scope. Returns GenericDocumentDto (country-keyed object) for core/supported/all scopes, or CountryDocumentTypesResponseDto for onboarding scope.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GenericDocumentDto" }, { "$ref": "#/components/schemas/CountryDocumentTypesResponseDto" } ] } } } }, "400": { "description": "Invalid request parameters" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/countries/{countrySymbol}/economic-activities": { "get": { "operationId": "getCountryEconomicActivities", "summary": "Get economic activities for a country", "description": "Retrieve all economic activities available for a specific country, including their status (ALLOWED/FORBIDDEN) and active state.", "parameters": [ { "name": "countrySymbol", "required": true, "in": "path", "description": "Two-letter ISO country code (e.g., CL, PE, CO)", "schema": { "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } }, { "name": "isActive", "required": false, "in": "query", "description": "Filter by active status", "schema": { "example": true, "type": "boolean" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by activity status (ALLOWED or FORBIDDEN). Can specify multiple values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "ALLOWED", "FORBIDDEN" ] } } } ], "responses": { "200": { "description": "Economic activities for the specified country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryEconomicActivitiesResponseDto" } } } }, "400": { "description": "Invalid country symbol or request parameters" }, "404": { "description": "Country not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/economic-activities": { "get": { "operationId": "getAllEconomicActivities", "summary": "Get all economic activities", "description": "Retrieve the master list of all economic activities available in the system.", "parameters": [], "responses": { "200": { "description": "List of all economic activities", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EconomicActivityResponseDto" } } } } }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/applicant-company-roles": { "get": { "operationId": "getApplicantCompanyRoles", "summary": "Get applicant company roles", "description": "Retrieve the list of available roles/positions that an applicant can have within a company. Used during the pre-onboarding process.", "parameters": [], "responses": { "200": { "description": "List of available applicant company roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicantCompanyRoleResponseDto" } } } } }, "500": { "description": "Internal server error" } }, "tags": [ "Countries" ] } }, "/api/v1/currencies": { "get": { "operationId": "getAllCurrencies", "summary": "Get all currencies", "description": "Retrieve a list of available currencies with optional filtering by scope, fiat type, and/or country. The scope parameter controls which currencies are returned: core (default) returns currencies with full operational support, supported returns all fiat currencies we support for operations, and all returns every currency in the system.", "parameters": [ { "name": "isFiat", "required": false, "in": "query", "description": "Filter currencies by type: true for fiat/traditional currencies, false for digital currencies", "schema": { "example": true, "type": "boolean" } }, { "name": "country", "required": false, "in": "query", "description": "Filter currencies available in a specific country (two letter ISO code, e.g., PE, CL, AR)", "schema": { "example": "PE", "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "Filter currencies by scope: core (default) for currencies with full balance support (USD, CLP, ARS, COP, MXN, PEN, BRL, BOB), supported for all fiat currencies we support for operations, all for every currency in the system", "schema": { "enum": [ "core", "supported", "all", "onboarding" ], "type": "string" } } ], "responses": { "200": { "description": "Gets currencies based on the specified scope and filters", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyResponseDto" } } } } }, "400": { "description": "Invalid request parameters" }, "500": { "description": "Internal server error" } }, "tags": [ "Currencies" ] } }, "/api/v1/currencies/{id}": { "get": { "operationId": "getCurrencyById", "summary": "Get currency by ID", "description": "Retrieve detailed information for a specific currency using its hash identifier", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Currency hash identifier (e.g., 'cur_abc123', 'cur_def456')", "schema": { "example": "cur_abc123", "type": "string" } } ], "responses": { "200": { "description": "Gets a currency by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Currency not found" }, "422": { "description": "Invalid currency ID format" }, "500": { "description": "Internal server error" } }, "tags": [ "Currencies" ] } }, "/api/v1/currencies/symbol/{symbol}": { "get": { "operationId": "getCurrencyBySymbol", "summary": "Get currency by symbol", "description": "Retrieve detailed information for a specific currency using its standard symbol code", "parameters": [ { "name": "symbol", "required": true, "in": "path", "description": "Currency symbol code (e.g., USD, EUR, CLP, BTC, ETH)", "schema": { "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ], "type": "string" } } ], "responses": { "200": { "description": "Gets a currency by symbol", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "404": { "description": "Currency not found" }, "422": { "description": "Invalid currency symbol format" }, "500": { "description": "Internal server error" } }, "tags": [ "Currencies" ] } }, "/api/v1/payment-method": { "get": { "operationId": "getPaymentMethods", "summary": "Get all payin payment methods", "description": "Retrieves available payment methods for payin operations. Results can be filtered by country and currency to get region-specific payment options. This is a public endpoint that does not require authentication.", "parameters": [ { "name": "countrySymbol", "required": false, "in": "query", "description": "Filter payment methods by country code (e.g., \"CO\" for Colombia, \"CL\" for Chile)", "schema": { "example": "CO", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } }, { "name": "currencySymbol", "required": false, "in": "query", "description": "Filter payment methods by currency code (e.g., \"COP\" for Colombian Peso, \"USD\" for US Dollar)", "schema": { "example": "COP", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ], "type": "string" } }, { "name": "paymentType", "required": false, "in": "query", "description": "Filter by payment type (e.g., PAYMENT_LINK, QR, PUSH_NOTIFICATION)", "schema": { "enum": [ "QR", "PAYMENT_LINK", "PUSH_NOTIFICATION", "BANK_TRANSFER" ], "type": "string" } } ], "responses": { "200": { "description": "Payin payment methods found successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinPaymentMethodsResponseCamelCaseDto" }, "examples": { "Default Response (No Filters)": { "summary": "Example response when no country or currency filters are applied", "value": { "currency": null, "country": null, "payment_methods": [ { "method": "PSE", "description": null, "min_amount": 0, "max_amount": 0, "response_type": "PAYMENT_LINK", "required_fields": { "urls": [ "redirect" ], "contact": [ "email", "last_name", "first_name", "document_number", "document_type", "phone_number", "phone_country", "business_type" ] } }, { "method": "NEQUI", "description": null, "min_amount": 0, "max_amount": 20000000, "response_type": "PUSH_NOTIFICATION", "required_fields": { "contact": [ "email", "phone_number", "phone_country" ] } }, { "method": "BANCOLOMBIA_QR", "description": null, "min_amount": 0, "max_amount": 20000000, "response_type": "QR", "required_fields": { "contact": [ "email" ] } }, { "method": "KHIPU", "description": null, "min_amount": 1, "max_amount": 1000000000, "response_type": "PAYMENT_LINK", "required_fields": { "urls": [ "webhook", "redirect", "cancel" ], "contact": [ "email", "last_name", "first_name" ] } }, { "method": "BITSO_TRANSFER", "description": null, "min_amount": 100, "max_amount": 200, "response_type": "BANK_TRANSFER", "required_fields": { "contact": [ "email" ] } }, { "method": "ETPAY", "description": null, "min_amount": 1, "max_amount": 1000000000, "response_type": "PAYMENT_LINK", "required_fields": { "urls": [ "webhook", "redirect", "cancel" ], "contact": [ "email", "last_name", "first_name" ] } }, { "method": "KHIPU", "description": null, "min_amount": 1, "max_amount": 1000000000, "response_type": "PAYMENT_LINK", "required_fields": { "urls": [ "redirect" ], "contact": [ "email", "last_name", "first_name", "document_number", "document_type", "phone_number", "phone_country", "business_type" ] } } ] } }, "Filtered by Country CO, Currency COP": { "summary": "Example response filtered by country CO and currency COP", "value": { "currency": "COP", "country": "CO", "payment_methods": [ { "method": "PSE", "description": null, "min_amount": 0, "max_amount": 0, "response_type": "PAYMENT_LINK", "required_fields": { "urls": [ "redirect" ], "contact": [ "email", "last_name", "first_name", "document_number", "document_type", "phone_number", "phone_country", "business_type" ] } }, { "method": "NEQUI", "description": null, "min_amount": 0, "max_amount": 20000000, "response_type": "PUSH_NOTIFICATION", "required_fields": { "contact": [ "email", "phone_number", "phone_country" ] } }, { "method": "BANCOLOMBIA_QR", "description": null, "min_amount": 0, "max_amount": 20000000, "response_type": "QR", "required_fields": { "contact": [ "email" ] } } ] } }, "Filtered by Country CO, Currency USD (Empty Methods)": { "summary": "Example response filtered by country CO and currency USD, resulting in no payment methods", "value": { "currency": "USD", "country": "CO", "payment_methods": [] } } } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Payment Method" ], "security": [ {} ] } }, "/api/v1/payment-method/card/merchants/{merchantId}/verify": { "get": { "operationId": "verifyCardPaymentCredentials", "summary": "Verify card payment credentials", "description": "Verifies that the merchant has valid (card payment) credentials configured in the PSP system. Returns 200 OK with hasCredentials boolean indicating if credentials exist and are configured. Requires MERCHANT_PAYMENT_METHODS_VIEW permission.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_5e76b163-ddf3-427a-a968-c40796e30d5d", "type": "string" } } ], "responses": { "200": { "description": "Credentials verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PspVerifyCredentialsResponseDto" } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to verify card payment credentials" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Payment Method" ], "security": [ {}, { "bearer": [] } ] } }, "/api/v1/auth/sign-in": { "post": { "operationId": "createToken", "summary": "Sign in with API key", "description": "Authenticates a user using their API key credentials", "parameters": [], "requestBody": { "required": true, "description": "API key credentials for authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenDto" } } } }, "responses": { "200": { "description": "Authentication successful, returns JWT token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponseDto" } } } }, "401": { "description": "Invalid API key credentials", "content": { "application/json": { "schema": { "example": { "message": "Invalid credentials", "error": "Unauthorized", "statusCode": 401 } } } } }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "apiKey should not be empty", "secret should not be empty" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ] } }, "/api/v1/auth/me": { "get": { "operationId": "getUserInfo", "summary": "Get current user information", "description": "Returns the information of the currently authenticated user", "parameters": [], "responses": { "200": { "description": "User information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInfoResponseDto" } } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/credentials": { "post": { "operationId": "createOrganizationApiCredentials", "summary": "Create organization API credentials", "description": "Creates new API credentials for an organization with the following validations:\n \n1. **Organization Validation**:\n - Organization must exist\n - User must have access to the organization\n\n2. **Role Assignment** (required):\n - At least one role must be provided\n - Roles will be assigned to the API credentials for the organization\n - Roles must be valid organization roles (not merchant roles)\n - Invalid or missing roles will result in a 400 error\n\n3. **Permission Requirements**:\n - User must have MERCHANT_DEV_SETTINGS_CREATE_API_KEY permission\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "API credentials information to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialsDto" } } } }, "responses": { "201": { "description": "Organization API credentials created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentialsResponseDto" } } } }, "400": { "description": "Invalid organization ID or roles", "content": { "application/json": { "schema": { "example": { "message": "Roles are required for API credentials", "error": "Bad Request", "statusCode": 400 } } } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } }, "403": { "description": "User does not have required permissions", "content": { "application/json": { "schema": { "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "example": { "message": "Organization not found with id: :organizationId", "error": "Not Found", "statusCode": 404 } } } } }, "409": { "description": "API credentials with that name already exist", "content": { "application/json": { "schema": { "example": { "message": "API credentials with that name already exist", "error": "Conflict", "statusCode": 409 } } } } }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "name should not be empty" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/credentials": { "post": { "operationId": "createApiCredentials", "summary": "Create API credentials", "description": "Creates new API credentials for a merchant with the following validations:\n \n1. **Organization Validation**:\n - Organization must exist\n - User must have access to the organization\n\n2. **Merchant Validation**:\n - Merchant must exist\n - Merchant must belong to the specified organization\n - User must have the required permissions for the merchant\n\n3. **Role Assignment** (required):\n - At least one role must be provided\n - Roles will be assigned to the API credentials for the merchant\n - Roles must be valid merchant roles (not organization roles)\n - Invalid or missing roles will result in a 400 error\n\n4. **Permission Requirements**:\n - User must have MERCHANT_DEV_SETTINGS_CREATE_API_KEY permission\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "API credentials information to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCredentialsDto" } } } }, "responses": { "201": { "description": "API credentials created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCredentialsResponseDto" } } } }, "400": { "description": "Invalid organization or merchant ID", "content": { "application/json": { "schema": { "oneOf": [ { "example": { "message": "Organization not found with id: :organizationId", "error": "Bad Request", "statusCode": 400 } }, { "example": { "message": "Merchant not found with id: :merchantId", "error": "Bad Request", "statusCode": 400 } } ] } } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } }, "403": { "description": "User does not have required permissions", "content": { "application/json": { "schema": { "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } } }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "name should not be empty" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/mfa/prepare": { "post": { "operationId": "prepareApiUserMfaEnrollment", "summary": "Prepare delegated MFA enrollment for an API user", "description": "Builds the exact request body that the root passkey holder must sign in order to create or rotate the delegated MFA key for an API user.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollPrepareResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/mfa/enroll/prepare": { "post": { "operationId": "prepareApiUserMfaApproval", "summary": "Prepare delegated MFA approval request for root signing", "description": "Loads the exact stored enrollment payload from a delegated MFA pending approval so the root user can sign it without any handoff from the API user.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaApprovalPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollPrepareResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/mfa/enroll/approve": { "post": { "operationId": "approveApiUserMfaEnrollment", "summary": "Approve delegated MFA enrollment for an API user", "description": "Forwards the stamped enrollment request and persists the delegated MFA credential for the target API user.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollApproveRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollApproveResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/{apiKey}/mfa": { "get": { "operationId": "listApiUserMfaCredentials", "summary": "List delegated MFA credentials for an API user", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "apiKey", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiUserMfaCredentialResponseDto" } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/wallet-access/request": { "post": { "operationId": "requestWalletAccess", "summary": "Request embedded wallet signing access for the authenticated user", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSigningAccessResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/wallet-access/prepare": { "post": { "operationId": "prepareWalletAccessApproval", "summary": "Prepare wallet signing access approval request for root signing", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSigningAccessPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSigningAccessPrepareResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/wallet-access/approve": { "post": { "operationId": "approveWalletAccess", "summary": "Approve wallet signing access for root signing", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSigningAccessApproveRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletSigningAccessApproveResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/{apiKey}/mfa/revoke": { "post": { "operationId": "revokeApiUserMfaCredential", "summary": "Revoke a delegated MFA credential for an API user", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "apiKey", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaEnrollPrepareResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/api-users/mfa/revoke/approve": { "post": { "operationId": "approveApiUserMfaRevocation", "summary": "Approve delegated MFA credential revocation", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaRevokeApproveRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiUserMfaRevokeResponseDto" } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/pos/credentials/create": { "post": { "operationId": "createPosCredentials", "summary": "Create POS credentials", "description": "Creates new POS credentials for a merchant with the following validations:\n \n1. **Organization Validation**:\n - Organization must exist\n - User must have access to the organization\n\n2. **Merchant Validation**:\n - Merchant must exist\n - Merchant must belong to the specified organization\n - User must have the required permissions for the merchant\n\n3. **POS Credentials Creation**:\n - Alias and password are required\n - Email is automatically generated: {alias}-{merchant-slug}.pos@koywe.com\n - Merchant name is slugified (spaces and invalid chars replaced with hyphens)\n4. **Permission Requirements**:\n - User must have MERCHANT_DEV_SETTINGS_CREATE_API_KEY permission\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "POS credentials information to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePosCredentialsDto" } } } }, "responses": { "201": { "description": "POS credentials created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "example": "mypos-merchant-name@koywe.com" } } } } } }, "400": { "description": "Invalid organization or merchant ID", "content": { "application/json": { "schema": { "oneOf": [ { "example": { "message": "Organization not found with id: :organizationId", "error": "Bad Request", "statusCode": 400 } }, { "example": { "message": "Merchant not found with id: :merchantId", "error": "Bad Request", "statusCode": 400 } } ] } } } }, "401": { "description": "User is not authenticated", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } }, "403": { "description": "User does not have required permissions", "content": { "application/json": { "schema": { "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } } }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "alias should not be empty", "password should not be empty" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/invitation/redeem": { "post": { "operationId": "redeemInvitation", "summary": "Redeem an invitation token to join a merchant", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationDto" } } } }, "responses": { "200": { "description": "Invitation redeemed successfully. Roles assigned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationRedeemedDto" } } } }, "400": { "description": "Invalid token or invitation status not pending." }, "401": { "description": "User not authenticated." }, "404": { "description": "Invitation token not found." }, "409": { "description": "Invitation token has already been used." }, "410": { "description": "Invitation token has expired." }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "token must be exactly 64 characters long" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred while redeeming the invitation.", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/invitation/check-status": { "post": { "operationId": "checkInvitationStatus", "summary": "Check invitation status and user existence", "description": "Check if an invitation token is valid and whether it's for an existing user or new user. This helps determine whether to show login or register flow in the frontend.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckInvitationStatusDto" } } } }, "responses": { "200": { "description": "Invitation status checked successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationStatusResponseDto" } } } }, "400": { "description": "Invalid token or invitation status not pending." }, "404": { "description": "Invitation token not found." }, "409": { "description": "Invitation token has already been used." }, "410": { "description": "Invitation token has expired." }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "token must be exactly 64 characters long" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred while checking invitation status.", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ] } }, "/api/v1/auth/credentials/rotate-secret": { "post": { "operationId": "rotateApiSecret", "summary": "Rotate API secret", "description": "Generates a new secret for the authenticated API user. Only API users (not regular email users) can use this endpoint.", "parameters": [], "responses": { "200": { "description": "Secret rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiSecretResponseDto" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } }, "403": { "description": "Only API users can rotate their secret", "content": { "application/json": { "schema": { "example": { "message": "Only API users can rotate their secret", "errorCode": "AUTH00011", "statusCode": 403 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ], "security": [ { "bearer": [] } ] } }, "/api/v1/auth/organization-invitation/redeem": { "post": { "operationId": "redeemOrganizationInvitation", "summary": "Redeem an organization invitation token to join an organization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemInvitationDto" } } } }, "responses": { "200": { "description": "Organization invitation redeemed successfully. Roles assigned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully joined organization My Organization" }, "organization": { "type": "object", "properties": { "id": { "type": "string", "example": "org3_xxxxxxxxxxxxxx" }, "name": { "type": "string", "example": "My Organization" } } }, "grantedRoles": { "type": "array", "items": { "type": "string" }, "example": [ "k3r_user_org_inviter", "k3r_user_org_viewer", "k3r_user_org_manager" ] } } } } } }, "400": { "description": "Invalid token or invitation status not pending." }, "401": { "description": "User not authenticated." }, "404": { "description": "Organization invitation token not found." }, "409": { "description": "Organization invitation token has already been used." }, "410": { "description": "Organization invitation token has expired." }, "422": { "description": "Validation error in request payload", "content": { "application/json": { "schema": { "example": { "message": [ "token must be exactly 64 characters long" ], "error": "Unprocessable Entity", "statusCode": 422 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "An unexpected error occurred while redeeming the organization invitation.", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "tags": [ "Auth" ] } }, "/api/v1/auth/forgot-password": { "post": { "operationId": "forgotPassword", "summary": "Request password reset email", "description": "Sends a password reset email if the address is registered. Always returns 200 to prevent user enumeration.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordDto" } } } }, "responses": { "200": { "description": "Password reset request processed successfully", "content": { "application/json": { "schema": { "example": { "statusCode": 200, "message": "If the email is registered, you will receive an email with instructions.", "timestamp": "2026-02-25T20:00:00.000Z" } } } } }, "400": { "description": "Invalid email format", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "timestamp": "2026-02-25T20:00:00.000Z", "path": "/api/v1/auth/forgot-password", "message": [ "email must be an email" ], "error": "Bad Request" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "example": { "statusCode": 429, "timestamp": "2026-02-25T20:00:00.000Z", "path": "/api/v1/auth/forgot-password", "message": "Too many requests. Please try again later." } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "statusCode": 500, "timestamp": "2026-02-25T20:00:00.000Z", "path": "/api/v1/auth/forgot-password", "message": "An unexpected error occurred", "error": "Internal Server Error" } } } } } }, "tags": [ "Auth" ] } }, "/api/v1/auth/send-verification-email": { "post": { "operationId": "sendVerificationEmail", "summary": "Request email verification", "description": "Sends a verification email if the address is registered. Always returns 200 to prevent user enumeration.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendVerificationEmailRequestDto" } } } }, "responses": { "200": { "description": "Verification email request processed successfully", "content": { "application/json": { "schema": { "example": { "statusCode": 200, "message": "If the email is registered, you will receive a verification email.", "timestamp": "2026-02-27T12:00:00.000Z" } } } } }, "400": { "description": "Invalid email format", "content": { "application/json": { "schema": { "example": { "statusCode": 400, "timestamp": "2026-02-27T12:00:00.000Z", "path": "/api/v1/auth/send-verification-email", "message": [ "email must be an email" ], "error": "Bad Request" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "statusCode": 500, "timestamp": "2026-02-27T12:00:00.000Z", "path": "/api/v1/auth/send-verification-email", "message": "An unexpected error occurred", "error": "Internal Server Error" } } } } } }, "tags": [ "Auth" ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/bankIncome/accounts": { "get": { "operationId": "getDepositAccountInfo", "summary": "Get deposit account information", "description": "Retrieves the bank account information where the merchant should make wire transfers to deposit funds. For Argentina, Mexico and USA, returns virtual account details (accountNumber, routingNumber, bankName for US). For Chile and Peru, returns fixed bank account details.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_def456", "type": "string" } } ], "responses": { "200": { "description": "Deposit account information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAccountInfoResponseDto" }, "examples": { "argentina": { "summary": "Argentina — CVU (BIND/ARS)", "value": { "accountType": "VIRTUAL", "country": "AR", "countryName": "Argentina", "currency": "ARS", "currencyName": "Peso Argentino", "accountDetails": { "id": "pivba_ar_001", "accountNumber": "0000001700000000000024", "alias": "MITO.FILA.OJOTA", "provider": "BIND", "isActive": true, "merchantId": "mrc_def456", "merchantName": "Acme Corp", "routingNumber": null, "bankName": null } } }, "mexico": { "summary": "Mexico — CLABE (BITSO_MX/MXN)", "value": { "accountType": "VIRTUAL", "country": "MX", "countryName": "México", "currency": "MXN", "currencyName": "Peso Mexicano", "accountDetails": { "id": "pivba_mx_001", "accountNumber": "646180110400000007", "alias": null, "provider": "BITSO_MX", "isActive": true, "merchantId": "mrc_def456", "merchantName": "Acme Corp", "routingNumber": null, "bankName": null } } }, "usa": { "summary": "USA — Bank Account (MURAL/USD)", "value": { "accountType": "VIRTUAL", "country": "US", "countryName": "United States", "currency": "USD", "currencyName": "US Dollar", "accountDetails": { "id": "pivba_us_001", "accountNumber": "123456789", "alias": null, "provider": "MURAL", "isActive": true, "merchantId": "mrc_def456", "merchantName": "Acme Corp", "routingNumber": "021000021", "bankName": "JPMorgan Chase" } } }, "chile": { "summary": "Chile — Cuenta Corriente (ITAU_CL/CLP)", "value": { "accountType": "FIXED", "country": "CL", "countryName": "Chile", "currency": "CLP", "currencyName": "Peso Chileno", "accountDetails": { "bankName": "Banco Itaú", "bankCode": "ITAU_CL", "accountHolderName": "Koywe S.A.", "accountNumber": "0123456789", "accountType": "CORRIENTE", "routingNumber": null, "swift": null, "documentNumber": "76.123.456-7", "documentType": "RUT" } } }, "peru": { "summary": "Peru — Cuenta (LIGO_PE/PEN)", "value": { "accountType": "FIXED", "country": "PE", "countryName": "Perú", "currency": "PEN", "currencyName": "Sol Peruano", "accountDetails": { "bankName": "Ligo", "bankCode": "LIGO_PE", "accountHolderName": "Koywe Perú S.A.C.", "accountNumber": "9876543210", "accountType": null, "routingNumber": null, "swift": null, "documentNumber": null, "documentType": null } } } } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to access deposit accounts" }, "404": { "description": "Organization, merchant, or account not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Bank Income" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts": { "post": { "operationId": "createContact", "summary": "Create a new Contact", "description": "Creates a new contact with the following validations:\n \n1. **Contact Information**:\n - Email and phone are optional fields\n - If email is provided, it must be valid\n - If phone is provided, it must be valid according to country format\n\n2. **Document Validation**:\n - If documentType is provided, documentNumber must also be provided\n - Document number must be valid according to country format\n - Document type must match business type (e.g. DNI for PERSON, CUIT for COMPANY)\n\n3. **Tax Information**:\n - If taxIdType is provided, taxIdNumber must also be provided\n - Tax ID number must be valid according to country format\n\n4. **Business Type**:\n - Must be one of: PERSON, COMPANY, GOVERNMENT, NON_PROFIT, PROVIDER, OTHER\n - Must match the provided document type\n\n5. **Country Symbol**:\n - Must be one of:\n - AR (Argentina)\n - CL (Chile)\n - BR (Brazil)\n - CO (Colombia)\n - MX (Mexico)\n - PE (Peru)\n - US (United States)\n - Determines the valid formats for phone, document, and tax numbers\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Contact information to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreationDto" } } } }, "responses": { "201": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "422": { "description": "Validation error in request payload" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "getAll", "summary": "Get all contacts", "description": "Returns a paginated list of contacts with optional filtering by search text and creation date", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org_12345", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mer_67890", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of responses per page", "schema": { "enum": [ 10, 20, 50, 100 ], "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Ascending or descending order (by creation date)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter by creation date", "schema": { "format": "date-time", "example": "2024-05-27T14:44:56.953Z", "type": "string" } }, { "name": "searchText", "required": false, "in": "query", "description": "Search text for firstName, lastName, or externalId", "schema": { "example": "Emergency Medical Kits", "type": "string" } }, { "name": "countrySymbol", "required": false, "in": "query", "description": "Filter by country code (e.g., US, AR)", "schema": { "example": "CL", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } }, { "name": "countrySymbolNot", "required": false, "in": "query", "description": "Filter by country code (not equals) (e.g., US, AR, CL)", "schema": { "example": "AR", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } } ], "responses": { "200": { "description": "Paginated list of contacts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedContactsResponseDto" } } } }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "422": { "description": "Validation error in query parameters" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}": { "get": { "operationId": "getContact", "summary": "Return contact by id", "description": "Returns the complete contact information for the specified contact ID", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org_12345", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mer_67890", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "example": "con_abc123", "type": "string" } } ], "responses": { "200": { "description": "Contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "404": { "description": "Contact not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "updateContact", "summary": "Update contact by id", "description": "Updates an existing contact with the same validations as creation:\n \n1. **Contact Information**:\n - Email and phone are optional fields\n - If email is provided, it must be valid\n - If phone is provided, it must be valid according to country format\n\n2. **Document Validation**:\n - If documentType is provided, documentNumber must also be provided\n - Document number must be valid according to country format\n - Document type must match business type (e.g. DNI for PERSON, RUT for COMPANY)\n\n3. **Tax Information**:\n - If taxIdType is provided, taxIdNumber must also be provided\n - Tax ID number must be valid according to country format\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org_12345", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mer_67890", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "ID of the contact to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Contact information to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateDto" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "404": { "description": "Contact not found" }, "422": { "description": "Validation error in request payload" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deleteContact", "summary": "Delete contact by id", "description": "Deletes a contact if it meets the following conditions:\n \n1. **Validation**:\n - Contact must exist\n - Contact must not have any active orders\n - Contact must not be linked to any active transactions\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org_12345", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mer_67890", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "ID of the contact to delete", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Contact deleted successfully" }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "404": { "description": "Contact not found" }, "409": { "description": "Cannot delete contact with active orders" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}/documents": { "delete": { "operationId": "deleteContactDocuments", "summary": "Delete contact documents", "description": "Deletes specified contact documents with the following validations:\n \n1. **Document Validation**:\n - All specified documents must exist and belong to the contact\n - Contact must have at least one document remaining after deletion\n - Cannot delete all documents from a contact\n\n2. **Default Document Handling**:\n - If the default document is deleted, the first remaining document will be set as default\n - Documents are ordered by creation date for default selection\n\n3. **Permissions**:\n - User must have MERCHANT_CONTACTS_EDIT_CONTACT permission\n ", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org_12345", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mer_67890", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "ID of the contact whose documents will be deleted", "schema": { "example": "con_a627a569-51c4-4fc4-ace6-a43482f1b08b", "type": "string" } } ], "requestBody": { "required": true, "description": "Array of document IDs to delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDocumentDeleteDto" } } } }, "responses": { "204": { "description": "Documents deleted successfully" }, "400": { "description": "Invalid request data or cannot delete all documents" }, "401": { "description": "User is not authenticated" }, "403": { "description": "User does not have required permissions" }, "404": { "description": "Contact or documents not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}/accounts": { "get": { "operationId": "getBankAccountsByContact", "summary": "Get bank accounts by contact", "description": "Retrieves all bank accounts associated with a specific contact, with optional filtering by currency symbol.", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Filter bank accounts by currency symbol (e.g. USD, ARS, CLP)", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get bankAccounts by Contact", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } } }, "400": { "description": "Invalid currency symbol provided" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to view contact bank accounts" }, "404": { "description": "Contact or merchant not found" }, "422": { "description": "Invalid request parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "createAccount", "summary": "Create a new contact bank account", "description": "Creates a new bank account for the specified contact. Supports both fiat and crypto accounts with appropriate validation.", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCreateDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid account data or validation errors" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to create contact bank accounts" }, "404": { "description": "Contact or merchant not found" }, "422": { "description": "Invalid account creation data or business rule violations" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}/accounts/{accountId}": { "get": { "operationId": "getBankAccountById", "summary": "Get contact bank account by ID", "description": "Retrieves a specific bank account by its ID for a contact. The account must belong to the specified contact.", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "Bank Account ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get contact bankAccount by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid account ID format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account does not belong to contact" }, "404": { "description": "Account, contact, or merchant not found" }, "422": { "description": "Invalid request parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deleteBankAccount", "summary": "Delete contact bank account", "description": "Soft deletes a contact bank account by ID. The account must belong to the specified contact.", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "Bank Account ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Contact bank account deleted successfully" }, "400": { "description": "Invalid account ID format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account does not belong to contact" }, "404": { "description": "Account, contact, or merchant not found" }, "422": { "description": "Invalid deletion parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}/accounts/confirm-mfa": { "post": { "operationId": "confirmContactAccountCreationMfa", "summary": "Confirm MFA for pending contact account creation", "description": "Confirms MFA for a contact bank account creation that requires policy approval.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmBankAccountMfaRequestDto" } } } }, "responses": { "200": { "description": "MFA confirmed. Account created if all conditions met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/contacts/{contactId}/accounts/{id}": { "put": { "operationId": "updateAccount", "summary": "Update contact bank account", "description": "Updates an existing contact bank account with new information. The account must belong to the specified contact.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Bank Account ID to update", "schema": { "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "Contact ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountUpdateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid update data or validation errors" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account belongs to another contact" }, "404": { "description": "Account, contact, or merchant not found" }, "422": { "description": "Invalid update data or business rule violations" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Contact" ], "security": [ { "bearer": [] } ] } }, "/api/v1/cli-auth": { "get": { "operationId": "redirectCliAuth", "summary": "CLI browser auth redirect", "description": "Validates loopback callback + state and redirects browser to frontend /cli-auth page.", "parameters": [ { "name": "callback", "required": true, "in": "query", "description": "URL-encoded loopback callback (must be http://127.0.0.1:/...)", "schema": { "type": "string" } }, { "name": "state", "required": true, "in": "query", "description": "Opaque CSRF nonce generated by CLI", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirects to frontend /cli-auth with callback and state" }, "400": { "description": "Invalid callback or state parameter" } }, "tags": [ "CLI Auth" ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/{orderId}/notification": { "post": { "operationId": "sendOrderNotification", "summary": "Send order notification", "description": "Send an order notification to the specified recipients", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org3_e2fc0500-9ffb-4a45-bdd3-d11db7d0752c", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_1ba7638e-6b0d-462f-9810-726b53975ae5", "type": "string" } }, { "name": "orderId", "required": true, "in": "path", "description": "Order identifier", "schema": { "example": "ord_1ba7638e-6b0d-462f-9810-726b53975ae5", "type": "string" } }, { "name": "type", "required": true, "in": "query", "description": "Notification type", "schema": { "example": "email", "type": "string" } } ], "responses": { "200": { "description": "Order notification sent successfully" }, "400": { "description": "Invalid request parameters or payload" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to send notifications" }, "404": { "description": "Organization, merchant or order not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/api/v1/global-feature-flags": { "get": { "operationId": "getAll", "summary": "Get all global feature flags (Public)", "description": "Retrieves all global feature flags. No authentication required.", "parameters": [], "responses": { "200": { "description": "Global feature flags retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlobalFeatureFlagsListResponseDto" } } } } }, "tags": [ "Global Feature Flags" ] } }, "/api/v1/organizations/{organizationId}/merchants": { "post": { "operationId": "create", "summary": "Create a new merchant", "description": "Create a new merchant within an organization. Requires ORGANIZATION_SETTINGS_ADD_MERCHANT permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantDto" } } } }, "responses": { "201": { "description": "Merchant created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to create merchant" }, "404": { "description": "Organization not found" }, "422": { "description": "Invalid merchant data provided" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "getOrganizationMerchants", "summary": "Get organization merchants", "description": "Get merchants belonging to an organization that the user has access to", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } } ], "responses": { "200": { "description": "Organization merchants retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserMerchantDto" } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view merchants" }, "404": { "description": "Organization not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}": { "delete": { "operationId": "delete", "summary": "Delete a merchant", "description": "Delete an existing merchant from an organization. Requires ORGANIZATION_SETTINGS_REMOVE_MERCHANT permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mer_def456", "type": "string" } } ], "responses": { "204": { "description": "Merchant deleted successfully" }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to delete merchant" }, "404": { "description": "Organization or merchant not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "get", "summary": "Get merchant by ID", "description": "Retrieve detailed information for a specific merchant within an organization. Requires ORGANIZATION_SETTINGS_VIEW_MERCHANT or MERCHANT_SETTINGS_VIEW_USER permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mer_def456", "type": "string" } } ], "responses": { "200": { "description": "Merchant information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view merchant" }, "404": { "description": "Organization or merchant not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "update", "summary": "Update merchant", "description": "Update an existing merchant within an organization. Requires ORGANIZATION_SETTINGS_ADD_MERCHANT permission.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mer_def456", "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } } ], "requestBody": { "required": true, "description": "Updated merchant information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantDto" } } } }, "responses": { "200": { "description": "Merchant updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to update merchant" }, "404": { "description": "Organization or merchant not found" }, "422": { "description": "Invalid merchant update data provided" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/users": { "get": { "operationId": "getMerchantUsers", "summary": "Get merchant users", "description": "Retrieve a paginated list of users for a specific merchant. Requires ORGANIZATION_SETTINGS_VIEW_MERCHANT permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_def456", "type": "string" } }, { "name": "page", "required": true, "in": "query", "description": "Page number", "schema": { "minimum": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": true, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "name", "required": false, "in": "query", "description": "Filter by user name (partial match, case-insensitive).", "schema": { "example": "John", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by user email (partial match, case-insensitive).", "schema": { "example": "john@doe.com", "type": "string" } } ], "responses": { "200": { "description": "List of merchant users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMerchantUsersResponseDto" } } } }, "400": { "description": "Invalid request parameters (invalid page, limit, name, or email filters)" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view merchant users" }, "404": { "description": "Organization or merchant not found" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "updateUserRoles", "summary": "Update user roles in merchant", "description": "Update the roles assigned to a user in a specific merchant. Requires MERCHANT_SETTINGS_ASSIGN_ROLE_TO_USER permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_def456", "type": "string" } } ], "requestBody": { "required": true, "description": "User and roles information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRolesRequestDto" } } } }, "responses": { "200": { "description": "User roles updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRolesResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to update user roles" }, "404": { "description": "Organization, merchant or user not found" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/features": { "get": { "operationId": "getMerchantFeatures", "summary": "Get merchant features", "description": "Retrieve features configuration for a specific merchant within an organization. Requires ORGANIZATION_SETTINGS_VIEW_MERCHANT permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_def456", "type": "string" } } ], "responses": { "200": { "description": "Merchant features retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantFeaturesResponseDto" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view merchant features" }, "404": { "description": "Organization or merchant not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts": { "get": { "operationId": "getBankAccountsByMerchant", "summary": "Get bank accounts by merchant", "description": "Retrieves all bank accounts associated with a specific merchant, with optional filtering by currency symbol.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Filter bank accounts by currency symbol (e.g. USD, ARS, CLP)", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get bankAccounts by Merchant", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } } }, "400": { "description": "Invalid currency symbol provided" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to view bank accounts" }, "404": { "description": "Merchant not found" }, "422": { "description": "Invalid request parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "createAccount", "summary": "Create a new bank account", "description": "Creates a new bank account for the specified merchant. Supports both fiat and crypto accounts with appropriate validation.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCreateDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid account data or validation errors" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to create bank accounts" }, "404": { "description": "Merchant not found" }, "422": { "description": "Invalid account creation data or business rule violations" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/balances": { "get": { "operationId": "getBankAccountBalances", "summary": "Get balances for all merchant accounts", "description": "Retrieves account balances for all bank accounts associated with a merchant, with optional filtering by currency and date.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "currency", "required": false, "in": "query", "description": "Filter balances by currency symbol (e.g. USD, ARS, CLP)", "schema": { "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ], "type": "string" } }, { "name": "date", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2024-05-27T14:44:56.953Z" }, "description": "Date to get balances for. If not provided, returns the latest balances" }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get balances for all merchant accounts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceResponseDto" } } } } }, "400": { "description": "Invalid currency symbol or date format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to view account balances" }, "404": { "description": "Merchant not found" }, "422": { "description": "Invalid query parameters" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Unable to retrieve account balances at this time. Please try again later." } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}/balance": { "get": { "operationId": "getBankAccountBalanceByAccountId", "summary": "Get balance for a specific merchant account", "description": "Retrieves the account balance for a specific bank account by ID, with optional date filtering.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "The ID of the bank account to fetch balances for.", "schema": { "type": "string" } }, { "name": "date", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time", "example": "2024-05-27T14:44:56.953Z" }, "description": "Date to get balance for. If not provided, returns the latest balance." }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get balance for a specific merchant account by ID", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalanceResponseDto" } } } } }, "400": { "description": "Invalid date format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account belongs to contact" }, "404": { "description": "Account or merchant not found" }, "422": { "description": "Invalid account ID format" }, "500": { "description": "Internal Server Error" }, "503": { "description": "Unable to retrieve account balances at this time. Please try again later." } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/search": { "get": { "operationId": "findBankAccountsByCriteria", "summary": "Find bank accounts by criteria", "description": "Searches for bank accounts based on specified criteria such as account type, currency, or other filters.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Filter by bank account name", "schema": { "type": "string" } }, { "name": "entity", "required": false, "in": "query", "description": "Filter by bank entity name", "schema": { "type": "string" } }, { "name": "kind", "required": false, "in": "query", "description": "Filter by bank account kind (e.g., BANK, CRYPTO)", "schema": { "enum": [ "BANK", "CRYPTO" ], "type": "string" } }, { "name": "isVirtual", "required": false, "in": "query", "description": "Filter by whether the account is virtual (true/false)", "schema": { "type": "string" } }, { "name": "address", "required": false, "in": "query", "description": "Filter by crypto address (if applicable)", "schema": { "type": "string" } }, { "name": "network", "required": false, "in": "query", "description": "Filter by crypto network (if applicable)", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by bank account type", "schema": { "enum": [ "SAVINGS", "CHECKING", "CREDIT" ], "type": "string" } }, { "name": "accountNumber", "required": false, "in": "query", "description": "Filter by account number", "schema": { "type": "string" } }, { "name": "routingNumber", "required": false, "in": "query", "description": "Filter by routing number", "schema": { "type": "string" } }, { "name": "countryId", "required": false, "in": "query", "description": "Filter by country ID (UUID)", "schema": { "type": "string" } }, { "name": "currencyId", "required": false, "in": "query", "description": "Filter by currency ID (UUID)", "schema": { "type": "string" } }, { "name": "contactId", "required": false, "in": "query", "description": "Filter by associated contact ID (UUID)", "schema": { "type": "string" } }, { "name": "countrySymbol", "required": false, "in": "query", "description": "Filter by country code (e.g., US, AR)", "schema": { "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string" } }, { "name": "currencySymbol", "required": false, "in": "query", "description": "Filter by currency code (e.g., USD, ARS)", "schema": { "type": "string" } }, { "name": "isDefault", "required": false, "in": "query", "description": "Filter by whether the account is the default account (true/false)", "schema": { "type": "string" } }, { "name": "isTracked", "required": false, "in": "query", "description": "Filter by whether the account balance is tracked (true/false)", "schema": { "type": "string" } }, { "name": "isDeleted", "required": false, "in": "query", "description": "Filter by deletion status (true/false). If omitted, defaults to active accounts", "schema": { "type": "string" } }, { "name": "isFiat", "required": false, "in": "query", "description": "Filter by account type: true for fiat accounts (BANK), false for crypto accounts (CRYPTO)", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Find bank accounts by criteria for a merchant", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } } }, "400": { "description": "Invalid search criteria" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to search bank accounts" }, "404": { "description": "Merchant not found" }, "422": { "description": "Invalid search parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}": { "get": { "operationId": "getBankAccountById", "summary": "Get bank account by ID", "description": "Retrieves a specific bank account by its ID. The account must belong to the specified merchant.", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "Bank Account ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get bankAccount by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid account ID format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account belongs to contact" }, "404": { "description": "Account or merchant not found" }, "422": { "description": "Invalid request parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deleteBankAccount", "summary": "Delete bank account", "description": "Soft deletes a bank account by ID. The account must belong to the specified merchant and cannot be a contact account.", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "Bank Account ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Bank account deleted successfully" }, "400": { "description": "Invalid account ID format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account belongs to contact" }, "404": { "description": "Account or merchant not found" }, "422": { "description": "Invalid deletion parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/confirm-mfa": { "post": { "operationId": "confirmAccountCreationMfa", "summary": "Confirm MFA for pending account creation", "description": "Confirms MFA for a bank account creation that requires policy approval.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmBankAccountMfaRequestDto" } } } }, "responses": { "200": { "description": "MFA confirmed. Account created if all conditions met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{id}": { "put": { "operationId": "updateAccount", "summary": "Update bank account", "description": "Updates an existing bank account with new information. The account must belong to the specified merchant.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Bank Account ID to update", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountUpdateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountResponseDto" } } } }, "400": { "description": "Invalid update data or validation errors" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account belongs to another merchant" }, "404": { "description": "Account or merchant not found" }, "422": { "description": "Invalid update data or business rule violations" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/deals": { "get": { "operationId": "getScheduledDeals", "summary": "Get list of deals", "description": "Retrieves a paginated list of deals (scheduled ONRAMP/OFFRAMP operations) for the specified merchant. Each deal includes its associated orders.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of responses per page", "schema": { "default": 10, "example": 10, "enum": [ 10, 20, 50, 100 ], "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Ascending or descending order (by creation date)", "schema": { "default": "desc", "example": "desc", "enum": [ "asc", "desc" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date to filter deals (optional)", "schema": { "format": "date-time", "example": "2024-01-01T00:00:00.000Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date to filter deals (optional)", "schema": { "format": "date-time", "example": "2024-12-31T23:59:59.999Z", "type": "string" } } ], "responses": { "200": { "description": "Deals retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledDealsResponseDto" } } } } }, "tags": [ "Deals" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "createDeal", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KoyweDealInputDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "Deals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/deals/{dealId}": { "get": { "operationId": "getDealById", "summary": "Get deal by ID", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "dealId", "required": true, "in": "path", "description": "Deal ID (K3 internal ID)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealResponseDto" } } } }, "404": { "description": "Deal not found" } }, "tags": [ "Deals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/deals/{dealId}/confirm": { "post": { "operationId": "confirmDeal", "summary": "Confirm MFA for pending deal", "description": "Confirms requester MFA for an ON_HOLD deal that requires policy approval.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "dealId", "required": true, "in": "path", "description": "Deal ID (K3 internal ID)", "schema": { "type": "string" } }, { "name": "pendingApprovalId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deal confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealResponseDto" } } } } }, "tags": [ "Deals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/deals/{dealId}/transfer": { "post": { "operationId": "transferScheduledDeal", "summary": "Transfer scheduled deal", "description": "Transfers a scheduled deal to a new destination email and address", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferScheduledDealInputDto" } } } }, "responses": { "200": { "description": "Deal transferred successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferScheduledDealResponseDto" } } } }, "400": { "description": "Invalid request or deal validation failed" }, "404": { "description": "Merchant or deal not found" }, "500": { "description": "Internal server error" } }, "tags": [ "Deals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations": { "get": { "operationId": "getUserOrganizations", "summary": "Get organizations accessible to the authenticated user", "description": "Retrieves a list of all organizations that the authenticated user has access to, including organizations where the user is a member or has been granted specific permissions.", "parameters": [], "responses": { "200": { "description": "Organizations retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationDto" } } } } }, "401": { "description": "Authentication required" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/users": { "get": { "operationId": "getOrganizationUsers", "summary": "Get organization users", "description": "Retrieve a paginated list of users for a specific organization. Requires ORGANIZATION_SETTINGS_VIEW_USER permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "page", "required": true, "in": "query", "description": "Page number", "schema": { "minimum": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": true, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "name", "required": false, "in": "query", "description": "Filter by user name (partial match, case-insensitive).", "schema": { "example": "John", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Filter by user email (partial match, case-insensitive).", "schema": { "example": "john@doe.com", "type": "string" } } ], "responses": { "200": { "description": "List of organization users retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrganizationUsersResponseDto" } } } }, "400": { "description": "Invalid request parameters (invalid page, limit, name, or email filters)" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view organization users" }, "404": { "description": "Organization not found" } }, "tags": [ "Organizations" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "updateUserOrganizationRoles", "summary": "Update user roles in organization", "description": "Update the roles assigned to a user in a specific organization. Requires ORGANIZATION_SETTINGS_ASSIGN_ROLE_TO_USER permission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } } ], "requestBody": { "required": true, "description": "User and roles information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserOrganizationRolesRequestDto" } } } }, "responses": { "200": { "description": "User organization roles updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserOrganizationRolesResponseDto" } } } }, "400": { "description": "Invalid request parameters (invalid userId or rolesIds)" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to update user roles" }, "404": { "description": "Organization or user not found" } }, "tags": [ "Organizations" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/feature-flags": { "get": { "operationId": "getOrganizationFeatureFlags", "summary": "Get organization feature flags", "description": "Retrieve all feature flags configured for an organization, including org-level summary maps and active merchants by flag.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } } ], "responses": { "200": { "description": "Organization feature flags retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationFeatureFlagsResponseDto" } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view organization feature flags" }, "404": { "description": "Organization not found" } }, "tags": [ "Organizations" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/balances": { "get": { "operationId": "getOrganizationBalances", "summary": "Get organization balance aggregation with multi-currency conversion", "description": "Retrieves aggregated virtual account balances across all merchants in an organization with optional currency conversion.\n\n**Features:**\n- Aggregates all virtual accounts across merchants the user has access to\n- Converts balances to a user-selectable base currency (default: USD)\n- Supports merchant filtering via merchantIds parameter\n- Two modes: current/point-in-time balance OR historical time-series data\n- Includes organization-wide summaries and optional per-merchant breakdowns in snapshots\n\n**Permission Model:**\nOnly returns data for merchants where the user has MERCHANT_BANK_ACCOUNTS_SETTINGS_VIEW_VIRTUAL_ACCOUNT permission. If the user has no access to any merchants in the organization, a 403 Forbidden error (OB00002) is returned.\n\n**Note:** This endpoint specifically queries virtual accounts only (isVirtual=true), therefore it requires the view_virtual_account permission rather than view_external_bank_account.\n\n**Current Balance Mode:**\nProvide neither `date` nor `period` for latest balances, or provide `date` for a specific point in time. Returns organization-wide summary.\n\n**Historical Mode:**\nProvide `period` parameter (e.g., \"30d\") to receive time-series data. The `interval` is auto-selected based on period unless explicitly provided. Use `includeMerchantBreakdown=true` to get per-merchant details in each snapshot.\n\n**Example Requests:**\n- Current balance (all merchants): `GET /organizations/:orgId/balances?baseCurrency=USD`\n- Current balance (filtered merchants): `GET /organizations/:orgId/balances?merchantIds=mrc_123,mrc_456&baseCurrency=USD`\n- Point-in-time balance: `GET /organizations/:orgId/balances?date=2025-10-15T00:00:00.000Z`\n- Historical (7 days, auto interval): `GET /organizations/:orgId/balances?period=7d&baseCurrency=USD`\n- Historical (30 days, weekly, with breakdown): `GET /organizations/:orgId/balances?period=30d&interval=weekly&includeMerchantBreakdown=true&baseCurrency=USD`\n- Historical (filtered merchants): `GET /organizations/:orgId/balances?merchantIds=mrc_123&period=14d&interval=daily`", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier (UUID format)", "schema": { "example": "org3_abc123def456", "type": "string" } }, { "name": "merchantIds", "required": false, "in": "query", "description": "Optional comma-separated list of merchant IDs to filter results. Only merchants the user has access to will be included.", "schema": { "example": "mrc_abc123,mrc_def456", "type": "string" } }, { "name": "date", "required": false, "in": "query", "description": "Optional ISO 8601 date for point-in-time balance snapshot. Mutually exclusive with period parameter.", "schema": { "format": "date-time", "example": "2025-10-15T00:00:00.000Z", "type": "string" } }, { "name": "baseCurrency", "required": false, "in": "query", "description": "Base currency for conversion (ISO 4217 code). Currently only USD is supported. Defaults to USD if not provided.", "schema": { "type": "string", "enum": [ "USD" ], "default": "USD" } }, { "name": "period", "required": false, "in": "query", "description": "Time period for historical data. Mutually exclusive with date parameter. Values: 3d, 7d, 14d, 30d, 90d, 180d, 1y, all.\n\n**Interval Auto-Selection** (if interval not provided): 3d/7d/14d→daily, 30d/90d→weekly, 180d/1y/all→monthly.\n\n**Restrictions**: Daily interval only allowed for periods ≤14d. Weekly only for periods ≤180d. Monthly required for periods >180d or \"all\".", "schema": { "enum": [ "3d", "7d", "14d", "30d", "90d", "180d", "1y", "all" ], "type": "string" } }, { "name": "interval", "required": false, "in": "query", "description": "Data point frequency for historical mode. Auto-selected based on period if not provided. Values: daily, weekly, monthly.\n\n**Performance Restrictions**:\n- daily: Only allowed with periods 3d, 7d, or 14d (max 14 data points)\n- weekly: Allowed with periods 3d, 7d, 14d, 30d, 90d, or 180d (max ~26 data points)\n- monthly: Allowed with any period, required for 180d, 1y, or all (max ~24 data points)", "schema": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" } }, { "name": "includeMerchantBreakdown", "required": false, "in": "query", "description": "Include per-merchant breakdown in historical snapshots. Default: false. When true, each snapshot includes detailed merchant balances with currency conversions. Set to false for better performance with large datasets.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "excludeToday", "required": false, "in": "query", "description": "Exclude today's snapshot from historical data for better cache performance. When true, only historical data (ending at yesterday) is returned, and currentSummary is omitted. Use this pattern: fetch current balance separately for real-time updates, while historical chart data uses aggressive caching. Default: false", "schema": { "default": false, "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "Balance aggregation retrieved successfully. Response type depends on whether period parameter is provided.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Current Balance Response", "description": "Returned when neither date nor period is provided (current balance), or when date parameter is specified (point-in-time balance)", "allOf": [ { "$ref": "#/components/schemas/OrganizationBalanceResponseDto" } ] }, { "title": "Historical Balance Response", "description": "Returned when period parameter is provided (e.g., ?period=30d). Includes time-series snapshots with optional per-merchant breakdown controlled by includeMerchantBreakdown parameter.", "allOf": [ { "$ref": "#/components/schemas/OrganizationBalanceHistoryResponseDto" } ] } ] }, "examples": { "Current Balance Response": { "summary": "Current Balance Response", "description": "Returned when neither date nor period is provided (current balance), or when date parameter is specified (point-in-time balance)", "value": { "organizationId": "org3_abc123def456", "organizationName": "Acme Corporation", "requestedAt": "2025-11-03T18:30:45.123Z", "balanceDate": "2025-11-03T18:30:00.000Z", "baseCurrency": "USD", "merchantCount": 2, "summary": { "totalsByCurrency": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" }, "totalInBaseCurrency": "10399.80", "baseCurrency": "USD", "totalAccounts": 4, "currenciesCount": 4, "lastUpdated": "2025-11-03T18:30:00.000Z" }, "exchangeRates": [ { "fromCurrency": "USD", "toCurrency": "CLP", "rate": "896.86098655", "timestamp": "2025-11-03T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "COP", "rate": "4065.04065041", "timestamp": "2025-11-03T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "USDC", "rate": "1.00020004", "timestamp": "2025-11-03T18:30:45.123Z" } ] } }, "Historical Balance Response": { "summary": "Historical Balance Response", "description": "Returned when period parameter is provided (e.g., ?period=30d). Includes time-series snapshots with optional per-merchant breakdown controlled by includeMerchantBreakdown parameter.", "value": { "organizationId": "org3_abc123def456", "organizationName": "Acme Corporation", "requestedAt": "2025-11-03T18:30:45.123Z", "baseCurrency": "USD", "period": "7d", "interval": "daily", "snapshots": [ { "timestamp": "2025-10-27T00:00:00.000Z", "totalInBaseCurrency": "9245.30", "totalsByCurrency": { "CLP": "4500000.00", "USD": "1150.00", "COP": "11000000.00", "USDC": "475.00" }, "merchantCount": 2, "merchantBreakdown": [ { "merchantId": "mrc_def456abc789", "merchantName": "Acme Store Chile", "totalInBaseCurrency": "6172.50", "currencyBreakdown": [ { "currency": "CLP", "originalAmount": "4500000.00", "convertedAmount": "5022.50" }, { "currency": "USD", "originalAmount": "1150.00", "convertedAmount": "1150.00" } ], "accountCount": 2 }, { "merchantId": "mrc_ghi789jkl012", "merchantName": "Acme Store Colombia", "totalInBaseCurrency": "3072.80", "currencyBreakdown": [ { "currency": "COP", "originalAmount": "11000000.00", "convertedAmount": "2597.80" }, { "currency": "USDC", "originalAmount": "475.00", "convertedAmount": "475.00" } ], "accountCount": 2 } ] }, { "timestamp": "2025-11-03T00:00:00.000Z", "totalInBaseCurrency": "10399.80", "totalsByCurrency": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" }, "merchantCount": 2, "merchantBreakdown": [ { "merchantId": "mrc_def456abc789", "merchantName": "Acme Store Chile", "totalInBaseCurrency": "6825.00", "currencyBreakdown": [ { "currency": "CLP", "originalAmount": "5000000.00", "convertedAmount": "5574.50" }, { "currency": "USD", "originalAmount": "1250.50", "convertedAmount": "1250.50" } ], "accountCount": 2 }, { "merchantId": "mrc_ghi789jkl012", "merchantName": "Acme Store Colombia", "totalInBaseCurrency": "3574.80", "currencyBreakdown": [ { "currency": "COP", "originalAmount": "12500000.00", "convertedAmount": "3074.55" }, { "currency": "USDC", "originalAmount": "500.25", "convertedAmount": "500.25" } ], "accountCount": 2 } ] } ], "currentSummary": { "totalsByCurrency": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" }, "totalInBaseCurrency": "10399.80", "baseCurrency": "USD", "totalAccounts": 4, "currenciesCount": 4, "lastUpdated": "2025-11-03T18:30:00.000Z" }, "trend": { "percentageChange": "+12.49", "direction": "up" }, "exchangeRates": [ { "fromCurrency": "USD", "toCurrency": "CLP", "rate": "896.86098655", "timestamp": "2025-11-03T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "COP", "rate": "4065.04065041", "timestamp": "2025-11-03T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "USDC", "rate": "1.00020004", "timestamp": "2025-11-03T18:30:45.123Z" } ] } } } } } }, "400": { "description": "Invalid request parameters. Possible errors: both date and period provided, invalid currency format, invalid period/interval values, invalid period/interval combination (e.g., daily with 30d period), malformed merchantIds." }, "401": { "description": "Missing or invalid authentication token." }, "403": { "description": "User has no access to any merchants with virtual account view permissions in this organization. Error code: OB00002." }, "404": { "description": "Organization not found." }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks": { "post": { "operationId": "createEndpoint", "summary": "Create webhook endpoint", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } } } }, "400": { "description": "Invalid request data" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "listEndpoints", "summary": "List webhook endpoints", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks/{webhookId}": { "get": { "operationId": "getEndpoint", "summary": "Get webhook endpoint", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointResponseDto" } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deleteEndpoint", "summary": "Delete webhook endpoint (soft delete)", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Endpoint deleted successfully" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "rotateSecret", "summary": "Rotate webhook endpoint secret", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretDto" } } } }, "responses": { "204": { "description": "Secret rotated successfully" }, "400": { "description": "Validation error" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks/{webhookId}/pause": { "post": { "operationId": "pauseEndpoint", "summary": "Pause webhook endpoint", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Endpoint paused successfully" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks/{webhookId}/resume": { "post": { "operationId": "resumeEndpoint", "summary": "Resume webhook endpoint", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Endpoint resumed successfully" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhook-events": { "get": { "operationId": "listEvents", "summary": "List webhook events", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Event type filter (e.g., order.created)", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "From date (ISO string) inclusive", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "To date (ISO string) inclusive", "schema": { "type": "string" } }, { "name": "merchantId", "required": false, "in": "query", "description": "Merchant id filter", "schema": { "type": "string" } }, { "name": "resourceType", "required": false, "in": "query", "description": "Resource type filter (e.g., order, contact)", "schema": { "type": "string" } }, { "name": "resourceId", "required": false, "in": "query", "description": "Resource id filter (e.g., ord_..., con_...)", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size", "schema": { "example": 10, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedWebhookEventsDto" } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhook-events/{eventId}/deliveries": { "get": { "operationId": "listEventDeliveries", "summary": "List deliveries for a webhook event (with live status)", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventDeliveryResponseDto" } } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook event not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhook-events/{eventId}": { "get": { "operationId": "getEvent", "summary": "Get webhook event by id", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventResponseDto" } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook event not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhook-events/{eventId}/replay": { "post": { "operationId": "replayEvent", "summary": "Replay webhook event to one or all endpoints", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "eventId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayEventRequestDto" } } } }, "responses": { "202": { "description": "Replay scheduled" }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook event not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webhooks/{webhookId}/ping": { "post": { "operationId": "ping", "summary": "Ping a webhook endpoint (creates and sends a synthetic event)", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "webhookId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingEventRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventResponseDto" } } } }, "401": { "description": "User not authenticated" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Webhook endpoint not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organization Webhooks" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders": { "get": { "operationId": "getOrders", "summary": "Get a list of orders", "description": "Retrieves a paginated list of orders for the specified merchant with optional filtering by status, type, date range, and currency.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by order status", "schema": { "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED" ], "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by order type", "schema": { "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "PAYMENT_LINK" ], "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Filter orders created on or after this date (ISO 8601 format)", "schema": { "format": "date-time", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "Filter orders created on or before this date (ISO 8601 format)", "schema": { "format": "date-time", "type": "string" } }, { "name": "currencyId", "required": false, "in": "query", "description": "Filter by currency ID", "schema": { "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 10, "example": 10, "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number to retrieve", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order (e.g., \"createdAt:desc\")", "schema": { "example": "createdAt:desc", "type": "string" } }, { "name": "includeResolvedPaymentLinks", "required": false, "in": "query", "description": "Whether to include resolved payment link URLs", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "originAccountId", "required": false, "in": "query", "description": "Filter orders by origin account ID. Cannot be combined with accountId parameter.", "schema": { "example": "acc_origin_123", "type": "string" } }, { "name": "destinationAccountId", "required": false, "in": "query", "description": "Filter orders by destination account ID. Cannot be combined with accountId parameter.", "schema": { "example": "acc_dest_456", "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Filter orders where the account ID matches either the origin or destination account. This parameter is mutually exclusive with originAccountId and destinationAccountId.", "schema": { "example": "acc_789", "type": "string" } } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginationOrderDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to access orders" }, "422": { "description": "Invalid query parameters" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] }, "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Creates a new order of the specified type:\n \n1. **PAYIN**: Receive funds from external sources into virtual balance or real accounts\n - originCurrencySymbol and destinationCurrencySymbol must be fiat\n - Must include exactly one payment method\n - destinationAccountId is optional (defaults to virtual balance)\n\n2. **PAYOUT**: Send funds from virtual balance to external accounts\n - originCurrencySymbol and destinationCurrencySymbol must be fiat\n - destinationAccountId is required (must be a real bank account)\n\n3. **ONRAMP**: Convert fiat to crypto\n - originCurrencySymbol must be fiat\n - destinationCurrencySymbol must be crypto\n - destinationAccountId is required (must be a crypto wallet)\n - paymentMethods is optional (defaults to virtual balance)\n\n4. **OFFRAMP**: Convert crypto to fiat\n - originCurrencySymbol must be crypto\n - destinationCurrencySymbol must be fiat\n - destinationAccountId is optional (defaults to virtual balance)\n\n5. **BALANCE_TRANSFER**: Transfer between virtual balances\n - originCurrencySymbol and destinationCurrencySymbol must be fiat\n - No destinationAccountId needed (handled internally)\n\n6. **PAYMENT_LINK**: Create a payment link for external users\n - originCurrencySymbol and destinationCurrencySymbol must be fiat\n - destinationAccountId is optional (defaults to virtual balance)\n - paymentMethods can be empty (all methods) or multiple methods\n - dueDate can be set for expiry (if not provided, defaults to 24 hours; if provided, must be a future date and cannot exceed 24 hours from creation or order creation will fail)", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequestDto" }, "examples": { "PAYIN_VIRTUAL_BALANCE": { "summary": "PAYIN to Virtual Balance", "description": "Order to the merchant's virtual balance with PSE", "value": { "type": "PAYIN", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "COP", "amountIn": 1000000, "description": "Pago por servicios", "externalId": "payin-ext-001", "paymentMethods": [ { "method": "PSE", "extra": "BANCOLOMBIA" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed" } }, "PAYIN_VIRTUAL_BALANCE_PIX": { "summary": "PAYIN to Virtual Balance with PIX STATIC", "description": "Order to the merchant's virtual balance with PIX", "value": { "type": "PAYIN", "originCurrencySymbol": "BRL", "destinationCurrencySymbol": "BRL", "amountIn": 500, "description": "Pago por servicios", "externalId": "payin-ext-002", "paymentMethods": [ { "method": "PIX_STATIC" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "isMerchantSelfOrder": true } }, "PAYIN_VIRTUAL_BALANCE_KHIPU_AR": { "summary": "PAYIN to Virtual Balance with KHIPU", "description": "Order to the merchant's virtual balance with KHIPU", "value": { "type": "PAYIN", "originCurrencySymbol": "ARS", "destinationCurrencySymbol": "ARS", "amountIn": 500, "description": "Pago por servicios", "externalId": "payin-ext-004", "dueDate": "2026-01-28T12:36:55.523694Z", "paymentMethods": [ { "method": "KHIPU" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "isMerchantSelfOrder": true } }, "PAYIN_VIRTUAL_BALANCE_KHIPU_CL": { "summary": "PAYIN to Virtual Balance with KHIPU in CLP", "description": "Order to the merchant's virtual balance with KHIPU in CLP", "value": { "type": "PAYIN", "originCurrencySymbol": "CLP", "destinationCurrencySymbol": "CLP", "amountIn": 500, "description": "Pago por servicios", "externalId": "payin-ext-005", "dueDate": "2026-01-28T12:36:55.523694Z", "paymentMethods": [ { "method": "KHIPU" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "isMerchantSelfOrder": true } }, "PAYIN_VIRTUAL_BALANCE_QRI": { "summary": "PAYIN to Virtual Balance with QRI", "description": "Order to the merchant's virtual balance with QRI", "value": { "type": "PAYIN", "originCurrencySymbol": "ARS", "destinationCurrencySymbol": "ARS", "amountIn": 500, "description": "Pago por servicios", "externalId": "payin-ext-003", "dueDate": "2026-01-28T12:36:55.523694Z", "paymentMethods": [ { "method": "QRI" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "isMerchantSelfOrder": true } }, "PAYIN_VIRTUAL_BALANCE_ETPAY": { "summary": "PAYIN to Virtual Balance with ETPAY", "description": "Order to the merchant's virtual balance with ETPAY", "value": { "type": "PAYIN", "originCurrencySymbol": "CLP", "destinationCurrencySymbol": "CLP", "amountIn": 500, "description": "Pago por servicios", "externalId": "payin-ext-006", "dueDate": "2026-01-28T12:36:55.523694Z", "paymentMethods": [ { "method": "ETPAY" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "isMerchantSelfOrder": true } }, "PAYOUT": { "summary": "PAYOUT to Bank Account", "description": "Order from merchant to a bank account", "value": { "type": "PAYOUT", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "COP", "amountOut": 900000, "destinationAccountId": "bank-account-456", "description": "Payout al cliente", "externalId": "payout-ext-001", "isMerchantSelfOrder": true } }, "ONRAMP_PAYMENT_METHOD": { "summary": "ONRAMP from Payment Method", "description": "Convert fiat to crypto using a payment method", "value": { "type": "ONRAMP", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "ETH", "amountIn": 1000000, "destinationAccountId": "eth-wallet-789", "description": "Compra de ETH", "externalId": "onramp-ext-001", "paymentMethods": [ { "method": "PSE", "extra": "BANCOLOMBIA" } ], "quoteId": "quote-123" } }, "ONRAMP_BALANCE": { "summary": "ONRAMP from Balance", "description": "Convert fiat to crypto using merchant balance", "value": { "type": "ONRAMP", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "ETH", "amountIn": 1000000, "destinationAccountId": "eth-wallet-789", "description": "Compra de ETH desde balance", "externalId": "onramp-ext-002", "quoteId": "quote-124" } }, "OFFRAMP_VIRTUAL_BALANCE": { "summary": "OFFRAMP to Virtual Balance", "description": "Convert crypto to fiat in merchant balance", "value": { "type": "OFFRAMP", "originCurrencySymbol": "ETH", "destinationCurrencySymbol": "COP", "amountIn": 1.5, "description": "Venta de ETH", "externalId": "offramp-ext-001", "quoteId": "quote-456" } }, "OFFRAMP_BANK_ACCOUNT": { "summary": "OFFRAMP to Bank Account", "description": "Convert crypto to fiat and send to bank account", "value": { "type": "OFFRAMP", "originCurrencySymbol": "ETH", "destinationCurrencySymbol": "COP", "amountIn": 1.5, "destinationAccountId": "bank-account-789", "description": "Venta de ETH a banco", "externalId": "offramp-ext-002", "quoteId": "quote-457" } }, "BALANCE_TRANSFER": { "summary": "Balance Transfer", "description": "Transfer between different currency balances", "value": { "type": "BALANCE_TRANSFER", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "USD", "amountIn": 1000000, "description": "Transferencia de balance", "externalId": "transfer-ext-001", "quoteId": "quote-789", "isMerchantSelfOrder": true } }, "PAYMENT_LINK_MULTI_METHOD": { "summary": "Payment Link with Multiple Methods", "description": "Create a payment link with multiple payment methods", "value": { "type": "PAYMENT_LINK", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "COP", "amountIn": 1000000, "description": "Pago de factura", "externalId": "plink-ext-001", "paymentMethods": [ { "method": "PSE" }, { "method": "NEQUI" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "dueDate": "2026-01-28T12:36:55.523694Z", "isMerchantSelfOrder": true } }, "PAYMENT_LINK_ALL_METHODS": { "summary": "Payment Link with All Methods", "description": "Create a payment link with all available methods", "value": { "type": "PAYMENT_LINK", "originCurrencySymbol": "COP", "destinationCurrencySymbol": "COP", "amountIn": 1000000, "destinationAccountId": "bank-account-123", "description": "Pago de factura a banco", "externalId": "plink-ext-002", "paymentMethods": [], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "dueDate": "2026-01-28T12:36:55.523694Z", "isMerchantSelfOrder": true } }, "PAYMENT_LINK_ONLY_PIX": { "summary": "Payment Link with only PIX STATIC", "description": "Create a payment link with only PIX STATIC", "value": { "type": "PAYMENT_LINK", "originCurrencySymbol": "BRL", "destinationCurrencySymbol": "BRL", "amountIn": 500, "description": "Pago de factura", "externalId": "plink-ext-007", "paymentMethods": [ { "method": "PIX_STATIC" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "dueDate": "2026-01-28T12:36:55.523694Z", "isMerchantSelfOrder": true } }, "PAYMENT_LINK_ONLY_QRI": { "summary": "Payment Link with only QRI", "description": "Create a payment link with only QRI", "value": { "type": "PAYMENT_LINK", "originCurrencySymbol": "BRL", "destinationCurrencySymbol": "BRL", "amountIn": 500, "description": "Pago de factura", "externalId": "plink-ext-007", "paymentMethods": [ { "method": "QRI" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "dueDate": "2026-01-28T12:36:55.523694Z", "isMerchantSelfOrder": true } }, "PAYMENT_LINK_ONLY_KHIPU": { "summary": "Payment Link with only KHIPU", "description": "Create a payment link with only KHIPU", "value": { "type": "PAYMENT_LINK", "originCurrencySymbol": "ARS", "destinationCurrencySymbol": "ARS", "amountIn": 500, "description": "Pago de factura", "externalId": "plink-ext-007", "paymentMethods": [ { "method": "KHIPU" } ], "successUrl": "https://merchant.com/success", "failedUrl": "https://merchant.com/failed", "dueDate": "2026-01-28T12:36:55.523694Z", "isMerchantSelfOrder": true } } } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseDto" } } } }, "400": { "description": "Invalid request body structure" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to create orders" }, "422": { "description": "Invalid order data or business rule violations" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/{orderId}": { "get": { "operationId": "getOrderById", "summary": "Get an order by ID", "description": "Retrieves a specific order by its ID for the specified merchant. The order must belong to the merchant and the merchant must belong to the organization.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "orderId", "required": true, "in": "path", "description": "Order ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Order does not belong to merchant or merchant does not belong to organization" }, "404": { "description": "Order not found" }, "422": { "description": "Invalid order ID format" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] }, "patch": { "operationId": "updateOrder", "summary": "Update an order", "description": "Updates an existing order. Currently supports associating a blockchain transaction hash (txHash) with the order. Used for networks like Stellar or Algorand where the client sends crypto externally and provides the txHash afterwards.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "orderId", "required": true, "in": "path", "description": "Order ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderDto" } } } }, "responses": { "200": { "description": "Order updated successfully" }, "400": { "description": "Invalid request body" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Order not found" } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/external/{externalId}": { "get": { "operationId": "getOrderByExternalId", "summary": "Get an order by external ID", "description": "Retrieves a specific order by its external ID (merchant-provided identifier). The order must belong to the merchant and the merchant must belong to the organization.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "externalId", "required": true, "in": "path", "description": "External ID (merchant-provided identifier)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Order does not belong to merchant or merchant does not belong to organization" }, "404": { "description": "Order not found" }, "422": { "description": "Invalid external ID format" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/{orderId}/confirm": { "post": { "operationId": "confirmOrder", "summary": "Confirm an ON_HOLD order via MFA", "description": "Confirms an order that is ON_HOLD awaiting MFA verification. If approval is also required, the order remains ON_HOLD until approvals are received.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "orderId", "required": true, "in": "path", "description": "Order ID to confirm", "schema": { "type": "string" } }, { "name": "pendingApprovalId", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order confirmed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseDto" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/{orderId}/sign": { "get": { "operationId": "prepareEmbeddedWalletSigning", "summary": "Prepare an embedded-wallet-backed order for requester signing", "description": "Builds the embedded wallet transaction-management request body the requester must stamp with their passkey or delegated API key.", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order signing request prepared successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSigningPrepareResponseDto" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/orders/{orderId}/sign/confirm": { "post": { "operationId": "confirmEmbeddedWalletSigning", "summary": "Confirm a stamped embedded wallet signature for an embedded-wallet-backed order", "description": "Validates and stores the requester-stamped embedded wallet transaction request, then enqueues payout processing.", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSigningConfirmRequestDto" } } } }, "responses": { "200": { "description": "Embedded wallet transaction request accepted and payout flow enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponseDto" } } } } }, "tags": [ "Orders" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/notifications": { "post": { "operationId": "send", "summary": "Send a notification for merchant", "description": "Send a notification on behalf of a specific merchant within an organization. Requires MERCHANT_NOTIFICATIONS_SEND permission.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier (e.g., 'mer_def456')", "schema": { "example": "mer_def456", "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier (e.g., 'org_abc123')", "schema": { "example": "org_abc123", "type": "string" } } ], "requestBody": { "required": true, "description": "Notification data to be sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNotificationDto" } } } }, "responses": { "202": { "description": "Notification has been queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok", "description": "Operation status" } } } } } }, "400": { "description": "Invalid request parameters or body" }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to send notifications for this merchant" }, "404": { "description": "Organization or merchant not found" }, "422": { "description": "Invalid notification data provided" }, "500": { "description": "Internal server error" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/api/v1/me/notifications": { "post": { "operationId": "sendToUser", "summary": "Send a notification to authenticated user", "description": "Send a notification to the currently authenticated user. No additional permissions required beyond authentication.", "parameters": [], "requestBody": { "required": true, "description": "Notification data to be sent to the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendNotificationDto" } } } }, "responses": { "202": { "description": "Notification has been queued for processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok", "description": "Operation status" } } } } } }, "400": { "description": "Invalid request parameters or body" }, "401": { "description": "Missing or invalid authentication token" }, "422": { "description": "Invalid notification data provided" }, "500": { "description": "Internal server error" } }, "tags": [ "Notifications" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/quotes": { "post": { "operationId": "createQuote", "summary": "Create a quote", "description": "Creates a new quote for currency exchange or payment operations. The quote provides pricing information including exchange rates, fees, and estimated processing times based on the specified parameters such as amount, source and destination currencies, and operation type.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Quote request data including amount, currencies, and operation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequestDto" } } } }, "responses": { "201": { "description": "Quote created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponseDto" } } } }, "400": { "description": "Invalid request body structure" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to create quotes" }, "422": { "description": "Invalid quote data or business rule violations" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Quotes" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/quotes/{quoteId}": { "get": { "operationId": "getQuote", "summary": "Get a quote by ID", "description": "Retrieves a quote by its ID", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "quoteId", "required": true, "in": "path", "description": "Quote ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParsedQuoteDaoResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions to access quotes" }, "404": { "description": "Quote not found" }, "422": { "description": "Invalid quote ID format" }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpException" } } } } }, "tags": [ "Quotes" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-statement": { "get": { "operationId": "getLedgerStatement", "summary": "Get ledger statement of account", "description": "Retrieves a bank-style statement of account showing all ledger movements that affected the merchant's balance for the specified account and date range.\n\n**Features:**\n- Opening balance at period start\n- Chronological list of all movements (debits and credits)\n- Running balance after each movement\n- Closing balance at period end\n- Human-readable descriptions enriched from order context\n\n**Date Range:**\n- Use `from` and `to` parameters in YYYY-MM-DD format\n- Maximum range is 365 days\n- Granularity parameter controls date cutoffs (daily or monthly)\n\n**Pagination:**\n- Uses cursor-based pagination\n- The `cursor` from the response can be used to fetch the next page\n- Default page size is 50, maximum is 100\n\n**Example:**\n`GET /v1/organizations/org3_xxx/merchants/mrc_xxx/accounts/acc_xxx/reports/ledger-statement?from=2025-01-01&to=2025-01-31&granularity=daily&limit=50`", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org3_8821b7b4-7f0c-45d9-aa5f-a9ce41ee2f1e", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mrc_2e8f96ab-dbd5-45f9-b4b6-645945daf340", "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "Virtual account ID (must be a virtual account)", "schema": { "example": "acc_0031c537-2301-40ab-9153-0f7c48505350", "type": "string" } }, { "name": "from", "required": true, "in": "query", "description": "Start date (YYYY-MM-DD)", "schema": { "example": "2025-01-01", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "End date (YYYY-MM-DD)", "schema": { "example": "2025-01-31", "type": "string" } }, { "name": "granularity", "required": false, "in": "query", "description": "Report granularity for date cutoffs", "schema": { "default": "daily", "enum": [ "daily", "monthly" ], "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination (from previous response)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } } ], "responses": { "200": { "description": "Ledger statement generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerStatementResponseDto" } } } }, "400": { "description": "Invalid date range, granularity, or cursor format" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account does not belong to merchant" }, "404": { "description": "Account not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Reports" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}/reports/orders": { "get": { "operationId": "getOrdersReport", "summary": "Get executed orders report", "description": "Retrieves a report of all orders associated with the specified account within the date range.\n\n**Features:**\n- Lists all orders (PAYINs, PAYOUTs, transfers, etc.) for the account\n- Includes order type, status, amounts, currencies\n- Counterparty information when available\n- Summary statistics by type and status\n\n**Filters:**\n- Filter by order type (PAYIN, PAYOUT, BALANCE_TRANSFER, etc.)\n- Filter by order status (COMPLETED, PENDING, FAILED, etc.)\n\n**Note:** This report shows orders/deals, not ledger movements. For balance reconciliation, use the ledger-statement endpoint.\n\n**Example:**\n`GET /v1/organizations/org3_xxx/merchants/mrc_xxx/accounts/acc_xxx/reports/orders?from=2025-01-01&to=2025-01-31&type=PAYIN&status=COMPLETED`", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org3_8821b7b4-7f0c-45d9-aa5f-a9ce41ee2f1e", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mrc_2e8f96ab-dbd5-45f9-b4b6-645945daf340", "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "Virtual account ID", "schema": { "example": "acc_0031c537-2301-40ab-9153-0f7c48505350", "type": "string" } }, { "name": "from", "required": true, "in": "query", "description": "Start date (YYYY-MM-DD)", "schema": { "example": "2025-01-01", "type": "string" } }, { "name": "to", "required": true, "in": "query", "description": "End date (YYYY-MM-DD)", "schema": { "example": "2025-01-31", "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by order type", "schema": { "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "CRYPTO_PAYOUT", "PAYMENT_LINK", "INTER_MERCHANT_TRANSFER" ], "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by order status", "schema": { "enum": [ "DRAFT", "PENDING", "PAID", "CANCELLED", "REFUND_REQUESTED", "COMPLETED", "PROCESSING", "FAILED", "REFUNDED", "EXPIRED", "ON_HOLD" ], "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor for pagination (from previous response)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "number" } } ], "responses": { "200": { "description": "Orders report generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersReportResponseDto" } } } }, "400": { "description": "Invalid date range or filter parameters" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or account does not belong to merchant" }, "404": { "description": "Account not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Reports" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-entry/{ledgerEntryId}": { "get": { "operationId": "getLedgerEntryReceipt", "summary": "Get details for a single ledger entry", "description": "Retrieves detailed information (receipt) for a specific ledger entry (movement).\n\n**Features:**\n- Detailed information about a single ledger movement\n- Merchant and account details\n- Movement type, amount, and currency\n- Human-readable description\n- Balance before and after the movement\n- References to associated orders/payouts\n\n**Use Case:**\n- Generate proof of transaction for accounting\n- Provide transaction details to counterparties\n- Support audit requirements\n\n**Example:**\n`GET /v1/organizations/org3_xxx/merchants/mrc_xxx/accounts/acc_xxx/reports/ledger-entry/137`", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "example": "org3_8821b7b4-7f0c-45d9-aa5f-a9ce41ee2f1e", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "example": "mrc_2e8f96ab-dbd5-45f9-b4b6-645945daf340", "type": "string" } }, { "name": "accountId", "required": true, "in": "path", "description": "Virtual account ID", "schema": { "example": "acc_0031c537-2301-40ab-9153-0f7c48505350", "type": "string" } }, { "name": "ledgerEntryId", "required": true, "in": "path", "description": "Ledger entry ID (transaction ID from ledger)", "schema": { "example": "137", "type": "string" } } ], "responses": { "200": { "description": "Receipt generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerEntryReceiptDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or entry does not belong to account" }, "404": { "description": "Ledger entry not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Reports" ], "security": [ { "bearer": [] } ] } }, "/api/v1/users/me": { "get": { "operationId": "getUser", "summary": "Get the authenticated user", "description": "Retrieves the profile information of the currently authenticated user, including their personal details and account information.", "parameters": [], "responses": { "200": { "description": "User profile retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Koywe3UserDto" } } } }, "404": { "description": "User not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/api/v1/users/organizations/{organizationId}/merchants/{merchantId}/invitations": { "post": { "operationId": "createInvitation", "summary": "Create and send an invitation to join a merchant", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID to invite the user to", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationDto" } } } }, "responses": { "201": { "description": "Invitation created and sent successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponseDto" } } } }, "400": { "description": "Invalid request data (e.g., merchant not found, user not found, invalid roles)." }, "401": { "description": "User not authenticated." }, "403": { "description": "User does not have permission to invite to this merchant." }, "409": { "description": "A pending invitation already exists for this email address and merchant." }, "422": { "description": "Invalid invitation data or business rule violations" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "listInvitations", "summary": "List invitations sent for a merchant", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID to list invitations for", "schema": { "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of invitations per page", "schema": { "enum": [ 10, 20, 50, 100 ], "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number to retrieve", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order for invitations (e.g., by createdAt)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "List of invitations retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedInvitationsDto" } } } }, "400": { "description": "Invalid request data (e.g., merchant not found)." }, "401": { "description": "User not authenticated." }, "403": { "description": "User does not have permission to view invitations for this merchant." }, "422": { "description": "Invalid query parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/api/v1/users/organizations/{organizationId}/invitations": { "post": { "operationId": "createOrganizationInvitation", "summary": "Create and send an organization invitation", "description": "Create an invitation to join an existing organization. The organization ID is specified in the URL.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID to invite the user to", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Organization invitation data with email and roles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationInvitationDto" } } } }, "responses": { "201": { "description": "Organization invitation created and sent successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationInvitationResponseDto" } } } }, "400": { "description": "Invalid request data (e.g., organization not found, invalid roles)." }, "401": { "description": "User not authenticated." }, "403": { "description": "User does not have permission to invite to this organization." }, "409": { "description": "A pending organization invitation already exists for this email address." }, "422": { "description": "Invalid organization invitation data or business rule violations" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "listOrganizationInvitations", "summary": "List organization invitations", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization ID", "schema": { "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of invitations per page", "schema": { "enum": [ 10, 20, 50, 100 ], "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number to retrieve", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order for invitations (e.g., by createdAt)", "schema": { "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "List of organization invitations retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrganizationInvitationsDto" } } } }, "400": { "description": "Invalid request data (e.g., organization not found)." }, "401": { "description": "User not authenticated." }, "403": { "description": "User does not have permission to view invitations for this organization." }, "422": { "description": "Invalid query parameters" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts": { "post": { "operationId": "createPayInVirtualBankAccount", "summary": "Create Virtual Bank Account", "description": "Creates a new virtual bank account for a merchant within an organization. This endpoint initiates the creation process through the Payment Service Provider (PSP) and stores the account details locally.\n\n**Supported Countries & Currencies:**\n- Argentina (AR) → ARS (Argentine Peso) — returns CVU + alias\n- Mexico (MX) → MXN (Mexican Peso) — returns CLABE\n- United States (US) → USD (US Dollar) — returns account number + routing number\n\n**Business Rules:**\n- Each merchant can have only one virtual account per country/currency combination\n- For US/USD accounts, the merchant must have a KYC_APPROVED status\n**Roles with Access:**\n- Platform Admin\n- Wallet & Bank Admin", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "merchant_123", "type": "string" } } ], "requestBody": { "required": true, "description": "Virtual bank account creation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayInVirtualBankAccountDto" }, "examples": { "argentina": { "summary": "Argentina — CVU (ARS)", "description": "Creates a CVU (Clave Virtual Uniforme) for Argentine Peso transactions.", "value": { "country": "AR", "currency": "ARS" } }, "mexico": { "summary": "Mexico — CLABE (MXN)", "description": "Creates a CLABE (Clave Bancaria Estandarizada) for Mexican Peso transactions.", "value": { "country": "MX", "currency": "MXN" } }, "usa": { "summary": "USA — Bank Account (USD)", "description": "Creates a USD bank account for the merchant. Requires the merchant to have a KYC_APPROVED status.", "value": { "country": "US", "currency": "USD" } } } } } }, "responses": { "201": { "description": "Virtual bank account created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayInVirtualBankAccountResponseDto" }, "examples": { "argentina": { "summary": "Argentina — CVU (ARS)", "value": { "id": "pivba_ar_001", "merchantId": "merchant_123", "country": "AR", "currency": "ARS", "isActive": true, "virtualBankAccountNumber": "0000001700000000000024", "alias": "EXAMPLE.ALIAS.AR", "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" } }, "mexico": { "summary": "Mexico — CLABE (MXN)", "value": { "id": "pivba_mx_001", "merchantId": "merchant_123", "country": "MX", "currency": "MXN", "isActive": true, "virtualBankAccountNumber": "000000000000000000", "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" } }, "usa": { "summary": "USA — Bank Account (USD)", "value": { "id": "pivba_us_001", "merchantId": "merchant_123", "country": "US", "currency": "USD", "isActive": true, "virtualBankAccountNumber": "000000000", "routingNumber": "000000000", "bankName": "Example Bank", "createdAt": "2026-02-24T12:00:00.000Z", "updatedAt": "2026-02-24T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request data or business rule violations", "content": { "application/json": { "examples": { "invalidCountryCurrency": { "summary": "PIVBA00012 — Invalid Country/Currency Combination", "description": "Attempted to create account with an invalid country/currency pair (e.g., AR+MXN)", "value": { "errorCode": "PIVBA00012", "message": "Currency not supported for country", "statusCode": 400 } }, "countryNotSupported": { "summary": "PIVBA00007 — Country Not Supported", "description": "The provided country code is not supported (must be AR, MX, or US)", "value": { "errorCode": "PIVBA00007", "message": "Country not supported", "statusCode": 400 } }, "missingRequiredFields": { "summary": "Missing Required Fields", "description": "Required fields are missing from the request", "value": { "message": [ "country must be one of the following values: AR, MX, US", "currency must be one of the following values: ARS, MXN, USD" ], "error": "Bad Request", "statusCode": 400 } } } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to create virtual bank account" }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "example": { "errorCode": "PIVBA00004", "message": "Merchant not found", "statusCode": 404 } } } } }, "409": { "description": "Virtual bank account already exists for this merchant/country/currency", "content": { "application/json": { "schema": { "example": { "errorCode": "PIVBA00002", "message": "Virtual bank account already exists", "statusCode": 409 } } } } }, "422": { "description": "KYC not approved — only applies to US/USD accounts", "content": { "application/json": { "schema": { "example": { "errorCode": "PIVBA00016", "message": "Recipient KYC not approved for virtual account creation", "statusCode": 422 } } } } }, "500": { "description": "PSP communication error or internal server error", "content": { "application/json": { "examples": { "pspError": { "summary": "PIVBA00006 — PSP Communication Error", "description": "Returned when the Payment Service Provider fails to process the request. Always includes an errorCode.", "value": { "errorCode": "PIVBA00006", "message": "PSP communication error", "statusCode": 500 } }, "internalError": { "summary": "Internal Server Error", "description": "Returned for unhandled exceptions (e.g. unexpected runtime errors). No errorCode is attached in this case.", "value": { "message": "Internal server error", "statusCode": 500 } } } } } } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "getPayInVirtualBankAccountsByMerchant", "summary": "Get Virtual Bank Accounts by Merchant", "description": "Retrieves all virtual bank accounts associated with a specific merchant within an organization. This endpoint provides a comprehensive view of all virtual accounts, including their status, account numbers, and aliases.\n\n**Response Information:**\n- Merchant details and contact information\n- List of all virtual bank accounts with their current status\n- Account numbers, aliases, and creation timestamps\n- Country and currency information for each account\n\n**Roles with Access:**\n- Platform Admin\n- Wallet & Bank Admin\n- Platform Contact Support\n- Financial Operator - Views", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "merchant_123", "type": "string" } } ], "responses": { "200": { "description": "Virtual bank accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PayInVirtualBankAccountItemDto" } } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to view virtual bank accounts" }, "404": { "description": "Merchant not found", "content": { "application/json": { "schema": { "example": { "message": "Merchant with ID merchant-123 not found", "error": "Not Found", "statusCode": 404 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "Internal server error", "statusCode": 500 } } } } } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts/{id}/alias": { "patch": { "operationId": "updateAlias", "summary": "Update Virtual Bank Account Alias (Argentina Only)", "description": "Updates the custom alias of an existing virtual bank account. This operation synchronizes the alias change with both the Payment Service Provider (PSP) and the local database.\n\n**🚫 RESTRICTED ENDPOINT:** This endpoint is ONLY available for Argentina (AR) accounts. All other countries (Mexico/MX, etc.) will receive a 400 error immediately.\n\n**Alias Requirements:**\n- Must contain only letters, numbers, and dots (.)\n- Cannot be empty or contain special characters\n- Must be unique within the merchant's account scope\n- Only supported for Argentina (AR) accounts\n\n**Validation Process:**\n- **Early validation:** Rejects non-Argentina accounts immediately\n- Verifies the virtual bank account belongs to the specified merchant\n- Updates the alias in the PSP system\n- Synchronizes changes with the local database\n\n**Error Responses:**\n- `400 PIVBA00013`: Alias not supported for this country (non-AR accounts)\n- `404 PIVBA00001`: Virtual bank account not found\n\n**Roles with Access:**\n- Platform Admin\n- Wallet & Bank Admin", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_abc123", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "merchant_123", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Virtual bank account identifier", "schema": { "example": "pivba_123456", "type": "string" } } ], "requestBody": { "required": true, "description": "Virtual bank account alias update details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAliasRequestDto" }, "examples": { "basicAlias": { "summary": "📝 Update to Basic Alias", "description": "Updates the account alias to a simple, descriptive name", "value": { "alias": "koywe.main.account" } }, "merchantSpecific": { "summary": "🏢 Update to Merchant-Specific Alias", "description": "Updates the alias to include merchant identification", "value": { "alias": "merchant.001.argentina" } }, "departmentBased": { "summary": "🏬 Update to Department-Based Alias", "description": "Updates the alias to reflect the department or purpose", "value": { "alias": "sales.argentina.2024" } }, "invalidAlias": { "summary": "❌ Invalid Alias Example", "description": "Example of an invalid alias that would be rejected", "value": { "alias": "invalid@alias#with$special%chars" } } } } } }, "responses": { "200": { "description": "Alias updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayInVirtualBankAccountResponseDto" } } } }, "400": { "description": "Invalid request data or alias format violations", "content": { "application/json": { "examples": { "emptyAlias": { "summary": "❌ Empty Alias", "description": "Alias field is required and cannot be empty", "value": { "message": [ "alias should not be empty" ], "error": "Bad Request", "statusCode": 400 } }, "invalidAliasFormat": { "summary": "❌ Invalid Alias Format", "description": "Alias contains invalid characters or format", "value": { "message": [ "Alias must contain only letters, numbers, and dots", "Special characters are not allowed in alias" ], "error": "Bad Request", "statusCode": 400 } }, "aliasTooLong": { "summary": "❌ Alias Too Long", "description": "Alias exceeds maximum length limit", "value": { "message": [ "Alias must not exceed 50 characters" ], "error": "Bad Request", "statusCode": 400 } } } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to update virtual bank account alias" }, "404": { "description": "Merchant or virtual bank account not found", "content": { "application/json": { "schema": { "example": { "message": "Virtual bank account not found for merchant merchant-123 with account number 0000001700000000001232", "error": "Not Found", "statusCode": 404 } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "example": { "message": "Internal server error", "statusCode": 500 } } } } } }, "tags": [ "Merchant" ], "security": [ { "bearer": [] } ] } }, "/api/v1/onboarding/me": { "get": { "operationId": "getOnboardingMe", "summary": "Get onboarding status for authenticated user", "description": "Returns all onboarding evaluations and their setup status for the currently authenticated user. Optionally filter by evaluation status or setup status.", "parameters": [ { "name": "evaluationStatus", "required": false, "in": "query", "description": "Filter by evaluation status", "schema": { "enum": [ "RECEIVED", "IN_REVIEW", "COMPLIANCE_IN_REVIEW", "ACCOUNT_SETUP_IN_PROGRESS", "COMPLETED", "ACTION_REQUIRED", "APPROVED", "REJECTED", "PENDING_KYB" ], "type": "string" } }, { "name": "setupStatus", "required": false, "in": "query", "description": "Filter by setup status", "schema": { "enum": [ "PENDING", "RUNNING", "FAILED", "COMPLETED" ], "type": "string" } } ], "responses": { "200": { "description": "Onboarding status retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingMeResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token", "content": { "application/json": { "schema": { "example": { "message": "Unauthorized", "statusCode": 401 } } } } } }, "tags": [ "Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/onboarding/kyb": { "post": { "operationId": "triggerKyb", "summary": "Trigger KYB process for a merchant", "description": "Initiates the KYB (Know Your Business) process for the given merchant. Gathers pre-onboarding data, submits it to the KYB provider, and returns a process record. The form link will be available via the GET endpoint once the provider has processed the submission.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerKybRequestDto" } } } }, "responses": { "202": { "description": "KYB process triggered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybProcessResponseDto" } } } }, "404": { "description": "Merchant not found" }, "409": { "description": "KYB process already exists in a non-terminal state" } }, "tags": [ "Onboarding KYB" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "listKybProcesses", "summary": "List KYB processes for a merchant", "description": "Returns all KYB processes for the given merchant, ordered by most recent first.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } } ], "responses": { "200": { "description": "List of KYB processes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KybProcessResponseDto" } } } } } }, "tags": [ "Onboarding KYB" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/onboarding/kyb/{kybId}": { "get": { "operationId": "getKybStatus", "summary": "Get KYB process status", "description": "Returns the current status of a KYB process, including the form link when available. Use this endpoint to poll for status updates after triggering a KYB process.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization identifier", "schema": { "example": "org_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant identifier", "schema": { "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc", "type": "string" } }, { "name": "kybId", "required": true, "in": "path", "description": "KYB process identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "KYB process status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybProcessResponseDto" } } } }, "404": { "description": "KYB process not found" } }, "tags": [ "Onboarding KYB" ], "security": [ { "bearer": [] } ] } }, "/api/v1/pre-onboarding/registration-draft": { "post": { "operationId": "createDraft", "summary": "Create registration draft", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/pre-onboarding/registration-draft/{draftId}": { "put": { "operationId": "updateDraft", "summary": "Update registration draft (full replace)", "parameters": [ { "name": "draftId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDraftRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "getDraft", "summary": "Get registration draft", "parameters": [ { "name": "draftId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/pre-onboarding/registration-form/{draftId}": { "post": { "operationId": "submitRegistrationFromDraft", "summary": "Submit registration from draft (no body required)", "parameters": [ { "name": "draftId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRegistrationResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/pre-onboarding/registrations": { "get": { "operationId": "getUserRegistrations", "summary": "List user registrations and active draft", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRegistrationsResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/pre-onboarding/registrations/{registrationId}/status": { "get": { "operationId": "getRegistrationStatus", "summary": "Get registration status", "parameters": [ { "name": "registrationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationFormStatusResponseDto" } } } } }, "tags": [ "Pre-Onboarding" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy": { "post": { "operationId": "createPolicy", "summary": "Create transactional policy for organization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] }, "get": { "operationId": "getPolicy", "summary": "Get active policy for organization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deactivatePolicy", "summary": "Deactivate policy for organization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/rules": { "post": { "operationId": "addRule", "summary": "Add a rule to the policy", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRuleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/rules/reorder": { "put": { "operationId": "reorderRules", "summary": "Reorder policy rules", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderPolicyRulesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/rules/{ruleId}": { "put": { "operationId": "updateRule", "summary": "Update a policy rule", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "ruleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyRuleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "deleteRule", "summary": "Delete a policy rule", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "ruleId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyMutationResponseDto" } } } } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/audit": { "get": { "operationId": "getAuditLog", "summary": "Get audit log for policy", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "pageSize", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "pageNumber", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "tags": [ "Transactional Policy" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/approvals": { "get": { "operationId": "getPendingApprovals", "summary": "Get pending approvals", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "merchantId", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "scope", "required": false, "in": "query", "description": "mine: approvals assigned to you (default). requested: approvals requested by you. all: all pending approvals.", "schema": { "enum": [ "mine", "requested", "all" ], "type": "string" } }, { "name": "operationType", "required": false, "in": "query", "description": "Optional filter by operation type (e.g. PAYOUT_FIAT).", "schema": { "enum": [ "PAYOUT_FIAT", "PAYOUT_CRYPTO", "BALANCE_TRANSFER", "POLICY_MANAGE", "DESTINATION_EDIT", "PASSKEY_ENROLL", "API_USER_MFA_ENROLL", "API_USER_MFA_REVOKE", "EMBEDDED_WALLET_ACCESS_GRANT", "USER_INVITE" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingApprovalResponseDto" } } } } } }, "tags": [ "Transactional Policy - Approvals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/approvals/{approvalId}": { "get": { "operationId": "getApprovalById", "summary": "Get a pending approval by ID", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "approvalId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponseDto" } } } } }, "tags": [ "Transactional Policy - Approvals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/approvals/{approvalId}/approve": { "post": { "operationId": "approve", "summary": "Approve a pending operation", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "approvalId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveOperationRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponseDto" } } } } }, "tags": [ "Transactional Policy - Approvals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/policy/approvals/{approvalId}/reject": { "post": { "operationId": "reject", "summary": "Reject a pending operation", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "approvalId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-mfa-token", "required": true, "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponseDto" } } } } }, "tags": [ "Transactional Policy - Approvals" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/register/init": { "post": { "operationId": "registerInit", "summary": "Initialize passkey registration (bootstrap or re-init)", "description": "Returns rpId and mode. In bootstrap mode, the client creates a passkey and calls register/complete. If already bootstrapped, returns existing sub-org info.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnRegisterInitResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/register/complete": { "post": { "operationId": "registerComplete", "summary": "Complete passkey registration (bootstrap)", "description": "Creates the embedded wallet organization with the calling user as root and auto-creates a transactional policy for the organization. Only works when no sub-org exists for this org.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnRegisterCompleteRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnRegisterCompleteResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/challenge": { "post": { "operationId": "challenge", "summary": "Request MFA challenge nonce", "description": "Returns a random nonce and sub-org ID. The client authenticates with their passkey via the embedded wallet SDK and submits the signed stamp to /verify.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnChallengeResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/verify": { "post": { "operationId": "verify", "summary": "Verify passkey and receive MFA JWT", "description": "Validates the signed passkey stamp with the embedded wallet provider, then issues a short-lived JWT that can be passed as x-mfa-token header on policy-protected endpoints.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnVerifyRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnVerifyResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/credentials": { "get": { "operationId": "listCredentials", "summary": "List my registered passkeys for this organization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebAuthnCredentialInfoDto" } } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/credentials/all": { "get": { "operationId": "listAllCredentials", "summary": "List all registered passkeys for this organization (admin)", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebAuthnCredentialInfoDto" } } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/enroll/init": { "post": { "operationId": "enrollInit", "summary": "Submit passkey attestation for enrollment (invited user)", "description": "The invited user creates a passkey on their device and submits the attestation. A PolicyPendingApproval (PASSKEY_ENROLL) is created. The root user must then prepare and approve the enrollment.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnInviteRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnInviteResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/enroll/prepare": { "post": { "operationId": "enrollPrepare", "summary": "Prepare passkey enrollment request for root signing", "description": "Returns the embedded wallet enrollment body that the root user must sign with their passkey. The root signs this body, then calls /enroll/approve.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnEnrollPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnEnrollPrepareResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/wallet/prepare": { "post": { "operationId": "walletPrepare", "summary": "Prepare embedded wallet provisioning request for passkey signing", "description": "Builds the exact embedded wallet request body the user must sign with their passkey. If the merchant wallet already exists, returns the existing address instead.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnWalletPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnWalletPrepareResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/wallet/{merchantId}/status": { "get": { "operationId": "walletStatus", "summary": "Get embedded wallet provisioning status for a merchant", "description": "Returns whether the organization is bootstrapped, whether the org wallet exists, whether the merchant wallet account exists, and whether the merchant still requires passkey-based provisioning.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnWalletStatusResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/wallet/complete": { "post": { "operationId": "walletComplete", "summary": "Complete embedded wallet provisioning with a stamped request", "description": "Forwards the signed embedded wallet request and persists the resulting embedded wallet binding for the merchant.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnWalletCompleteRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnWalletCompleteResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/recovery/initiate": { "post": { "operationId": "recoveryInitiate", "summary": "Initiate passkey recovery for a locked-out user (root only)", "description": "Root user triggers this to send a 6-digit OTP to the locked-out user's email. Returns an otpId that the locked-out user needs for the verify-otp step.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryInitiateRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryInitiateResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/recovery/verify-otp": { "post": { "operationId": "recoveryVerifyOtp", "summary": "Verify recovery OTP and get credential bundle", "description": "The locked-out user submits the OTP code received via email along with a targetPublicKey from the embedded wallet client. Returns a credentialBundle that the frontend uses to register a new passkey directly with the embedded wallet provider.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryVerifyOtpRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryVerifyOtpResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/recovery/prepare": { "post": { "operationId": "recoveryPrepare", "summary": "Build recovery passkey registration request", "description": "After OTP verification, the locked-out user creates a new passkey on their device and submits the attestation here. Returns the recovery body that the client must stamp with the ephemeral API key from the credential bundle.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryPrepareRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryPrepareResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/recovery/complete": { "post": { "operationId": "recoveryComplete", "summary": "Complete recovery — forward stamped request, revoke old credential, register new one", "description": "Called by the locked-out user after stamping the createAuthenticators body with the ephemeral API key from the credential bundle. Forwards the stamped request to the embedded wallet provider, revokes the old credential, and creates the new one in the DB. No root permission required — the OTP verification already proved identity.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCompleteRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCompleteResponseDto" } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/webauthn/recovery/sessions": { "get": { "operationId": "listRecoverySessions", "summary": "List active recovery sessions for this organization", "description": "Returns PENDING and VERIFIED recovery sessions that have not expired. Root user can use this to monitor ongoing recoveries.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecoverySessionInfoDto" } } } } } }, "tags": [ "WebAuthn — Passkeys & MFA" ], "security": [ { "bearer": [] } ] } }, "/api/v1/merchants/{merchantId}/notifications/inapp": { "get": { "operationId": "list", "summary": "List in-app notifications for merchant", "description": "Returns a paginated list of in-app notifications for the given merchant, ordered by most recent first.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page (default: 50)", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (default: 1)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Paginated notification list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationListResponseDto" } } } }, "400": { "description": "Invalid pagination parameters (NE00003): page must be >= 1, limit must be between 1 and 200" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notifications In-App" ], "security": [ { "bearer": [] } ] } }, "/api/v1/merchants/{merchantId}/notifications/inapp/unread-count": { "get": { "operationId": "unreadCount", "summary": "Get unread notification count", "description": "Returns the number of unread in-app notifications for the given merchant.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Unread notification count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCountResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notifications In-App" ], "security": [ { "bearer": [] } ] } }, "/api/v1/merchants/{merchantId}/notifications/inapp/read-all": { "patch": { "operationId": "markAllRead", "summary": "Mark all notifications as read", "description": "Marks all unread notifications as read for the given merchant. Returns the number of updated notifications.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Number of updated notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkAllReadResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notifications In-App" ], "security": [ { "bearer": [] } ] } }, "/api/v1/merchants/{merchantId}/notifications/inapp/{notificationId}/read": { "patch": { "operationId": "markRead", "summary": "Mark a notification as read", "description": "Marks a single notification as read. Returns NE00001 if the notification does not exist; NE00002 if it belongs to a different merchant.", "parameters": [ { "name": "notificationId", "required": true, "in": "path", "description": "Notification ID", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Notification marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReadResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions or wrong merchant (NE00002)" }, "404": { "description": "Notification not found (NE00001)" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notifications In-App" ], "security": [ { "bearer": [] } ] } }, "/api/v1/merchants/{merchantId}/notification-settings": { "get": { "operationId": "getSettings", "summary": "Get merchant email notification settings", "description": "Returns the email notification settings for the given merchant. If no settings have been configured, returns the defaults (emailEnabled: false, recipients: []).", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current notification settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettingsResponseDto" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notification Settings" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "updateSettings", "summary": "Update merchant email notification settings", "description": "Creates or updates the email notification settings for the given merchant. Set emailEnabled to true and provide at least one recipient to start receiving email notifications on order events.", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "Merchant ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationSettingsDto" } } } }, "responses": { "200": { "description": "Updated notification settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettingsResponseDto" } } } }, "400": { "description": "Validation failed — at least one recipient required when emailEnabled is true" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Notification Settings" ], "security": [ { "bearer": [] } ] } }, "/api/v1/organizations/{organizationId}/merchants/{merchantId}/sandbox/bank-income/simulate": { "post": { "operationId": "simulate", "summary": "Simulate a sandbox bank income for a merchant", "description": "Sandbox-only endpoint. Provisions a fake virtual account for the selected currency when needed and registers a simulated incoming deposit that flows through the normal bank-income processor.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "merchantId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateSandboxBankIncomeDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateSandboxBankIncomeResponseDto" } } } }, "401": { "description": "Missing or invalid authentication token" }, "403": { "description": "Insufficient permissions to simulate a sandbox deposit" }, "404": { "description": "Sandbox simulation is unavailable in production or the merchant/organization was not found" } }, "tags": [ "Sandbox" ], "security": [ { "bearer": [] } ] } } }, "info": { "title": "Koywe Financial API", "description": "Unified API for LATAM cross-border payments, payouts, invoicing, and treasury operations with stablecoin and fiat support.", "version": "1", "contact": {} }, "tags": [], "servers": [ { "url": "https://api-sandbox.koywe.com", "description": "Sandbox" }, { "url": "https://api.koywe.com", "description": "Production" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "HealthzDto": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "ApplicantCompanyRoleResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the role", "example": "1" }, "name": { "type": "string", "description": "Display name of the role", "example": "Dirección / Gerencia General" }, "value": { "type": "string", "description": "Value identifier for the role", "enum": [ "direccion-gerencia-general", "finanzas-y-tesoreria", "operaciones", "tecnologia-producto", "riesgo-y-cumplimiento" ], "example": "direccion-gerencia-general" } }, "required": [ "id", "name", "value" ] }, "GenericCountryBanksDto": { "type": "object", "properties": { "AR": { "type": "array", "items": { "type": "string" } }, "BO": { "type": "array", "items": { "type": "string" } }, "BR": { "type": "array", "items": { "type": "string" } }, "CL": { "type": "array", "items": { "type": "string" } }, "CO": { "type": "array", "items": { "type": "string" } }, "MX": { "type": "array", "items": { "type": "string" } }, "PE": { "type": "array", "items": { "type": "string" } }, "US": { "type": "array", "items": { "type": "string" } }, "VE": { "type": "array", "items": { "type": "string" } }, "CN": { "type": "array", "items": { "type": "string" } }, "HK": { "type": "array", "items": { "type": "string" } }, "IN": { "type": "array", "items": { "type": "string" } }, "JP": { "type": "array", "items": { "type": "string" } }, "PH": { "type": "array", "items": { "type": "string" } }, "SG": { "type": "array", "items": { "type": "string" } }, "TH": { "type": "array", "items": { "type": "string" } }, "TW": { "type": "array", "items": { "type": "string" } }, "AT": { "type": "array", "items": { "type": "string" } }, "BE": { "type": "array", "items": { "type": "string" } }, "DE": { "type": "array", "items": { "type": "string" } }, "EE": { "type": "array", "items": { "type": "string" } }, "ES": { "type": "array", "items": { "type": "string" } }, "FI": { "type": "array", "items": { "type": "string" } }, "FR": { "type": "array", "items": { "type": "string" } }, "IE": { "type": "array", "items": { "type": "string" } }, "IT": { "type": "array", "items": { "type": "string" } }, "LT": { "type": "array", "items": { "type": "string" } }, "LV": { "type": "array", "items": { "type": "string" } }, "NL": { "type": "array", "items": { "type": "string" } }, "PT": { "type": "array", "items": { "type": "string" } }, "BG": { "type": "array", "items": { "type": "string" } }, "CZ": { "type": "array", "items": { "type": "string" } }, "DK": { "type": "array", "items": { "type": "string" } }, "GB": { "type": "array", "items": { "type": "string" } }, "HU": { "type": "array", "items": { "type": "string" } }, "PL": { "type": "array", "items": { "type": "string" } }, "RO": { "type": "array", "items": { "type": "string" } }, "SE": { "type": "array", "items": { "type": "string" } } }, "required": [ "AR", "BO", "BR", "CL", "CO", "MX", "PE", "US", "VE", "CN", "HK", "IN", "JP", "PH", "SG", "TH", "TW", "AT", "BE", "DE", "EE", "ES", "FI", "FR", "IE", "IT", "LT", "LV", "NL", "PT", "BG", "CZ", "DK", "GB", "HU", "PL", "RO", "SE" ] }, "ValueDto": { "type": "object", "properties": { "id": { "type": "string" }, "bank_code": { "type": "string" }, "bank_name": { "type": "string" } }, "required": [ "id", "bank_name" ] }, "GenericDocumentDto": { "type": "object", "properties": { "AR": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "CUIL", "DNI" ] }, "BR": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "CPF", "CURP", "NIT" ] }, "CL": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "RUT" ] }, "CO": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "CED_CIU", "CED_EXT", "NIT" ] }, "MX": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "CURP" ] }, "PE": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "DNI", "DNI", "CED_CIU" ] }, "US": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": [ "EIN" ] } }, "required": [ "AR", "BR", "CL", "CO", "MX", "PE", "US" ] }, "DocumentTypeItemDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Document type ID", "example": "docdef_123" }, "label": { "type": "string", "description": "Document type label in local language", "example": "RUT" }, "labelEng": { "type": "string", "description": "Document type label in English", "example": "Tax ID" }, "code": { "type": "string", "description": "Document type short name/value", "example": "RUT" }, "entityType": { "type": "string", "description": "Entity type (PERSON or COMPANY)", "enum": [ "PERSON", "COMPANY" ], "example": "PERSON" } }, "required": [ "id", "label", "labelEng", "code", "entityType" ] }, "CountryDocumentTypesResponseDto": { "type": "object", "properties": { "countrySymbol": { "type": "string", "description": "Country ISO code (two-letter)", "example": "CL" }, "documentTypes": { "description": "List of document types available for the country", "type": "array", "items": { "$ref": "#/components/schemas/DocumentTypeItemDto" } } }, "required": [ "countrySymbol", "documentTypes" ] }, "EconomicActivityResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Economic activity ID", "example": "econact_12345678-1234-1234-1234-123456789012" }, "code": { "type": "string", "description": "Economic activity code", "example": "COMMERCE_RETAIL" }, "name": { "type": "string", "description": "Economic activity name", "example": "Comercio y Retail (mayorista, minorista, e-commerce, marketplaces)" } }, "required": [ "id", "code", "name" ] }, "CountryEconomicActivityResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Economic activity ID", "example": "econact_12345678-1234-1234-1234-123456789012" }, "code": { "type": "string", "description": "Economic activity code", "example": "TECH_DIGITAL_SERVICES" }, "name": { "type": "string", "description": "Economic activity name", "example": "Tecnología y Servicios Digitales (software, IT, transformación digital)" }, "status": { "type": "string", "description": "Status of the economic activity for this country", "enum": [ "ALLOWED", "FORBIDDEN" ], "example": "ALLOWED" }, "isActive": { "type": "boolean", "description": "Whether the economic activity is active for this country", "example": true } }, "required": [ "id", "code", "name", "status", "isActive" ] }, "CountryEconomicActivitiesResponseDto": { "type": "object", "properties": { "countrySymbol": { "type": "string", "description": "Country symbol (two-letter ISO code)", "example": "CL" }, "economicActivities": { "description": "List of economic activities for this country", "type": "array", "items": { "$ref": "#/components/schemas/CountryEconomicActivityResponseDto" } } }, "required": [ "countrySymbol", "economicActivities" ] }, "CountryCurrencyResponseDto": { "type": "object", "properties": { "currency": { "type": "string", "example": "ARS" }, "currencyId": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" } }, "required": [ "currency", "currencyId" ] }, "CountryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "ctry_8efa0d0c-f834-42eb-af78-ff4149c2e6ef" }, "name": { "type": "string" }, "fullName": { "type": [ "string", "null" ] }, "Currency": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/CountryCurrencyResponseDto" } ] }, { "type": "null" } ] }, "twoLetterIso": { "type": "string" }, "operationalStatus": { "type": "string" } }, "required": [ "id", "name", "fullName", "Currency", "twoLetterIso", "operationalStatus" ] }, "StateResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "State ID", "example": "st_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "name": { "type": "string", "description": "State name", "example": "Aguascalientes" }, "code": { "type": "string", "description": "State code", "example": "AGU" }, "countryId": { "type": "string", "description": "Country ID", "example": "ctry_234d985a-a899-473c-915b-04cbb67207cc" }, "billingId": { "type": "number", "description": "Billing ID", "example": 18 }, "Country": { "$ref": "#/components/schemas/CountryResponseDto" } }, "required": [ "id", "name", "countryId", "Country" ] }, "CountyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "cnty_b99a52f0-dd5e-4659-953f-15a1db623afd" }, "name": { "type": "string" }, "stateId": { "type": "string" }, "code": { "type": "string" }, "billingId": { "type": "number" }, "State": { "$ref": "#/components/schemas/StateResponseDto" } }, "required": [ "id", "name", "stateId", "code", "billingId", "State" ] }, "CurrencyResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "name": { "type": "string", "example": "PESOS ARGENTINOS" }, "symbol": { "type": "object", "example": "ARS" }, "shortName": { "type": "string", "example": "PESOS" }, "decimals": { "type": "number", "example": 2, "description": "Número de posiciones decimales de la moneda" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-07-02T13:28:24.041Z" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2024-07-02T13:28:24.041Z" } }, "required": [ "id", "name", "symbol", "shortName", "decimals", "createdAt", "updatedAt" ] }, "RequiredFieldsCamelCaseDto": { "type": "object", "properties": { "contact": { "type": "array", "description": "The contact of the payment", "items": { "type": "string", "enum": [ "email", "phone", "last_name", "first_name", "document.number", "document.type", "phone.number", "phone.country", "business_type", "bank.type" ] } }, "account": { "description": "The account of the payment", "type": "array", "items": { "type": "string" } }, "urls": { "description": "The urls of the payment", "type": "array", "items": { "type": "string" } } }, "required": [ "contact", "account" ] }, "PaymentMethodCamelCaseDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the payment", "example": "Pay with Pix" }, "method": { "type": "string", "description": "The method of the payment", "enum": [ "NEQUI", "PSE", "BANCOLOMBIA_QR", "PCOL", "BANCOLOMBIA_BNPL", "BANCOLOMBIA_TRANSFER", "DAVIPLATA", "SU_PLUS", "BITSO_TRANSFER", "KHIPU", "ETPAY", "PIX", "PIX_DYNAMIC", "QRI", "LIGO", "SIP_QR", "PIX_STATIC", "CLABE", "CARD_PAYMENT" ], "example": "PIX" }, "description": { "type": [ "string", "null" ], "description": "The description of the payment" }, "requiredFields": { "description": "The required fields of the payment", "allOf": [ { "$ref": "#/components/schemas/RequiredFieldsCamelCaseDto" } ] }, "responseType": { "type": "string", "description": "The response type of the payment", "enum": [ "QR", "PAYMENT_LINK", "PUSH_NOTIFICATION", "BANK_TRANSFER" ] }, "minAmount": { "type": "number", "description": "The minimum amount of the payment" }, "maxAmount": { "type": [ "number", "null" ], "description": "The maximum amount of the payment" }, "country": { "type": [ "string", "null" ], "description": "The country of the payment", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "currency": { "type": [ "string", "null" ], "description": "The currency of the payment", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ] } }, "required": [ "name", "method", "description", "requiredFields", "responseType", "minAmount", "maxAmount", "country", "currency" ] }, "PayinPaymentMethodsResponseCamelCaseDto": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ], "description": "The currency of the payment", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ] }, "country": { "type": [ "string", "null" ], "description": "The country of the payment", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "paymentMethods": { "description": "The payment methods of the payment", "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodCamelCaseDto" } } }, "required": [ "currency", "country", "paymentMethods" ] }, "PspVerifyCredentialsResponseDto": { "type": "object", "properties": { "card_enabled": { "type": "boolean", "description": "Indicates if the merchant has credentials configured", "example": true } }, "required": [ "card_enabled" ] }, "CreateTokenDto": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "API Key of the API user", "example": "your-api-key" }, "secret": { "type": "string", "description": "Secret of the API user", "example": "your-secret" } }, "required": [ "apiKey", "secret" ] }, "SignInResponseDto": { "type": "object", "properties": { "token": { "type": "string", "description": "JWT token for authentication", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }, "required": [ "token" ] }, "UserInfoResponseDto": { "type": "object", "properties": { "uid": { "type": "string", "description": "User ID", "example": "1234567890" }, "email": { "type": "string", "description": "User email", "example": "user@example.com" }, "emailVerified": { "type": "boolean" }, "name": { "type": "string" }, "picture": { "type": "string" }, "hasPasskey": { "type": "boolean" }, "hasDelegatedKey": { "type": "boolean" }, "hasWalletAccess": { "type": "boolean" }, "walletAccessPending": { "type": "boolean" } }, "required": [ "uid", "email" ] }, "CreateCredentialsDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Descriptive name to identify the purpose of the API credentials", "example": "API Key for Koywe integration" }, "roles": { "example": [ "MERCHANT_ADMIN", "MERCHANT_VIEWER" ], "description": "Array of role IDs or names to assign to the API credentials for the merchant. Must contain at least 1 role.", "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "name", "roles" ] }, "ApiCredentialsResponseDto": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Generated API Key for the merchant", "example": "f7d8e9c0-b1a2-3d4e-5f6g-7h8i9j0k1l2m" }, "secret": { "type": "string", "description": "Generated Secret for the merchant", "example": "2af81190b3a153r48a3df3a1eefcc386ca763b99fba53d39666751ffd4e2ae81" } }, "required": [ "apiKey", "secret" ] }, "ApiUserMfaEnrollPrepareRequestDto": { "type": "object", "properties": { "publicKey": { "type": "string", "description": "PEM-encoded P-256 PUBLIC KEY generated client-side by the API user" } }, "required": [ "publicKey" ] }, "ApiUserMfaEnrollPrepareResponseDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id that stores the prepared delegated MFA enrollment payload" }, "body": { "type": "string", "description": "Exact JSON request body that the root passkey holder must stamp" }, "mode": { "type": "string", "enum": [ "CREATE_USER", "ADD_API_KEY", "DELETE_API_KEY" ], "description": "Whether this request creates the signing user, adds a new API key to an existing one, or deletes an old API key" } }, "required": [ "pendingApprovalId", "body", "mode" ] }, "ApiUserMfaApprovalPrepareRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id created for delegated MFA enrollment" } }, "required": [ "pendingApprovalId" ] }, "SignedStampDto": { "type": "object", "properties": { "stampHeaderName": { "type": "string" }, "stampHeaderValue": { "type": "string" } }, "required": [ "stampHeaderName", "stampHeaderValue" ] }, "StampedRequestDto": { "type": "object", "properties": { "body": { "type": "string" }, "stamp": { "$ref": "#/components/schemas/SignedStampDto" } }, "required": [ "body", "stamp" ] }, "ApiUserMfaEnrollApproveRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id returned by prepare; used to load the exact stored enrollment payload" }, "stampedRequest": { "description": "The stamped provider request signed by the organization root passkey", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "pendingApprovalId", "stampedRequest" ] }, "ApiUserMfaCredentialResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "publicKey": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "revokedAt": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "id", "userId", "organizationId", "publicKey", "status", "createdAt", "revokedAt" ] }, "ApiUserMfaEnrollApproveResponseDto": { "type": "object", "properties": { "enrolled": { "type": "boolean" }, "credential": { "$ref": "#/components/schemas/ApiUserMfaCredentialResponseDto" } }, "required": [ "enrolled", "credential" ] }, "WalletSigningAccessResponseDto": { "type": "object", "properties": { "alreadyGranted": { "type": "boolean" }, "pendingApprovalId": { "type": "string" }, "result": { "type": "string" } }, "required": [ "alreadyGranted", "result" ] }, "WalletSigningAccessPrepareRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id returned by wallet access request or found in the approvals list" } }, "required": [ "pendingApprovalId" ] }, "WalletSigningAccessPrepareResponseDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id that stores the prepared wallet access grant payload" }, "body": { "type": "string", "description": "Exact JSON request body that the root passkey holder must stamp to grant wallet signing access" }, "mode": { "type": "string", "enum": [ "GRANT_ACCESS" ] } }, "required": [ "pendingApprovalId", "body", "mode" ] }, "WalletSigningAccessApproveRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id returned by wallet access request or prepare" }, "stampedRequest": { "description": "The stamped provider wallet-access grant request signed by the organization root passkey", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "pendingApprovalId", "stampedRequest" ] }, "WalletSigningAccessApproveResponseDto": { "type": "object", "properties": { "granted": { "type": "boolean" }, "pendingApprovalId": { "type": "string" } }, "required": [ "granted", "pendingApprovalId" ] }, "ApiUserMfaRevokeApproveRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "Pending approval id returned by delegated MFA revoke prepare" }, "stampedRequest": { "description": "The stamped provider revoke request signed by the organization root passkey", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "pendingApprovalId", "stampedRequest" ] }, "ApiUserMfaRevokeResponseDto": { "type": "object", "properties": { "revoked": { "type": "boolean" }, "credential": { "$ref": "#/components/schemas/ApiUserMfaCredentialResponseDto" } }, "required": [ "revoked", "credential" ] }, "CreatePosCredentialsDto": { "type": "object", "properties": { "alias": { "type": "string", "description": "Alias for the POS credentials", "example": "mypos" }, "password": { "type": "string", "description": "Password for the POS credentials", "example": "Str0ng!POS-Secret", "format": "password", "writeOnly": true, "minLength": 12 } }, "required": [ "alias", "password" ] }, "RedeemInvitationDto": { "type": "object", "properties": { "token": { "type": "string", "example": "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b", "description": "The unique invitation token received by the user" } }, "required": [ "token" ] }, "InvitedByUserDetailsDto": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user who sent the invitation" }, "name": { "type": "string", "description": "Name of the user who sent the invitation" } }, "required": [ "id", "name" ] }, "RedeemedMerchantDetailsDto": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the merchant" }, "name": { "type": "string", "description": "Name of the merchant" }, "logoUrl": { "type": [ "string", "null" ], "description": "Logo URL of the merchant" } }, "required": [ "id", "name", "logoUrl" ] }, "InvitationRedeemedDto": { "type": "object", "properties": { "invitedByUser": { "$ref": "#/components/schemas/InvitedByUserDetailsDto" }, "grantedRoles": { "description": "Names of the roles granted to the user for the merchant", "type": "array", "items": { "type": "string" } }, "merchant": { "$ref": "#/components/schemas/RedeemedMerchantDetailsDto" } }, "required": [ "invitedByUser", "grantedRoles", "merchant" ] }, "CheckInvitationStatusDto": { "type": "object", "properties": { "token": { "type": "string", "example": "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b", "description": "The unique invitation token to check" } }, "required": [ "token" ] }, "InvitationStatusResponseDto": { "type": "object", "properties": { "isExistingUser": { "type": "boolean", "example": true, "description": "Whether the invitation is for an existing user (true) or new user (false)" }, "email": { "type": "string", "example": "user@example.com", "description": "Email address associated with the invitation" }, "invitationType": { "type": "string", "example": "MERCHANT", "description": "Type of invitation: MERCHANT or ORGANIZATION", "enum": [ "MERCHANT", "ORGANIZATION" ] } }, "required": [ "isExistingUser", "email", "invitationType" ] }, "RotateApiSecretResponseDto": { "type": "object", "properties": { "secret": { "type": "string", "description": "The newly generated secret for the API credentials", "example": "2af81190b3a153r48a3df3a1eefcc386ca763b99fba53d39666751ffd4e2ae81" } }, "required": [ "secret" ] }, "ForgotPasswordDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the user requesting password reset.", "example": "user@example.com" } }, "required": [ "email" ] }, "SendVerificationEmailRequestDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the user requesting email verification.", "example": "user@example.com" } }, "required": [ "email" ] }, "DepositAccountInfoResponseDto": { "type": "object", "properties": { "accountType": { "type": "string", "enum": [ "VIRTUAL", "FIXED" ], "example": "VIRTUAL", "description": "Type of account (virtual or fixed)" }, "country": { "type": "string", "example": "AR", "description": "Two-letter country code" }, "countryName": { "type": "string", "example": "Argentina", "description": "Country name" }, "currency": { "type": "string", "example": "ARS", "description": "Currency code" }, "currencyName": { "type": "string", "example": "Peso Argentino", "description": "Currency name" }, "accountDetails": { "type": "object", "description": "Account-specific details (structure varies by accountType)" } }, "required": [ "accountType", "country", "countryName", "currency", "currencyName", "accountDetails" ] }, "ContactDocumentCreationDto": { "type": "object", "properties": { "documentType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "CUIT", "CNPJ", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER" ], "example": "DNI", "description": "Document type from AllDocumentType enum" }, "documentNumber": { "type": "string", "example": "123456789", "description": "Document number" }, "isDefault": { "type": "boolean", "example": true, "description": "Whether this is the default document for the contact", "default": false }, "isCompany": { "type": "boolean", "example": false, "description": "Whether this is a company document", "default": false } }, "required": [ "documentType", "documentNumber" ] }, "ContactCreationDto": { "type": "object", "properties": { "countrySymbol": { "type": "string", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "example": "AR", "description": "Country symbol of the contact. Must be one of:\n- AR (Argentina)\n- CL (Chile)\n- BR (Brazil)\n- CO (Colombia)\n- MX (Mexico)\n- PE (Peru)\n- US (United States)" }, "externalId": { "type": "string", "example": "ext_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "john.doe@example.com", "description": "Contact email (optional)" }, "phone": { "type": "string", "example": "+54116644624", "description": "Contact phone number (optional)" }, "addressLine1": { "type": "string", "example": "123 Main Street" }, "addressLine2": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "postalCode": { "type": "string", "example": "10001" }, "businessType": { "type": "string", "enum": [ "PERSON", "COMPANY", "PROVIDER", "GOVERNMENT", "NON_PROFIT", "OTHER" ], "example": "PERSON", "description": "Business type of the contact. Allowed values: PERSON, COMPANY, PROVIDER, GOVERNMENT, NON_PROFIT, OTHER. Must match the provided document type" }, "taxIdType": { "type": "string", "enum": [ "RUT", "CUIT", "CNPJ", "RFC", "RUC", "NIT", "EIN", "VAT", "OTHER" ], "example": "CUIT", "description": "DEPRECATED: Use documentType instead. If provided, taxIdNumber must also be included.", "deprecated": true }, "taxIdNumber": { "type": "string", "example": "123456789", "description": "DEPRECATED: Use documentNumber instead. Required if taxIdType is provided.", "deprecated": true }, "documentType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": "DNI", "description": "If provided, documentNumber must also be included" }, "documentNumber": { "type": "string", "example": "123456789", "description": "Required if documentType is provided" }, "externalBillingId": { "type": "number", "example": 123456789 }, "type": { "type": "string", "enum": [ "PERSON", "BUSINESS", "GOVERNMENT", "NGO", "FOREIGN" ], "example": "PERSON", "description": "Contact type determined by document type and business type" }, "stateId": { "type": "string", "example": "st_a627a569-51c4-4fc4-ace6-a43482f1b08b", "description": "ID of the state/province/region" }, "countyId": { "type": "string", "example": "cnt_a627a569-51c4-4fc4-ace6-a43482f1b08b", "description": "ID of the county/district/municipality" }, "dateOfBirth": { "type": "string", "example": "1990-01-15", "description": "Date of birth in ISO format (YYYY-MM-DD). Optional for all countries except Hong Kong." }, "documentExpirationDate": { "type": "string", "example": "2030-12-31", "description": "Document expiration date in ISO format (YYYY-MM-DD). Optional for all countries except Hong Kong." }, "nationalityCountrySymbol": { "type": "string", "example": "HK", "description": "Nationality country code (ISO 3166-1 alpha-2). Will be resolved to nationalityCountryId.", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality (reference to Countries table). Auto-populated from nationalityCountrySymbol." }, "documents": { "description": "Array of documents for the contact. If provided, only one can have isDefault=true. If only one document is provided, it will automatically be set as default.", "example": [ { "documentType": "DNI", "documentNumber": "12345678", "isDefault": true, "isCompany": false } ], "type": "array", "items": { "$ref": "#/components/schemas/ContactDocumentCreationDto" } } }, "required": [ "countrySymbol", "firstName", "businessType", "type" ] }, "ContactAddressResponseDto": { "type": "object", "properties": { "addressLine1": { "type": "string", "example": "San Martín 123" }, "addressLine2": { "type": "string", "example": "Belgrano 222" }, "city": { "type": "string", "example": "CABA" }, "state": { "type": "string", "example": "Buenos Aires" }, "postalCode": { "type": "string", "example": "1419" }, "stateId": { "type": "string", "example": "st_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "countyId": { "type": "string", "example": "cnt_a627a569-51c4-4fc4-ace6-a43482f1b08b" } }, "required": [ "addressLine1", "addressLine2", "city", "state", "postalCode", "stateId", "countyId" ] }, "ContactTaxResponseDto": { "type": "object", "properties": { "taxIdType": { "type": "string", "example": "DNI", "deprecated": true }, "taxIdNumber": { "type": "string", "example": "123456789", "deprecated": true } }, "required": [ "taxIdType", "taxIdNumber" ] }, "ContactDocumentResponseDto": { "type": "object", "properties": { "documentType": { "type": "string", "example": "DNI" }, "documentNumber": { "type": "string", "example": "123456789" } }, "required": [ "documentType", "documentNumber" ] }, "ContactDocumentItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "cdoc_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "documentType": { "type": "string", "example": "DNI" }, "documentNumber": { "type": "string", "example": "123456789" }, "isDefault": { "type": "boolean", "example": true }, "isCompany": { "type": "boolean", "example": false } }, "required": [ "id", "documentType", "documentNumber", "isDefault", "isCompany" ] }, "ContactResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "con_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "countrySymbol": { "type": "string", "example": "AR" }, "merchantId": { "type": "string", "example": "mer_84b8b218-2777-4e7f-863e-7d0601ac289f" }, "firstName": { "type": "string", "example": "Mariano" }, "lastName": { "type": "string", "example": "Romero" }, "email": { "type": "string", "example": "mariano.romero@row.com" }, "phone": { "type": "string", "example": "0116644624" }, "address": { "$ref": "#/components/schemas/ContactAddressResponseDto" }, "businessType": { "type": "string", "example": "PERSON" }, "tax": { "$ref": "#/components/schemas/ContactTaxResponseDto" }, "document": { "$ref": "#/components/schemas/ContactDocumentResponseDto" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-09-03T15:47:03.175Z" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2024-09-03T15:47:03.175Z" }, "externalId": { "type": "string", "example": "ext_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "documents": { "description": "Array of contact documents", "example": [ { "id": "cdoc_a627a569-51c4-4fc4-ace6-a43482f1b08b", "documentType": "DNI", "documentNumber": "12345678", "isDefault": true, "isCompany": false, "isDeleted": false } ], "type": "array", "items": { "$ref": "#/components/schemas/ContactDocumentItemResponseDto" } }, "dateOfBirth": { "format": "date-time", "type": "string", "example": "1990-01-15T00:00:00.000Z", "description": "Date of birth" }, "documentExpirationDate": { "format": "date-time", "type": "string", "example": "2030-12-31T00:00:00.000Z", "description": "Document expiration date" }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality" }, "nationalityCountry": { "type": "object", "description": "Nationality country details" } }, "required": [ "id", "countrySymbol", "merchantId", "firstName", "lastName", "email", "phone", "address", "businessType", "tax", "document", "createdAt", "updatedAt", "externalId", "documents" ] }, "PaginationMetadataDto": { "type": "object", "properties": { "current": { "type": "number", "description": "Current page number", "example": 1 }, "next": { "type": [ "number", "null" ], "description": "Next page number, null if there is no next page", "example": 2 }, "previous": { "type": [ "number", "null" ], "description": "Previous page number, null if there is no previous page", "example": null }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 }, "totalCount": { "type": "number", "description": "Total number of items", "example": 50 }, "pageSize": { "type": "number", "description": "Number of items per page", "example": 10 }, "sort": { "type": "string", "description": "Sort order (asc or desc)", "example": "desc" } }, "required": [ "current", "next", "previous", "totalPages", "totalCount", "pageSize", "sort" ] }, "PaginatedContactsResponseDto": { "type": "object", "properties": { "contacts": { "description": "Array of contacts", "type": "array", "items": { "$ref": "#/components/schemas/ContactResponseDto" } }, "pagination": { "description": "Pagination metadata", "allOf": [ { "$ref": "#/components/schemas/PaginationMetadataDto" } ] } }, "required": [ "contacts", "pagination" ] }, "ContactUpdateDto": { "type": "object", "properties": { "countrySymbol": { "type": "string", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "example": "AR", "description": "Country symbol of the contact. Must be one of:\n- AR (Argentina)\n- CL (Chile)\n- BR (Brazil)\n- CO (Colombia)\n- MX (Mexico)\n- PE (Peru)\n- US (United States)" }, "externalId": { "type": "string", "example": "ext_a627a569-51c4-4fc4-ace6-a43482f1b08b" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "email": { "type": "string", "example": "john.doe@example.com", "description": "Contact email (optional)" }, "phone": { "type": "string", "example": "+54116644624", "description": "Contact phone number (optional)" }, "addressLine1": { "type": "string", "example": "123 Main Street" }, "addressLine2": { "type": "string", "example": "Apt 4B" }, "city": { "type": "string", "example": "New York" }, "state": { "type": "string", "example": "NY" }, "postalCode": { "type": "string", "example": "10001" }, "businessType": { "type": "string", "enum": [ "PERSON", "COMPANY", "PROVIDER", "GOVERNMENT", "NON_PROFIT", "OTHER" ], "example": "PERSON", "description": "Business type of the contact. Allowed values: PERSON, COMPANY, PROVIDER, GOVERNMENT, NON_PROFIT, OTHER. Must match the provided document type" }, "taxIdType": { "type": "string", "enum": [ "RUT", "CUIT", "CNPJ", "RFC", "RUC", "NIT", "EIN", "VAT", "OTHER" ], "example": "CUIT", "description": "DEPRECATED: Use documentType instead. If provided, taxIdNumber must also be included.", "deprecated": true }, "taxIdNumber": { "type": "string", "example": "123456789", "description": "DEPRECATED: Use documentNumber instead. Required if taxIdType is provided.", "deprecated": true }, "documentType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": "DNI", "description": "If provided, documentNumber must also be included" }, "documentNumber": { "type": "string", "example": "123456789", "description": "Required if documentType is provided" }, "externalBillingId": { "type": "number", "example": 123456789 }, "type": { "type": "string", "enum": [ "PERSON", "BUSINESS", "GOVERNMENT", "NGO", "FOREIGN" ], "example": "PERSON", "description": "Contact type determined by document type and business type" }, "stateId": { "type": "string", "example": "st_a627a569-51c4-4fc4-ace6-a43482f1b08b", "description": "ID of the state/province/region" }, "countyId": { "type": "string", "example": "cnt_a627a569-51c4-4fc4-ace6-a43482f1b08b", "description": "ID of the county/district/municipality" }, "dateOfBirth": { "type": "string", "example": "1990-01-15", "description": "Date of birth in ISO format (YYYY-MM-DD). Optional for all countries except Hong Kong." }, "documentExpirationDate": { "type": "string", "example": "2030-12-31", "description": "Document expiration date in ISO format (YYYY-MM-DD). Optional for all countries except Hong Kong." }, "nationalityCountrySymbol": { "type": "string", "example": "HK", "description": "Nationality country code (ISO 3166-1 alpha-2). Will be resolved to nationalityCountryId.", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality (reference to Countries table). Auto-populated from nationalityCountrySymbol." }, "documents": { "description": "Array of documents for the contact. If provided, only one can have isDefault=true. If only one document is provided, it will automatically be set as default.", "example": [ { "documentType": "DNI", "documentNumber": "12345678", "isDefault": true, "isCompany": false } ], "type": "array", "items": { "$ref": "#/components/schemas/ContactDocumentCreationDto" } } } }, "ContactDocumentDeleteDto": { "type": "object", "properties": { "documents": { "example": [ "cdoc_a627a569-51c4-4fc4-ace6-a43482f1b08b", "cdoc_b627a569-51c4-4fc4-ace6-a43482f1b08c" ], "description": "Array of document IDs to delete. Contact must have at least one document remaining after deletion.", "type": "array", "items": { "type": "string" } } }, "required": [ "documents" ] }, "BankAccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_6ead3cb5-e87f-4756-8389-8ad2f56757d0" }, "name": { "type": "string", "example": "Banking of the Corp" }, "entity": { "type": "string", "example": "Citibank NA" }, "kind": { "type": "string", "example": "bank", "enum": [ "BANK", "CRYPTO", "CASH", "ACQUIRER", "ACQUIRER_VIRTUAL" ] }, "isVirtual": { "type": "boolean", "example": false }, "address": { "type": "string", "example": "0x123..." }, "network": { "type": "string", "example": "ethereum" }, "type": { "type": "string", "example": "SAVINGS", "enum": [ "SAVINGS", "CHECKING", "VIRTUAL" ] }, "accountNumber": { "type": "string", "example": "012342134123" }, "routingNumber": { "type": "string", "example": "123456789" }, "countryId": { "type": "string", "example": "ctry_c7168583-0eeb-49b8-8c9b-0bffcf954fef" }, "countryCode": { "type": "string", "example": "AR", "description": "Two-letter ISO country code" }, "currencyId": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "currencyCode": { "type": "string", "example": "ARS", "description": "Currency symbol" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-07-01T22:40:22.003Z" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2024-07-01T22:40:22.003Z" }, "isDefault": { "type": "boolean", "example": false }, "isTracked": { "type": "boolean", "example": false }, "merchantId": { "type": "string", "example": "mrc_31352afb-ce3a-4b7f-963d-b2512c646400" }, "contactId": { "type": "string", "example": "con_31352afb-ce3a-4b7f-963d-b2512c646400" }, "pendingApprovalId": { "type": "string", "example": "ppa_31352afb-ce3a-4b7f-963d-b2512c646400", "description": "Present when account creation requires policy approval. The account is not yet created." } }, "required": [ "id", "name", "entity", "kind", "isVirtual", "address", "network", "type", "accountNumber", "routingNumber", "countryId", "currencyId", "currencyCode", "createdAt", "updatedAt", "isDefault", "isTracked", "merchantId", "contactId" ] }, "BankAccountCreateDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Banking of the Corp" }, "entity": { "type": "string", "example": "CITIBANK_NA", "description": "Bank entity code. Optional for AR, MX, PE, BO, BR, US (auto-deduced). Required for CL, CO." }, "kind": { "type": "string", "example": "bank", "enum": [ "BANK", "CRYPTO", "CASH", "ACQUIRER", "ACQUIRER_VIRTUAL" ] }, "isVirtual": { "type": "boolean", "example": false, "description": "Whether this is a virtual account. Optional for all account types. Defaults to false if not provided." }, "address": { "type": "string", "example": "0x123..." }, "network": { "type": "string", "example": "ETHEREUM", "enum": [ "ETHEREUM", "POLYGON", "SOLANA", "TRON", "BSC", "BITCOIN", "BASE", "ALGORAND" ], "description": "Blockchain network. Required for crypto accounts (kind=CRYPTO)." }, "type": { "type": "string", "example": "SAVINGS", "enum": [ "SAVINGS", "CHECKING", "VIRTUAL" ], "description": "Account type (SAVINGS, CHECKING, VIRTUAL). Optional for all account types. Defaults to VIRTUAL if not provided." }, "accountNumber": { "type": "string", "example": "012342134-123" }, "routingNumber": { "type": "string", "example": "123456789" }, "isDefault": { "type": "boolean", "example": true }, "isTracked": { "type": "boolean", "example": false, "description": "Whether this account is tracked for balance monitoring. Optional for all account types. Defaults to false if not provided." }, "countrySymbol": { "type": "string", "example": "CL", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "Country code. Required for fiat accounts (kind=BANK), optional/ignored for crypto accounts (kind=CRYPTO)." }, "currencySymbol": { "type": "string", "example": "CLP", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ] } }, "required": [ "name", "kind", "address", "network", "accountNumber", "routingNumber", "isDefault", "currencySymbol" ] }, "HttpException": { "type": "object", "properties": {} }, "ConfirmBankAccountMfaRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "example": "ppa_31352afb-ce3a-4b7f-963d-b2512c646400", "description": "Pending approval ID for the bank account creation awaiting requester MFA." } }, "required": [ "pendingApprovalId" ] }, "BankAccountUpdateDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Banking of the Corp" }, "entity": { "type": "string", "example": "Citibank NA" } } }, "GlobalFeatureFlagResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "gff_onramp" }, "flagCode": { "type": "string", "example": "ONRAMP_ENABLED" }, "isActive": { "type": "boolean", "example": true }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id", "flagCode", "isActive", "createdAt", "updatedAt" ] }, "GlobalFeatureFlagsListResponseDto": { "type": "object", "properties": { "featureFlags": { "description": "List of global feature flags", "type": "array", "items": { "$ref": "#/components/schemas/GlobalFeatureFlagResponseDto" } }, "flagsMap": { "type": "object", "example": { "ONRAMP_ENABLED": true, "OFFRAMP_ENABLED": true }, "description": "Global feature flags as a key-value map for quick lookup" } }, "required": [ "featureFlags", "flagsMap" ] }, "CreateMerchantProfileDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Galactic Republic Trading" }, "address": { "type": "string", "example": "123 Main St", "description": "Address Line 1" }, "addressLine2": { "type": "string", "example": "Suite 100", "description": "Address Line 2" }, "city": { "type": "string", "example": "Springfield", "description": "City" }, "postalCode": { "type": "string", "example": "90210", "description": "Postal Code" }, "stateId": { "type": "string", "example": "st_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "State ID" }, "countyId": { "type": "string", "example": "cnt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "County ID" }, "taxIdType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": "RUC" }, "taxIdNumber": { "type": "string", "example": "123456789" }, "description": { "type": "string", "example": "1234 Main St, Coruscant" }, "email": { "type": "string", "example": "galactic.republic@row.com" }, "phone": { "type": "string", "example": "1234567890" }, "url": { "type": "string", "example": "https://galacticrepublic.com" }, "slug": { "type": "string", "example": "republic" }, "supportEmail": { "type": "string", "example": "galactic.republic@support.com" }, "supportPhone": { "type": "string", "example": "1234567890" }, "supportUrl": { "type": "string", "example": "https://galacticrepublic.com/support" }, "dateOfBirth": { "type": "string", "example": "1990-01-15", "description": "Date of birth (YYYY-MM-DD)" }, "nationalityCountrySymbol": { "type": "string", "example": "HK", "description": "Nationality country code (ISO 3166-1 alpha-2). Will be resolved to nationalityCountryId.", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality (reference to Countries table). Auto-populated from nationalityCountrySymbol." } }, "required": [ "name", "address", "taxIdType", "taxIdNumber", "slug", "supportEmail" ] }, "CreateMerchantSettingsBrandingDto": { "type": "object", "properties": { "icon": { "type": "string", "example": "https://galacticrepublic.com/icon" }, "logo": { "type": "string", "example": "https://galacticrepublic.com/logo" }, "primaryColor": { "type": "string", "example": "#000000" }, "secondaryColor": { "type": "string", "example": "#FFFFFF" } } }, "CreateMerchantSettingsDashboardDto": { "type": "object", "properties": { "displayName": { "type": "string", "example": "Galactic Republic Trading" }, "timezone": { "type": "string", "example": "America/Argentina/Buenos_Aires" } } }, "CreateMerchantSettingsDto": { "type": "object", "properties": { "branding": { "$ref": "#/components/schemas/CreateMerchantSettingsBrandingDto" }, "dashboard": { "$ref": "#/components/schemas/CreateMerchantSettingsDashboardDto" }, "isCreditLine": { "type": "boolean", "example": false, "description": "Whether this merchant has a credit line. Defaults to false." } } }, "CreateMerchantBillingDto": { "type": "object", "properties": { "roundingType": { "type": "string", "enum": [ "NET", "GROSS" ], "example": "NET", "description": "Billing rounding type for the merchant. Defaults to NET if not specified." } } }, "CreateMerchantDto": { "type": "object", "properties": { "countryId": { "type": "string", "example": "ctry_84b8b218-2777-4e7f-863e-7d0601ac289f" }, "profile": { "$ref": "#/components/schemas/CreateMerchantProfileDto" }, "defaultCurrencyId": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "settings": { "$ref": "#/components/schemas/CreateMerchantSettingsDto" }, "billing": { "description": "Billing configuration for the merchant", "allOf": [ { "$ref": "#/components/schemas/CreateMerchantBillingDto" } ] } }, "required": [ "countryId", "profile" ] }, "StateDto": { "type": "object", "properties": { "id": { "type": "string", "description": "State ID" }, "name": { "type": "string", "description": "State name" }, "code": { "type": "string", "description": "State code (e.g., ISO 3166-2)" }, "countryId": { "type": "string", "description": "Country ID for this state" } }, "required": [ "id", "name" ] }, "CountyDto": { "type": "object", "properties": { "id": { "type": "string", "description": "County ID" }, "name": { "type": "string", "description": "County name" }, "code": { "type": "string", "description": "County code" }, "stateId": { "type": "string", "description": "State ID for this county" } }, "required": [ "id", "name" ] }, "CurrencyDto": { "type": "object", "properties": {} }, "CountryDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fullName": { "type": [ "string", "null" ] }, "Currency": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/CurrencyDto" } ] }, { "type": "null" } ] }, "twoLetterIso": { "type": "object" }, "threeLetterIso": { "type": "object" }, "operationalStatus": { "type": "object" } }, "required": [ "id", "name", "fullName", "Currency", "twoLetterIso", "threeLetterIso", "operationalStatus" ] }, "MerchantProfileResponseDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Galactic Republic Trading" }, "description": { "type": "string", "example": "1234 Main St, Coruscant" }, "address": { "type": "string", "example": "1234 Main St, Coruscant", "description": "Address Line 1" }, "addressLine2": { "type": "string", "example": "Suite 100", "description": "Address Line 2" }, "city": { "type": "string", "example": "Springfield", "description": "City" }, "postalCode": { "type": "string", "example": "90210", "description": "Postal Code" }, "state": { "type": "string", "example": "California", "description": "State name", "deprecated": true }, "stateId": { "type": "string", "example": "st_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "State ID" }, "State": { "$ref": "#/components/schemas/StateDto" }, "countyId": { "type": "string", "example": "cnt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "County ID" }, "County": { "$ref": "#/components/schemas/CountyDto" }, "Country": { "$ref": "#/components/schemas/CountryDto" }, "email": { "type": "string", "example": "galactic.republic@row.com" }, "phone": { "type": "string", "example": "1234567890" }, "url": { "type": "string", "example": "https://galacticrepublic.com" }, "supportEmail": { "type": "string", "example": "galacticrepublic" }, "supportPhone": { "type": "string", "example": "1234567890" }, "supportUrl": { "type": "string", "example": "https://galacticrepublic.com/support" }, "taxIdType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": "CUIT" }, "taxIdNumber": { "type": "string", "example": "123456789" }, "dateOfBirth": { "format": "date-time", "type": "string", "example": "1990-01-15T00:00:00.000Z", "description": "Date of birth or company incorporation date" }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality" }, "nationalityCountry": { "type": "object", "description": "Nationality country details" } }, "required": [ "name", "description", "address", "email", "phone", "url", "supportEmail", "supportPhone", "supportUrl", "taxIdType", "taxIdNumber" ] }, "MerchantCapabilitiesResponseDto": { "type": "object", "properties": { "payments": { "type": "boolean", "example": true }, "collections": { "type": "boolean", "example": true } }, "required": [ "payments", "collections" ] }, "MerchantBillingResponseDto": { "type": "object", "properties": { "roundingType": { "type": "string", "enum": [ "NET", "GROSS" ], "example": "NET", "description": "Billing rounding type for the merchant" } }, "required": [ "roundingType" ] }, "MerchantBrandingResponseDto": { "type": "object", "properties": { "icon": { "type": [ "string", "null" ], "example": "https://example.com/icon.png" }, "logo": { "type": [ "string", "null" ], "example": "https://example.com/logo.png" }, "primaryColor": { "type": [ "string", "null" ], "example": "#FF0000" }, "secondaryColor": { "type": [ "string", "null" ], "example": "#00FF00" } } }, "MerchantResponseDto": { "type": "object", "properties": { "merchantId": { "type": "string", "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc" }, "slug": { "type": "string", "example": "republic" }, "profile": { "$ref": "#/components/schemas/MerchantProfileResponseDto" }, "businessType": { "type": "string", "example": "Galactic Republic Trading" }, "businessStructure": { "type": "string", "example": "Galactic Republic Trading" }, "capabilities": { "$ref": "#/components/schemas/MerchantCapabilitiesResponseDto" }, "chargesEnabled": { "type": "boolean", "example": true }, "countryId": { "type": "string", "example": "ctry_84b8b218-2777-4e7f-863e-7d0601ac289f" }, "Country": { "$ref": "#/components/schemas/CountryDto" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-07-01T22:40:22.003Z" }, "defaultCurrencyId": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "kybComplete": { "type": "boolean", "example": true }, "disabled": { "type": "boolean", "example": true }, "disabledReason": { "type": "string", "example": "N/D" }, "billing": { "description": "Billing configuration for the merchant", "allOf": [ { "$ref": "#/components/schemas/MerchantBillingResponseDto" } ] }, "branding": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/MerchantBrandingResponseDto" } ] }, { "type": "null" } ] }, "lifecycleStatus": { "type": "string", "enum": [ "DRAFT", "ENABLED_LIMITED", "KYB_REQUIRED", "ACTIVE", "KYB_RENEWAL_REQUIRED", "REJECTED" ], "example": "ENABLED_LIMITED", "description": "Current lifecycle state of the merchant" }, "canOperate": { "type": "boolean", "example": true, "description": "Whether the merchant can currently process transactions" }, "validTransitions": { "example": [ "KYB_REQUIRED" ], "description": "Valid next states the merchant can transition to", "type": "array", "items": { "type": "string" } } }, "required": [ "merchantId", "slug", "profile", "businessType", "businessStructure", "capabilities", "chargesEnabled", "countryId", "createdAt", "defaultCurrencyId", "kybComplete", "disabled", "disabledReason", "billing", "lifecycleStatus", "canOperate", "validTransitions" ] }, "UserMerchantCountryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Country ID" }, "name": { "type": "string", "description": "Country name" }, "twoLetterIso": { "type": "string", "description": "Country two letter ISO code" }, "threeLetterIso": { "type": "string", "description": "Country three letter ISO code" } }, "required": [ "id", "name", "twoLetterIso", "threeLetterIso" ] }, "PermissionDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Permission name" } }, "required": [ "name" ] }, "RoleWithPermissionsDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name" }, "permissions": { "description": "Permissions (name only) associated with this role", "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } }, "required": [ "name", "permissions" ] }, "UserMerchantBrandingDto": { "type": "object", "properties": { "icon": { "type": [ "string", "null" ], "description": "Merchant icon URL" }, "logo": { "type": [ "string", "null" ], "description": "Merchant logo URL" }, "primaryColor": { "type": [ "string", "null" ], "description": "Merchant primary color" }, "secondaryColor": { "type": [ "string", "null" ], "description": "Merchant secondary color" } } }, "UserMerchantDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Merchant ID" }, "name": { "type": "string", "description": "Merchant name" }, "url": { "type": "string", "description": "Merchant URL" }, "slug": { "type": "string", "description": "Merchant slug" }, "country": { "description": "Merchant country information", "allOf": [ { "$ref": "#/components/schemas/UserMerchantCountryDto" } ] }, "isCompany": { "type": "boolean", "description": "Merchant is company" }, "organizationId": { "type": [ "string", "null" ], "description": "Organization ID associated with the merchant" }, "organizationName": { "type": [ "string", "null" ], "description": "Organization name associated with the merchant" }, "roles": { "description": "Roles assigned to the user for this merchant", "type": "array", "items": { "$ref": "#/components/schemas/RoleWithPermissionsDto" } }, "branding": { "description": "Merchant branding information", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/UserMerchantBrandingDto" } ] }, { "type": "null" } ] }, "isCreditLine": { "type": [ "boolean", "null" ], "description": "Merchant is credit line" }, "maxCryptoUsdLimit": { "type": [ "number", "null" ], "description": "Merchant maximum crypto USD limit" } }, "required": [ "id", "name", "url", "slug", "country", "isCompany" ] }, "UpdateMerchantProfileDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Galactic Republic Trading" }, "address": { "type": "string", "example": "1234 Main St, Coruscant" }, "addressLine2": { "type": "string", "example": "Suite 100", "description": "Address Line 2" }, "city": { "type": "string", "example": "Springfield", "description": "City" }, "postalCode": { "type": "string", "example": "90210", "description": "Postal Code" }, "stateId": { "type": "string", "example": "st_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "State ID" }, "countyId": { "type": "string", "example": "cnt_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "County ID" }, "taxIdType": { "type": "string", "enum": [ "RUT", "DNI", "CUIL", "CPF", "CURP", "CED_CIU", "CED_EXT", "NIT", "NOP", "RC", "PP", "DIE", "EIN", "SSN", "RFC", "RUC", "VAT", "HKID", "CNID", "NRIC", "FIN", "OTHER", "CUIT", "CNPJ", "TXID" ], "example": "CUIT" }, "taxIdNumber": { "type": "string", "example": "123456789" }, "description": { "type": "string", "example": "1234 Main St, Coruscant" }, "email": { "type": "string", "example": "galactic.republic@row.com" }, "phone": { "type": "string", "example": "1234567890" }, "url": { "type": "string", "example": "https://galacticrepublic.com" }, "supportEmail": { "type": "string", "example": "galacticrepublic" }, "supportPhone": { "type": "string", "example": "1234567890" }, "supportUrl": { "type": "string", "example": "https://galacticrepublic.com/support" }, "dateOfBirth": { "type": "string", "example": "1990-01-15", "description": "Date of birth (YYYY-MM-DD)" }, "nationalityCountrySymbol": { "type": "string", "example": "HK", "description": "Nationality country code (ISO 3166-1 alpha-2). Will be resolved to nationalityCountryId.", "enum": [ "AR", "CL", "BR", "CO", "MX", "PE", "US", "BO", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BQ", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CM", "CN", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "nationalityCountryId": { "type": "string", "example": "ctry_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "description": "Country ID for nationality (reference to Countries table). Auto-populated from nationalityCountrySymbol." } }, "required": [ "name", "taxIdNumber" ] }, "UpdateMerchantSettingsBrandingDto": { "type": "object", "properties": { "icon": { "type": "string", "example": "https://galacticrepublic.com/icon" }, "logo": { "type": "string", "example": "https://galacticrepublic.com/logo" }, "primaryColor": { "type": "string", "example": "#000000" }, "secondaryColor": { "type": "string", "example": "#FFFFFF" } } }, "UpdateMerchantSettingsDashboardDto": { "type": "object", "properties": { "displayName": { "type": "string", "example": "Galactic Republic Trading" }, "timezone": { "type": "string", "example": "America/Argentina/Buenos_Aires" } } }, "UpdateMerchantSettingsDto": { "type": "object", "properties": { "branding": { "$ref": "#/components/schemas/UpdateMerchantSettingsBrandingDto" }, "dashboard": { "$ref": "#/components/schemas/UpdateMerchantSettingsDashboardDto" }, "isCreditLine": { "type": "boolean", "example": false, "description": "Whether this merchant has a credit line." } } }, "UpdateMerchantBillingDto": { "type": "object", "properties": { "roundingType": { "type": "string", "enum": [ "NET", "GROSS" ], "example": "NET", "description": "Billing rounding type for the merchant. Defaults to NET if not specified." } } }, "UpdateMerchantDto": { "type": "object", "properties": { "countryId": { "type": "string", "example": "ctry_84b8b218-2777-4e7f-863e-7d0601ac289f" }, "profile": { "$ref": "#/components/schemas/UpdateMerchantProfileDto" }, "defaultCurrencyId": { "type": "string", "example": "cur_8289dc19-e775-4c0c-a42a-e0da129e3b64" }, "settings": { "$ref": "#/components/schemas/UpdateMerchantSettingsDto" }, "billing": { "description": "Billing configuration for the merchant", "allOf": [ { "$ref": "#/components/schemas/UpdateMerchantBillingDto" } ] } }, "required": [ "profile" ] }, "RoleDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Role ID", "example": "k3r_operator" }, "name": { "type": "string", "description": "Role name", "example": "Operator" }, "description": { "type": [ "string", "null" ], "description": "Role description", "example": "Can manage security settings" }, "assignedAt": { "format": "date-time", "type": "string", "description": "Date when the role was assigned to the user", "example": "2024-01-15T10:30:00.000Z" }, "lastModified": { "format": "date-time", "type": "string", "description": "Date when the role assignment was last modified", "example": "2024-01-20T14:45:00.000Z" } }, "required": [ "id", "name", "description", "assignedAt", "lastModified" ] }, "MerchantUserResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "example": "k3u_abc123" }, "name": { "type": "string", "description": "User name", "example": "John Doe" }, "email": { "type": "string", "description": "User email", "example": "john@example.com" }, "isActive": { "type": "boolean", "description": "Indicates if the user is active", "example": true }, "lastModifiedRole": { "format": "date-time", "type": "string", "description": "Date of the most recent role modification for this user", "example": "2024-01-20T14:45:00.000Z" }, "roles": { "description": "User roles", "type": "array", "items": { "$ref": "#/components/schemas/RoleDto" } } }, "required": [ "id", "name", "email", "isActive", "lastModifiedRole", "roles" ] }, "PaginationResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page", "example": 1 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 }, "totalItems": { "type": "number", "description": "Total number of items", "example": 50 } }, "required": [ "page", "totalPages", "totalItems" ] }, "GetMerchantUsersResponseDto": { "type": "object", "properties": { "users": { "description": "List of users", "type": "array", "items": { "$ref": "#/components/schemas/MerchantUserResponseDto" } }, "pagination": { "description": "Pagination information", "allOf": [ { "$ref": "#/components/schemas/PaginationResponseDto" } ] } }, "required": [ "users", "pagination" ] }, "UpdateUserRolesRequestDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID", "example": "k3u_abc123" }, "rolesIds": { "description": "Array of role IDs to assign to the user", "example": [ "k3r_operator" ], "type": "array", "items": { "type": "string" } } }, "required": [ "userId", "rolesIds" ] }, "UpdateUserRolesResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "description": "Optional message providing more details about the operation", "example": "User roles updated successfully" } }, "required": [ "success" ] }, "MerchantFeaturesResponseDto": { "type": "object", "properties": { "merchantId": { "type": "string", "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc", "description": "Merchant identifier" }, "features": { "type": "object", "example": { "crypto_enabled": true, "payments_enabled": false, "billing_enabled": true }, "description": "Features configuration for the merchant" } }, "required": [ "merchantId", "features" ] }, "AccountBalanceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_6ead3cb5-e87f-4756-8389-8ad2f56757d0" }, "accountNumber": { "type": "string", "example": "012342134123", "description": "The account number of the bank account" }, "currency": { "type": "string", "example": "USD", "description": "The currency symbol of the account" }, "address": { "type": "string", "example": "0x123...", "description": "The blockchain address for crypto accounts" }, "network": { "type": "string", "example": "ethereum", "description": "The blockchain network for crypto accounts" }, "merchantId": { "type": "string", "example": "mrc_31352afb-ce3a-4b7f-963d-b2512c646400", "description": "The merchant ID if this is a merchant account" }, "contactId": { "type": "string", "example": "con_31352afb-ce3a-4b7f-963d-b2512c646400", "description": "The contact ID if this is a contact account" }, "balance": { "type": "string", "example": "1000.50", "description": "The current balance of the account" }, "balanceDate": { "type": "string", "example": "2024-07-01T22:40:22.003Z", "format": "date-time", "description": "The date when the balance was requested. This could be the current date or a historical date if requesting past balances." } }, "required": [ "id", "accountNumber", "currency", "balance", "balanceDate" ] }, "AccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "acc_123456789", "description": "Account ID" }, "name": { "type": "string", "example": "My Crypto Wallet", "description": "Account name" }, "entity": { "type": "string", "example": "Polygon", "description": "Entity or provider name" }, "kind": { "type": "string", "example": "crypto_wallet", "description": "Type of account (bank_account, crypto_wallet, virtual_account)" }, "isVirtual": { "type": "boolean", "example": false, "description": "Whether this is a virtual account" }, "accountNumber": { "type": [ "string", "null" ], "example": "0x742d35Cc6634C0532925a3b8D402dD81Ca8d8d8", "description": "Account number or wallet address" }, "type": { "type": "string", "example": "checking", "description": "Account type (checking, savings, etc.)" }, "network": { "type": [ "string", "null" ], "example": "polygon", "description": "Network for crypto accounts" }, "currencyId": { "type": "string", "example": "cur_123456789", "description": "Currency ID associated with this account" }, "currencySymbol": { "type": [ "string", "null" ], "example": "USDC", "description": "Currency symbol associated with this account" }, "address": { "type": [ "string", "null" ], "example": "0x452d042346864646736ebcc5fbd45c3cffca78eb", "description": "EVM address (Ethereum, Polygon, etc.)" } }, "required": [ "id", "name", "entity", "kind", "isVirtual", "type", "currencyId" ] }, "OrderResponseDao": { "type": "object", "properties": {} }, "DealResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "sdeal_123456789", "description": "K3 internal deal ID" }, "type": { "type": "string", "example": "ONRAMP", "enum": [ "ONRAMP", "OFFRAMP" ], "description": "Type of deal" }, "status": { "type": "string", "example": "PENDING", "enum": [ "PENDING", "COMPLETED", "CANCELED", "ON_HOLD" ], "description": "Current status of the deal" }, "pendingApprovalId": { "type": "string", "example": "ppa_123456789", "description": "Pending approval ID when the deal is ON_HOLD due to policy requirements." }, "originCurrencySymbol": { "type": "string", "example": "CLP", "description": "Origin currency symbol" }, "destinationCurrencySymbol": { "type": "string", "example": "USDC", "description": "Destination currency symbol" }, "amountIn": { "type": "number", "example": 97339, "description": "Amount in origin currency" }, "amountOut": { "type": "number", "example": 100, "description": "Amount in destination currency" }, "pendingAmount": { "type": "number", "example": 97339, "description": "Remaining amount to be executed" }, "quoteId": { "type": "string", "example": "quote_123456789", "description": "K3 quote ID used for this deal" }, "destinationAccountId": { "type": "string", "example": "bacc_destination_123", "description": "Destination account ID (crypto wallet)" }, "originAccountId": { "type": "string", "example": "bacc_origin_123", "description": "Origin account ID (fiat virtual account)" }, "destinationAccount": { "description": "Destination account details", "allOf": [ { "$ref": "#/components/schemas/AccountResponseDto" } ] }, "originAccount": { "description": "Origin account details", "allOf": [ { "$ref": "#/components/schemas/AccountResponseDto" } ] }, "contactId": { "type": [ "string", "null" ], "example": "con_contact_123", "description": "Contact ID" }, "dueDate": { "type": "string", "example": "2025-01-28T12:36:55.523Z", "description": "Deal expiration date" }, "createdAt": { "type": "string", "example": "2025-01-20T10:30:00.000Z", "description": "Deal creation timestamp" }, "updatedAt": { "type": "string", "example": "2025-01-20T10:30:00.000Z", "description": "Deal last update timestamp" }, "cryptoDestinationWallet": { "type": "string", "example": "0x742d35Cc6634C0532925a3b8D402dD81Ca8d8d8", "description": "Destination wallet address in offramp deals" }, "orders": { "description": "List of orders in this deal. When returned from the getOrders endpoint, this excludes the current order to avoid redundancy (shows only sibling orders).", "example": [ { "id": "ord_123456789", "type": "ONRAMP", "status": "COMPLETED", "amountIn": 100000, "amountOut": 100, "description": "ONRAMP_DEAL_sdeal_123456789", "externalId": "ondeal-1234567890", "createdAt": "2025-01-20T10:30:00.000Z", "updatedAt": "2025-01-20T10:35:00.000Z" } ], "type": "array", "items": { "$ref": "#/components/schemas/OrderResponseDao" } } }, "required": [ "id", "type", "status", "originCurrencySymbol", "destinationCurrencySymbol", "amountIn", "amountOut", "pendingAmount", "quoteId", "destinationAccountId", "originAccountId", "contactId", "dueDate", "createdAt", "updatedAt", "cryptoDestinationWallet", "orders" ] }, "ScheduledDealsResponseDto": { "type": "object", "properties": { "data": { "description": "List of scheduled deals", "type": "array", "items": { "$ref": "#/components/schemas/DealResponseDto" } }, "totalPages": { "type": "number", "description": "Total number of pages" } }, "required": [ "data", "totalPages" ] }, "KoyweDealInputDto": { "type": "object", "properties": { "quoteId": { "type": "string", "description": "Quote ID (required for all deal creation)", "example": "d15cf8fe-a5de-4cc7-a720-2c394f67d508" }, "destinationAccountId": { "type": "string", "description": "Destination account ID from K3 BankAccounts (crypto account)", "example": "acc_77a80cf9-496c-4d72-9c33-fca3c8d5bcfe" } }, "required": [ "quoteId", "destinationAccountId" ] }, "TransferScheduledDealInputDto": { "type": "object", "properties": { "scheduledDealId": { "type": "string", "description": "ID of the scheduled deal to transfer", "example": "89e266fa-be8b-47c3-94c3-9b5b6c3696a2" }, "destinationEmail": { "type": "string", "description": "Recipient email for the transfer", "example": "recipient@example.com" }, "destinationAddress": { "type": "string", "description": "Destination address for the new deal", "example": "0x742d35Cc6634C0532925a3b8D402dD81Ca8d8d8" }, "documentNumber": { "type": "string", "description": "Recipient document number", "example": "12345678-9" } }, "required": [ "scheduledDealId", "destinationEmail", "destinationAddress" ] }, "TransferScheduledDealResponseDto": { "type": "object", "properties": { "newDealId": { "type": "string", "description": "ID of the newly created deal", "example": "89e266fa-be8b-47c3-94c3-9b5b6c3696a2" }, "originEmail": { "type": "string", "description": "Origin email for the transfer", "example": "origin@example.com" }, "destinationEmail": { "type": "string", "description": "Destination email for the transfer", "example": "recipient@example.com" }, "pendingAmount": { "type": "number", "description": "Pending amount of the transferred deal", "example": 100 } }, "required": [ "newDealId", "originEmail", "destinationEmail", "pendingAmount" ] }, "OrganizationBalanceSummary": { "type": "object", "properties": { "totalsByCurrency": { "type": "object", "description": "Total balances per currency across all merchants. Keys are currency symbols, values are aggregated amounts.", "additionalProperties": { "type": "string" }, "example": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" } }, "totalInBaseCurrency": { "type": "string", "description": "Grand total balance converted to base currency. Sum of all merchants totals in base currency.", "example": "10399.80" }, "baseCurrency": { "type": "string", "description": "Base currency used for conversion", "example": "USD" }, "totalAccounts": { "type": "number", "description": "Total number of virtual accounts across all merchants", "example": 4 }, "currenciesCount": { "type": "number", "description": "Number of distinct currencies present in the organization", "example": 4 }, "lastUpdated": { "format": "date-time", "type": "string", "description": "Most recent balance date across all accounts in the organization", "example": "2025-11-02T18:30:00.000Z" } }, "required": [ "totalsByCurrency", "totalInBaseCurrency", "baseCurrency", "totalAccounts", "currenciesCount", "lastUpdated" ] }, "CurrencyConversionRate": { "type": "object", "properties": { "fromCurrency": { "type": "string", "description": "Source currency symbol (e.g., USD, EUR). Typically the base currency.", "example": "USD" }, "toCurrency": { "type": "string", "description": "Target currency symbol (e.g., CLP, COP, USDC). The currency being converted to.", "example": "CLP" }, "rate": { "type": "string", "description": "Exchange rate as string for precision. Represents how many units of toCurrency equals 1 unit of fromCurrency. Rates are shown as \"1 USD = X currency\" for better readability.", "example": "896.86098655" }, "timestamp": { "format": "date-time", "type": "string", "description": "Timestamp when the exchange rate was fetched", "example": "2025-11-02T18:30:45.123Z" } }, "required": [ "fromCurrency", "toCurrency", "rate", "timestamp" ] }, "OrganizationBalanceResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization unique identifier", "example": "org3_abc123def456" }, "organizationName": { "type": "string", "description": "Organization name", "example": "Acme Corporation" }, "requestedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the request was made", "example": "2025-11-02T18:30:45.123Z" }, "balanceDate": { "format": "date-time", "type": "string", "description": "Effective date for the balance data. Either the provided date parameter or current timestamp.", "example": "2025-11-02T18:30:00.000Z" }, "baseCurrency": { "type": "string", "description": "Base currency used for conversions throughout the response", "example": "USD" }, "merchantCount": { "type": "number", "description": "Total number of merchants included in the response", "example": 2 }, "summary": { "description": "Organization-wide aggregated summary across all merchants", "example": { "totalsByCurrency": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" }, "totalInBaseCurrency": "10399.80", "baseCurrency": "USD", "totalAccounts": 4, "currenciesCount": 4, "lastUpdated": "2025-11-02T18:30:00.000Z" }, "allOf": [ { "$ref": "#/components/schemas/OrganizationBalanceSummary" } ] }, "exchangeRates": { "description": "All exchange rates used for currency conversions. Provided for transparency and auditability. Rates are shown as \"1 USD = X currency\" for better readability.", "example": [ { "fromCurrency": "USD", "toCurrency": "CLP", "rate": "896.86098655", "timestamp": "2025-11-02T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "COP", "rate": "4065.04065041", "timestamp": "2025-11-02T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "USDC", "rate": "1.00020004", "timestamp": "2025-11-02T18:30:45.123Z" } ], "type": "array", "items": { "$ref": "#/components/schemas/CurrencyConversionRate" } } }, "required": [ "organizationId", "organizationName", "requestedAt", "balanceDate", "baseCurrency", "merchantCount", "summary", "exchangeRates" ] }, "CurrencyBalanceDetail": { "type": "object", "properties": { "originalAmount": { "type": "string", "description": "Original amount in the currency", "example": "10000000.00" }, "convertedAmount": { "type": "string", "description": "Amount converted to base currency", "example": "11150.00" }, "currency": { "type": "string", "description": "Currency code (ISO 4217 or crypto symbol)", "example": "CLP" } }, "required": [ "originalAmount", "convertedAmount", "currency" ] }, "MerchantSnapshotBalance": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Merchant unique identifier", "example": "mrc_def456abc789" }, "merchantName": { "type": "string", "description": "Merchant business name", "example": "Acme Store Chile" }, "totalInBaseCurrency": { "type": "string", "description": "Total balance for this merchant in base currency", "example": "11650.00" }, "currencyBreakdown": { "description": "Detailed breakdown per currency showing original and converted amounts", "example": [ { "currency": "CLP", "originalAmount": "10000000.00", "convertedAmount": "11150.00" }, { "currency": "USD", "originalAmount": "500.00", "convertedAmount": "500.00" } ], "type": "array", "items": { "$ref": "#/components/schemas/CurrencyBalanceDetail" } }, "accountCount": { "type": "number", "description": "Number of accounts for this merchant", "example": 2 } }, "required": [ "merchantId", "merchantName", "totalInBaseCurrency", "currencyBreakdown", "accountCount" ] }, "BalanceSnapshotDto": { "type": "object", "properties": { "timestamp": { "format": "date-time", "type": "string", "description": "Timestamp of this snapshot", "example": "2025-10-03T00:00:00.000Z" }, "totalInBaseCurrency": { "type": "string", "description": "Total organization balance in base currency at this point in time", "example": "9245.30" }, "totalsByCurrency": { "type": "object", "description": "Breakdown of balances per currency at this point in time", "additionalProperties": { "type": "string" }, "example": { "CLP": "4500000.00", "USD": "1150.00", "COP": "11000000.00", "USDC": "475.00" } }, "merchantCount": { "type": "number", "description": "Number of merchants included in this snapshot", "example": 2 }, "merchantBreakdown": { "description": "Per-merchant balance breakdown showing original amounts and USD equivalents. Only included when includeMerchantBreakdown=true query parameter is provided.", "example": [ { "merchantId": "mrc_def456abc789", "merchantName": "Acme Store Chile", "totalInBaseCurrency": "5572.65", "currencyBreakdown": [ { "currency": "CLP", "originalAmount": "4500000.00", "convertedAmount": "5022.50" }, { "currency": "USD", "originalAmount": "550.15", "convertedAmount": "550.15" } ], "accountCount": 2 }, { "merchantId": "mrc_ghi789jkl012", "merchantName": "Acme Store Colombia", "totalInBaseCurrency": "3672.65", "currencyBreakdown": [ { "currency": "COP", "originalAmount": "11000000.00", "convertedAmount": "2706.00" }, { "currency": "USDC", "originalAmount": "966.75", "convertedAmount": "966.65" } ], "accountCount": 2 } ], "type": "array", "items": { "$ref": "#/components/schemas/MerchantSnapshotBalance" } } }, "required": [ "timestamp", "totalInBaseCurrency", "totalsByCurrency", "merchantCount" ] }, "BalanceTrendDto": { "type": "object", "properties": { "percentageChange": { "type": "string", "description": "Percentage change from first to last snapshot. Positive values indicate growth.", "example": "+12.48" }, "direction": { "type": "string", "description": "Trend direction: \"up\" for growth, \"down\" for decline, \"stable\" for no significant change", "enum": [ "up", "down", "stable" ], "example": "up" } }, "required": [ "percentageChange", "direction" ] }, "OrganizationBalanceHistoryResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization unique identifier", "example": "org3_abc123def456" }, "organizationName": { "type": "string", "description": "Organization name", "example": "Acme Corporation" }, "requestedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the request was made", "example": "2025-11-02T18:30:45.123Z" }, "baseCurrency": { "type": "string", "description": "Base currency used for conversions", "example": "USD" }, "period": { "type": "string", "description": "Time period requested for historical data", "example": "30d" }, "interval": { "type": "string", "description": "Interval used for data points. Auto-selected based on period if not explicitly provided.", "example": "weekly" }, "snapshots": { "description": "Array of balance snapshots over time, ordered chronologically from oldest to newest. Each snapshot includes organization-wide totals. Per-merchant breakdown with original and converted amounts is only included when includeMerchantBreakdown=true query parameter is provided.", "example": [ { "timestamp": "2025-10-03T00:00:00.000Z", "totalInBaseCurrency": "9245.30", "totalsByCurrency": { "CLP": "4500000.00", "USD": "1150.00", "COP": "11000000.00", "USDC": "475.00" }, "merchantCount": 2, "merchantBreakdown": [ { "merchantId": "mrc_def456abc789", "merchantName": "Acme Store Chile", "totalInBaseCurrency": "6172.50", "currencyBreakdown": [ { "currency": "CLP", "originalAmount": "4500000.00", "convertedAmount": "5022.50" }, { "currency": "USD", "originalAmount": "1150.00", "convertedAmount": "1150.00" } ], "accountCount": 2 }, { "merchantId": "mrc_ghi789jkl012", "merchantName": "Acme Store Colombia", "totalInBaseCurrency": "3072.80", "currencyBreakdown": [ { "currency": "COP", "originalAmount": "11000000.00", "convertedAmount": "2706.00" }, { "currency": "USDC", "originalAmount": "475.00", "convertedAmount": "366.80" } ], "accountCount": 2 } ] }, { "timestamp": "2025-10-17T00:00:00.000Z", "totalInBaseCurrency": "10399.80", "totalsByCurrency": { "CLP": "5000000.00", "USD": "1250.50", "COP": "12500000.00", "USDC": "500.25" }, "merchantCount": 2, "merchantBreakdown": [ { "merchantId": "mrc_def456abc789", "merchantName": "Acme Store Chile", "totalInBaseCurrency": "6823.32", "currencyBreakdown": [ { "currency": "CLP", "originalAmount": "5000000.00", "convertedAmount": "5572.82" }, { "currency": "USD", "originalAmount": "1250.50", "convertedAmount": "1250.50" } ], "accountCount": 2 }, { "merchantId": "mrc_ghi789jkl012", "merchantName": "Acme Store Colombia", "totalInBaseCurrency": "3576.48", "currencyBreakdown": [ { "currency": "COP", "originalAmount": "12500000.00", "convertedAmount": "3075.00" }, { "currency": "USDC", "originalAmount": "500.25", "convertedAmount": "501.48" } ], "accountCount": 2 } ] } ], "type": "array", "items": { "$ref": "#/components/schemas/BalanceSnapshotDto" } }, "currentSummary": { "description": "Current (most recent) aggregated summary. Excluded when excludeToday=true for performance optimization.", "allOf": [ { "$ref": "#/components/schemas/OrganizationBalanceSummary" } ] }, "trend": { "description": "Trend analysis comparing first and last snapshots in the time period", "example": { "percentageChange": "+12.48", "direction": "up" }, "allOf": [ { "$ref": "#/components/schemas/BalanceTrendDto" } ] }, "exchangeRates": { "description": "All exchange rates used for currency conversions. Provided for transparency and auditability. Rates are shown as \"1 USD = X currency\" for better readability.", "example": [ { "fromCurrency": "USD", "toCurrency": "CLP", "rate": "896.86098655", "timestamp": "2025-11-02T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "COP", "rate": "4065.04065041", "timestamp": "2025-11-02T18:30:45.123Z" }, { "fromCurrency": "USD", "toCurrency": "USDC", "rate": "1.00020004", "timestamp": "2025-11-02T18:30:45.123Z" } ], "type": "array", "items": { "$ref": "#/components/schemas/CurrencyConversionRate" } } }, "required": [ "organizationId", "organizationName", "requestedAt", "baseCurrency", "period", "interval", "snapshots", "trend", "exchangeRates" ] }, "OrganizationDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isPartner": { "type": "boolean", "description": "Indicates if organization is a partner" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "isPartner", "createdAt", "updatedAt" ] }, "OrganizationRoleDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Role ID", "example": "k3r_admin" }, "name": { "type": "string", "description": "Role name", "example": "Admin" }, "description": { "type": [ "string", "null" ], "description": "Role description", "example": "Management of users and organizations" }, "assignedAt": { "format": "date-time", "type": "string", "description": "Date when the role was assigned to the user in the organization", "example": "2024-01-15T10:30:00.000Z" }, "lastModified": { "format": "date-time", "type": "string", "description": "Date when the role assignment was last modified", "example": "2024-01-20T14:45:00.000Z" } }, "required": [ "id", "name", "description", "assignedAt", "lastModified" ] }, "OrganizationUserResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID", "example": "k3u_abc123" }, "name": { "type": "string", "description": "User name", "example": "John Doe" }, "email": { "type": "string", "description": "User email", "example": "john@example.com" }, "isActive": { "type": "boolean", "description": "Indicates if the user is active", "example": true }, "lastModifiedRole": { "format": "date-time", "type": "string", "description": "Date of the most recent role modification for this user in the organization", "example": "2024-01-20T14:45:00.000Z" }, "roles": { "description": "User roles in the organization", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationRoleDto" } } }, "required": [ "id", "name", "email", "isActive", "lastModifiedRole", "roles" ] }, "GetOrganizationUsersResponseDto": { "type": "object", "properties": { "users": { "description": "List of users", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationUserResponseDto" } }, "pagination": { "description": "Pagination information", "allOf": [ { "$ref": "#/components/schemas/PaginationResponseDto" } ] } }, "required": [ "users", "pagination" ] }, "UpdateUserOrganizationRolesRequestDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID", "example": "k3u_abc123" }, "rolesIds": { "description": "Array of role IDs to assign to the user in the organization", "example": [ "k3r_admin" ], "type": "array", "items": { "type": "string" } } }, "required": [ "userId", "rolesIds" ] }, "UpdateUserOrganizationRolesResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "description": "Optional message providing more details about the operation", "example": "User organization roles updated successfully" } }, "required": [ "success" ] }, "OrganizationFeatureFlagItemDto": { "type": "object", "properties": { "id": { "type": "string", "example": "ffm_abc123-def456" }, "organizationId": { "type": "string", "example": "org_abc123" }, "merchantId": { "type": "string", "example": "mrc_abc123" }, "flagCode": { "type": "string", "example": "CRYPTO_ENABLED" }, "isActive": { "type": "boolean", "example": true }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id", "organizationId", "merchantId", "flagCode", "isActive", "createdAt", "updatedAt" ] }, "OrganizationFeatureFlagsResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "example": "org_abc123" }, "featureFlags": { "description": "All feature flag rows configured for the organization", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationFeatureFlagItemDto" } }, "flagsMap": { "type": "object", "example": { "CRYPTO_ENABLED": false }, "description": "Org-level feature summary (true if any merchant has the flag active)" }, "merchantsByFlag": { "type": "object", "example": { "CRYPTO_ENABLED": [ "mrc_abc123" ] }, "description": "Merchant IDs per flag where the flag is currently active" } }, "required": [ "organizationId", "featureFlags", "flagsMap", "merchantsByFlag" ] }, "CreateWebhookEndpointDto": { "type": "object", "properties": { "url": { "type": "string", "description": "Target URL to receive webhooks", "example": "https://example.com/webhooks" }, "name": { "type": "string", "description": "Display name", "maxLength": 128 }, "description": { "type": "string", "description": "Description", "maxLength": 512 }, "secret": { "type": "string", "description": "Endpoint secret (client-provided). Not returned by the API." } }, "required": [ "url", "secret" ] }, "WebhookEndpointResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "environment": { "type": "string", "enum": [ "local", "qa", "sandbox", "production" ] }, "isActive": { "type": "boolean" }, "isDeleted": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "url", "environment", "isActive", "isDeleted", "createdAt", "updatedAt" ] }, "RotateSecretDto": { "type": "object", "properties": { "secret": { "type": "string", "description": "New endpoint secret (client-provided). Not returned by the API." } }, "required": [ "secret" ] }, "PaginationDto": { "type": "object", "properties": { "current": { "type": "number", "example": 1 }, "next": { "type": "number", "example": null }, "previous": { "type": "number", "example": null }, "totalPages": { "type": "number", "example": 1, "default": 1 }, "totalCount": { "type": "number", "example": 1 }, "pageSize": { "type": "string", "example": 10 }, "sort": { "type": "string", "example": 1 } }, "required": [ "current", "next", "previous", "totalPages", "totalCount", "pageSize", "sort" ] }, "WebhookEventResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "merchantId": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "string" }, "occurredAt": { "format": "date-time", "type": "string" }, "payload": { "type": "string", "description": "Stringified JSON payload (redacted in read APIs)" }, "requestId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "type", "version", "occurredAt", "payload", "createdAt" ] }, "PaginatedWebhookEventsDto": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationDto" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventResponseDto" } } }, "required": [ "pagination", "events" ] }, "LeanTaskStatusDto": { "type": "object", "properties": { "deliveryStatus": { "type": "string", "description": "Delivery status" }, "retryCount": { "type": "number", "description": "Retry attempts performed" }, "lastRetryAt": { "format": "date-time", "type": "string", "description": "Timestamp of last retry" }, "lastStatusCode": { "type": "number", "description": "Status code of last attempt" }, "lastRespondedAt": { "format": "date-time", "type": "string", "description": "Timestamp when last attempt responded" } }, "required": [ "deliveryStatus", "retryCount" ] }, "WebhookEventDeliveryResponseDto": { "type": "object", "properties": { "endpointId": { "type": "string" }, "taskId": { "type": "string" }, "jobId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/LeanTaskStatusDto" } }, "required": [ "endpointId", "taskId", "jobId", "createdAt", "status" ] }, "ReplayEventRequestDto": { "type": "object", "properties": { "endpointId": { "type": "string", "description": "Endpoint id to replay to. If omitted, replay to all active endpoints." } } }, "PingEventRequestDto": { "type": "object", "properties": { "data": { "type": "object", "description": "Optional additional data to include in ping payload" } } }, "PolicyApprovalRequirementsDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ANY_OF", "ALL_OF", "THRESHOLD" ] }, "approvers": { "type": "array", "items": { "type": "string" } }, "threshold": { "type": "number" } }, "required": [ "mode", "approvers" ] }, "OrderPaymentExtraBankAccountDto": { "type": "object", "properties": { "name": { "type": "string", "example": "BANCOLOMBIA", "description": "Payment method extra information" } }, "required": [ "name" ] }, "PhoneDto": { "type": "object", "properties": { "countryCode": { "type": "string", "example": "+57", "description": "Country code" }, "number": { "type": "string", "example": "3178901234", "description": "Phone number" } }, "required": [ "countryCode", "number" ] }, "OrderPaymentExtraDto": { "type": "object", "properties": { "bankAccount": { "description": "Payment method extra information", "allOf": [ { "$ref": "#/components/schemas/OrderPaymentExtraBankAccountDto" } ] }, "phone": { "$ref": "#/components/schemas/PhoneDto" }, "email": { "type": "string", "format": "email" } }, "required": [ "bankAccount", "phone", "email" ] }, "OrderPaymentMethodDto": { "type": "object", "properties": { "method": { "type": "string", "example": "PSE", "description": "Payment method type (e.g., PSE, NEQUI, KHIPU)", "enum": [ "NEQUI", "PSE", "BANCOLOMBIA_QR", "PCOL", "BANCOLOMBIA_BNPL", "BANCOLOMBIA_TRANSFER", "DAVIPLATA", "SU_PLUS", "BITSO_TRANSFER", "KHIPU", "ETPAY", "PIX", "PIX_DYNAMIC", "QRI", "LIGO", "SIP_QR", "PIX_STATIC", "CLABE", "CARD_PAYMENT" ] }, "extra": { "$ref": "#/components/schemas/OrderPaymentExtraDto" } }, "required": [ "method", "extra" ] }, "OrderResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "ord_123456789", "description": "Unique order ID" }, "type": { "type": "string", "example": "PAYIN", "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "CRYPTO_PAYOUT", "PAYMENT_LINK", "INTER_MERCHANT_TRANSFER" ], "description": "Type of order" }, "destinationAccountId": { "type": "string", "example": "bank-account-123", "description": "Destination account ID (bank or wallet)" }, "originAccountId": { "type": [ "string", "null" ], "example": "bank-account-456", "description": "Origin account ID (bank or wallet)" }, "destinationMerchantId": { "type": "string", "description": "ID of the destination merchant (only for INTER_MERCHANT_TRANSFER)", "example": "mrc_b2c3d4e5-f6a7-8901-bcde-f23456789012" }, "destinationMerchantName": { "type": "string", "description": "Name of the destination merchant (only for INTER_MERCHANT_TRANSFER)", "example": "Sucursal Norte" }, "destinationAccount": { "description": "Destination account details", "allOf": [ { "$ref": "#/components/schemas/AccountResponseDto" } ] }, "originAccount": { "description": "Origin account details", "allOf": [ { "$ref": "#/components/schemas/AccountResponseDto" } ] }, "originCurrencySymbol": { "type": "string", "example": "COP", "description": "Origin currency symbol" }, "destinationCurrencySymbol": { "type": "string", "example": "COP", "description": "Destination currency symbol" }, "amountIn": { "type": "number", "example": 1000000, "description": "Amount in origin currency" }, "pendingApprovalId": { "type": "string", "description": "Pending approval ID when the order is ON_HOLD due to policy requirements.", "example": "ppa_123456789" }, "policyResult": { "type": "string", "description": "Policy evaluation result that led to the current order state.", "enum": [ "ALLOW", "REQUIRE_MFA", "REQUIRE_APPROVALS", "REQUIRE_MFA_AND_APPROVALS", "DENY" ] }, "approval": { "description": "Approval requirements returned by policy evaluation.", "allOf": [ { "$ref": "#/components/schemas/PolicyApprovalRequirementsDto" } ] }, "requiresSignature": { "type": "boolean", "description": "Whether the requester must complete the next signature step for this order.", "example": true }, "amountOut": { "type": "number", "example": 900000, "description": "Amount in destination currency" }, "dueDate": { "type": "string", "example": "2026-01-28T12:36:55.523694Z", "description": "Due date for payment links. If not provided during creation, defaults to 24 hours from order creation. Cannot exceed the maximum allowed lifetime." }, "description": { "type": "string", "example": "Payment for invoice #1234", "description": "Description of the order" }, "externalId": { "type": "string", "example": "payin-ext-001", "description": "External ID (idempotent identifier)" }, "paymentMethods": { "description": "Payment methods used", "example": [ { "method": "PSE", "extra": "BANCOLOMBIA" } ], "type": "array", "items": { "$ref": "#/components/schemas/OrderPaymentMethodDto" } }, "quoteId": { "type": "string", "example": "quote-123", "description": "Quote ID used for currency conversion" }, "contactId": { "type": "string", "example": "contact-123", "description": "Contact ID identifying the counterparty to whom this order is directed. This represents the entity on the other side of the transaction." }, "enforcedDocument": { "type": "string", "example": "45676946", "description": "National ID document (e.g. DNI, RUT, Cédula) that must be provided to complete the order" }, "sendEmail": { "type": "boolean", "example": true, "description": "Whether email notifications are enabled" }, "sendNotification": { "type": "boolean", "example": true, "description": "Whether in-app notifications are enabled" }, "sendWhatsapp": { "type": "boolean", "example": true, "description": "Whether WhatsApp notifications are enabled" }, "sendReminders": { "type": "boolean", "example": true, "description": "Whether order reminders are enabled" }, "providedAction": { "type": "string", "example": "https://checkout.row.com/order/123456789", "description": "Action URL or data provided to the user to complete the order, such as a QR code, payment link, or other actionable payment method" }, "providedActionType": { "type": "string", "example": "PAYMENT_LINK", "description": "Type of provided action", "enum": [ "QR", "PAYMENT_LINK", "PUSH_NOTIFICATION", "BANK_TRANSFER" ] }, "createdAt": { "type": "string", "example": "2025-01-15T10:30:00.000Z", "description": "Timestamp when the order was created" }, "status": { "type": "string", "example": "PENDING", "enum": [ "DRAFT", "PENDING", "PAID", "CANCELLED", "REFUND_REQUESTED", "COMPLETED", "PROCESSING", "FAILED", "REFUNDED", "EXPIRED", "ON_HOLD" ], "description": "Current status of the order" }, "errorCode": { "type": [ "string", "null" ], "example": "PSP00002", "description": "Internal error code when order fails" }, "errorMessage": { "type": [ "string", "null" ], "example": "The destination bank account number is invalid or does not exist", "description": "Human-readable error message when order fails" }, "transactionHash": { "type": [ "string", "null" ], "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "description": "Blockchain transaction hash (available after crypto transaction is confirmed)" }, "deal": { "description": "Associated deal information. Present when the order is part of a deal (ONRAMP/OFFRAMP).", "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/DealResponseDto" } ] }, { "type": "null" } ] } }, "required": [ "id", "type", "destinationAccountId", "originAccountId", "originCurrencySymbol", "destinationCurrencySymbol", "amountIn", "amountOut", "dueDate", "description", "externalId", "paymentMethods", "quoteId", "contactId", "enforcedDocument", "sendEmail", "sendNotification", "sendWhatsapp", "sendReminders", "providedAction", "providedActionType", "createdAt", "status", "errorCode", "errorMessage" ] }, "PaginationOrderDto": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationDto" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponseDto" } } }, "required": [ "pagination", "orders" ] }, "Decimal": { "type": "object", "properties": {} }, "OrderRequestDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "CRYPTO_PAYOUT", "PAYMENT_LINK", "INTER_MERCHANT_TRANSFER" ], "description": "Type of order", "example": "PAYIN" }, "network": { "type": "string", "enum": [ "ETHEREUM", "POLYGON", "SOLANA", "TRON", "BSC", "BITCOIN", "BASE", "ALGORAND" ], "description": "Blockchain network for crypto orders. Required for ONRAMP and OFFRAMP.", "example": "POLYGON" }, "destinationAccountId": { "type": "string", "example": "bank-account-123", "description": "Destination Account ID (bank account or wallet). Required for PAYOUT and ONRAMP. Optional for PAYIN, OFFRAMP, and PAYMENT_LINK (defaults to merchant virtual balance if omitted)." }, "destinationMerchantId": { "type": "string", "description": "ID of the destination merchant for INTER_MERCHANT_TRANSFER orders. Must belong to the same organization as the origin merchant.", "example": "mrc_b2c3d4e5-f6a7-8901-bcde-f23456789012" }, "originCurrencySymbol": { "type": "object", "example": "COP", "description": "Currency symbol for origin. Must be fiat for PAYIN/PAYOUT/PAYMENT_LINK/BALANCE_TRANSFER and crypto for OFFRAMP (e.g., COP, USD, ETH). Not required when quoteId is provided." }, "destinationCurrencySymbol": { "type": "object", "example": "COP", "description": "Currency symbol for destination. Must be fiat for PAYIN/PAYOUT/PAYMENT_LINK/BALANCE_TRANSFER/OFFRAMP and crypto for ONRAMP (e.g., COP, USD, BTC). Not required when quoteId is provided." }, "amountIn": { "type": "number", "example": 102.45 }, "amountOut": { "example": 900000, "description": "Amount in destination currency. Must provide either amountIn or amountOut (but not both) when quoteId is not provided. Not required when quoteId is provided.", "allOf": [ { "$ref": "#/components/schemas/Decimal" } ] }, "dueDate": { "type": "string", "example": "2026-01-28T12:36:55.523694Z", "description": "ISO 8601 date for order expiry. If not provided, orders will expire after 24 hours by default. If provided, must be a future date and cannot exceed the maximum allowed lifetime (24 hours from creation) or the order creation will fail. Applies to PAYMENT_LINK type." }, "description": { "type": "string", "example": "Payment for invoice #1234", "description": "Description of the order" }, "externalId": { "type": "string", "example": "payin-ext-001", "description": "Optional unique idempotent identifier provided by the client. If provided, it prevents duplicate operations for the same merchantId and type. If omitted, idempotency check is skipped." }, "failedUrl": { "type": "string", "example": "https://merchant.com/order/failed", "description": "URL for failed order notifications" }, "successUrl": { "type": "string", "example": "https://merchant.com/order/success", "description": "URL for successful order notifications" }, "paymentMethods": { "description": "Array of payment methods. Required for PAYIN (exactly one method). Required for PAYMENT_LINK (can be empty for all available methods or multiple specific methods). Optional for other order types.", "example": [ { "method": "PSE", "extra": { "bankAccount": { "name": "BANCOLOMBIA" } } } ], "type": "array", "items": { "$ref": "#/components/schemas/OrderPaymentMethodDto" } }, "quoteId": { "type": "string", "example": "quote-123", "description": "Quote ID to fix exchange rate for cross-currency or crypto operations (ONRAMP, OFFRAMP, BALANCE_TRANSFER). When provided, originCurrencySymbol, destinationCurrencySymbol, amountIn, and amountOut must not be provided." }, "enforcedDocument": { "type": "string", "example": "12345678-9", "description": "Government-issued ID number required for the operation (e.g. DNI, RUT, Cédula)" }, "contactId": { "type": "string", "example": "contact-123", "description": "Contact ID for the person involved in the order transaction. This identifies who the order is directed to. Required for using notification features." }, "sendEmail": { "type": "boolean", "example": true, "description": "Whether to send email notifications to the contact. Requires contactId to be set." }, "sendNotification": { "type": "boolean", "example": true, "description": "Whether to send in-app notifications to the contact. Requires contactId to be set." }, "sendWhatsapp": { "type": "boolean", "example": true, "description": "Whether to send WhatsApp notifications to the contact. Requires contactId to be set." }, "sendReminders": { "type": "boolean", "example": true, "description": "Whether to send order reminders when order is pending. Requires contactId to be set." }, "isMerchantSelfOrder": { "type": "boolean", "example": false, "description": "Indicates that the order is initiated by the merchant for themselves, rather than involving a third-party contact (such as a customer or supplier). Defaults to false when omitted." }, "isInvoicing": { "type": "boolean", "example": false, "description": "Indicates that the order is for invoicing purposes." }, "txHash": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "description": "Blockchain transaction hash. Used for networks like Stellar or Algorand where the client sends crypto externally and provides the txHash at order creation time." } }, "required": [ "type", "originCurrencySymbol", "destinationCurrencySymbol" ] }, "UpdateOrderDto": { "type": "object", "properties": { "txHash": { "type": "string", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "description": "Blockchain transaction hash to associate with the order" } } }, "OrderSigningPrepareResponseDto": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order id being prepared for signing", "example": "ord_123456789" }, "body": { "type": "string", "description": "JSON-stringified embedded wallet signing request that must be stamped exactly as returned" }, "signWith": { "type": "string", "description": "Wallet account address that will be used to sign the transaction" }, "chain": { "type": "string", "description": "Blockchain network for the transaction", "example": "BASE" }, "signatureMethod": { "type": "string", "enum": [ "PASSKEY", "API_DELEGATED_KEY" ], "description": "Requester signature method that must be used to stamp the signing request", "example": "PASSKEY" } }, "required": [ "orderId", "body", "signWith", "chain", "signatureMethod" ] }, "OrderSigningConfirmRequestDto": { "type": "object", "properties": { "stampedRequest": { "description": "The embedded wallet signing request stamped by the requester passkey or delegated API key", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "stampedRequest" ] }, "SendNotificationDto": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Merchant ID", "example": "mer_1234567890" }, "type": { "type": "string", "description": "Notification type", "example": "payment_received" }, "message": { "type": "string", "description": "Notification message", "example": "Payment of $100 received" }, "channels": { "type": "array", "description": "Channels to send the notification through", "example": [ "email", "whatsapp" ], "items": { "type": "string", "enum": [ "email", "whatsapp", "sms", "slack", "telegram", "push", "in-app" ] } }, "data": { "type": "object", "description": "Additional data for the notification", "example": { "amount": 100, "currency": "USD" } } }, "required": [ "type", "message", "channels" ] }, "QuoteRequestDto": { "type": "object", "properties": { "amountIn": { "type": "number", "description": "Amount to send (input currency)" }, "amountOut": { "type": "number", "description": "Amount to receive (output currency)" }, "originCurrencySymbol": { "type": "string", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ], "description": "Input currency symbol", "example": "CLP" }, "destinationCurrencySymbol": { "type": "string", "enum": [ "ARS", "CLP", "COP", "MXN", "USD", "PEN", "BRL", "ETH", "USDC", "USDT", "SOL", "TRX", "BTC", "BOB", "MATIC", "GBP", "CHF", "GYD", "PYG", "SRD", "UYU", "VES", "BZD", "CRC", "GTQ", "HNL", "NIO", "PAB", "CUP", "DOP", "HTG", "EUR", "CNY", "HKD", "SGD", "PHP", "JPY", "CAD", "AUD" ], "description": "Output currency symbol", "example": "USDC" }, "executable": { "type": "boolean", "description": "Whether the quote is executable" }, "paymentMethod": { "type": "string", "description": "Payment method ID" }, "orderType": { "type": "string", "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "CRYPTO_PAYOUT", "PAYMENT_LINK", "INTER_MERCHANT_TRANSFER" ], "description": "Type of order - determines valid currency pairs and network requirements", "example": "ONRAMP" }, "network": { "type": "string", "enum": [ "ETHEREUM", "POLYGON", "SOLANA", "TRON", "BSC", "BITCOIN", "BASE", "ALGORAND" ], "description": "Blockchain network for crypto quotes. Required for ONRAMP and OFFRAMP, ignored for fiat-to-fiat orderTypes.", "example": "POLYGON" }, "merchantId": { "type": "string", "description": "Merchant ID for the quote" }, "isInvoicing": { "type": "boolean", "description": "Whether the quote is for invoicing purposes" }, "contactId": { "type": "string", "description": "Contact ID for the recipient. Required for Asian currency quotes (e.g., HKD)" }, "bankAccountId": { "type": "string", "description": "Bank Account ID for routing. When provided, the bank account country is used for PSP routing decisions instead of the contact country." }, "destinationCountry": { "type": "string", "description": "Destination country code for PSP routing. Used when no contactId or bankAccountId is provided to determine the payout corridor.", "example": "GB" } }, "required": [ "originCurrencySymbol", "destinationCurrencySymbol", "executable", "orderType" ] }, "QuoteResponseComponent": { "type": "object", "properties": {} }, "QuoteResponseSummary": { "type": "object", "properties": {} }, "QuoteResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the quote, if applicable" }, "originCurrencySymbol": { "type": "string", "description": "Original origin currency symbol" }, "destinationCurrencySymbol": { "type": "string", "description": "Original destination currency symbol" }, "validForSeconds": { "type": "number", "description": "Number of seconds the quote is valid for" }, "validUntil": { "format": "date-time", "type": "string", "description": "Timestamp when the quote expires" }, "fee": { "type": "number", "description": "Total effective fee charged (base fees + tax on fees), in origin currency terms" }, "taxes": { "type": "number", "description": "Total tax applied directly to the transaction amount" }, "requestedAmountIn": { "type": "number", "description": "Original amountIn from request, if applicable" }, "requestedAmountOut": { "type": "number", "description": "Original amountOut from request, if applicable" }, "finalAmountIn": { "type": "number", "description": "Final total amount the user pays in the origin currency" }, "finalAmountOut": { "type": "number", "description": "Final net amount the user/recipient receives in the destination currency" }, "exchangeRate": { "type": "number", "description": "Effective exchange rate after all fees and taxes directly on amount are considered" }, "orderType": { "type": "string", "description": "Type of order from the request" }, "components": { "description": "Detailed breakdown of all fees and taxes applied", "type": "array", "items": { "$ref": "#/components/schemas/QuoteResponseComponent" } }, "summary": { "description": "Summary of financial calculations", "allOf": [ { "$ref": "#/components/schemas/QuoteResponseSummary" } ] } }, "required": [ "id", "originCurrencySymbol", "destinationCurrencySymbol", "validForSeconds", "validUntil", "fee", "taxes", "requestedAmountIn", "requestedAmountOut", "finalAmountIn", "finalAmountOut", "exchangeRate", "orderType", "components", "summary" ] }, "ParsedQuoteDaoResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the quote", "example": "quote_123456789" }, "merchantId": { "type": "string", "description": "ID of the merchant that owns this quote", "example": "merchant_abc123" }, "userId": { "type": "string", "description": "ID of the user who created this quote", "example": "user_xyz789" }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the quote was created", "example": "2024-01-15T10:30:00.000Z" }, "validForSeconds": { "type": "number", "description": "Number of seconds the quote is valid for", "example": 300 }, "validUntil": { "format": "date-time", "type": "string", "description": "Timestamp when the quote expires", "example": "2024-01-15T10:35:00.000Z" }, "isExecutable": { "type": "boolean", "description": "Whether the quote can be executed to create an order", "example": true }, "amountIn": { "type": "number", "description": "Total amount the user pays in the origin currency", "example": 1000.5 }, "amountOut": { "type": "number", "description": "Total amount the recipient receives in the destination currency", "example": 950.25 }, "exchangeRate": { "type": "number", "description": "Exchange rate applied for the conversion", "example": 0.95025 }, "originCurrencySymbol": { "type": "string", "description": "Symbol of the origin currency", "example": "USD" }, "destinationCurrencySymbol": { "type": "string", "description": "Symbol of the destination currency", "example": "EUR" }, "totalBaseFeesApplied": { "type": "number", "description": "Total base fees applied to the transaction", "example": 25 }, "totalTaxesOnAmountApplied": { "type": "number", "description": "Total taxes applied directly to the transaction amount", "example": 15 }, "totalTaxesOnFeesApplied": { "type": "number", "description": "Total taxes applied to the fees", "example": 5 }, "feeDetailsJson": { "type": "object", "description": "Detailed fee calculation results in JSON format", "example": { "baseFees": [ { "code": "PROCESSING_FEE", "name": "Processing Fee", "amount": 25, "currency": "USD" } ] } }, "taxDetailsJson": { "type": "object", "description": "Detailed tax calculation results in JSON format", "example": { "taxOnAmount": [ { "code": "VAT", "name": "Value Added Tax", "amount": 15, "currency": "USD" } ] } }, "orderType": { "type": "string", "description": "Type of order this quote is for", "example": "PAYIN" }, "koyweQuotesJson": { "type": "object", "description": "Raw Koywe quote responses used for this calculation in JSON format", "example": { "directQuote": { "amountIn": 1000, "amountOut": 950, "exchangeRate": 0.95 } } }, "userRequestJson": { "type": "object", "description": "Original user request data in JSON format", "example": { "amountIn": 1000, "originCurrencySymbol": "USD", "destinationCurrencySymbol": "EUR", "executable": true } } }, "required": [ "id", "merchantId", "userId", "createdAt", "validForSeconds", "validUntil", "isExecutable", "amountIn", "amountOut", "exchangeRate", "originCurrencySymbol", "destinationCurrencySymbol", "totalBaseFeesApplied", "totalTaxesOnAmountApplied", "totalTaxesOnFeesApplied", "feeDetailsJson", "taxDetailsJson", "orderType", "koyweQuotesJson", "userRequestJson" ] }, "LedgerMovementDto": { "type": "object", "properties": { "ledgerEntryId": { "type": "string", "description": "Unique ledger entry ID", "example": "137" }, "postedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the movement was posted", "example": "2025-01-15T10:30:00.000Z" }, "type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Type of movement (debit decreases balance, credit increases)", "example": "credit" }, "amount": { "type": "string", "description": "Amount of the movement", "example": "1000000.00" }, "currency": { "type": "string", "description": "Currency symbol", "example": "CLP" }, "runningBalance": { "type": "string", "description": "Running balance after this movement", "example": "5000000.00" }, "description": { "type": "string", "description": "Human-readable description of the movement", "example": "PAYIN from Juan Pérez - Bank transfer received" }, "orderId": { "type": "string", "description": "Associated order ID if applicable", "example": "ord_abc123" }, "category": { "type": "string", "enum": [ "PAYIN", "PAYOUT", "BALANCE_TRANSFER", "SETTLEMENT", "ADJUSTMENT", "FEE", "TAX", "ONRAMP", "OFFRAMP", "REVERSE", "OTHER" ], "description": "Category of the movement", "example": "PAYIN" } }, "required": [ "ledgerEntryId", "postedAt", "type", "amount", "currency", "runningBalance", "description", "category" ] }, "LedgerStatementPaginationDto": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor for next page (null if no more pages)", "example": "eyJpZCI6IjEzNyIsImRhdGUiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoifQ==" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available", "example": true }, "limit": { "type": "number", "description": "Number of items per page", "example": 50 } }, "required": [ "hasMore", "limit" ] }, "LedgerStatementResponseDto": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Virtual account ID", "example": "acc_abc123" }, "currency": { "type": "string", "description": "Currency of the account", "example": "CLP" }, "merchantId": { "type": "string", "description": "Merchant ID", "example": "mrc_xyz789" }, "periodStart": { "format": "date-time", "type": "string", "description": "Start of the reporting period", "example": "2025-01-01T00:00:00.000Z" }, "periodEnd": { "format": "date-time", "type": "string", "description": "End of the reporting period", "example": "2025-01-31T23:59:59.999Z" }, "openingBalance": { "type": "string", "description": "Balance at the start of the period", "example": "4000000.00" }, "closingBalance": { "type": "string", "description": "Balance at the end of the period", "example": "5500000.00" }, "movements": { "description": "List of movements in chronological order", "type": "array", "items": { "$ref": "#/components/schemas/LedgerMovementDto" } }, "pagination": { "description": "Pagination information", "allOf": [ { "$ref": "#/components/schemas/LedgerStatementPaginationDto" } ] }, "generatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when this report was generated", "example": "2025-01-31T12:00:00.000Z" } }, "required": [ "accountId", "currency", "merchantId", "periodStart", "periodEnd", "openingBalance", "closingBalance", "movements", "pagination", "generatedAt" ] }, "OrderReportCounterpartyDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Counterparty name", "example": "Juan Pérez" }, "identifier": { "type": "string", "description": "Counterparty identifier (tax ID, document, etc.)", "example": "12345678-9" } }, "required": [ "name", "identifier" ] }, "OrderReportItemDto": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID", "example": "ord_abc123" }, "type": { "type": "string", "enum": [ "PAYIN", "PAYOUT", "ONRAMP", "OFFRAMP", "BALANCE_TRANSFER", "CRYPTO_PAYOUT", "PAYMENT_LINK", "INTER_MERCHANT_TRANSFER" ], "description": "Type of order", "example": "PAYIN" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING", "PAID", "CANCELLED", "REFUND_REQUESTED", "COMPLETED", "PROCESSING", "FAILED", "REFUNDED", "EXPIRED", "ON_HOLD" ], "description": "Current status of the order", "example": "COMPLETED" }, "amountIn": { "type": "string", "description": "Amount received/sent in origin currency", "example": "1000000.00" }, "amountOut": { "type": "string", "description": "Amount received/sent in destination currency", "example": "1000.00" }, "originCurrency": { "type": "string", "description": "Origin currency symbol", "example": "CLP" }, "destinationCurrency": { "type": "string", "description": "Destination currency symbol", "example": "USD" }, "counterparty": { "description": "Counterparty information (contact)", "allOf": [ { "$ref": "#/components/schemas/OrderReportCounterpartyDto" } ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Order creation timestamp", "example": "2025-01-15T10:30:00.000Z" }, "completedAt": { "format": "date-time", "type": "string", "description": "Order completion timestamp", "example": "2025-01-15T10:35:00.000Z" }, "externalId": { "type": "string", "description": "External reference ID provided by merchant", "example": "INV-2025-001" } }, "required": [ "orderId", "type", "status", "amountIn", "amountOut", "originCurrency", "destinationCurrency", "createdAt" ] }, "OrdersReportSummaryDto": { "type": "object", "properties": { "totalOrders": { "type": "number", "description": "Total number of orders in the period", "example": 150 }, "byType": { "type": "object", "description": "Count of orders by type", "example": { "PAYIN": 100, "PAYOUT": 50 } }, "byStatus": { "type": "object", "description": "Count of orders by status", "example": { "COMPLETED": 140, "PENDING": 10 } } }, "required": [ "totalOrders", "byType", "byStatus" ] }, "OrdersReportPaginationDto": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor for next page (null if no more pages)" }, "hasMore": { "type": "boolean", "description": "Whether there are more pages available", "example": true }, "limit": { "type": "number", "description": "Number of items per page", "example": 50 } }, "required": [ "hasMore", "limit" ] }, "OrdersReportResponseDto": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Virtual account ID", "example": "acc_abc123" }, "currency": { "type": "string", "description": "Currency of the account", "example": "CLP" }, "periodStart": { "format": "date-time", "type": "string", "description": "Start of the reporting period", "example": "2025-01-01T00:00:00.000Z" }, "periodEnd": { "format": "date-time", "type": "string", "description": "End of the reporting period", "example": "2025-01-31T23:59:59.999Z" }, "orders": { "description": "List of orders in chronological order", "type": "array", "items": { "$ref": "#/components/schemas/OrderReportItemDto" } }, "summary": { "description": "Summary statistics for the report", "allOf": [ { "$ref": "#/components/schemas/OrdersReportSummaryDto" } ] }, "pagination": { "description": "Pagination information", "allOf": [ { "$ref": "#/components/schemas/OrdersReportPaginationDto" } ] }, "generatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when this report was generated", "example": "2025-01-31T12:00:00.000Z" } }, "required": [ "accountId", "currency", "periodStart", "periodEnd", "orders", "summary", "pagination", "generatedAt" ] }, "LedgerEntryReceiptReferencesDto": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Associated order ID", "example": "ord_abc123" }, "settlementId": { "type": "string", "description": "Associated settlement ID", "example": "145" } } }, "LedgerEntryReceiptDto": { "type": "object", "properties": { "ledgerEntryId": { "type": "string", "description": "Unique ledger entry ID", "example": "137" }, "accountId": { "type": "string", "description": "Virtual account ID", "example": "acc_abc123" }, "merchantId": { "type": "string", "description": "Merchant ID", "example": "mrc_xyz789" }, "merchantName": { "type": "string", "description": "Merchant name", "example": "Acme Corporation" }, "type": { "type": "string", "enum": [ "debit", "credit" ], "description": "Type of movement", "example": "credit" }, "amount": { "type": "string", "description": "Amount of the movement", "example": "1000000.00" }, "currency": { "type": "string", "description": "Currency symbol", "example": "CLP" }, "postedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the movement was posted", "example": "2025-01-15T10:30:00.000Z" }, "description": { "type": "string", "description": "Human-readable description", "example": "PAYIN from Juan Pérez - Bank transfer received" }, "category": { "type": "string", "enum": [ "PAYIN", "PAYOUT", "BALANCE_TRANSFER", "SETTLEMENT", "ADJUSTMENT", "FEE", "TAX", "ONRAMP", "OFFRAMP", "REVERSE", "OTHER" ], "description": "Category of the movement", "example": "PAYIN" }, "references": { "description": "References to related entities", "allOf": [ { "$ref": "#/components/schemas/LedgerEntryReceiptReferencesDto" } ] }, "balanceBefore": { "type": "string", "description": "Balance before this movement", "example": "4000000.00" }, "balanceAfter": { "type": "string", "description": "Balance after this movement", "example": "5000000.00" }, "generatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when this receipt was generated", "example": "2025-01-31T12:00:00.000Z" } }, "required": [ "ledgerEntryId", "accountId", "merchantId", "merchantName", "type", "amount", "currency", "postedAt", "description", "category", "references", "balanceBefore", "balanceAfter", "generatedAt" ] }, "CreateOrganizationInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "example": "invited.user@example.com", "description": "Email address or API username (api_ format) of the user to invite" }, "roles": { "example": [ "k3r_admin" ], "description": "Array of role IDs to assign to the user for the organization. Must contain at least 1 role. Available roles: k3r_super_admin, k3r_admin, k3r_treasury_manager, k3r_operator, k3r_viewer", "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "email", "roles" ] }, "OrganizationRoleWithPermissionsDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Role name" }, "permissions": { "description": "Permissions (name only) associated with this role", "type": "array", "items": { "$ref": "#/components/schemas/PermissionDto" } } }, "required": [ "name", "permissions" ] }, "UserOrganizationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Organization ID" }, "name": { "type": "string", "description": "Organization name" }, "description": { "type": [ "string", "null" ], "description": "Organization description" }, "roles": { "description": "Roles assigned to the user in this organization, including their permissions", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationRoleWithPermissionsDto" } } }, "required": [ "id", "name", "description", "roles" ] }, "Koywe3UserDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "name": { "type": "string", "description": "User name" }, "email": { "type": "string", "description": "User email" }, "merchants": { "description": "Merchants associated with the user, including their roles", "type": "array", "items": { "$ref": "#/components/schemas/UserMerchantDto" } }, "organizations": { "description": "Organizations associated with the user, including their roles", "type": "array", "items": { "$ref": "#/components/schemas/UserOrganizationDto" } } }, "required": [ "id", "name", "email", "merchants", "organizations" ] }, "CreateInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "example": "invited.user@example.com", "description": "Email address or API username (api_ format) of the user to invite" }, "roles": { "example": [ "MERCHANT_ADMIN", "MERCHANT_VIEWER" ], "description": "Array of role IDs or names to assign to the user for the merchant. Must contain at least 1 role.", "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "email", "roles" ] }, "InvitationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_xxxxxxxxxxxxxx", "description": "Invitation ID" }, "email": { "type": "string", "example": "user@example.com", "description": "Email of the invited user" }, "roles": { "example": [ "ADMIN_ROLE", "VIEWER_ROLE" ], "description": "Roles assigned in the invitation", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "EXPIRED", "REVOKED" ], "example": "PENDING", "description": "Current status of the invitation" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2024-08-15T10:00:00.000Z", "description": "Expiration date of the invitation token" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-08-08T10:00:00.000Z", "description": "Creation date of the invitation" }, "acceptedAt": { "format": "date-time", "type": [ "string", "null" ], "example": "2024-08-09T10:00:00.000Z", "description": "Date when the invitation was accepted" }, "acceptedByUserId": { "type": [ "string", "null" ], "example": "k3u_xxxxxxxxxxxxxx", "description": "ID of the user who accepted the invitation" }, "invitedByUserId": { "type": "string", "example": "k3u_yyyyyyyyyyyyyy", "description": "ID of the user who sent the invitation" }, "merchantId": { "type": "string", "example": "mrc_zzzzzzzzzzzzzz", "description": "ID of the merchant for this invitation" }, "userExists": { "type": "boolean", "example": true, "description": "Indicates whether the invited user already exists in the system" }, "rolesAssignedImmediately": { "type": "boolean", "example": true, "description": "Indicates whether roles were assigned immediately without requiring invitation redemption" }, "message": { "type": "string", "example": "Invitation sent to user@example.com", "description": "Message describing the invitation result. For immediate assignments: \"Roles assigned immediately...\". For traditional flow: \"Invitation sent to...\"" }, "pendingApprovalId": { "type": "string", "example": "pa_xxxxxxxxxxxxxx", "description": "If the invitation requires policy approval (sensitive roles), the pending approval ID. The root passkey holder must approve this before the invitation proceeds." } }, "required": [ "id", "email", "roles", "status", "expiresAt", "createdAt", "invitedByUserId", "merchantId", "userExists" ] }, "InvitationDto": { "type": "object", "properties": { "id": { "type": "string", "example": "inv_xxxxxxxxxxxxxx", "description": "Invitation ID" }, "email": { "type": "string", "example": "user@example.com", "description": "Email of the invited user" }, "roles": { "example": [ "ADMIN_ROLE", "VIEWER_ROLE" ], "description": "Roles assigned in the invitation", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "EXPIRED", "REVOKED" ], "example": "PENDING", "description": "Current status of the invitation" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2024-08-15T10:00:00.000Z", "description": "Expiration date of the invitation token" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-08-08T10:00:00.000Z", "description": "Creation date of the invitation" }, "acceptedAt": { "format": "date-time", "type": [ "string", "null" ], "example": "2024-08-09T10:00:00.000Z", "description": "Date when the invitation was accepted" }, "acceptedByUserId": { "type": [ "string", "null" ], "example": "k3u_xxxxxxxxxxxxxx", "description": "ID of the user who accepted the invitation" }, "invitedByUserId": { "type": "string", "example": "k3u_yyyyyyyyyyyyyy", "description": "ID of the user who sent the invitation" }, "merchantId": { "type": "string", "example": "mrc_zzzzzzzzzzzzzz", "description": "ID of the merchant for this invitation" } }, "required": [ "id", "email", "roles", "status", "expiresAt", "createdAt", "invitedByUserId", "merchantId" ] }, "PaginatedInvitationsDto": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationDto" }, "invitations": { "description": "List of invitations", "type": "array", "items": { "$ref": "#/components/schemas/InvitationDto" } } }, "required": [ "pagination", "invitations" ] }, "OrganizationInvitationResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Indicates whether the operation was successful" }, "message": { "type": "string", "example": "Invitation sent to user@example.com for organization My Organization", "description": "Message describing the invitation result. For immediate assignments: \"Roles assigned immediately...\". For traditional flow: \"Invitation sent to...\"" }, "organizationId": { "type": "string", "example": "org3_xxxxxxxxxxxxxx", "description": "ID of the organization for this invitation" }, "userExists": { "type": "boolean", "example": true, "description": "Indicates whether the invited user already exists in the system" }, "rolesAssignedImmediately": { "type": "boolean", "example": true, "description": "Indicates whether roles were assigned immediately without requiring invitation redemption" }, "pendingApprovalId": { "type": "string", "example": "pa_xxxxxxxxxxxxxx", "description": "If the invitation requires policy approval (sensitive roles), the pending approval ID. The root passkey holder must approve this before the invitation proceeds." } }, "required": [ "success", "message", "organizationId", "userExists" ] }, "OrganizationInvitationDto": { "type": "object", "properties": { "id": { "type": "string", "example": "orginv_xxxxxxxxxxxxxx", "description": "Organization invitation ID" }, "email": { "type": "string", "example": "user@example.com", "description": "Email of the invited user" }, "roles": { "example": [ "k3r_user_org_inviter", "k3r_user_org_viewer", "k3r_user_org_manager" ], "description": "Role IDs assigned in the organization invitation", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "EXPIRED", "REVOKED" ], "example": "PENDING", "description": "Current status of the organization invitation" }, "expiresAt": { "format": "date-time", "type": "string", "example": "2024-08-15T10:00:00.000Z", "description": "Expiration date of the invitation token" }, "createdAt": { "format": "date-time", "type": "string", "example": "2024-08-08T10:00:00.000Z", "description": "Creation date of the invitation" }, "acceptedAt": { "format": "date-time", "type": [ "string", "null" ], "example": "2024-08-09T10:00:00.000Z", "description": "Date when the invitation was accepted" }, "acceptedByUserId": { "type": [ "string", "null" ], "example": "k3u_xxxxxxxxxxxxxx", "description": "ID of the user who accepted the invitation" }, "invitedByUserId": { "type": "string", "example": "k3u_yyyyyyyyyyyyyy", "description": "ID of the user who sent the invitation" }, "organizationId": { "type": "string", "example": "org3_zzzzzzzzzzzzzz", "description": "ID of the organization for this invitation" } }, "required": [ "id", "email", "roles", "status", "expiresAt", "createdAt", "invitedByUserId", "organizationId" ] }, "PaginatedOrganizationInvitationsDto": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationDto" }, "invitations": { "description": "List of organization invitations", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationInvitationDto" } } }, "required": [ "pagination", "invitations" ] }, "PayInVirtualBankAccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "pivba_123456", "description": "Virtual bank account ID" }, "merchantId": { "type": "string", "example": "merchant-456", "description": "Merchant ID" }, "country": { "type": "string", "enum": [ "AR", "MX", "US" ], "example": "AR", "description": "Country code" }, "currency": { "type": "string", "enum": [ "ARS", "MXN", "USD" ], "example": "ARS", "description": "Currency code" }, "isActive": { "type": "boolean", "example": true, "description": "Active status of the account" }, "virtualBankAccountNumber": { "type": "string", "example": "0000000000000000000000", "description": "Virtual bank account number" }, "alias": { "type": "string", "example": "john.doe.koywe", "description": "Custom alias for the virtual bank account. Contains only letters, numbers, and dots." }, "routingNumber": { "type": "string", "example": "021000021", "description": "Routing number (USA/ACH). Optional." }, "bankName": { "type": "string", "example": "Chase Bank", "description": "Bank name. Optional." }, "createdAt": { "format": "date-time", "type": "string", "example": "2025-10-25T12:00:00Z", "description": "Creation date" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2025-10-25T12:00:00Z", "description": "Last update date" } }, "required": [ "id", "merchantId", "country", "currency", "isActive", "createdAt", "updatedAt" ] }, "CreatePayInVirtualBankAccountDto": { "type": "object", "properties": { "country": { "type": "string", "enum": [ "AR", "MX", "US" ], "example": "AR", "description": "Two-letter country code (AR, MX, or US)" }, "currency": { "type": "string", "enum": [ "ARS", "MXN", "USD" ], "example": "ARS", "description": "Currency code (ARS, MXN, or USD)" } }, "required": [ "country", "currency" ] }, "PayInVirtualBankAccountItemDto": { "type": "object", "properties": { "id": { "type": "string", "example": "pivba_123456", "description": "Virtual bank account ID" }, "country": { "type": "string", "enum": [ "AR", "MX", "US" ], "example": "AR", "description": "Country code" }, "currency": { "type": "string", "enum": [ "ARS", "MXN", "USD" ], "example": "ARS", "description": "Currency code" }, "provider": { "type": "string", "example": "BITSO_MX", "description": "Payment Service Provider name" }, "isActive": { "type": "boolean", "example": true, "description": "Active status of the account" }, "virtualBankAccountNumber": { "type": "string", "example": "0000000000000000000000", "description": "Virtual bank account number" }, "alias": { "type": "string", "example": "john.doe.koywe", "description": "Custom alias for the virtual bank account. Contains only letters, numbers, and dots." }, "routingNumber": { "type": "string", "example": "021000021", "description": "Routing number (USA/ACH). Optional." }, "bankName": { "type": "string", "example": "Chase Bank", "description": "Bank name. Optional." }, "createdAt": { "format": "date-time", "type": "string", "example": "2025-10-25T12:00:00Z", "description": "Creation date" } }, "required": [ "id", "country", "currency", "provider", "isActive", "createdAt" ] }, "UpdateAliasRequestDto": { "type": "object", "properties": { "alias": { "type": "string", "example": "john.doe.koywe", "description": "New alias for the virtual bank account (Argentina only). Must contain only letters (a-z, A-Z), numbers (0-9), and dots (.). The alias will be updated both in the PSP and local database. Note: Alias functionality is only available for Argentina (AR) accounts." } }, "required": [ "alias" ] }, "SetupDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Setup register ID", "example": "setreg_a1f3c8b2-7d44-4f8b-9e12-91c1b8a21111" }, "organizationId": { "type": [ "string", "null" ], "description": "Organization ID (null if not yet created)", "example": "org_1234567890" }, "merchantId": { "type": [ "string", "null" ], "description": "Merchant ID (null if not yet created)", "example": "mrc_1234567890" }, "status": { "type": "string", "description": "Setup status", "enum": [ "PENDING", "RUNNING", "FAILED", "COMPLETED" ], "example": "PENDING" } }, "required": [ "id", "organizationId", "merchantId", "status" ] }, "EvaluationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Onboarding register ID", "example": "onbreg_6a37fda4-03ed-4954-9d64-87fb83242c93" }, "status": { "type": "string", "description": "Evaluation status", "enum": [ "RECEIVED", "IN_REVIEW", "COMPLIANCE_IN_REVIEW", "ACCOUNT_SETUP_IN_PROGRESS", "COMPLETED", "ACTION_REQUIRED", "APPROVED", "REJECTED", "PENDING_KYB" ], "example": "APPROVED" }, "subStatus": { "type": [ "string", "null" ], "description": "Evaluation sub-status", "enum": [ "AWAITING_EVALUATION", "COMPLIANCE_SCREENING", "RISK_ANALYSIS", "MISSING_DOCUMENTS", "MANUAL_REVIEW", "NO_OBSERVATIONS", "COMPLIANCE_RISK", "INVALID_DOCUMENT_TYPE", "INVALID_DOCUMENT_FORMAT", "COUNTRY_REQUIRES_KYB", "DECLARATION_NOT_ACCEPTED", "MERCHANT_ALREADY_EXISTS", "HIGH_RISK_COUNTRY", "REGISTERING_ACCOUNT", "APPLICANT_PENDING_COMPANY_PENDING", "APPLICANT_APPROVED_COMPANY_PENDING", "APPLICANT_APPROVED_COMPANY_APPROVED", "APPLICANT_APPROVED_COMPANY_REJECTED", "APPLICANT_REJECTED_COMPANY_PENDING", "APPLICANT_REJECTED_COMPANY_APPROVED", "APPLICANT_REJECTED_COMPANY_REJECTED", "APPLICANT_PENDING_COMPANY_APPROVED", "APPLICANT_PENDING_COMPANY_REJECTED", "COMPLIANCE_CHECK_ERROR", "SETUP_PENDING", "CREATING_ORGANIZATION", "CREATING_MERCHANT", "ASSIGNING_FEATURES", "ASSIGNING_FEES", "ASSIGNING_USER_ROLES", "ONBOARDING_COMPLETED" ], "example": "NO_OBSERVATIONS" }, "updatedAt": { "type": "string", "description": "Last update timestamp (ISO 8601)", "example": "2026-01-26T16:02:00Z" }, "setup": { "description": "Setup registers associated with this evaluation", "type": "array", "items": { "$ref": "#/components/schemas/SetupDto" } } }, "required": [ "id", "status", "updatedAt" ] }, "OnboardingMeResponseDto": { "type": "object", "properties": { "evaluation": { "description": "List of onboarding evaluations for the authenticated user", "type": "array", "items": { "$ref": "#/components/schemas/EvaluationDto" } } }, "required": [ "evaluation" ] }, "KybContactOverrideDto": { "type": "object", "properties": { "email": { "type": "string", "example": "john.doe@company.com", "description": "Override email for the focal point. If not provided, the email is resolved from the pre-onboarding user record or merchant data." }, "language": { "type": "string", "example": "en", "description": "Language for the KYB form (es, en, pt)", "default": "en" } } }, "TriggerKybRequestDto": { "type": "object", "properties": { "forceRetrigger": { "type": "boolean", "example": false, "description": "If true, forces re-creation of the KYB process even if one already exists in a terminal state (REJECTED, FAILED)", "default": false }, "contactOverride": { "description": "Optional overrides for the KYB contact. Name is always resolved from pre-onboarding data.", "allOf": [ { "$ref": "#/components/schemas/KybContactOverrideDto" } ] } } }, "KybProcessResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "kybp_31fd8637-f889-43fa-8b31-50d9296abfdc", "description": "KYB process identifier" }, "merchantId": { "type": "string", "example": "mrc_31fd8637-f889-43fa-8b31-50d9296abfdc", "description": "Merchant identifier" }, "status": { "type": "string", "example": "PENDING", "description": "Current status of the KYB process", "enum": [ "CREATED", "PENDING", "IN_PROGRESS", "APPROVED", "REJECTED", "MANUAL_REVIEW", "FAILED" ] }, "formLink": { "type": "string", "example": "https://app.chaindots.com/kyb/form/abc-123", "description": "Link to the KYB form for the merchant to complete" }, "statusReason": { "type": "string", "example": "All validation steps passed successfully.", "description": "Reason for the current status" }, "createdAt": { "format": "date-time", "type": "string", "example": "2025-01-15T10:30:00Z", "description": "When the KYB process was created" }, "updatedAt": { "format": "date-time", "type": "string", "example": "2025-01-15T10:30:00Z", "description": "When the KYB process was last updated" }, "warning": { "type": "string", "example": "Chaindots did not return an activation link — the email address may already have an active KYB process on the provider. The contact should log in directly.", "description": "Non-fatal advisory message. Present when the process was accepted by the provider but an activation link could not be generated (e.g. email already registered at Chaindots). The KYB process is tracked internally but the contact must complete verification through the provider directly." } }, "required": [ "id", "merchantId", "status", "createdAt", "updatedAt" ] }, "DraftApplicantDto": { "type": "object", "properties": { "fullName": { "type": "string" }, "documentIssuingCountry": { "type": "string" }, "documentType": { "type": "string" }, "documentNumber": { "type": "string" }, "phone": { "type": "string" }, "companyRole": { "type": "string" }, "linkedinProfileUrl": { "type": "string" } } }, "DraftProhibitedActivitiesDeclarationDto": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "acceptedAt": { "type": "string" } } }, "DraftCompanyDto": { "type": "object", "properties": { "legalName": { "type": "string" }, "tradeName": { "type": "string" }, "country": { "type": "string" }, "taxIdentificationType": { "type": "string" }, "taxIdentificationNumber": { "type": "string" }, "address": { "type": "string", "description": "Primary address line" }, "addressLine2": { "type": "string", "description": "Secondary address line" }, "city": { "type": "string", "description": "City or municipality" }, "postalCode": { "type": "string", "description": "Postal/ZIP code" }, "stateId": { "type": "string", "description": "State ID (reference to States table, e.g. st_xxx)" }, "countyId": { "type": "string", "description": "County ID (reference to Counties table, e.g. cnt_xxx)" }, "economicActivity": { "type": "string" }, "otherEconomicActivityDescription": { "type": "string", "description": "Required when economicActivity is OTHER (\"Otra\"). Free-text description of the activity. Must be empty when economicActivity is not OTHER." }, "companyUrl": { "type": "string" }, "prohibitedActivitiesDeclaration": { "$ref": "#/components/schemas/DraftProhibitedActivitiesDeclarationDto" } } }, "DraftAcceptanceDto": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "acceptedAt": { "type": "string" } } }, "DraftDeclarationDto": { "type": "object", "properties": { "informationVeracityDeclaration": { "$ref": "#/components/schemas/DraftAcceptanceDto" }, "marketingConsent": { "$ref": "#/components/schemas/DraftAcceptanceDto" } } }, "DraftTermsAndConditionsDto": { "type": "object", "properties": { "termsAndConditions": { "$ref": "#/components/schemas/DraftAcceptanceDto" }, "privacyPolicyRead": { "$ref": "#/components/schemas/DraftAcceptanceDto" } } }, "CreateDraftRequestDto": { "type": "object", "properties": { "applicant": { "$ref": "#/components/schemas/DraftApplicantDto" }, "company": { "$ref": "#/components/schemas/DraftCompanyDto" }, "declaration": { "$ref": "#/components/schemas/DraftDeclarationDto" }, "termsAndConditions": { "$ref": "#/components/schemas/DraftTermsAndConditionsDto" } } }, "DraftResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "submitted" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "data": { "type": "object", "description": "Stored form data" } }, "required": [ "id", "userId", "status", "createdAt", "updatedAt", "data" ] }, "UpdateDraftRequestDto": { "type": "object", "properties": { "applicant": { "$ref": "#/components/schemas/DraftApplicantDto" }, "company": { "$ref": "#/components/schemas/DraftCompanyDto" }, "declaration": { "$ref": "#/components/schemas/DraftDeclarationDto" }, "termsAndConditions": { "$ref": "#/components/schemas/DraftTermsAndConditionsDto" } } }, "SubmitRegistrationResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "draftId": { "type": "string" }, "status": { "type": "string", "enum": [ "RECEIVED", "PENDING_KYB", "REJECTED" ] }, "subStatus": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "string" }, "organizationId": { "type": "string", "description": "Organization ID created in DRAFT state. Only present when status is PENDING_KYB (greylist country). Use this together with merchantId to call POST /organizations/{orgId}/merchants/{mrcId}/onboarding/kyb." }, "merchantId": { "type": "string", "description": "Merchant ID created in DRAFT state. Only present when status is PENDING_KYB (greylist country). Use this ID to call POST /organizations/{orgId}/merchants/{mrcId}/onboarding/kyb." } }, "required": [ "id", "draftId", "status", "message", "createdAt" ] }, "RegistrationSummaryDto": { "type": "object", "properties": { "id": { "type": "string" }, "draftId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "subStatus": { "type": "string" }, "companyLegalName": { "type": "string" }, "companyCountry": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "draftId", "status", "companyLegalName", "companyCountry", "createdAt", "updatedAt" ] }, "ActiveDraftSummaryDto": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "status", "createdAt", "updatedAt" ] }, "UserRegistrationsResponseDto": { "type": "object", "properties": { "userId": { "type": "string" }, "registrations": { "type": "array", "items": { "$ref": "#/components/schemas/RegistrationSummaryDto" } }, "activeDraft": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/ActiveDraftSummaryDto" } ] }, { "type": "null" } ] } }, "required": [ "userId", "registrations" ] }, "RegistrationFormStatusResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Pre-onboarding registration ID", "example": "onbreg_8f32c1d4-1b1c-4e9c-9a77-cc912a1c5a01" }, "status": { "type": "string", "description": "Status of the pre-onboarding registration", "enum": [ "RECEIVED", "IN_REVIEW", "COMPLIANCE_IN_REVIEW", "ACCOUNT_SETUP_IN_PROGRESS", "COMPLETED", "ACTION_REQUIRED", "APPROVED", "REJECTED", "PENDING_KYB" ], "example": "RECEIVED" }, "subStatus": { "type": "string", "description": "Sub-status of the pre-onboarding registration", "enum": [ "AWAITING_EVALUATION", "COMPLIANCE_SCREENING", "RISK_ANALYSIS", "MISSING_DOCUMENTS", "MANUAL_REVIEW", "NO_OBSERVATIONS", "COMPLIANCE_RISK", "INVALID_DOCUMENT_TYPE", "INVALID_DOCUMENT_FORMAT", "COUNTRY_REQUIRES_KYB", "DECLARATION_NOT_ACCEPTED", "MERCHANT_ALREADY_EXISTS", "HIGH_RISK_COUNTRY", "REGISTERING_ACCOUNT", "APPLICANT_PENDING_COMPANY_PENDING", "APPLICANT_APPROVED_COMPANY_PENDING", "APPLICANT_APPROVED_COMPANY_APPROVED", "APPLICANT_APPROVED_COMPANY_REJECTED", "APPLICANT_REJECTED_COMPANY_PENDING", "APPLICANT_REJECTED_COMPANY_APPROVED", "APPLICANT_REJECTED_COMPANY_REJECTED", "APPLICANT_PENDING_COMPANY_APPROVED", "APPLICANT_PENDING_COMPANY_REJECTED", "COMPLIANCE_CHECK_ERROR", "SETUP_PENDING", "CREATING_ORGANIZATION", "CREATING_MERCHANT", "ASSIGNING_FEATURES", "ASSIGNING_FEES", "ASSIGNING_USER_ROLES", "ONBOARDING_COMPLETED" ], "example": "AWAITING_EVALUATION" }, "updatedAt": { "type": "string", "description": "Last update timestamp (ISO 8601)", "example": "2026-01-20T14:35:00Z" }, "organizationId": { "type": "string", "description": "Organization ID (present when org+merchant have been created for greylist/CT-flagged path)" }, "merchantId": { "type": "string", "description": "Merchant ID (present when org+merchant have been created for greylist/CT-flagged path). Use this to call POST /organizations/{orgId}/merchants/{mrcId}/onboarding/kyb." } }, "required": [ "id", "status", "updatedAt" ] }, "PolicyRuleResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "policyId": { "type": "string" }, "ruleOrder": { "type": "number" }, "description": { "type": "string" }, "principalMatch": { "type": "string" }, "merchantMatch": { "type": "string" }, "originMatch": { "type": "string" }, "destinationMatch": { "type": "string" }, "operationTypeMatch": { "type": "string" }, "minAmountUsd": { "type": "number" }, "minDailyAmountUsd": { "type": "number" }, "action": { "type": "string", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] }, "approvalMode": { "type": "string", "enum": [ "ANY_OF", "ALL_OF", "THRESHOLD" ] }, "approvers": { "type": "array", "items": { "type": "string" } }, "approvalThreshold": { "type": "number" }, "isActive": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "policyId", "ruleOrder", "principalMatch", "merchantMatch", "originMatch", "destinationMatch", "operationTypeMatch", "minAmountUsd", "action", "isActive", "createdAt", "updatedAt" ] }, "PolicyResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "isActive": { "type": "boolean" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyRuleResponseDto" } }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "organizationId", "isActive", "rules", "createdAt", "updatedAt" ] }, "PolicyMutationResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "APPLIED", "PENDING_APPROVAL" ] }, "pendingApprovalId": { "type": "string" }, "approval": { "$ref": "#/components/schemas/PolicyApprovalRequirementsDto" }, "policy": { "$ref": "#/components/schemas/PolicyResponseDto" }, "rule": { "$ref": "#/components/schemas/PolicyRuleResponseDto" } }, "required": [ "status" ] }, "CreatePolicyRuleDto": { "type": "object", "properties": { "ruleOrder": { "type": "number", "description": "Rule evaluation order (lower = higher priority)" }, "description": { "type": "string", "description": "Human-readable description of the rule" }, "principalMatch": { "type": "string", "description": "User ID or \"*\" for any principal", "default": "*" }, "merchantMatch": { "type": "string", "description": "Merchant ID or \"*\" for any merchant", "default": "*" }, "originMatch": { "type": "string", "description": "Account ID, currency symbol, or \"*\" for any origin", "default": "*" }, "destinationMatch": { "type": "string", "description": "Account ID, currency symbol, or \"*\" for any destination", "default": "*" }, "operationTypeMatch": { "type": "string", "description": "PolicyOperationType value or \"*\" for any operation", "default": "*" }, "minAmountUsd": { "type": "number", "description": "Minimum transaction amount in USD that activates this rule", "default": 0 }, "minDailyAmountUsd": { "type": "number", "description": "Minimum daily cumulative amount in USD that activates this rule" }, "action": { "type": "string", "description": "Action to take when rule matches", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] }, "approvalMode": { "type": "string", "description": "Approval mode (required when action = REQUIRE_APPROVAL)", "enum": [ "ANY_OF", "ALL_OF", "THRESHOLD" ] }, "approvers": { "description": "List of approver User IDs", "type": "array", "items": { "type": "string" } }, "approvalThreshold": { "type": "number", "description": "Required approval count for THRESHOLD mode" } }, "required": [ "ruleOrder", "principalMatch", "merchantMatch", "originMatch", "destinationMatch", "operationTypeMatch", "minAmountUsd", "action" ] }, "ReorderPolicyRuleItemDto": { "type": "object", "properties": { "ruleId": { "type": "string" }, "ruleOrder": { "type": "number" } }, "required": [ "ruleId", "ruleOrder" ] }, "ReorderPolicyRulesDto": { "type": "object", "properties": { "ruleOrders": { "description": "Array of { ruleId, ruleOrder } pairs", "type": "array", "items": { "$ref": "#/components/schemas/ReorderPolicyRuleItemDto" } } }, "required": [ "ruleOrders" ] }, "UpdatePolicyRuleDto": { "type": "object", "properties": { "description": { "type": "string", "description": "Human-readable description of the rule" }, "principalMatch": { "type": "string", "description": "User ID or \"*\" for any principal" }, "merchantMatch": { "type": "string", "description": "Merchant ID or \"*\" for any merchant" }, "originMatch": { "type": "string", "description": "Account ID, currency symbol, or \"*\" for any origin" }, "destinationMatch": { "type": "string", "description": "Account ID, currency symbol, or \"*\" for any destination" }, "operationTypeMatch": { "type": "string", "description": "PolicyOperationType value or \"*\" for any operation" }, "minAmountUsd": { "type": "number", "description": "Minimum transaction amount in USD" }, "minDailyAmountUsd": { "type": "number", "description": "Minimum daily cumulative amount in USD" }, "action": { "type": "string", "description": "Action to take when rule matches", "enum": [ "ALLOW", "REQUIRE_APPROVAL", "DENY" ] }, "approvalMode": { "type": "string", "description": "Approval mode", "enum": [ "ANY_OF", "ALL_OF", "THRESHOLD" ] }, "approvers": { "description": "List of approver User IDs", "type": "array", "items": { "type": "string" } }, "approvalThreshold": { "type": "number", "description": "Required approval count for THRESHOLD mode" } } }, "UserIdentityDto": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "firebaseUuid": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "name", "firebaseUuid" ] }, "PendingApprovalResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "policyId": { "type": "string" }, "ruleId": { "type": "string" }, "operationType": { "type": "string", "enum": [ "PAYOUT_FIAT", "PAYOUT_CRYPTO", "BALANCE_TRANSFER", "POLICY_MANAGE", "DESTINATION_EDIT", "PASSKEY_ENROLL", "API_USER_MFA_ENROLL", "API_USER_MFA_REVOKE", "EMBEDDED_WALLET_ACCESS_GRANT", "USER_INVITE" ] }, "requestedBy": { "$ref": "#/components/schemas/UserIdentityDto" }, "merchantId": { "type": "string" }, "resourceType": { "type": "string" }, "resourceOwnerType": { "type": "string", "enum": [ "merchant", "contact" ], "description": "Ownership scope of the target resource when the approval applies to a merchant-owned or contact-owned resource." }, "resourceId": { "type": "string", "description": "Resource identifier when known. For create-on-approve flows this may contain the placeholder PENDING_CREATION until the resource exists." }, "contactId": { "type": "string", "description": "Contact ID when the approval targets a contact-owned resource." }, "amountUsd": { "type": "number" }, "requiredApprovers": { "type": "array", "items": { "$ref": "#/components/schemas/UserIdentityDto" } }, "receivedApprovals": { "type": "array", "items": { "$ref": "#/components/schemas/UserIdentityDto" } }, "approvalMode": { "type": "string", "enum": [ "ANY_OF", "ALL_OF", "THRESHOLD" ] }, "approvalThreshold": { "type": "number" }, "mfaRequired": { "type": "boolean" }, "mfaRequiredFrom": { "type": "string", "enum": [ "REQUESTER", "APPROVER" ] }, "mfaCompletedBy": { "$ref": "#/components/schemas/UserIdentityDto" }, "mfaCompletedByTurnkeyUserId": { "type": [ "string", "null" ] }, "mfaCompletedAt": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED", "EXPIRED" ] }, "expiresAt": { "format": "date-time", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "policyId", "ruleId", "operationType", "requestedBy", "merchantId", "amountUsd", "requiredApprovers", "receivedApprovals", "approvalMode", "mfaRequired", "mfaRequiredFrom", "status", "expiresAt", "createdAt", "updatedAt" ] }, "ApproveOperationRequestDto": { "type": "object", "properties": { "operationData": { "type": "object", "description": "Operation-specific data. For PASSKEY_ENROLL, must include stampedRequest with url, body, and stamp from the enroll/prepare step." } } }, "WebAuthnRegisterInitResponseDto": { "type": "object", "properties": { "rpId": { "type": "string" }, "mode": { "type": "string", "enum": [ "bootstrap", "already_bootstrapped" ] } }, "required": [ "rpId", "mode" ] }, "WebAuthnAttestationDto": { "type": "object", "properties": { "credentialId": { "type": "string" }, "clientDataJson": { "type": "string" }, "attestationObject": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "credentialId", "clientDataJson", "attestationObject", "transports" ] }, "WebAuthnRegisterCompleteRequestDto": { "type": "object", "properties": { "encodedChallenge": { "type": "string", "description": "Base64url-encoded challenge from passkey creation" }, "attestation": { "description": "WebAuthn attestation from navigator.credentials.create", "allOf": [ { "$ref": "#/components/schemas/WebAuthnAttestationDto" } ] } }, "required": [ "encodedChallenge", "attestation" ] }, "WebAuthnRegisterCompleteResponseDto": { "type": "object", "properties": { "registered": { "type": "boolean" }, "isRoot": { "type": "boolean" }, "credentialId": { "type": "string" }, "webauthnCredentialId": { "type": "string", "description": "ID of the credential on the device, used later for lookup. Differs from credentialId, which is the internal Koywe credential record ID.", "example": "cred-id-abc" } }, "required": [ "registered", "isRoot" ] }, "WebAuthnChallengeResponseDto": { "type": "object", "properties": { "challenge": { "type": "string", "description": "Random nonce to be signed by the passkey" }, "bodyToSign": { "type": "string", "description": "The exact JSON body the client must sign with the passkey. Hash this with SHA-256, then text-encode the hex as the WebAuthn challenge." }, "rpId": { "type": "string", "description": "Relying party ID for WebAuthn operations" } }, "required": [ "challenge", "bodyToSign", "rpId" ] }, "WebAuthnVerifyRequestDto": { "type": "object", "properties": { "challenge": { "type": "string", "description": "The challenge nonce that was signed" }, "signedStamp": { "description": "Signed stamp from the embedded wallet SDK proving passkey ownership", "allOf": [ { "$ref": "#/components/schemas/SignedStampDto" } ] } }, "required": [ "challenge", "signedStamp" ] }, "WebAuthnVerifyResponseDto": { "type": "object", "properties": { "mfaToken": { "type": "string", "description": "Short-lived MFA JWT (5 minutes)" } }, "required": [ "mfaToken" ] }, "WebAuthnCredentialInfoDto": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "userEmail": { "type": "string" }, "userName": { "type": "string" }, "isRoot": { "type": "boolean" }, "credentialName": { "type": "string" }, "webauthnCredentialId": { "type": "string", "description": "ID of the credential on the device, used later for lookup. Differs from credentialId, which is the internal Koywe credential record ID.", "example": "cred-id-abc" }, "registeredAt": { "format": "date-time", "type": "string" }, "lastUsedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "userId", "isRoot", "credentialName", "registeredAt" ] }, "WebAuthnInviteRequestDto": { "type": "object", "properties": { "targetUserId": { "type": "string", "description": "User ID of the person being invited" }, "encodedChallenge": { "type": "string", "description": "Base64url-encoded challenge from passkey creation" }, "attestation": { "description": "WebAuthn attestation from navigator.credentials.create", "allOf": [ { "$ref": "#/components/schemas/WebAuthnAttestationDto" } ] } }, "required": [ "targetUserId", "encodedChallenge", "attestation" ] }, "WebAuthnInviteResponseDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string" }, "result": { "type": "string" } }, "required": [ "pendingApprovalId", "result" ] }, "WebAuthnEnrollPrepareRequestDto": { "type": "object", "properties": { "pendingApprovalId": { "type": "string", "description": "ID of the PolicyPendingApproval to prepare for signing" } }, "required": [ "pendingApprovalId" ] }, "WebAuthnEnrollPrepareResponseDto": { "type": "object", "properties": { "body": { "type": "string", "description": "JSON-stringified enrollment body — root user must sign this exact string" } }, "required": [ "body" ] }, "WebAuthnWalletPrepareRequestDto": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Merchant id to provision the embedded wallet for" } }, "required": [ "merchantId" ] }, "WebAuthnWalletPrepareResponseDto": { "type": "object", "properties": { "alreadyExists": { "type": "boolean" }, "address": { "type": "string" }, "body": { "type": "string", "description": "JSON-stringified embedded wallet provisioning request that must be signed exactly as returned" } }, "required": [ "alreadyExists" ] }, "WebAuthnWalletStatusResponseDto": { "type": "object", "properties": { "organizationBootstrapped": { "type": "boolean" }, "organizationWalletExists": { "type": "boolean" }, "merchantWalletAccountExists": { "type": "boolean" }, "usdBankAccountExists": { "type": "boolean" }, "bankAccountBound": { "type": "boolean" }, "requiresProvisioning": { "type": "boolean" }, "address": { "type": "string" } }, "required": [ "organizationBootstrapped", "organizationWalletExists", "merchantWalletAccountExists", "usdBankAccountExists", "bankAccountBound", "requiresProvisioning" ] }, "WebAuthnWalletCompleteRequestDto": { "type": "object", "properties": { "merchantId": { "type": "string", "description": "Merchant id to provision the embedded wallet for" }, "stampedRequest": { "description": "The wallet provisioning request stamped by the user passkey. This is forwarded to the signing provider and never persisted.", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "merchantId", "stampedRequest" ] }, "WebAuthnWalletCompleteResponseDto": { "type": "object", "properties": { "created": { "type": "boolean" }, "address": { "type": "string" } }, "required": [ "created", "address" ] }, "RecoveryInitiateRequestDto": { "type": "object", "properties": { "targetUserId": { "type": "string", "description": "User ID of the locked-out user" } }, "required": [ "targetUserId" ] }, "RecoveryInitiateResponseDto": { "type": "object", "properties": { "otpId": { "type": "string", "description": "OTP ID — pass this to the locked-out user for verify-otp step" }, "targetEmail": { "type": "string", "description": "Masked email where the OTP was sent (e.g., g***@koywe.com)" } }, "required": [ "otpId", "targetEmail" ] }, "RecoveryVerifyOtpRequestDto": { "type": "object", "properties": { "otpId": { "type": "string", "description": "OTP ID returned from the initiate step" }, "otpCode": { "type": "string", "description": "6-digit OTP code received via email" }, "targetPublicKey": { "type": "string", "description": "Target public key generated by the embedded wallet client. Used to create an ephemeral session for passkey registration." } }, "required": [ "otpId", "otpCode", "targetPublicKey" ] }, "RecoveryVerifyOtpResponseDto": { "type": "object", "properties": { "credentialBundle": { "type": "string", "description": "Ephemeral credential bundle for client-side recovery operations" }, "providerUserId": { "type": "string", "description": "Signing-provider user ID of the recovered user" } }, "required": [ "credentialBundle", "providerUserId" ] }, "RecoveryPrepareRequestDto": { "type": "object", "properties": { "encodedChallenge": { "type": "string", "description": "Base64url-encoded challenge from the new passkey creation" }, "attestation": { "description": "WebAuthn attestation from navigator.credentials.create for the new passkey", "allOf": [ { "$ref": "#/components/schemas/WebAuthnAttestationDto" } ] } }, "required": [ "encodedChallenge", "attestation" ] }, "RecoveryPrepareResponseDto": { "type": "object", "properties": { "body": { "type": "string", "description": "JSON-stringified createAuthenticators body — client must stamp this exact string" } }, "required": [ "body" ] }, "RecoveryCompleteRequestDto": { "type": "object", "properties": { "stampedRequest": { "description": "The embedded wallet recovery request stamped with the ephemeral API key from the credential bundle. Required to register the new passkey.", "allOf": [ { "$ref": "#/components/schemas/StampedRequestDto" } ] } }, "required": [ "stampedRequest" ] }, "RecoveryCompleteResponseDto": { "type": "object", "properties": { "recovered": { "type": "boolean" }, "credentialId": { "type": "string" }, "webauthnCredentialId": { "type": "string", "description": "ID of the credential on the device, used later for lookup. Differs from credentialId, which is the internal Koywe credential record ID.", "example": "cred-id-abc" } }, "required": [ "recovered" ] }, "RecoverySessionInfoDto": { "type": "object", "properties": { "id": { "type": "string" }, "targetUserId": { "type": "string" }, "initiatedByUserId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "COMPLETED", "EXPIRED" ] }, "createdAt": { "format": "date-time", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "targetUserId", "initiatedByUserId", "status", "createdAt", "expiresAt" ] }, "NotificationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "d2dd8481-3552-4466-b99e-a7caad69a302" }, "merchantId": { "type": "string", "example": "koywe-3-sys" }, "orderId": { "type": [ "string", "null" ], "example": "ord_abc123" }, "orderType": { "type": [ "string", "null" ], "example": "PAYIN" }, "eventType": { "type": "string", "example": "order.completed" }, "title": { "type": "string", "example": "Tu pago se completó" }, "body": { "type": [ "string", "null" ], "example": "El pago de $500 USD fue procesado correctamente." }, "read": { "type": "boolean", "example": false }, "readAt": { "format": "date-time", "type": [ "string", "null" ], "example": null }, "createdAt": { "format": "date-time", "type": "string", "example": "2026-04-13T18:00:00.000Z" }, "metadata": { "type": [ "object", "null" ], "example": null } }, "required": [ "id", "merchantId", "orderId", "orderType", "eventType", "title", "body", "read", "readAt", "createdAt", "metadata" ] }, "NotificationListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationResponseDto" } }, "total": { "type": "number", "example": 10 }, "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 50 } }, "required": [ "data", "total", "page", "limit" ] }, "UnreadCountResponseDto": { "type": "object", "properties": { "count": { "type": "integer", "example": 3, "minimum": 0 } }, "required": [ "count" ] }, "MarkAllReadResponseDto": { "type": "object", "properties": { "updated": { "type": "integer", "example": 5, "minimum": 0 } }, "required": [ "updated" ] }, "MarkReadResponseDto": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } }, "required": [ "ok" ] }, "NotificationSettingsResponseDto": { "type": "object", "properties": { "emailEnabled": { "type": "boolean", "description": "Whether email notifications are enabled for this merchant", "example": false }, "recipients": { "description": "List of recipient email addresses", "example": [ "ops@merchant.com" ], "type": "array", "items": { "type": "string" } } }, "required": [ "emailEnabled", "recipients" ] }, "UpdateNotificationSettingsDto": { "type": "object", "properties": { "emailEnabled": { "type": "boolean", "description": "Whether email notifications are enabled for this merchant", "example": true }, "recipients": { "description": "List of recipient email addresses for order notifications. Optional when emailEnabled is false; at least one valid email required when emailEnabled is true.", "example": [ "ops@merchant.com", "finance@merchant.com" ], "type": "array", "items": { "type": "string" } } }, "required": [ "emailEnabled" ] }, "SimulateSandboxBankIncomeDto": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "ARS", "MXN", "USD" ], "example": "ARS", "description": "Selected sandbox currency. This determines which fake virtual account is provisioned." }, "amount": { "type": "number", "example": 500000, "description": "Credited amount to simulate." }, "documentType": { "type": "string", "example": "CUIT", "description": "Depositor document type. Required for ARS and MXN simulations unless validation is bypassed by merchant flags." }, "documentNumber": { "type": "string", "example": "30712345678", "description": "Depositor document number. Required for ARS and MXN simulations unless validation is bypassed by merchant flags." }, "customerReference": { "type": "string", "example": "customer-test-001", "description": "Optional customer reference used to make the simulated movement easier to trace." } }, "required": [ "currency", "amount" ] }, "SimulateSandboxBankIncomeResponseDto": { "type": "object", "properties": { "referenceId": { "type": "string", "example": "bm_1234567890", "description": "Reference ID of the registered bank income." }, "virtualAccount": { "description": "Virtual account used for the simulated deposit.", "allOf": [ { "$ref": "#/components/schemas/PayInVirtualBankAccountResponseDto" } ] }, "virtualAccountProvisioned": { "type": "boolean", "example": true, "description": "Whether the endpoint provisioned a fake virtual account during this call." } }, "required": [ "referenceId", "virtualAccount", "virtualAccountProvisioned" ] } } } }