{ "openapi": "3.0.0", "paths": { "/v1/banks": { "get": { "operationId": "getBanks", "summary": "List supported banks", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankResponseDto" } } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/quote": { "get": { "operationId": "getQuote", "summary": "Quote a USD amount in VES at the current BCV rate", "description": "Returns the authoritative VEX FX BCV rate (bcvRate/vesAmount) used for payment settlement, plus medianRate/medianVesAmount from available BCV sources (VEX FX and R4 when configured).", "parameters": [ { "name": "usdAmount", "required": true, "in": "query", "schema": { "example": 25, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponseDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/c2p/request": { "post": { "operationId": "requestC2p", "summary": "Create a pending C2P payment intent", "description": "The tenant must collect the bank-issued token from the customer before executing the intent.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/C2pRequestDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/C2pIntentResponseDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/c2p": { "post": { "operationId": "executeC2p", "summary": "Execute a C2P charge", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/C2pPaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "The supplied intent does not exist or is no longer pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "The provider rejected the charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/vpos": { "post": { "operationId": "executeVpos", "summary": "Execute a VPOS card charge", "description": "BNC only. Submit card data only from a PCI-compliant server.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VposPaymentDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "422": { "description": "The provider rejected the charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/pago-movil/verify": { "post": { "operationId": "verifyPagoMovil", "summary": "Verify a customer-originated Pago Móvil transfer", "description": "BNC only.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagoMovilVerifyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/by-ref/{externalRef}": { "get": { "operationId": "getPaymentByRef", "summary": "Find the latest payment with an external reference", "description": "externalRef is not unique and does not prevent duplicate payments.", "parameters": [ { "name": "externalRef", "required": true, "in": "path", "schema": { "example": "order-1042", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "Get a payment by ID", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/{id}/reverse": { "post": { "operationId": "reversePayment", "summary": "Reverse a completed C2P payment", "description": "Reversal is supported for C2P payments only.", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReceiptDto" } } } }, "400": { "description": "Invalid request or unsupported operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/debit/otp": { "post": { "operationId": "generarOtp", "summary": "Send a debit authorization code to the customer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDebitOtpDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/debit": { "post": { "operationId": "debitoInmediato", "summary": "Execute an immediate debit", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImmediateDebitDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/operations/{id}": { "get": { "operationId": "consultarOperacion", "summary": "Poll a pending payment operation", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment operation ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/credit": { "post": { "operationId": "creditoInmediato", "summary": "Execute an immediate credit by phone", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImmediateCreditDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/credit/account": { "post": { "operationId": "creditoCuentas", "summary": "Execute a credit to a bank account", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreditDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/credit/disburse": { "post": { "operationId": "dispersarCredito", "summary": "Disburse credits by phone", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditDisbursementDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/payouts": { "post": { "operationId": "dispersarPagos", "summary": "Disburse payments to bank accounts", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/payments/change": { "post": { "operationId": "ejecutarVuelto", "summary": "Send change to a customer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePaymentDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "503": { "description": "The payment service is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Advanced payments" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register a webhook endpoint", "description": "The signing secret is returned only on creation. Delivery currently uses one attempt with a 10-second timeout.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Webhooks" ], "security": [ { "tenant-api-key": [] } ] }, "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "description": "Signing secrets are never included.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointDto" } } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Webhooks" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint and its delivery history", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookResponseDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Webhooks" ], "security": [ { "tenant-api-key": [] } ] } }, "/v1/notifications/test": { "post": { "operationId": "sendTest", "summary": "Send a test event to subscribed webhook endpoints", "parameters": [], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationTestResponseDto" } } } }, "401": { "description": "Missing, invalid, or inactive tenant API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" } } } } }, "tags": [ "Webhooks" ], "security": [ { "tenant-api-key": [] } ] } } }, "info": { "title": "VE Banking Tenant API", "description": "Tenant-facing API for collecting Venezuelan payments.\n\nAuthenticate with the `x-api-key` header. For C2P, create an intent, collect the bank-issued token from your customer, then execute the payment. VE Banking does not contact the customer on your behalf.\n\n`externalRef` is a correlation value, not an idempotency key. Reusing it can create duplicate payments.", "version": "1.0", "contact": {} }, "tags": [], "servers": [ { "url": "/", "description": "Current environment" } ], "components": { "securitySchemes": { "tenant-api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Tenant API key. Keep it server-side and rotate it if exposed." } }, "schemas": { "ApiErrorDto": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "error": { "type": "string", "example": "Bad Request" } }, "required": [ "statusCode", "message" ] }, "BankResponseDto": { "type": "object", "properties": { "code": { "type": "string", "example": "0102", "description": "Canonical four-digit SIMF bank code." }, "name": { "type": "string", "example": "Banco de Venezuela" }, "services": { "description": "Provider-reported services; may be empty.", "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "services" ] }, "QuoteResponseDto": { "type": "object", "properties": { "usdAmount": { "type": "number", "example": 25 }, "bcvRate": { "type": "number", "example": 36.5, "description": "Authoritative VEX FX BCV rate used for payment settlement" }, "vesAmount": { "type": "number", "example": 912.5 }, "medianRate": { "type": "number", "example": 36.55, "description": "Median of available BCV sources (VEX FX + R4)" }, "medianVesAmount": { "type": "number", "example": 913.75, "description": "USD amount converted at medianRate" }, "source": { "type": "string", "example": "bcv" }, "fetchedAt": { "type": "string", "format": "date-time" }, "sources": { "type": "object", "additionalProperties": true } }, "required": [ "usdAmount", "bcvRate", "vesAmount", "medianRate", "medianVesAmount", "source", "fetchedAt", "sources" ] }, "C2pRequestDto": { "type": "object", "properties": { "usdAmount": { "type": "number", "minimum": 0.01, "maximum": 100000, "example": 25 }, "debtorId": { "type": "string", "example": "V12345678" }, "debtorCellPhone": { "type": "string", "example": "584121234567", "description": "Country code 58 followed by 10 digits." }, "debtorBankCode": { "type": "number", "example": 102, "description": "Bank code accepted as a number; use GET /v1/banks to discover supported banks." }, "externalRef": { "type": "string", "maxLength": 64, "example": "order-1042", "description": "Correlation value; not an idempotency key." } }, "required": [ "usdAmount", "debtorId", "debtorCellPhone", "debtorBankCode" ] }, "C2pIntentResponseDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid", "example": "3fd84b2d-9ad1-4f74-a2d9-0f2f56984db5" }, "externalRef": { "type": "string", "example": "order-1042", "description": "Tenant correlation value; not an idempotency key." }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "REVERSED" ] }, "method": { "type": "string", "enum": [ "C2P", "VPOS", "PAGO_MOVIL" ] }, "usdAmount": { "type": "number", "example": 25 }, "vesAmount": { "type": "number", "example": 912.5 }, "bcvRate": { "type": "number", "example": 36.5 }, "bankReference": { "type": "string", "example": "00512673" }, "bankTxId": { "type": "number", "example": 842901 }, "debtorId": { "type": "string", "example": "V12345678" }, "debtorPhone": { "type": "string", "example": "584121234567" }, "debtorBankCode": { "type": "number", "example": 102 }, "debtorBankName": { "type": "string", "example": "Banco de Venezuela" }, "cardLast4": { "type": "string", "example": "4242" }, "cardBrand": { "type": "string", "example": "Visa" }, "cardProduct": { "type": "string", "example": "Crédito" }, "accountTypeLabel": { "type": "string", "example": "Cuenta corriente" }, "tenantName": { "type": "string", "example": "Comercio Demo" }, "createdAt": { "type": "string", "format": "date-time" }, "failureCode": { "type": "string", "example": "MOVEMENT_NOT_FOUND" }, "reversedAt": { "type": "string", "format": "date-time" }, "reversalRef": { "type": "string", "example": "00991420" }, "reversalTxId": { "type": "number", "example": 842950 }, "intentId": { "type": "string", "format": "uuid", "description": "Use this value as intentId when executing the C2P charge." } }, "required": [ "paymentId", "status", "method", "usdAmount", "vesAmount", "bcvRate", "tenantName", "createdAt", "intentId" ] }, "C2pPaymentDto": { "type": "object", "properties": { "intentId": { "type": "string", "format": "uuid", "description": "Pending intent returned by POST /v1/payments/c2p/request." }, "usdAmount": { "type": "number", "minimum": 0.01, "maximum": 100000, "example": 25 }, "debtorId": { "type": "string", "example": "V12345678" }, "debtorCellPhone": { "type": "string", "example": "584121234567" }, "debtorBankCode": { "type": "number", "example": 102 }, "token": { "type": "string", "pattern": "^\\d{6,8}$", "example": "123456", "description": "Bank-issued token collected by the tenant from the customer." }, "externalRef": { "type": "string", "maxLength": 64, "example": "order-1042", "description": "Correlation value; not an idempotency key." } }, "required": [ "usdAmount", "debtorId", "debtorCellPhone", "debtorBankCode", "token" ] }, "PaymentReceiptDto": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid", "example": "3fd84b2d-9ad1-4f74-a2d9-0f2f56984db5" }, "externalRef": { "type": "string", "example": "order-1042", "description": "Tenant correlation value; not an idempotency key." }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED", "REVERSED" ] }, "method": { "type": "string", "enum": [ "C2P", "VPOS", "PAGO_MOVIL" ] }, "usdAmount": { "type": "number", "example": 25 }, "vesAmount": { "type": "number", "example": 912.5 }, "bcvRate": { "type": "number", "example": 36.5 }, "bankReference": { "type": "string", "example": "00512673" }, "bankTxId": { "type": "number", "example": 842901 }, "debtorId": { "type": "string", "example": "V12345678" }, "debtorPhone": { "type": "string", "example": "584121234567" }, "debtorBankCode": { "type": "number", "example": 102 }, "debtorBankName": { "type": "string", "example": "Banco de Venezuela" }, "cardLast4": { "type": "string", "example": "4242" }, "cardBrand": { "type": "string", "example": "Visa" }, "cardProduct": { "type": "string", "example": "Crédito" }, "accountTypeLabel": { "type": "string", "example": "Cuenta corriente" }, "tenantName": { "type": "string", "example": "Comercio Demo" }, "createdAt": { "type": "string", "format": "date-time" }, "failureCode": { "type": "string", "example": "MOVEMENT_NOT_FOUND" }, "reversedAt": { "type": "string", "format": "date-time" }, "reversalRef": { "type": "string", "example": "00991420" }, "reversalTxId": { "type": "number", "example": 842950 } }, "required": [ "paymentId", "status", "method", "usdAmount", "vesAmount", "bcvRate", "tenantName", "createdAt" ] }, "VposPaymentDto": { "type": "object", "properties": { "usdAmount": { "type": "number", "minimum": 0.01, "maximum": 100000, "example": 25 }, "cardNumber": { "type": "string", "pattern": "^\\d{13,19}$", "example": "4111111111111111", "description": "Handle only in a PCI-compliant server environment." }, "expirationMonth": { "type": "number", "minimum": 1, "maximum": 12, "example": 12 }, "expirationYear": { "type": "number", "minimum": 2020, "maximum": 2099, "example": 2028 }, "cvv": { "type": "string", "pattern": "^\\d{3,4}$", "example": "123", "writeOnly": true }, "cardPin": { "type": "string", "pattern": "^\\d{4}$", "example": "1234", "writeOnly": true }, "cardHolderName": { "type": "string", "minLength": 2, "maxLength": 80, "example": "Maria Perez" }, "cardHolderId": { "type": "string", "example": "V12345678" }, "accountType": { "type": "number", "enum": [ 0, 10, 20 ], "example": 0, "description": "0 credit, 10 savings, 20 checking." }, "cardType": { "type": "number", "enum": [ 1, 2, 3 ], "example": 1, "description": "Provider card-brand code." }, "externalRef": { "type": "string", "maxLength": 64, "example": "order-1042", "description": "Correlation value; not an idempotency key." } }, "required": [ "usdAmount", "cardNumber", "expirationMonth", "expirationYear", "cvv", "cardHolderName", "cardHolderId", "accountType", "cardType" ] }, "PagoMovilVerifyDto": { "type": "object", "properties": { "usdAmount": { "type": "number", "minimum": 0.01, "maximum": 100000, "example": 25 }, "reference": { "type": "string", "minLength": 4, "maxLength": 32, "example": "12345678" }, "dateMovement": { "type": "string", "format": "date", "example": "2026-07-20" }, "externalRef": { "type": "string", "maxLength": 64, "example": "order-1042", "description": "Correlation value; not an idempotency key." } }, "required": [ "usdAmount", "reference" ] }, "GenerateDebitOtpDto": { "type": "object", "properties": { "banco": { "type": "string", "example": "0191", "pattern": "^\\d{3,4}$" }, "monto": { "type": "number", "example": 50, "minimum": 0.01, "maximum": 1000000 }, "telefono": { "type": "string", "example": "584121234567" }, "cedula": { "type": "string", "example": "V12345678" } }, "required": [ "banco", "monto", "telefono", "cedula" ] }, "ImmediateDebitDto": { "type": "object", "properties": { "banco": { "type": "string", "example": "0191", "pattern": "^\\d{3,4}$" }, "monto": { "type": "number", "example": 50, "minimum": 0.01, "maximum": 1000000 }, "telefono": { "type": "string", "example": "584121234567" }, "cedula": { "type": "string", "example": "V12345678" }, "nombre": { "type": "string", "example": "Maria Perez", "maxLength": 20 }, "otp": { "type": "string", "example": "123456", "pattern": "^\\d{6,8}$" }, "concepto": { "type": "string", "example": "Pago de factura", "maxLength": 30 } }, "required": [ "banco", "monto", "telefono", "cedula", "nombre", "otp", "concepto" ] }, "ImmediateCreditDto": { "type": "object", "properties": { "banco": { "type": "string", "example": "0191" }, "cedula": { "type": "string", "example": "V12345678" }, "telefono": { "type": "string", "example": "584121234567" }, "monto": { "type": "number", "example": 50, "minimum": 0.01, "maximum": 1000000 }, "concepto": { "type": "string", "example": "Pago de factura", "maxLength": 30 } }, "required": [ "banco", "cedula", "telefono", "monto", "concepto" ] }, "AccountCreditDto": { "type": "object", "properties": { "cedula": { "type": "string", "example": "V12345678" }, "cuenta": { "type": "string", "example": "01910000000000000000", "minLength": 20, "maxLength": 20 }, "monto": { "type": "number", "example": 50 }, "concepto": { "type": "string", "example": "Pago de factura", "maxLength": 30 } }, "required": [ "cedula", "cuenta", "monto", "concepto" ] }, "CreditRecipientDto": { "type": "object", "properties": { "banco": { "type": "string", "example": "0191" }, "cedula": { "type": "string", "example": "V12345678" }, "telefono": { "type": "string", "example": "584121234567" }, "montoPart": { "type": "number", "example": 25 } }, "required": [ "banco", "cedula", "telefono", "montoPart" ] }, "CreditDisbursementDto": { "type": "object", "properties": { "monto": { "type": "number", "example": 50 }, "referencia": { "type": "string", "example": "12345678" }, "concepto": { "type": "string", "example": "Dispersión", "maxLength": 30 }, "personas": { "type": "array", "items": { "$ref": "#/components/schemas/CreditRecipientDto" } } }, "required": [ "monto", "referencia", "concepto", "personas" ] }, "PayoutRecipientDto": { "type": "object", "properties": { "nombres": { "type": "string", "example": "Maria Perez", "maxLength": 80 }, "documento": { "type": "string", "example": "V12345678" }, "destino": { "type": "string", "example": "01910000000000000000", "minLength": 20, "maxLength": 20 }, "montoPart": { "type": "number", "example": 25 } }, "required": [ "nombres", "documento", "destino", "montoPart" ] }, "PayoutDto": { "type": "object", "properties": { "monto": { "type": "number", "example": 50 }, "fecha": { "type": "string", "example": "07/20/2026", "pattern": "^\\d{2}/\\d{2}/\\d{4}$" }, "referencia": { "type": "string", "example": "12345678" }, "personas": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutRecipientDto" } } }, "required": [ "monto", "fecha", "referencia", "personas" ] }, "ChangePaymentDto": { "type": "object", "properties": { "telefonoDestino": { "type": "string", "example": "584121234567" }, "cedula": { "type": "string", "example": "V12345678" }, "banco": { "type": "string", "example": "0191" }, "monto": { "type": "number", "example": 5 }, "concepto": { "type": "string", "example": "Vuelto de compra", "maxLength": 30 }, "ip": { "type": "string", "example": "203.0.113.10", "maxLength": 15 } }, "required": [ "telefonoDestino", "cedula", "banco", "monto" ] }, "CreateWebhookDto": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://merchant.example.com/webhooks/ve-banking" }, "secret": { "type": "string", "description": "Signing secret. If omitted, a random secret is generated and returned once.", "example": "replace-with-a-long-random-secret" }, "events": { "type": "array", "example": [ "payment.completed", "payment.failed" ], "items": { "type": "string", "enum": [ "payment.pending", "payment.completed", "payment.failed", "payment.reversed", "tenant.status_changed", "tenant.api_key.rotated", "notification.test" ] } } }, "required": [ "url", "events" ] }, "WebhookEndpointDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "payment.pending", "payment.completed", "payment.failed", "payment.reversed", "tenant.status_changed", "tenant.api_key.rotated", "notification.test" ] } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Returned only when the endpoint is created. Store it securely; list responses omit it." } }, "required": [ "id", "tenantId", "url", "events", "isActive", "createdAt" ] }, "DeleteWebhookResponseDto": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } }, "required": [ "deleted" ] }, "NotificationTestResponseDto": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true }, "event": { "type": "string", "example": "notification.test" }, "tenantId": { "type": "string", "format": "uuid" } }, "required": [ "sent", "event", "tenantId" ] } } } }