{ "openapi": "3.1.0", "info": { "title": "OrvenPay API", "version": "2026-11-08", "summary": "Pasarela de pagos en criptomonedas custodial.", "description": "API nativa (/v1, cabecera X-Api-Key), endpoints públicos del checkout (/public) y API Gateway (/gateway/api/v1, api_key + verify_hash). Documentación completa: https://orvenpay.com/llms-full.txt" }, "externalDocs": { "description": "Documentación", "url": "https://orvenpay.com/docs" }, "servers": [ { "url": "https://api.orvenpay.com", "description": "API" } ], "security": [ { "ApiKeyHeader": [] } ], "tags": [ { "name": "Facturas" }, { "name": "Monedas" }, { "name": "Fondos" }, { "name": "Público", "description": "Sin autenticación; para la página de pago." }, { "name": "API Gateway", "description": "Formato api_key + verify_hash. Base para plugins: https://api.orvenpay.com/gateway" } ], "paths": { "/v1/invoices": { "post": { "tags": [ "Facturas" ], "operationId": "createInvoice", "summary": "Crear factura", "description": "Idempotente por orderNumber: repetir con los mismos datos de importe devuelve 200 con existing=true; con otros datos, 409 DUPLICATE_ORDER. Tiendas estándar: address=null (el cliente paga en invoiceUrl). Tiendas White Label: datos completos.", "security": [ { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } } }, "responses": { "200": { "description": "Ya existía (misma petición repetida)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelopeCreate" } } } }, "201": { "description": "Factura creada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelopeCreate" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } }, "get": { "tags": [ "Facturas" ], "operationId": "listInvoices", "summary": "Listar facturas (cursor)", "security": [ { "ApiKeyHeader": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 64 }, "description": "nextCursor de la página anterior." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Estados separados por coma: NEW, PENDING, COMPLETED, MISMATCH, EXPIRED, CANCELLED, ERROR." }, { "name": "orderNumber", "in": "query", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/invoices/{id}": { "get": { "tags": [ "Facturas" ], "operationId": "getInvoice", "summary": "Consultar factura", "security": [ { "ApiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/invoices/{id}/cancel": { "post": { "tags": [ "Facturas" ], "operationId": "cancelInvoice", "summary": "Cancelar factura (sólo NEW)", "security": [ { "ApiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/currencies": { "get": { "tags": [ "Monedas" ], "operationId": "listCurrencies", "summary": "Monedas activas", "security": [ { "ApiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Currency" } } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/balances": { "get": { "tags": [ "Fondos" ], "operationId": "getBalances", "summary": "Saldos de la cuenta", "security": [ { "ApiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balances" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/v1/withdrawals": { "post": { "tags": [ "Fondos" ], "operationId": "createWithdrawal", "summary": "Crear retiro a una dirección activa de la libreta", "security": [ { "ApiKeyHeader": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Alternativa a idempotencyKey en el cuerpo." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWithdrawalRequest" } } } }, "responses": { "200": { "description": "Repetición idempotente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEnvelope" } } } }, "201": { "description": "Retiro creado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEnvelope" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/withdrawals/{id}": { "get": { "tags": [ "Fondos" ], "operationId": "getWithdrawal", "summary": "Consultar retiro", "security": [ { "ApiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalEnvelope" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/public/config": { "get": { "tags": [ "Público" ], "operationId": "getPublicConfig", "summary": "Configuración pública", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConfig" } } } }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/public/invoices/{id}": { "get": { "tags": [ "Público" ], "operationId": "getPublicInvoice", "summary": "Estado de una factura para la página de pago", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/PublicInvoice" } } } } } }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/public/invoices/{id}/select-currency": { "post": { "tags": [ "Público" ], "operationId": "selectInvoiceCurrency", "summary": "Elegir moneda en una factura fiat", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency" ], "properties": { "currency": { "type": "string", "minLength": 1, "maxLength": 20 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/PublicInvoice" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/public/stores/{id}/logo": { "get": { "tags": [ "Público" ], "operationId": "getStoreLogo", "summary": "Logo de una tienda White Label", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "Imagen (PNG, JPEG o WebP)", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/public/invoices/{id}/events": { "get": { "tags": [ "Público" ], "operationId": "streamInvoiceEvents", "summary": "Server-Sent Events de la factura", "description": "Emite `event: invoice` con el objeto PublicInvoice cuando cambia; `: ping` periódico; cierra en estado final o a los 30 min. Máx. 3 conexiones por IP y 1 por (IP, factura).", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "Stream SSE", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/gateway/api/v1/invoices/new": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayCreateInvoice", "summary": "Crear factura (formato Gateway)", "description": "Parámetros en query y/o cuerpo (form o JSON; gana el cuerpo). Tiendas estándar: data = {txn_id, invoice_url, invoice_total_sum}. White Label: datos completos (GatewayInvoiceWhiteLabel).", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "order_number", "in": "query", "required": true, "description": "Id de pedido (1-128), único por tienda.", "schema": { "type": "string" } }, { "name": "order_name", "in": "query", "required": false, "description": "Concepto (máx. 255).", "schema": { "type": "string" } }, { "name": "description", "in": "query", "required": false, "description": "Máx. 1000.", "schema": { "type": "string" } }, { "name": "source_currency", "in": "query", "required": false, "description": "Fiat del precio (por defecto USD si hay source_amount) o código cripto.", "schema": { "type": "string" } }, { "name": "source_amount", "in": "query", "required": false, "description": "Precio en source_currency (decimal). Si está presente, amount se ignora.", "schema": { "type": "string" } }, { "name": "amount", "in": "query", "required": false, "description": "Importe en cripto; requiere currency/psys_cid.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Moneda (psys_cid o código nativo).", "schema": { "type": "string" } }, { "name": "psys_cid", "in": "query", "required": false, "description": "Alias de currency.", "schema": { "type": "string" } }, { "name": "allowed_psys_cids", "in": "query", "required": false, "description": "Lista separada por comas.", "schema": { "type": "string" } }, { "name": "callback_url", "in": "query", "required": false, "description": "URL de callbacks; con json=true en su query se envían como JSON.", "schema": { "type": "string" } }, { "name": "success_callback_url", "in": "query", "required": false, "description": "Callback adicional en completed.", "schema": { "type": "string" } }, { "name": "fail_callback_url", "in": "query", "required": false, "description": "Callback adicional en expired/cancelled/pago parcial expirado.", "schema": { "type": "string" } }, { "name": "success_invoice_url", "in": "query", "required": false, "description": "Retorno tras pagar (alias success_url).", "schema": { "type": "string" } }, { "name": "fail_invoice_url", "in": "query", "required": false, "description": "Retorno si falla (alias cancel_url, fail_url).", "schema": { "type": "string" } }, { "name": "email", "in": "query", "required": false, "description": "Email del cliente (máx. 254).", "schema": { "type": "string" } }, { "name": "expire_min", "in": "query", "required": false, "description": "Minutos de validez (máx. 1440).", "schema": { "type": "string" } }, { "name": "return_existing", "in": "query", "required": false, "description": "1/true: devuelve la factura existente si order_number ya existe.", "schema": { "type": "string" } }, { "name": "redirect_to_invoice", "in": "query", "required": false, "description": "1/true: responde 302 hacia la página de pago.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/GatewayInvoiceStandard" }, { "$ref": "#/components/schemas/GatewayInvoiceWhiteLabel" } ] } } } } } }, "302": { "description": "redirect_to_invoice=1: Location = página de pago" }, "400": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "429": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "503": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } }, "post": { "tags": [ "API Gateway" ], "operationId": "gatewayCreateInvoicePost", "summary": "Crear factura (formato Gateway, POST)", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GatewayInvoiceNewParams" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GatewayInvoiceNewParams" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/GatewayInvoiceStandard" }, { "$ref": "#/components/schemas/GatewayInvoiceWhiteLabel" } ] } } } } } }, "302": { "description": "redirect_to_invoice=1" }, "400": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "409": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "429": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/shops": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayShop", "summary": "Datos de la tienda", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "object", "required": [ "id", "name", "white_label" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "white_label": { "type": "boolean" } } } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayListOperations", "summary": "Listar operaciones (facturas de la tienda y retiros de la cuenta)", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Alias: per-page, page_size." }, { "name": "type", "in": "query", "schema": { "enum": [ "invoice", "cash_out" ] } }, { "name": "status", "in": "query", "schema": { "enum": [ "new", "pending", "completed", "mismatch", "expired", "cancelled", "error" ] } }, { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "psys_cid", "in": "query", "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "object", "required": [ "operations", "_links", "_meta" ], "properties": { "operations": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/GatewayInvoiceOperation" }, { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } ] } }, "_links": { "type": "object", "additionalProperties": { "type": "object", "properties": { "href": { "type": "string" } } } }, "_meta": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "pageCount": { "type": "integer" }, "currentPage": { "type": "integer" }, "perPage": { "type": "integer" } } } } } } } } } }, "400": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations/{id}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayGetOperation", "summary": "Consultar operación", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/GatewayInvoiceOperation" }, { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } ] } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations/withdraw": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayWithdraw", "summary": "Retiro (desactivado por defecto por tienda)", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" }, "description": "O psys_cid." }, { "name": "psys_cid", "in": "query", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Dirección activa de la libreta." }, { "name": "amount", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "const": "cash_out", "default": "cash_out" } } ], "responses": { "200": { "description": "Misma petición en 120 s", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } } } } } }, "201": { "description": "Retiro creado", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } } } } } }, "400": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "503": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } }, "post": { "tags": [ "API Gateway" ], "operationId": "gatewayWithdrawPost", "summary": "Retiro (POST)", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "to", "amount" ], "properties": { "currency": { "type": "string" }, "psys_cid": { "type": "string" }, "to": { "type": "string" }, "amount": { "type": "string" }, "type": { "const": "cash_out" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } } } } } }, "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayWithdrawalOperation" } } } } } }, "400": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "403": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations/fee/{psys_cid}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayWithdrawFee", "summary": "Fee de red de retiro", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "psys_cid", "in": "path", "required": true, "description": "psys_cid o código nativo.", "schema": { "type": "string", "maxLength": 20, "examples": [ "USDT_TRX" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "object", "properties": { "fee": { "type": "string" }, "psys_cid": { "type": "string" }, "currency": { "type": "string" }, "plan": { "const": "normal" } } } } } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations/fee-plan/{psys_cid}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayFeePlan", "summary": "Planes de fee", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "psys_cid", "in": "path", "required": true, "description": "psys_cid o código nativo.", "schema": { "type": "string", "maxLength": 20, "examples": [ "USDT_TRX" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayFeePlans" } } } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/operations/commission/{psys_cid}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayCommission", "summary": "Comisión y fee de retiro", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "psys_cid", "in": "path", "required": true, "description": "psys_cid o código nativo.", "schema": { "type": "string", "maxLength": 20, "examples": [ "USDT_TRX" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "object", "properties": { "commission": { "type": "string" }, "fee": { "type": "string" }, "plan": { "type": "string" }, "useWallet": { "type": "string" }, "useWalletBalance": { "type": "string" }, "plans": { "$ref": "#/components/schemas/GatewayFeePlans" } } } } } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/balances": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayBalances", "summary": "Saldo de una moneda (?currency=) o de todas", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "currency", "in": "query", "schema": { "type": "string" } }, { "name": "psys_cid", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/GatewayBalance" }, { "type": "array", "items": { "$ref": "#/components/schemas/GatewayBalance" } } ] } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/balances/{psys_cid}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayBalance", "summary": "Saldo de una moneda", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "psys_cid", "in": "path", "required": true, "description": "psys_cid o código nativo.", "schema": { "type": "string", "maxLength": 20, "examples": [ "USDT_TRX" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "$ref": "#/components/schemas/GatewayBalance" } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/currencies": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayCurrencies", "summary": "Monedas (precios en USD)", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayCurrency" } } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } }, "/gateway/api/v1/currencies/{fiat}": { "get": { "tags": [ "API Gateway" ], "operationId": "gatewayCurrenciesFiat", "summary": "Monedas con precios en una moneda fiat", "security": [ { "GatewayApiKeyQuery": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "fiat", "in": "path", "required": true, "schema": { "enum": [ "USD", "EUR", "GBP", "RUB", "UAH", "BRL", "MXN", "ARS", "COP", "CLP", "PEN", "VES", "TRY", "INR", "CNY", "JPY", "KRW", "CAD", "AUD", "CHF", "PLN", "NGN", "KZT", "IDR", "PHP", "VND", "THB", "AED", "SAR" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayCurrency" } } } } } } }, "401": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "422": { "description": "Error en formato Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } } } } }, "webhooks": { "orvenpayInvoiceEvent": { "post": { "summary": "Webhook OrvenPay (facturas de la API nativa y del panel)", "description": "Cabeceras: X-OrvenPay-Signature: t=,v1=; X-OrvenPay-Event; X-OrvenPay-Delivery; User-Agent OrvenPay-Webhooks/1.0. Responde 2xx en < 10 s; hasta 8 intentos (1m, 5m, 15m, 1h, 6h, 12h, 24h).", "parameters": [ { "name": "X-OrvenPay-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^t=\\d+,v1=[0-9a-f]{64}$" } }, { "name": "X-OrvenPay-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-OrvenPay-Delivery", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Cualquier 2xx confirma la entrega" } } } }, "gatewayCallback": { "post": { "summary": "Callback de la API Gateway (facturas creadas con invoices/new)", "description": "Formulario por defecto; JSON si callback_url contiene json=true. verify_hash = HMAC-SHA1(api_key que creó la factura, serialize(ksort(datos sin verify_hash))) en formulario, o de JSON.stringify(datos ordenados sin verify_hash) en JSON.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GatewayCallback" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCallback" } } } }, "responses": { "200": { "description": "Cualquier 2xx confirma la entrega" } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key de la tienda (op_live_...)." }, "GatewayApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "API key en la query string (también en el cuerpo o en X-Api-Key)." } }, "responses": { "Error400": { "description": "Petición inválida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "VALIDATION_ERROR", "message": "..." } } } } } } }, "Error401": { "description": "API key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "INVALID_API_KEY", "message": "..." } } } } } } }, "Error403": { "description": "Prohibido (cuenta suspendida, tienda inactiva, reglas de retiro)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "STORE_INACTIVE", "message": "..." } } } } } } }, "Error404": { "description": "No encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "NOT_FOUND", "message": "..." } } } } } } }, "Error409": { "description": "Conflicto", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "DUPLICATE_ORDER", "message": "..." } } } } } } }, "Error410": { "description": "Factura expirada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "INVOICE_EXPIRED", "message": "..." } } } } } } }, "Error429": { "description": "Rate limit. Cabecera Retry-After (segundos).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "RATE_LIMITED", "message": "..." } } } } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } }, "Error503": { "description": "Servicio no disponible temporalmente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ejemplo": { "value": { "error": { "code": "RATES_UNAVAILABLE", "message": "..." } } } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Código estable (ver catálogo de errores)." }, "message": { "type": "string" }, "details": {} } } } }, "CurrencyCode": { "type": "string", "enum": [ "BTC", "LTC", "TRX", "USDT_TRC20", "ETH", "USDT_ERC20", "USDC_ERC20", "BNB", "USDT_BEP20" ] }, "InvoiceStatus": { "type": "string", "enum": [ "NEW", "PENDING", "COMPLETED", "MISMATCH", "EXPIRED", "CANCELLED", "ERROR" ] }, "FeePaidBy": { "type": "string", "enum": [ "MERCHANT", "CUSTOMER" ] }, "CreateInvoiceRequest": { "type": "object", "required": [ "orderNumber" ], "description": "Indica sourceAmount (+sourceCurrency) o amount + currency.", "properties": { "orderNumber": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "number" } ] }, "orderName": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "sourceCurrency": { "type": "string", "maxLength": 10, "description": "Fiat (USD, EUR, GBP, RUB, UAH, BRL, MXN, ARS, COP, CLP, PEN, VES, TRY, INR, CNY, JPY, KRW, CAD, AUD, CHF, PLN, NGN, KZT, IDR, PHP, VND, THB, AED, SAR) o código cripto. Por defecto USD." }, "sourceAmount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,18}(\\.\\d{1,18})?$", "description": "Precio en sourceCurrency.", "examples": [ "49.90" ] }, { "type": "number", "exclusiveMinimum": 0 } ] }, "currency": { "type": "string", "maxLength": 20, "description": "Código o psysCid. Fija la cripto." }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,18}(\\.\\d{1,18})?$", "description": "Importe base en cripto (requiere currency)." }, { "type": "number", "exclusiveMinimum": 0 } ] }, "allowedCurrencies": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 20 } }, "callbackUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "successUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "failUrl": { "oneOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "expireMin": { "type": "integer", "minimum": 1, "maximum": 1440 }, "metadata": { "type": "object", "additionalProperties": true, "description": "Máx. 4 KB serializado." } }, "examples": [ { "orderNumber": "10245", "orderName": "Plan Pro mensual", "sourceCurrency": "USD", "sourceAmount": "49.90", "metadata": { "userId": "u_981" } } ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceId": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "txHash": { "type": "string" }, "logIndex": { "type": "integer" }, "fromAddress": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "toAddress": { "oneOf": [ { "type": "string", "description": "null en tiendas estándar." }, { "type": "null" } ] }, "amount": { "type": "string", "pattern": "^\\d{1,18}(\\.\\d{1,18})?$", "description": "Importe del pago." }, "confirmations": { "type": "integer" }, "blockNumber": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "DETECTED", "CONFIRMED", "ORPHANED" ] }, "explorerUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Invoice": { "type": "object", "required": [ "id", "status", "orderNumber", "invoiceUrl", "expiresAt", "whiteLabel" ], "properties": { "id": { "type": "string", "examples": [ "cmhx3v8qk0004l70gq2b9d7ma" ] }, "storeId": { "type": "string" }, "storeName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "API", "GATEWAY", "DASHBOARD" ] }, "orderNumber": { "type": "string" }, "orderName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "overpaid": { "type": "boolean" }, "sourceCurrency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "oneOf": [ { "$ref": "#/components/schemas/CurrencyCode" }, { "type": "null" } ] }, "symbol": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "rate": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "oneOf": [ { "type": "string", "description": "Total a pagar por el cliente." }, { "type": "null" } ] }, "baseAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amountReceived": { "type": "string" }, "pendingAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "oneOf": [ { "type": "string", "description": "Sólo White Label; null en tiendas estándar." }, { "type": "null" } ] }, "derivationIndex": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "confirmations": { "type": "integer" }, "requiredConfirmations": { "type": "integer" }, "allowedCurrencies": { "type": "array", "items": { "type": "string" } }, "feePercent": { "type": "string" }, "commission": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "feeAmount": { "type": "string" }, "feeAmountUsd": { "type": "string" }, "feePaidBy": { "$ref": "#/components/schemas/FeePaidBy" }, "networkFee": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "networkFeePaidBy": { "$ref": "#/components/schemas/FeePaidBy" }, "networkFeeCharged": { "type": "string" }, "callbackUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "successCallbackUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "failCallbackUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "successUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "failUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "invoiceUrl": { "type": "string", "format": "uri", "examples": [ "https://orvenpay.com/invoice/cmhx3v8qk0004l70gq2b9d7ma" ] }, "whiteLabel": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "paidAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" }, "description": "Ausente en el listado." } } }, "InvoiceEnvelope": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } }, "InvoiceEnvelopeCreate": { "type": "object", "required": [ "invoice", "existing" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" }, "existing": { "type": "boolean" } } }, "Currency": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/CurrencyCode" }, "psysCid": { "type": "string", "enum": [ "BTC", "LTC", "TRX", "USDT_TRX", "ETH", "USDT", "USDC", "BNB", "USDT_BSC" ] }, "name": { "type": "string" }, "symbol": { "type": "string" }, "icon": { "type": "string" }, "networkIcon": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "type": "string" }, "decimals": { "type": "integer" }, "displayDecimals": { "type": "integer" }, "confirmations": { "type": "integer" }, "rateUsd": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "withdrawalFee": { "type": "string" }, "available": { "type": "boolean" } } }, "Balances": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "network": { "type": "string" }, "icon": { "type": "string" }, "networkIcon": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "available": { "type": "string" }, "locked": { "type": "string" }, "withdrawable": { "type": "string" }, "maturingUntil": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "availableUsd": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "totalUsd": { "type": "string" }, "withdrawalsPaused": { "type": "boolean" } } }, "CreateWithdrawalRequest": { "type": "object", "required": [ "currency", "amount" ], "description": "Indica addressId o address (de tu libreta, activa).", "properties": { "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "addressId": { "type": "string", "maxLength": 64 }, "address": { "type": "string", "maxLength": 128 }, "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d{1,18}(\\.\\d{1,18})?$", "description": "Importe que recibe el destino.", "examples": [ "250" ] }, { "type": "number" } ] }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "address": { "type": "string" }, "amount": { "type": "string" }, "networkFee": { "type": "string" }, "total": { "type": "string" }, "amountUsd": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "PENDING_REVIEW", "APPROVED", "PROCESSING", "SENT", "CONFIRMED", "FAILED", "REJECTED", "CANCELLED" ] }, "auto": { "type": "boolean" }, "txHash": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "explorerUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewNote": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "sentAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "WithdrawalEnvelope": { "type": "object", "required": [ "withdrawal" ], "properties": { "withdrawal": { "$ref": "#/components/schemas/Withdrawal" } } }, "PublicConfig": { "type": "object", "properties": { "brandName": { "type": "string" }, "registrationOpen": { "type": "boolean" }, "maintenanceMode": { "type": "boolean" }, "withdrawalsPaused": { "type": "boolean" }, "pushPublicKey": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "feePercent": { "type": "string", "examples": [ "0.5" ] }, "whiteLabelFeePercent": { "type": "string", "examples": [ "1" ] }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/CurrencyCode" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "network": { "type": "string" }, "icon": { "type": "string" }, "networkIcon": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "withdrawalFee": { "type": "string" } } } } } }, "PublicInvoice": { "type": "object", "additionalProperties": true, "description": "Datos seguros para la página de pago. Puede ampliarse sin aviso.", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "overpaid": { "type": "boolean" }, "storeName": { "type": "string" }, "whiteLabel": { "type": "boolean" }, "branding": { "oneOf": [ { "type": "object", "description": "Sólo tiendas White Label.", "properties": { "name": { "type": "string" }, "color": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } }, { "type": "null" } ] }, "orderName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceCurrency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amountReceived": { "type": "string" }, "pendingAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "minAcceptedAmount": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "withinTolerance": { "type": "boolean" }, "address": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentUri": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "walletUri": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "confirmations": { "type": "integer" }, "requiredConfirmations": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" }, "paidAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "serverTime": { "type": "string", "format": "date-time" }, "successUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "failUrl": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "availableCurrencies": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "network": { "type": "string" }, "amountEstimate": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "networkFeeEstimate": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "payments": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "WebhookEvent": { "type": "object", "required": [ "event", "createdAt", "data" ], "properties": { "event": { "enum": [ "invoice.pending", "invoice.completed", "invoice.mismatch", "invoice.expired", "invoice.cancelled" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "orderNumber": { "type": "string" }, "orderName": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus" }, "overpaid": { "type": "boolean" }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "type": "string" }, "amountReceived": { "type": "string" }, "feeAmount": { "type": "string" }, "address": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceCurrency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceAmount": { "type": "string" }, "rate": { "type": "string" }, "confirmations": { "type": "integer" }, "requiredConfirmations": { "type": "integer" }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "paidAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "GatewayError": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "const": "error" }, "data": { "type": "object", "required": [ "name", "message", "code" ], "properties": { "name": { "type": "string", "examples": [ "Bad Request" ] }, "message": { "type": "string", "description": "En validación: JSON {\"campo\":\"motivo\"}." }, "code": { "type": "integer", "examples": [ 103 ] } } } } }, "GatewayInvoiceNewParams": { "type": "object", "required": [ "order_number" ], "properties": { "order_number": { "type": "string", "description": "Id de pedido (1-128), único por tienda." }, "order_name": { "type": "string", "description": "Concepto (máx. 255)." }, "description": { "type": "string", "description": "Máx. 1000." }, "source_currency": { "type": "string", "description": "Fiat del precio (por defecto USD si hay source_amount) o código cripto." }, "source_amount": { "type": "string", "description": "Precio en source_currency (decimal). Si está presente, amount se ignora." }, "amount": { "type": "string", "description": "Importe en cripto; requiere currency/psys_cid." }, "currency": { "type": "string", "description": "Moneda (psys_cid o código nativo)." }, "psys_cid": { "type": "string", "description": "Alias de currency." }, "allowed_psys_cids": { "type": "string", "description": "Lista separada por comas." }, "callback_url": { "type": "string", "description": "URL de callbacks; con json=true en su query se envían como JSON." }, "success_callback_url": { "type": "string", "description": "Callback adicional en completed." }, "fail_callback_url": { "type": "string", "description": "Callback adicional en expired/cancelled/pago parcial expirado." }, "success_invoice_url": { "type": "string", "description": "Retorno tras pagar (alias success_url)." }, "fail_invoice_url": { "type": "string", "description": "Retorno si falla (alias cancel_url, fail_url)." }, "email": { "type": "string", "description": "Email del cliente (máx. 254)." }, "expire_min": { "type": "string", "description": "Minutos de validez (máx. 1440)." }, "return_existing": { "type": "string", "description": "1/true: devuelve la factura existente si order_number ya existe." }, "redirect_to_invoice": { "type": "string", "description": "1/true: responde 302 hacia la página de pago." }, "api_key": { "type": "string", "description": "API key (alternativa a la query/cabecera)." } } }, "GatewayInvoiceStandard": { "type": "object", "required": [ "txn_id", "invoice_url", "invoice_total_sum" ], "properties": { "txn_id": { "type": "string" }, "invoice_url": { "type": "string", "format": "uri" }, "invoice_total_sum": { "type": "string", "description": "Vacío si aún no hay moneda." } } }, "GatewayInvoiceWhiteLabel": { "type": "object", "properties": { "txn_id": { "type": "string" }, "invoice_url": { "type": "string" }, "amount": { "type": "string" }, "pending_amount": { "type": "string" }, "wallet_hash": { "type": "string" }, "psys_cid": { "type": "string" }, "currency": { "type": "string" }, "status": { "type": "string" }, "source_currency": { "type": "string" }, "source_rate": { "type": "string" }, "expire_utc": { "type": "integer" }, "expected_confirmations": { "type": "string" }, "qr_code": { "type": "string", "description": "data:image/png;base64,..." }, "verify_hash": { "type": "string" }, "invoice_commission": { "type": "string" }, "invoice_sum": { "type": "string" }, "invoice_total_sum": { "type": "string" } } }, "GatewayInvoiceOperation": { "type": "object", "additionalProperties": true, "properties": { "type": { "const": "invoice" }, "id": { "type": "string" }, "status": { "type": "string" } } }, "GatewayWithdrawalOperation": { "type": "object", "additionalProperties": true, "properties": { "type": { "const": "cash_out" }, "id": { "type": "string" }, "status": { "type": "string" } } }, "GatewayBalance": { "type": "object", "properties": { "psys_cid": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" } } }, "GatewayFeePlans": { "type": "object", "properties": { "normal": { "type": "object", "properties": { "value": { "type": "string" } } }, "priority": { "type": "object", "properties": { "value": { "type": "string" } } } } }, "GatewayCurrency": { "type": "object", "properties": { "name": { "type": "string" }, "cid": { "type": "string" }, "currency": { "type": "string", "description": "psys_cid" }, "icon": { "type": "string" }, "rate_usd": { "type": "string" }, "price_usd": { "type": "string" }, "precision": { "type": "string" }, "output_precision": { "type": "string" }, "fiat": { "type": "string" }, "fiat_rate": { "type": "string" }, "min_sum_in": { "type": "string" }, "invoice_commission_percentage": { "type": "string" }, "hidden": { "type": "integer", "enum": [ 0, 1 ] }, "maintenance": { "type": "boolean" } } }, "GatewayCallback": { "type": "object", "description": "Todos los valores string; claves ordenadas (ksort) y verify_hash al final.", "properties": { "amount": { "type": "string" }, "comment": { "type": "string" }, "confirmations": { "type": "string" }, "currency": { "type": "string" }, "invoice_commission": { "type": "string" }, "invoice_sum": { "type": "string" }, "invoice_total_sum": { "type": "string" }, "ipn_type": { "type": "string" }, "merchant": { "type": "string" }, "merchant_id": { "type": "string" }, "order_name": { "type": "string" }, "order_number": { "type": "string" }, "pending_amount": { "type": "string" }, "psys_cid": { "type": "string" }, "source_amount": { "type": "string" }, "source_currency": { "type": "string" }, "source_rate": { "type": "string" }, "status": { "type": "string" }, "txn_id": { "type": "string" }, "wallet_hash": { "type": "string" }, "verify_hash": { "type": "string" } } } } } }