openapi: 3.1.0 servers: - url: https://api.onvopay.com description: ONVO REST API info: title: ONVO API version: "2.0" description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." tags: - name: Errores description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Paginación description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Monitoreo de fraude description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Autenticación 3DS description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Separar la autorización y la captura description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Marketplaces description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: SDK description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Métodos de pago de prueba description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Clientes description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Métodos de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Intenciones de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Reembolsos description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Productos description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Precios description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Cargos recurrentes description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Renovaciones description: "Las renovaciones representan cada período de cobro de un cargo recurrente. ONVO crea una renovación al inicio de la suscripción y en cada renovación exitosa. Cada renovación está asociada a una intención de pago y permite consultar el cobro que corresponde a ese período." - name: Tarifas de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Sesiones de Checkout description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Cupones description: "Crea y administra cupones que pueden aplicarse a Checkout." - name: SINPE Móvil description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Depósito Bancario (SINPE PIN) description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Métodos de pago de prueba description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Plugin de WordPress description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Extensión para Magento description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." - name: Webhooks description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." components: securitySchemes: PublishableApiKey: type: http scheme: bearer description: | Las Publishable API Keys están definidas para ser usadas desde código fuente client-side, donde están expuestas en el código fuente que es accesible desde el navegador. Se pueden identificar fácilmente por su prefijo `onvo_test_publishable_key_` o `onvo_live_publishable_key_`. Uno de los usos de las Publishable API Keys es para la creación de un nuevo método de pago y para autenticar nuestro SDK en tu integración. El Authorization header debe empezar con 'Bearer ' y luego el Publishable API Key que obtenés en el dashboard de ONVO. Ej: ``` 'Authorization': 'Bearer onvo_test_publishable_key_VL3ln7fwTC1DiJGvGE0H5A-XYPNJDmoGtwcduXYTRtsuKRc4d1PXEh33Ju9RZRXGJkX0KsRV5-F540ciRCQosQ' ``` bearerFormat: "Bearer onvo_api_key" SecretApiKey: type: http scheme: bearer description: | Las Secret API Keys están definidas para ser usadas desde código fuente server-side, donde deben mantenerse debidamente protegidas. Tus Secret API keys tienen muchos privilegios, mantenelas de forma segura. No compartás tus Secret API Keys ni las usés en código client-side. Se pueden identificar fácilmente por su prefijo `onvo_test_secret_key_` o `onvo_live_secret_key_`. Algunos de los usos de las Secret API Keys son crear una nueva intención de pago o un nuevo cargo recurrente. El Authorization header debe empezar con 'Bearer ' y luego la Secret API Key que obtenés en el dashboard de ONVO. Ej: ``` 'Authorization': 'Bearer onvo_test_secret_key_VL3ln7fwTC1DiJGvGE0H5A-XYPNJDmoGtwcduXYTRtsuKRc4d1PXEh33Ju9RZRXGJkX0KsRV5-F540ciRCQosQ' ``` bearerFormat: "Bearer onvo_api_key" schemas: WebhookSucceedePaymentIntentResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: payment-intent.succeeded data: type: object description: El payload con la información de la intención de pago procesada exitosamente. readOnly: true properties: id: type: string readOnly: true example: "clcl69c7m0011jbapzx04kwfw" accountId: type: string description: "Identificador de la cuenta asociada al Payment Intent" readOnly: true example: "cx2bdw8ez0078agdp6dgpwfm3" currency: type: string description: "La moneda utilizada para crear el Payment Intent" readOnly: true example: "USD" amount: type: number description: El monto total, en la moneda seleccionada y en centavos de la intención de pago procesada. readOnly: true example: 500000 status: type: string description: "El estado actual de la Intención de pago" readOnly: true example: "succeeded" confirmationAttempts: type: number description: La cantidad de veces que se intento procesar la intención de pago hasta que fue procesada correctamente. readOnly: true example: 1 description: type: string description: "El motivo de la intención de pago procesada" readOnly: true example: "Checkout Session Intent" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, de cuando se realizo el pago exitoso. example: 2023-01-01T21:21:10.587Z customer: type: object properties: id: type: string readOnly: true example: "zl3ky7muu702201lfd4td647c" name: type: string readOnly: true example: "John Doe" phone: type: string readOnly: true example: "+50688888888" email: type: string readOnly: true example: "johndoe@test.com" metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre la intención de pago. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres y los valores una longitud máxima de `500` caracteres. readOnly: false example: { "orderId": "123456789", "cartId": "987654321" } WebhookSucceedeSubscriptionResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: subscription.renewal.succeeded data: type: object description: El payload con la información de la subscripción renovada exitosamente. readOnly: true properties: mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live status: type: string description: El estado actual del pago de la suscripción. Puede ser `draft`, `open`, `paid`, `void`, `uncollectible`. example: "paid" enum: - draft - open - paid - void - uncollectible currency: type: string description: "La moneda utilizada para crear el Payment Intent" readOnly: true example: "USD" description: type: string description: Una descripción arbitraria del cargo recurrente. example: "Cargo recurrente de prueba" readOnly: true total: type: number description: El total del monto a cobrar en la subscripción. example: 2099 readOnly: true periodStart: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que inició el periodo de facturación actual. example: 2022-06-12T21:21:10.587Z readOnly: true periodEnd: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que inició el periodo de facturación actual. example: 2022-06-12T21:21:10.587Z readOnly: true subscriptionId: type: string description: Identificador único de la subscripción pagada. readOnly: true example: "clcl69c7m0011jbapzx04kwfw" paymentIntentId: type: string description: Identificador único del intento de pago. readOnly: true example: "clcl69c7m0011jhtrfs04kwfw" customerId: type: string description: Identificador único del cliente asociado al cargo recurrente readOnly: true example: cl502zv0d0127ebdp3zt27651 WebhookDeferredPaymentIntentResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: payment-intent.deferred data: type: object description: El payload con la información de la intención de pago y la descripción del error. readOnly: true properties: id: type: string readOnly: true example: "zl3ky7muu702201lfd4td647c" mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live currency: type: string description: "La moneda utilizada para crear el Payment Intent" readOnly: true example: "USD" status: type: string description: "El estado actual de la Intención de pago" readOnly: true example: "processing" confirmationAttempts: type: number description: La cantidad de veces que se intento procesar la intención de pago hasta que fue procesada correctamente. readOnly: true example: 1 description: type: string description: "El motivo de la intención de pago procesada" readOnly: true example: "Deferred Checkout Session Intent with SINPE" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, de cuando se realizo el pago exitoso. example: 2023-01-01T21:21:10.587Z amount: type: number description: El monto total, en la moneda seleccionada y en centavos de la intención de pago procesada. readOnly: true example: 500000 baseAmount: type: number description: El monto total, en dolares y en centavos de la intención de pago procesada. readOnly: true example: 868 paymentMethodId: type: string description: Identificador único del objeto de [Método de pago](#tag/Metodos-de-pago) previamente creado y asociado al mismo [Cliente](#tag/Clientes). example: cl502zv0d0127ebdp3zt27651 customerId: type: string description: Identificador único del cliente asociado al cargo recurrente readOnly: true example: cl502zv0d0127ebdp3zt27651 accountId: type: string description: "Identificador de la cuenta asociada al Payment Intent" readOnly: true example: "cx2bdw8ez0078agdp6dgpwfm3" WebhookErrorPaymentIntentResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: payment-intent.failed data: type: object description: El payload con la información de la intención de pago y la descripción del error. readOnly: true properties: id: type: string readOnly: true description: "Identificador del Payment Intent" example: "clcl69c7m0011jbapzx04kwfw" accountId: type: string description: "Identificador de la cuenta asociada al Payment Intent" readOnly: true example: "cx2bdw8ez0078agdp6dgpwfm3" currency: type: string description: "La moneda utilizada para crear el Payment Intent" readOnly: true example: "USD" status: type: string description: "El estado actual de la Intención de pago" readOnly: true example: "requires_payment_method" customer: type: object properties: id: type: string readOnly: true example: "zl3ky7muu702201lfd4td647c" name: type: string readOnly: true example: "John Doe" phone: type: string readOnly: true example: "+50688888888" email: type: string readOnly: true example: "johndoe@test.com" metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre la intención de pago. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres y los valores una longitud máxima de `500` caracteres. readOnly: false example: { "orderId": "123456789", "cartId": "987654321" } error: type: object properties: message: type: string readOnly: true example: "Transaction declined due to test payment method used" code: type: string readOnly: true example: "declined" type: type: string readOnly: true example: "processing_error" paymentMethodType: type: string readOnly: true example: "card" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, de cuando sucedio el error. example: 2023-01-01T21:21:10.587Z WebhookErrorSubscriptionResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: subscription.renewal.failed data: type: object description: El payload con la información de la renovación del cargo recurrente fallido y la descripción del error. readOnly: true properties: accountId: type: string description: "Identificador de la cuenta asociada al Cargo Recurrente" readOnly: true example: "cx2bdw8ez0078agdp6dgpwfm3" subscriptionId: type: string readOnly: true example: "clcl69c7m0011jbapzx04kwfw" paymentIntentId: type: string readOnly: true example: "" currency: type: string description: "La moneda utilizada para crear el Cargo Recurrente" readOnly: true example: "USD" invoiceStatus: type: string description: "El estado actual del Invoice correspondiente al Cargo Recurrente" readOnly: true example: "open" subscriptionStatus: type: string description: "El estado actual del Cargo Recurrente" readOnly: true example: "active" attemptCount: type: number readOnly: true example: 1 invoicePeriodStart: type: string readOnly: true description: "La fecha de inicio para la factura correspondiente al Cargo Recurrente que se intenta procesar." example: 2023-01-10T21:21:10.587Z invoicePeriodEnd: type: string readOnly: true description: "La fecha final para la factura correspondiente al Cargo Recurrente que se intenta procesar." example: 2023-01-11T21:21:10.587Z periodStart: type: string readOnly: true description: "La fecha de inicio correspondiente al Cargo Recurrente." example: 2023-01-10T21:21:10.587Z periodEnd: type: string readOnly: true description: "La fecha final correspondiente al Cargo Recurrente." example: 2023-01-11T21:21:10.587Z nextPaymentAttempt: type: string readOnly: true description: "La fecha en la cual se intentara procesar de nuevo el Cargo Recurrente." example: 2023-02-11T21:21:10.587Z lastPaymentAttempt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, de la ultima vez que se intento la renovación. example: 2023-01-01T21:21:10.587Z customer: type: object properties: id: type: string readOnly: true example: "zl3ky7muu702201lfd4td647c" name: type: string readOnly: true example: "John Doe" phone: type: string readOnly: true example: "+50688888888" email: type: string readOnly: true example: "johndoe@test.com" error: type: object properties: message: type: string readOnly: true example: "Transaction declined due to test payment method used" code: type: string readOnly: true example: "declined" type: type: string readOnly: true example: "processing_error" WebhookSucceedeCSResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: checkout-session.succeeded data: type: object description: El payload con la información del checkout session procesado exitosamente. readOnly: true properties: mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live paymentStatus: type: string description: El estado actual del pago. Puede ser `unpaid`, `paid`. example: "paid" enum: - unpaid - paid currency: type: string description: "La moneda utilizada para crear el Checkout Session" readOnly: true example: "CRC" url: type: string description: La url del Checkout Session que se proceso. example: "Cargo recurrente de prueba" readOnly: true amountTotal: type: number description: El total del monto(centavos) a cobrar en el Checkout Session. example: 350000 readOnly: true createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que creo el Checkout Session. example: 2022-06-12T21:21:10.587Z readOnly: true metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre la Sesión de Checkout. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres y los valores una longitud máxima de `500` caracteres. readOnly: false example: { "orderId": "123456789", "cartId": "987654321" } customer: type: object description: Lista de productos asociados al Checkout Session. properties: id: type: string description: Identificador unico del cliente asociado al Checkout Session name: type: string description: Nombre del cliente. readOnly: true example: John Doe phone: type: string description: "Número de teléfono asociado al cliente." readOnly: true example: +50688880000 email: type: string description: "Correo electrónico asociado al cliente." example: "john.doe@example.com" lineItems: type: array description: Lista de productos asociados al Checkout Session. readOnly: true items: type: object properties: name: type: string description: Nombre asociado al item. readOnly: true example: Producto de Prueba description: type: string description: Descripción asociada al item. readOnly: true example: Descripción del producto currency: type: string description: "La moneda utilizada en el precio del item" readOnly: true example: "CRC" amount: type: integer description: | El monto en `CRC` del precio asociado al item. example: 350000 readOnly: true WebhookMobileTransferResponse: type: object properties: type: type: string description: Identificador del evento recibido por el weebhook. readOnly: true example: mobile-transfer.received data: type: object description: El payload con la información de la transferencia SINPE Móvil recibida. readOnly: true properties: amount: type: number description: El monto enviado por medio de la transferencia, en formato de centavos. example: 1450000 currency: type: string description: "La moneda utilizada para enviar la transferencia." readOnly: true example: "CRC" description: type: string description: Descripción añadida por el usuario al momento de enviar la transferencia. example: "PAG0 DE SERVICIOS" SINPERefNumber: type: string description: "Identificador unico de la transfenrecia." readOnly: true example: "2025110312774577852010" originId: type: string description: | El número de identificación del cliente asociado a la cuenta SINPE Móvil. example: 01-1393-1919 originName: type: string description: Nombre completo de la persona que envia el SINPE Móvil example: JUAN PEREZ CASTRO originPhone: type: string description: Número telefónico asociado al cliente SINPE Móvil que envia la transferencia. example: "72940567" authorizationDate: type: string readOnly: true description: "La fecha en que fue enviada la transferencia" example: 2026-01-01T21:21:10.587Z NotFoundError: type: object properties: statusCode: type: integer example: 404 message: type: string example: "No customer found with the specified id." error: type: string example: "NotFoundException" UnauthorizedError: type: object properties: statusCode: type: integer example: 401 error: type: string example: "Unauthorized" ForbiddenError: type: object properties: statusCode: type: integer example: 403 message: type: string example: "The provided API key is not valid." error: type: string example: "Forbidden" ValidationError: type: object properties: statusCode: type: integer example: 400 message: type: array items: type: string example: - "address.country must be a valid ISO31661 Alpha2 code" error: type: string example: "Bad Request" CardDeclineReason: type: string description: | Categoría estable del rechazo de verificación de tarjeta. Usá este campo para decidir el tratamiento general del error: - `issuer_declined`: el emisor rechazó la verificación. - `gateway_declined`: el gateway o adquirente aplicó una regla no técnica de aceptación, autenticación, comercio o riesgo. - `onvo_declined`: ONVO aplicó una regla de elegibilidad o seguridad. - `processor_error`: un problema técnico impidió completar la verificación. - `unknown`: ONVO no recibió información suficiente para atribuir el rechazo. enum: - issuer_declined - gateway_declined - onvo_declined - processor_error - unknown example: issuer_declined CardDeclineDetails: type: object required: - reason - declineCode - declineMessage properties: reason: $ref: "#/components/schemas/CardDeclineReason" declineCode: type: string minLength: 1 description: Código seguro retornado por el gateway o emisor, o un valor de respaldo estable de ONVO. No pertenece a un espacio universal de códigos. example: "55" declineMessage: type: string minLength: 1 description: Mensaje informativo seguro para el comercio. No lo analices para lógica de negocio ni asumás que está localizado o que permanecerá sin cambios. example: Incorrect PIN OnvoAPIErrorDetails: type: object properties: card: description: Información opcional sobre un rechazo manejado durante la verificación de una tarjeta. $ref: "#/components/schemas/CardDeclineDetails" OnvoAPIError: type: object properties: code: type: string description: Código de error estable que podés usar para manejar el error en tu integración. example: cards.invalid_card_info path: type: string description: Ruta del endpoint que produjo el error. example: /v1/payment-methods type: type: string description: Tipo del error retornado por ONVO. example: OnvoAPIError message: type: string description: Mensaje legible que podés mostrar o registrar. example: There was an error with the card information provided. Please review card number, expiration date and cvv timestamp: type: string format: date-time description: Fecha y hora en la que ocurrió el error. example: 2026-04-29T17:36:28.477Z statusCode: type: integer description: Código HTTP del error. example: 400 details: description: Contexto estructurado opcional. Los errores que no tengan información adicional omiten este campo. $ref: "#/components/schemas/OnvoAPIErrorDetails" Error: type: object properties: statusCode: type: integer example: 400 description: Código HTTP del error. apiCode: type: string example: insufficient_funds description: Error de código adicional presente en el objeto relacionado a errores de procesamiento de los métodos de pago. message: type: array description: Mensaje humanamente legible incluyendo más detalles acerca del error. items: type: string example: - "The provided payment method does not have enough funds to process the transaction." error: type: string description: Nombre HTTP del error. example: "Bad Request" Pagination: type: object properties: createdAt: type: object description: Un filtro basado en el atributo de `createdAt` properties: gt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z gte: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z lt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z lte: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z endingBefore: type: string description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 limit: type: number description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 10 startingAfter: type: string description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 ListMeta: type: object description: Información de paginación para respuestas de listado. properties: total: type: number description: El número total de registros que coinciden con los filtros. example: 150 pages: type: number description: El número total de páginas usando el límite aplicado. example: 15 limit: type: number description: El límite aplicado a la página actual. example: 10 cursorNext: type: string description: Cursor de respuesta para la siguiente página. Enviá este valor como el parámetro query `startingAfter` en la siguiente solicitud. example: cl40muorw00493ndp0okzk2g3 cursorBefore: type: string description: Cursor de respuesta para la página anterior. Enviá este valor como el parámetro query `endingBefore` en la siguiente solicitud. example: cl40muorw00493ndp0okzk2g3 MarketplaceValidationError: type: object additionalProperties: false required: - statusCode - message - error properties: statusCode: type: integer description: Código HTTP de validación. message: type: array description: Lista de campos o reglas que no pasaron la validación. items: type: string error: type: string description: Nombre HTTP del error. MarketplaceAPIError: type: object additionalProperties: false required: - statusCode - type - code - message - path - timestamp properties: statusCode: type: integer description: Código HTTP del error. type: type: string description: Tipo del error retornado por ONVO. code: type: string description: Código de error estable que podés usar para manejar el error en tu integración. message: type: string description: Mensaje legible que podés mostrar o registrar. path: type: string description: Ruta del endpoint que produjo el error. timestamp: type: string format: date-time description: Fecha y hora en la que ocurrió el error. ConnectedAccountPublic: type: object additionalProperties: false required: - id - mode - status - businessName - marketplaceAppFee - createdAt properties: id: type: string description: Identificador único de la cuenta conectada. example: cl502zv0d0127ebdp3zt27651 mode: type: string description: Modo determinado por la Secret API Key de la cuenta primaria. enum: - test - live example: test status: type: string description: Estado actual de la cuenta conectada. La respuesta preserva el valor almacenado para mantener compatibilidad con cuentas antiguas. example: pending_onboarding businessName: type: - string - "null" description: Nombre comercial del vendedor. Solo puede ser `null` en cuentas antiguas sin perfil comercial. example: Tienda Conectada marketplaceAppFee: type: number format: double minimum: 0 maximum: 100 multipleOf: 0.01 description: Porcentaje efectivo de comisión del marketplace. `5` representa un 5 %; si se omite al crear la cuenta, retorna `0`. example: 5 createdAt: type: string format: date-time description: Fecha y hora UTC en la que se creó la cuenta conectada. example: 2026-07-25T17:00:00.000Z ConnectedAccountCreateResponse: type: object additionalProperties: false required: - id - mode - status - businessName - marketplaceAppFee - createdAt - onboardingUrl properties: id: type: string description: Identificador único de la cuenta conectada. example: cl502zv0d0127ebdp3zt27651 mode: type: string description: Modo determinado por la Secret API Key de la cuenta primaria. enum: - test - live example: test status: type: string description: Estado actual de la cuenta conectada. La respuesta preserva el valor almacenado para mantener compatibilidad con cuentas antiguas. example: pending_onboarding businessName: type: string description: Nombre comercial del vendedor. example: Tienda Conectada marketplaceAppFee: type: number format: double minimum: 0 maximum: 100 multipleOf: 0.01 description: Porcentaje efectivo de comisión del marketplace. `5` representa un 5 %; si se omite al crear la cuenta, retorna `0`. example: 5 createdAt: type: string format: date-time description: Fecha y hora UTC en la que se creó la cuenta conectada. example: 2026-07-25T17:00:00.000Z onboardingUrl: type: string format: uri description: Enlace alojado por ONVO para que el vendedor complete el onboarding. No lo registrés en logs ni lo expongás fuera del flujo de onboarding. example: https://onvopay.com/setup/account_onboarding_test_example ConnectedAccountList: type: object additionalProperties: false required: - data - meta properties: data: type: array description: Lista de cuentas conectadas visibles para la cuenta primaria y el modo de la Secret API Key. items: $ref: "#/components/schemas/ConnectedAccountPublic" meta: $ref: "#/components/schemas/ListMeta" ConnectedAccountWeeklyFee: type: object additionalProperties: false required: - id - marketplaceWeeklyFeeEnabled - marketplaceWeeklyFeeAmount - marketplaceWeeklyFeeCurrency properties: id: type: string description: Identificador único de la cuenta conectada. example: cl502zv0d0127ebdp3zt27651 marketplaceWeeklyFeeEnabled: type: boolean description: Indica si ONVO debe cobrar la tarifa semanal configurada. example: true marketplaceWeeklyFeeAmount: type: - integer - "null" minimum: 1 maximum: 2147483647 description: Monto semanal en la unidad menor de la moneda. Puede ser `null` mientras la tarifa está deshabilitada. example: 1000 marketplaceWeeklyFeeCurrency: type: - string - "null" description: Moneda configurada para cobrar la tarifa semanal. Puede ser `null` mientras la tarifa está deshabilitada. enum: - USD - CRC - GTQ - PEN - null example: CRC ConnectedAccountOnboardingLink: type: object additionalProperties: false required: - id - onboardingUrl properties: id: type: string description: Identificador único de la cuenta conectada. example: cl502zv0d0127ebdp3zt27651 onboardingUrl: type: string format: uri description: Nuevo enlace alojado por ONVO para completar el onboarding. El enlace anterior queda expirado. example: https://onvopay.com/setup/account_onboarding_test_example CustomerList: type: object properties: data: type: array description: Lista de clientes. items: $ref: "#/components/schemas/Customer" meta: $ref: "#/components/schemas/ListMeta" PaymentMethodList: type: object properties: data: type: array description: Lista de métodos de pago. items: $ref: "#/components/schemas/PaymentMethodResponse" meta: $ref: "#/components/schemas/ListMeta" PaymentIntentList: type: object properties: data: type: array description: Lista de intenciones de pago. items: $ref: "#/components/schemas/PaymentIntent" meta: $ref: "#/components/schemas/ListMeta" metadataKeys: type: array description: Claves de metadata disponibles para las intenciones de pago, cuando se solicitan con `includeMetadataKeys`. items: type: string example: - orderId - customerReference ProductList: type: object properties: data: type: array description: Lista de productos. items: $ref: "#/components/schemas/Product" meta: $ref: "#/components/schemas/ListMeta" PriceList: type: object properties: data: type: array description: Lista de precios. items: $ref: "#/components/schemas/Price" meta: $ref: "#/components/schemas/ListMeta" SubscriptionList: type: object properties: data: type: array description: Lista de cargos recurrentes. items: $ref: "#/components/schemas/Subscription" meta: $ref: "#/components/schemas/ListMeta" InvoiceListMeta: type: object description: Información de paginación para respuestas de listado de renovaciones. properties: total: type: number description: El número total de renovaciones que coinciden con los filtros. example: 150 pages: type: number description: El número total de páginas usando el límite aplicado. example: 6 limit: type: number description: El límite aplicado a la página actual. example: 25 startingAfter: type: string description: Cursor de respuesta para la siguiente página. Enviá este valor como el parámetro query `startingAfter` en la siguiente solicitud. example: cl40muorw00493ndp0okzk2g3 endingBefore: type: string description: Cursor de respuesta para la página anterior. Enviá este valor como el parámetro query `endingBefore` en la siguiente solicitud. example: cl40muorw00493ndp0okzk2g3 InvoiceList: type: object properties: data: type: array description: Lista de renovaciones. items: $ref: "#/components/schemas/Invoice" meta: $ref: "#/components/schemas/InvoiceListMeta" ShippingRateList: type: object properties: data: type: array description: Lista de tarifas de envío. items: $ref: "#/components/schemas/ShippingRate" meta: $ref: "#/components/schemas/ListMeta" MobileTransfer: type: object properties: id: type: string description: Identificador único del pago por SINPE Móvil. readOnly: true example: "clm8x9abc0001jk08example12" mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live example: "live" amount: type: number description: El monto del pago, en centavos. readOnly: true example: 1500000 currency: type: string description: La moneda del pago en formato ISO 4217. readOnly: true example: "CRC" status: type: string description: El estado actual del pago por SINPE Móvil. readOnly: true enum: - pending - received - attempt_not_found - charge_not_found - expired - canceled example: "received" description: type: string description: La descripción enviada con el pago por SINPE Móvil. readOnly: true example: "Pago factura 12345" SINPERefNumber: type: string description: El número de referencia único de 25 caracteres asignado por SINPE a la transferencia. readOnly: true example: "2025121616183220990502000" originId: type: string description: | El número de identificación (cédula) del remitente. El formato varía según el tipo: - Cédula física: 0#-####-#### - DIMEX: 1########### - Cédula jurídica: 2-###-###### o 3-###-###### - NITE: 4-000-###### - DIDI: 5########### - Pasaporte/Otro: 9########### readOnly: true example: "01-1393-1919" originName: type: string description: El nombre del remitente. readOnly: true example: "Juan Pérez Rodríguez" destinationPhone: type: string description: El número de teléfono de destino (tu número móvil personalizado). readOnly: true example: "70196686" authorizationDate: type: string format: date-time description: Fecha y hora en que el banco autorizó la transferencia. readOnly: true example: "2024-01-15T14:30:00.000Z" createdAt: type: string format: date-time description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue recibido el pago. readOnly: true example: "2024-01-15T14:30:05.587Z" paymentIntentId: type: string description: El ID de la intención de pago asociada, si existe. Si es null, la transferencia aún no ha sido vinculada a un pago. readOnly: true example: "clm8x9def0002jk08example34" MobileTransferList: type: object properties: data: type: array items: $ref: "#/components/schemas/MobileTransfer" description: Lista de pagos por SINPE Móvil. meta: type: object properties: total: type: number description: El número total de registros que coinciden con los filtros. example: 150 hasMore: type: boolean description: Indica si hay más registros disponibles después del último elemento retornado. example: true Customer: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 address: type: object description: La dirección del cliente. properties: city: type: string description: Nombre de ciudad o pueblo. example: "San José" country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: "10101" state: type: string description: Estado, provincia o región. example: "San José" amountSpent: type: number description: El monto total, en USD y en centavos, acumulado de transacciones satisfactorias del cliente. readOnly: true description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Cliente de prueba" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z email: type: string format: email description: La dirección de correo electrónico del cliente. example: "test_customer@onvopay.com" lastTransactionAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, de la última transacción satisfactoria del cliente. readOnly: true example: null mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live name: type: string description: El nombre completo del cliente. example: "John Doe" phone: type: string description: "El número de teléfono del cliente, incluyendo código de área (Ej: +50688880000)" example: "+50688880000" shipping: type: object description: La dirección de entrega a domicilio del cliente. properties: address: type: object description: La dirección del cliente. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null name: type: string description: Nombre del cliente o persona que recibe. example: "John Doe" phone: type: string description: Teléfono del cliente (incluyendo extensión). example: null transactionsCount: type: number description: Conteo histórico de las transacciones satisfactorias del cliente. readOnly: true updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z PaymentMethod: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 billing: type: object description: La dirección de facturación del método de pago. properties: address: type: object description: La dirección del cliente. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null name: type: string description: Nombre del cliente o persona que recibe. example: "John Doe" phone: type: string description: Teléfono del cliente (incluyendo extensión). example: null card: type: object description: "La información sobre la tarjeta de crédito o débito, cuando el tipo de método de pago sea `card`." properties: brand: type: string description: El nombre de la marca de la tarjeta. Puede ser `visa` o `mastercard`. example: "mastercard" readOnly: true enum: - visa - mastercard expMonth: type: integer description: El mes de expiración de la tarjeta. example: 12 readOnly: true expYear: type: integer description: El año de expiración de la tarjeta. example: 2026 readOnly: true last4: type: string description: Los últimos cuatro dígitos de la tarjeta. example: "4242" readOnly: true createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z customerId: type: string description: Identificador único del [cliente](#tag/Clientes) al que pertenece el método de pago. readOnly: true example: cl502zv0d0127ebdp3zt27651 mobileNumber: type: object description: "La información sobre el número asociado a SINPE Móvil, cuando el tipo de método de pago es `mobile_number`." properties: maskedNumber: type: string description: El número de teléfono, con los dígitos parcialmente ocultos. example: "+5068*****96" readOnly: true bankDeposit: type: object description: "La información sobre el depósito bancario (SINPE PIN), cuando el tipo de método de pago es `bank_deposit`." properties: identification: type: string description: El número de identificación del cliente asociado al depósito bancario. example: "01-2345-6789" readOnly: true identificationType: type: number description: | El tipo de identificación del cliente. Puede ser: - 1: Cédula física. - 2: Cédula jurídica. - 3: DIMEX. - 4: NITE. example: 1 readOnly: true maskedIBAN: type: string description: El número IBAN de la cuenta bancaria, con los dígitos parcialmente ocultos. example: "CR12**************7890" readOnly: true mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live status: type: string description: | El estado actual del método de pago. Puede ser uno de los siguientes: - Activo: `active`: Es el estado en el que los métodos de pago pueden ser utilizados para realizar transacciones. - Pendiente de autorización: `awaiting_authorization`. El método de pago requiere una autorización externa antes de activarse. - Requiere verificación: `requires-verification`. El método de pago debe verificarse antes de usarse. - Desconectado: `detached`. Es el estado en el que quedan los métodos de pago luego de haber sido removidos de un cliente. Este estatus es irreversible y el método de pago no se puede volver a utilizar. - Suspendido: `suspended`. Es un estado para los métodos de pago que han recibido una suspensión por parte de la plataforma. Estos métodos de pago no pueden ser utilizados para realizar transacciones. - Rechazado por ADA: `ada-rejected`. La verificación automática no aprobó el método de pago. readOnly: true enum: - awaiting_authorization - requires-verification - active - detached - suspended - ada-rejected type: type: string description: | El tipo de método de pago. Puede ser uno de los siguientes: - Tarjetas de crédito/débito VISA o MASTERCARD: `card` - SINPE Móvil: `mobile_number` - Depósito Bancario (SINPE PIN): `bank_deposit` - CREDIX: `credix` - Zunify: `zunify` - Crypto: `crypto` - Tasa cero: `tasa_cero` - Terminal: `terminal` readOnly: true enum: - card - mobile_number - bank_deposit - credix - zunify - crypto - tasa_cero - terminal example: card updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z VerifyPaymentMethodResponse: type: object properties: verified: type: boolean description: Indica si el metodo de pago fue verificado o no. example: true VerifyPaymentMethodNotRequired: type: object properties: statusCode: type: number description: "" example: 400 message: type: string description: "" example: "The provided payment method type does not require this verification. Please, verify the data and try again." PaymentMethodResponse: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 billing: type: object description: La dirección de facturación del método de pago. properties: address: type: object description: La dirección del cliente. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null name: type: string description: Nombre del cliente o persona que recibe. example: "John Doe" phone: type: string description: Teléfono del cliente (incluyendo extensión). example: null createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z customerId: type: string description: Identificador único del [cliente](#tag/Clientes) al que pertenece el método de pago. readOnly: true example: cl502zv0d0127ebdp3zt27651 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live status: type: string description: | El estado actual del método de pago. Puede ser uno de los siguientes: - Activo: `active`: Es el estado en el que los métodos de pago pueden ser utilizados para realizar transacciones. - Pendiente de autorización: `awaiting_authorization`. El método de pago requiere una autorización externa antes de activarse. - Requiere verificación: `requires-verification`. El método de pago debe verificarse antes de usarse. - Desconectado: `detached`. Es el estado en el que quedan los métodos de pago luego de haber sido removidos de un cliente. Este estatus es irreversible y el método de pago no se puede volver a utilizar. - Suspendido: `suspended`. Es un estado para los métodos de pago que han recibido una suspensión por parte de la plataforma. Estos métodos de pago no pueden ser utilizados para realizar transacciones. - Rechazado por ADA: `ada-rejected`. La verificación automática no aprobó el método de pago. readOnly: true enum: - awaiting_authorization - requires-verification - active - detached - suspended - ada-rejected type: type: string description: | El tipo de método de pago. Puede ser uno de los siguientes: - Tarjetas de crédito/débito VISA o MASTERCARD: `card` - SINPE Móvil: `mobile_number` - Depósito Bancario (SINPE PIN): `bank_deposit` - CREDIX: `credix` - Zunify: `zunify` - Crypto: `crypto` - Tasa cero: `tasa_cero` - Terminal: `terminal` readOnly: true enum: - card - mobile_number - bank_deposit - credix - zunify - crypto - tasa_cero - terminal example: card updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z VerifyPaymentMethod: type: object properties: amount: type: number description: El monto depositado en la cuenta IBAN, en formato de centavos. example: 99 PaymentMethodVerification: type: object properties: id: type: string description: Identificador único de la verificación. readOnly: true example: pmv_123 IBAN: type: string description: Cuenta IBAN asociada a la verificación. readOnly: true example: CR02010200000000000001 verificationType: type: string description: Tipo de verificación aplicada. readOnly: true example: manual identificationType: type: number description: Tipo de identificación asociada a la cuenta bancaria. readOnly: true example: 0 identification: type: string description: Número de identificación asociado a la cuenta bancaria. readOnly: true example: 01-1393-1919 currency: type: string description: Moneda usada para la verificación. readOnly: true example: CRC status: type: string description: Estado actual de la verificación. readOnly: true example: pending createdAt: type: string description: Fecha y hora, en formato ISO 8601 y zona horaria UTC, en la que fue creada la verificación. readOnly: true example: 2026-01-10T21:21:10.587Z updatedAt: type: string description: Fecha y hora, en formato ISO 8601 y zona horaria UTC, en la que fue actualizada por última vez la verificación. readOnly: true example: 2026-01-10T21:21:10.587Z BankAccountCheckInfo: type: object properties: IBAN: type: string minLength: 22 maxLength: 22 description: Número IBAN de la cuenta bancaria a validar. example: "CR02010200000000000001" identification: type: string minLength: 1 maxLength: 30 description: Número de identificación asociado a la cuenta. example: "01-1393-1919" identificationType: type: number description: Tipo de identificación asociado a la cuenta. example: 0 BankAccountCheckInfoResponse: type: object properties: found: type: boolean description: Indica si ONVO encontró una cuenta válida para esos datos. example: true currency: type: string description: Moneda reportada por la cuenta bancaria. example: CRC isVerified: type: boolean description: Indica si la cuenta ya está verificada para uso en ONVO. example: false CreatePaymentMethod: type: object properties: billing: type: object description: La dirección de facturación del método de pago. properties: address: type: object description: El detalle de la dirección de facturación. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null name: type: string description: Nombre asociado a la facturación. example: "John Doe" phone: type: string description: Teléfono (incluyendo extensión). example: null email: type: string description: Correo electrónico. example: null idType: type: string description: | El tipo de identificación del cliente. Puede ser uno de los siguientes: - national_natural_person: Persona física nacional. - resident_natural_person: Persona física residente. - government: Entidad estatal. - legal_person: Persona jurídica. - autonomous_institution: Institución autónoma. - diplomatic: Diplomático. - foreign_person: Extranjero. example: national_natural_person enum: - national_natural_person - resident_natural_person - government - legal_person - autonomous_institution - diplomatic - foreign_person idNumber: type: string minLength: 12 maxLength: 12 description: | El número de identificación del cliente asociado. Dependiendo del tipo, debe de enviarse en este formato: - national_natural_person: `0#-####-####` (Ej: 01-1393-1919) - resident_natural_person: `1###########` (Ej: 1293817461127) - government: `2-###-######` (Ej: 2-100-000001) - legal_person': `3-###-######` (Ej: 3-101-212393) - autonomous_institution: `4-000-######` (Ej: 4-000-042141) - diplomatic: `5###########` (Ej: 5123456789011) - foreign_person: `1###########` (Ej: 1293817461127) example: 01-1393-1919 card: type: object description: "La información sobre la tarjeta de crédito o débito. Cuando el tipo de método de pago sea `card`, este objeto será requerido." required: - number - expMonth - expYear - holderName properties: number: type: string pattern: "^[0-9]+$" description: El número de la tarjeta. Enviá solo dígitos, sin espacios ni separadores. El número también debe pasar validación Luhn. example: "4242424242424242" expMonth: type: integer minimum: 1 maximum: 12 description: El mes de expiración de la tarjeta. example: 12 expYear: type: integer minimum: 2023 maximum: 2100 description: El año de expiración de la tarjeta en cuatro dígitos. example: 2026 cvv: type: string pattern: "^[0-9]{3,4}$" description: El código de seguridad de la tarjeta. Si lo enviás, debe contener 3 o 4 dígitos. example: "123" holderName: type: string minLength: 1 description: El nombre del titular de la tarjeta. example: "John Doe" credix: type: object description: "La información sobre la tarjeta CREDIX. Cuando el tipo de método de pago sea `credix`, este objeto será requerido." properties: number: type: string description: El número de la tarjeta. example: "4111111111111111" expMonth: type: integer description: El mes de expiración de la tarjeta. example: 12 expYear: type: integer description: El año de expiración de la tarjeta. example: 2026 cvv: type: string description: El código de seguridad de la tarjeta. example: "123" holderName: type: string description: El nombre del titular de la tarjeta. example: "John Doe" brand: type: string description: Marca de la tarjeta, si está disponible. example: "credix" last4: type: string description: Últimos cuatro dígitos de la tarjeta, si están disponibles. example: "1111" identifier: type: string description: Identificador adicional provisto por CREDIX, si aplica. example: "credix_customer_123" crypto: type: object description: "La información del pago cripto. Cuando el tipo de método de pago sea `crypto`, este objeto será requerido." properties: cryptoPaymentId: type: string description: Identificador único del pago cripto creado por el proveedor. example: "crypto_pay_123" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z customerId: type: string description: Identificador único del [cliente](#tag/Clientes) al que pertenece el método de pago. Si no se especifica, se creará un nuevo cliente y se asociará al método de pago automáticamente. Para cuentas de comercio creadas en Perú, el cliente referenciado debe haber sido creado con el atributo `email`. example: cl502zv0d0127ebdp3zt27651 customer: type: object description: "La información sobre el cliente. Utilizado para crear un nuevo cliente y asociarlo al método de pago en la misma petición. Si se especifica, no se debe especificar el campo `customerId`. Para cuentas de comercio creadas en Perú, enviá `email` en este objeto." properties: name: type: string description: Nombre del cliente. example: "John Doe" email: type: string format: email description: Correo electrónico del cliente. example: "test_customer@onvopay.com" phone: type: string description: "El número de teléfono del cliente, incluyendo código de área (Ej: +50688880000)" example: "+50688880000" # consumerId: # type: string # description: Identificador único del comprador al que pertenece el método de pago. # nullable: true # example: cl502zv0d0127ebdp3zt27652 mobileNumber: type: object description: "La información sobre el número asociado a SINPE Móvil. Cuando el tipo de método de pago sea `mobile_number`, este objeto será requerido." properties: identification: type: string minLength: 12 maxLength: 12 description: | El número de identificación del cliente asociado a la cuenta SINPE Móvil. Dependiendo del tipo, debe de enviarse en este formato: - 0: `0#-####-####` (Ej: 01-1393-1919) - 1: `1###########` (Ej: 1293817461127) - 2: `2-###-######` (Ej: 2-100-000001) - 3: `3-###-######` (Ej: 3-101-212393) - 4: `4-000-######` (Ej: 4-000-042141) - 5: `5###########` (Ej: 5123456789011) - 9: `9###########` (Ej: 9CA9381461127) Se pueden utilizar librerías con funcionalidades como las de [react-number-format](https://www.npmjs.com/package/react-number-format) para formatear el número de identificación en inputs de texto. example: 01-1393-1919 identificationType: type: number description: | El tipo de identificación asociado a la cuenta SINPE Móvil. Puede ser uno de los siguientes: - 0: Persona física nacional. - 1: Persona física residente. - 2: Entidad estatal. - 3: Persona jurídica. - 4: Institución autónoma. - 5: Diplomático. - 9: Extranjero. example: 0 enum: - 0 - 1 - 2 - 3 - 4 - 5 - 9 number: type: string minLength: 12 maxLength: 12 description: "El número de teléfono previamente asociado a SINPE Móvil, incluyendo código de área (Ej: +50688880000)" example: "+50688880000" bankDeposit: type: object description: "La información sobre el depósito bancario (SINPE PIN). Cuando el tipo de método de pago sea `bank_deposit`, este objeto será requerido." properties: identification: type: string minLength: 1 maxLength: 30 description: | El número de identificación del cliente que realizará la transferencia bancaria. Este campo se utiliza para asociar automáticamente la transferencia entrante con la intención de pago. Debe coincidir con la identificación registrada en la cuenta bancaria del cliente (ej: `01-2345-6789` para cédula física). example: "01-2345-6789" identificationType: type: number description: | El tipo de identificación del cliente. Puede ser uno de los siguientes: - 1: Cédula física. - 2: Cédula jurídica. - 3: DIMEX. - 4: NITE. example: 1 enum: - 1 - 2 - 3 - 4 IBAN: type: string description: "El número IBAN de la cuenta bancaria del cliente (opcional). Ej: CR12345678901234567890" example: "CR12345678901234567890" zunify: type: object description: "La información sobre el número asociado a Zunify. Cuando el tipo de método de pago sea `zunify`, este objeto será requerido." properties: pin: type: string minLength: 4 maxLength: 4 description: | El número de PIN establecido en la aplicación de Zunify. example: 1234 phoneNumber: type: string minLength: 12 maxLength: 12 description: "El número de teléfono previamente asociado a Zunify, sin código de área (Ej: 11223344)" example: "11223344" type: type: string description: | El tipo de método de pago. Puede ser uno de los siguientes: - Tarjetas de crédito/débito VISA o MASTERCARD: `card` - SINPE Móvil: `mobile_number` - Depósito Bancario (SINPE PIN): `bank_deposit` - CREDIX: `credix` - Zunify: `zunify` - Crypto: `crypto` Cada tipo de método de pago tiene sus propiedades específicas representadas en los objetos de `card`, `mobileNumber`, `bankDeposit`, `credix`, `zunify` y `crypto`, respectivamente. Cada objeto correspondiente será requerido, según el tipo de método de pago, y los restantes objetos para los otros tipos de método de pago deben omitirse o se retornará un error de validación. enum: - card - mobile_number - bank_deposit - credix - zunify - crypto example: card UpdatePaymentMethod: type: object properties: billing: type: object description: La dirección de facturación del método de pago. properties: address: type: object description: El detalle de la dirección de facturación. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null name: type: string description: Nombre asociado a la facturación. example: "John Doe" phone: type: string description: Teléfono (incluyendo extensión). example: null card: type: object description: "En caso de que el tipo de método de pago sea `card`, se puede utilizar este objeto para re-tokenizar la tarjeta." properties: cvv: type: string description: El código de seguridad de la tarjeta. example: "123" Refund: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 amount: type: integer description: | El monto del reembolso. Si no se indica un monto en la creación, se reembolsará el monto total de la intención de pago. El monto no puede ser mayor al monto de la intención de pago. Debe ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`) example: 150 currency: type: string readOnly: true description: El tipo de moneda de la intención de pago. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z paymentIntentId: type: string description: Identificador único de la [intención de pago](#tag/Intenciones-de-pago) a la que pertenece el reembolso. example: cl502zv0d0127ebdp3zt27651 description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Reembolso de prueba" mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live status: type: string description: | El estado del reembolso. Puede ser uno de los siguientes: - Pendiente: `pending`. Estado de un reembolso en curso. - Satisfactorio: `succeeded`. Este estado se produce luego de el reembolso fue procesado de forma satisfactoria. - Fallido: `failed`. Estado resultante si el reembolso no pudo se procesado. readOnly: true enum: - pending - succeeded - failed reason: type: string default: requested_by_customer description: | La razón del reembolso. Si no se indica una razón, se utilizará la razón por defecto. Puede ser uno de los siguientes: - Reembolso por solicitud del cliente: `requested_by_customer`. El reembolso fue solicitado por el cliente. - Reembolso por fraude: `fraudulent`. El reembolso fue solicitado por el cliente debido a un fraude. - Duplicado: `duplicate`. El reembolso fue solicitado por el cliente debido a un cobro duplicado. - Otro: `other`. Se usa cuando el motivo no calza con las categorías anteriores. enum: - requested_by_customer - fraudulent - duplicate - other example: requested_by_customer updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z failureReason: type: string description: En caso de fallar el reembolso, se incluirá el motivo del fallo. readOnly: true example: declined PaymentIntent: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 amount: type: integer description: | El monto a cobrar en la intención de pago. Debe ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor indicado debe ser `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor indicado debe ser `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. example: 150 baseAmount: type: integer description: | El correspondiente monto en `USD` del monto indicado en `amount` según el tipo de cambio al momento de su creación. example: 102676 readOnly: true exchangeRate: type: float description: | El tipo de cambio utilizado para calcular el valor asignado a `baseAmount`. example: 0.0015 readOnly: true capturableAmount: type: integer description: | El monto capturable de la intención de pago. Al momento de crear la intención de pago, este valor es igual al monto indicado en `amount`. example: 150 readOnly: true receivedAmount: type: integer description: | El monto recibido de la intención de pago. Este valor es igual al monto indicado en `amount` si la intención de pago se encuentra en estado `succeeded`. El monto puede variar si se realizar un reembolso parcial o total de la intención de pago, así como una captura por un monto menor al monto autorizado. example: 150 readOnly: true captureMethod: type: string description: Atributo opcional para indicar el tipo de captura que se desea realizar. Puede ser `manual` o `automatic`. Si no se indica, se utilizará el valor por defecto `automatic`. Intenciones de pago con captura manual solo se pueden confirmar con métodos de pago de tipo `card`. Una vez confirmada, la intención de pago retornará el estado `requires_capture` y deberá ser capturada manualmente. Si no se completa la captura en un máximo de 30 días, los fondos serán liberados de vuelta al cliente. example: "automatic" enum: - manual - automatic default: automatic currency: type: string description: El tipo de moneda de la intención de pago. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z customerId: type: string description: Identificador único del [cliente](#tag/Clientes) al que pertenece la intención de pago. example: cl502zv0d0127ebdp3zt27651 description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Intención de pago de prueba" charges: type: array description: Lista de cargos asociados a la intención de pago. Cada cargo representa un intento de cobro con su respectivo estado. readOnly: true items: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: ch502zv0d0127ebdp3zt27651 amount: type: integer description: | El monto a cobrar en la intención de pago. Debe de ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor indicado debe ser `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor indicado debe ser `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. example: 150 baseAmount: type: integer description: | El correspondiente monto en `USD` del monto indicado en `amount` según el tipo de cambio al momento de su creación. example: 102676 readOnly: true exchangeRate: type: float description: | El tipo de cambio utilizado para calcular el valor asignado a `baseAmount`. example: 0.0015 readOnly: true currency: type: string description: El tipo de moneda de la intención de pago. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z failureCode: type: string description: | Código de error asociado al intento de cobro. Este código indica el tipo de error de procesamiento que ocurrió al intentar cobrar la intención de pago. example: "Declinado" readOnly: true failureMessage: type: string description: | Mensaje de error asociado al intento de cobro. Este mensaje es único para cada intento de cobro y puede ser utilizado para identificar el error específico que ocurrió. Los mensajes de error pueden ser consultados en la sección de [errores](#section/Errores). example: "Fondos insuficientes" readOnly: true isApproved: type: boolean description: | Indica si el intento de cobro fue aprobado. Un intento de cobro puede ser aprobado o rechazado por el banco emisor de la tarjeta de crédito o débito. example: false readOnly: true isCaptured: type: boolean description: | Indica si el intento de cobro fue capturado. Aplica únicamente para tarjetas de crédito o débito. example: false readOnly: true status: type: string description: | Estado del intento de cobro. Los estados posibles son: - `Pending`: El intento de cobro está pendiente de ser procesado. - `Succeeded`: El intento de cobro fue aprobado y procesado exitosamente. - `Failed`: El intento de cobro falló. example: "failed" readOnly: true enum: - pending - succeeded - failed lastPaymentError: type: object description: | Objeto que contiene información sobre el último error ocurrido al intentar cobrar la intención de pago. readOnly: true properties: code: type: string description: | Código de error asociado al intento de cobro. Este código indica el tipo de error de procesamiento que ocurrió al intentar cobrar la intención de pago. example: "Declinado" readOnly: true message: type: string description: | Mensaje de error asociado al intento de cobro. Este mensaje es único para cada intento de cobro y puede ser utilizado para identificar el error específico que ocurrió. Los mensajes de error pueden ser consultados en la sección de [errores](#section/Errores). example: "Fondos insuficientes" readOnly: true type: type: string description: | Tipo de error asociado al intento de cobro. Este tipo indica el tipo de error de procesamiento que ocurrió al intentar cobrar la intención de pago. example: "processing_error" readOnly: true mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live status: type: string description: | El estado actual de la intención de pago. Puede ser uno de los siguientes: - Requiere método de pago: `requires_payment_method`. Estado inicial de una intención de pago. También se mantiene en este estado si una confirmación falla, por ejemplo cuando una tarjeta es declinada. El cliente debe verificar que el método de pago es válido y que tiene fondos suficientes, o indicar uno diferente. - Requiere una acción: `requires_action`. Este estado es indicado cuando una intención de pago es confirmada, pero el método de pago requiere de una acción adicional para ser procesado. Por ejemplo, cuando se requiere de una autenticación 3DS para completar el cobro a través de una tarjeta de crédito o débito. - Requiere captura: `requires_capture`. La intención fue autorizada con captura manual y debe capturarse para completar el cobro. - Procesando: `processing`. ONVO está esperando confirmación del procesador o de un método de pago asincrónico. - Exitoso: `succeeded`. El estado que se produce luego de que la intención de pago haya sido cobrada y procesada satisfactoriamente. - Fallido: `failed`. El intento de cobro falló de forma definitiva. - Reembolsado: `refunded`. El estado que se produce luego de que la intención de pago haya sido reembolsada mediante el dashboard de ONVO. - Parcialmente reembolsado: `partially_refunded`. La intención de pago recibió uno o más reembolsos parciales. - Cancelado: `canceled`. El estado que se produce luego de que la intención de pago haya sido cancelada mediante el método de [cancelar intención de pago](#tag/Intenciones-de-pago/paths/~1v1~1payment-intents~1%7Bid%7D~1cancel/post) readOnly: true enum: - requires_payment_method - requires_action - requires_capture - processing - succeeded - failed - refunded - partially_refunded - canceled updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre la intención de pago. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres y los valores una longitud máxima de `500` caracteres. readOnly: false example: { "orderId": "123456789", "cartId": "987654321" } officeId: type: string description: Identificador opcional de la sede a la que pertenece la intención de pago. example: cl502zv0d0127ebdp3zt27651 onBehalfOf: type: string description: Identificador opcional de la cuenta de [marketplace](#tag/Marketplaces) a la que pertenece la intención de pago. example: cl502zv0d0127ebdp3zt27651 nextAction: type: object readOnly: true description: | Objeto que contiene la información de la siguiente acción requerida para procesar la intención de pago. Este objeto es retornado en caso de que la intención de pago requiera de una acción adicional para ser procesada como autenticación 3DS. properties: type: type: string description: | El tipo de acción requerida. Puede ser uno de los siguientes: - Autenticación 3DS: `redirect_to_url`. El cliente debe ser redirigido a una URL para completar la autenticación 3DS. example: redirect_to_url redirectToUrl: type: object description: | Objeto que contiene la URL a la que se debe redirigir al cliente para completar la autenticación 3DS. properties: url: type: string description: URL a la que se debe redirigir al cliente para completar la autenticación 3DS. example: "https://checkout.onvopay.com/authorize/test_clv..." returnUrl: type: string description: URL a la que se redirigirá al cliente luego de completar la autenticación 3DS, si se indicó una en la confirmación. example: "https://www.example.com/return" ConfirmPaymentIntent: type: object properties: paymentMethodId: type: string description: Identificador único del objeto de [Método de pago](#tag/Metodos-de-pago) previamente creado y asociado al mismo [Cliente](#tag/Clientes). example: cl502zv0d0127ebdp3zt27651 cvv: type: string description: Código de seguridad de la tarjeta. ONVO lo usa cuando el método de pago requiere confirmación con CVV. example: "123" credixInstallmentMonths: type: number description: Cantidad de cuotas a utilizar cuando el tipo del método de pago es [Credix](/payments/credix). **Requerido** cuando el método de pago es Credix. Usá 1 para pago contado o uno de los plazos de cuotas (3, 6, 10, 12, 18, 24); los plazos disponibles dependen de la configuración de tu comercio en el dashboard. example: 3 returnUrl: type: string description: URL a la que se redirigirá al cliente luego de completar la autenticación 3DS. example: "https://www.example.com/return" CapturePaymentIntent: type: object properties: amountToCapture: type: number description: Atributo opcional, si se desea capturar un monto menor al autorizado. Si no se envía, se utilizara el monto capturable de la intención de pago. Debe ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). example: 1099 Product: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Producto de prueba" images: type: array items: type: string description: URLs de imágenes para mostrar con el producto. example: [ "https://www.example.com/image.png", "https://www.example.com/image2.png", ] isActive: type: boolean description: Atributo booleano que indica si el producto está activo o no. En caso de no estar activo, no se podrán realizar cobros por este producto. example: true isShippable: type: boolean description: Atributo booleano que indica si el producto puede ser enviado a una dirección física. example: false name: type: string description: Nombre del producto para mostrar al cliente. example: "Producto de prueba" packageDimensions: type: object description: | Objeto que contiene las medidas del producto. Las medidas se expresan en centímetros (cm) gramos (g) y son los siguientes: - `length`: Longitud del producto. - `width`: Ancho del producto. - `height`: Altura del producto. - `weight`: Peso del producto. properties: length: type: number description: Longitud del producto, en centímetros. example: 10 width: type: number description: Ancho del producto, en centímetros. example: 10 height: type: number description: Altura del producto, en centímetros. example: 10 weight: type: number description: Peso del producto, en gramos. example: 10 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z Price: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 unitAmount: type: integer description: | El monto de precio unitario. Debe de ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor indicado debe ser `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor indicado debe ser `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. Cuando enviás `customUnitAmount` para un monto abierto, no enviés `unitAmount`; ONVO almacena el monto fijo del precio como `0` y usa `preset`, `minimum` y `maximum` para Checkout. example: 2099 customUnitAmount: type: object description: | Configuración para permitir que el comprador elija el monto en Checkout. El monto abierto no es un tipo adicional de precio: usá `type: "one_time"` para un cobro de monto abierto y enviá este objeto en lugar de `unitAmount`. properties: preset: type: integer description: Monto sugerido inicial en la menor denominación de la moneda. example: 1000000 minimum: type: integer description: Monto mínimo permitido en la menor denominación de la moneda. Omitilo si no querés definir un mínimo. example: 500000 maximum: type: integer description: Monto máximo permitido en la menor denominación de la moneda. Omitilo si no querés definir un máximo. example: 5000000 customizableAmount: type: boolean description: Indica si el precio permite monto abierto en Checkout. ONVO lo calcula a partir de `customUnitAmount`. readOnly: true example: true currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z nickname: type: string description: Una descripción breve del precio oculta a los clientes. Usada para identificar el precio en el dashboard de ONVO. example: "Precio de prueba" isActive: type: boolean description: Atributo booleano que indica si el precio está activo o no. En caso de no estar activo, no se podrán realizar cobros por este precio. example: true productId: type: string description: Identificador único del [producto](#tag/Productos) al que pertenece el precio. Enviá `productId` o `productData`, pero no ambos. example: cl502zv0d0127ebdp3zt27651 productData: type: object description: Datos para crear un producto inline al crear el precio. Enviá `productData` o `productId`, pero no ambos. properties: name: type: string description: Nombre del producto. example: Donación Fundación Azul description: type: string description: Descripción del producto. example: Aporte voluntario images: type: array description: URLs de imágenes asociadas al producto. items: type: string example: - https://example.com/donacion.png recurring: type: object description: | Objeto que contiene atributos adicionales cuando el tipo de precio es `recurring`. En caso de ser un precio recurrente, este objeto será requerido. properties: interval: type: string description: "La frecuencia en que se realizará el cargo recurrente. Puede ser uno de los siguientes valores: `day`, `week`, `month`, `year`." example: month enum: - day - week - month - year intervalCount: type: number description: "El número de intervalos a considerar, usando como base el valor enviado en `interval`. Por ejemplo, si se envía `interval` como `month` y `intervalCount` como `2`, se generará un cargo cada dos meses." example: 2 minimum: 1 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live type: type: string description: El tipo de precio. Puede ser `one_time` o `recurring`, dependiendo de si el precio es para una compra one-time o recurrente. El monto abierto no es un tercer tipo; para monto abierto usá `one_time` con `customUnitAmount`. enum: - one_time - recurring example: recurring updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z CreateCheckoutSession: type: object properties: mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live url: type: string description: La URL de la sesión de checkout2. readOnly: true example: https://checkout.onvopay.com/pay/cl502zv0d0127ebdp3zt27651 currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL paymentMode: type: string description: El modo de pago. Puede ser `payment` o `subscription`. example: payment enum: - payment - subscription paymentStatus: type: string description: El estado del pago. Puede ser `unpaid` o `paid`. example: unpaid enum: - unpaid - paid amountSubtotal: type: number description: El subtotal del monto a cobrar. example: 2099 amountTotal: type: number description: El monto total a cobrar. example: 2099 successUrl: type: string description: La URL a la que se redirigirá al cliente en caso de que el pago sea exitoso. example: https://example.com/success cancelUrl: type: string description: La URL a la que se redirigirá al cliente en caso de que el pago sea cancelado. example: https://example.com/cancel status: type: string description: El estado de la sesión de Checkout. Puede ser `open`, `complete` o `expired`. example: open enum: - open - complete - expired updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z AdditionalItem: type: object properties: mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live description: type: string description: Texto para identificar al item adicional. Comúnmente útil para mostrar a usuarios. example: "Producto de prueba" amount: type: number description: El monto del item adicional en centavos. example: 2099 quantity: type: number description: La cantidad del item adicional. example: 1 currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL UpdateItem: type: object properties: description: type: string description: Texto para identificar al item adicional. Comúnmente útil para mostrar a usuarios. example: "Item adicional de prueba" amount: type: number description: El monto del item adicional en centavos. example: 2099 quantity: type: number description: La cantidad del item adicional. example: 1 currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL CreateOneTimeLink: type: object properties: customerName: type: string description: Nombre completo del cliente para el primer paso de contacto. example: John Doe customerEmail: type: string format: email description: Correo electrónico del cliente para el primer paso de contacto. example: test@onvopay.com customerPhone: type: string description: "El número de teléfono del cliente, incluyendo código de área (Ej: +50688880000)" example: "+50688880000" redirectUrl: type: string description: La URL a la que se redirigirá al cliente en caso de que el pago sea exitoso. example: https://example.com/success cancelUrl: type: string description: La URL a la que se redirigirá al cliente en caso de que el pago sea cancelado. example: https://example.com/cancel officeId: type: string description: Identificador opcional de la sede a la que pertenece la sesión de Checkout. example: cl502zv0d0127ebdp3zt27651 onBehalfOf: type: string description: Identificador opcional de la cuenta de [marketplace](#tag/Marketplaces) a la que pertenece la sesión de Checkout. example: ma502zv0d0127ebdp3zt27651 captureMethod: type: string description: Atributo opcional para indicar el tipo de captura que se desea realizar. Puede ser `manual` o `automatic`. example: automatic enum: - manual - automatic paymentMethodTypes: type: array description: Lista opcional de métodos de pago permitidos para la sesión. items: type: string enum: - card - mobile_number - zunify - bank_deposit discounts: type: array description: | Lista opcional de descuentos a aplicar a la sesión de Checkout. Para enlaces de un solo uso, enviá como máximo un descuento. Cada descuento debe incluir `coupon` o `promotionCode`, pero no ambos. No enviés `discounts` junto con `discountCouponIds`. maxItems: 1 items: type: object properties: coupon: type: string description: Identificador único del cupón a aplicar. El cupón debe estar activo, pertenecer al mismo modo de la sesión, tener alcance `checkout_session` y aplicar a `one_time_links`. example: cpn_abc123 promotionCode: type: string description: Identificador único del código promocional a aplicar. Debe pertenecer al mismo modo de la sesión y estar activo. example: promo_abc123 discountCouponIds: type: array description: | Lista opcional de identificadores de cupones para integraciones existentes. Para nuevas integraciones preferí `discounts`. No enviés `discountCouponIds` junto con `discounts`. maxItems: 1 items: type: string example: - cpn_abc123 lineItems: type: array items: description: | Objeto que contiene los productos a asociar al one time link. Pueden ser productos existentes o nuevos. La lista debe tener al menos un elemento y todos los elementos deben ser en la misma moneda. Los atributos de cada producto son los siguientes: - `quantity`: Cantidad de productos. - `priceId`: Id del precio de un producto existente. Para monto abierto, creá un precio con `customUnitAmount` y enviá su `priceId` como único item con `quantity: 1`. - `unitAmount`: Monto del producto nuevo. - `currency`: Moneda del producto nuevo. - `description`: Descripción del producto nuevo. properties: quantity: type: integer description: Cantidad de productos. example: 1 priceId: type: string description: Identificador único del precio asociado a un producto existente. example: "c19rabxd122264F1639pwn1f3" isQuantityAdjustable: type: boolean description: Indica si el cliente puede ajustar la cantidad desde Checkout. example: true minimumQuantity: type: integer description: Cantidad mínima permitida cuando `isQuantityAdjustable` está activo. example: 1 maximumQuantity: type: integer description: Cantidad máxima permitida cuando `isQuantityAdjustable` está activo. example: 10 unitAmount: type: integer description: | El monto de precio unitario. Debe de ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor indicado debe ser `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor indicado debe ser `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. example: 2099 currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Producto de prueba" priceType: type: string description: Tipo de precio del item. Puede ser `one_time` o `recurring`. example: one_time enum: - one_time - recurring metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre la sesión de Checkout. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres y los valores una longitud máxima de `500` caracteres. readOnly: false example: { "orderId": "123456789", "cartId": "987654321" } CouponBinRule: type: object properties: id: type: string readOnly: true description: Identificador único de la regla de BIN. example: cbn_abc123 bin: type: string description: Primeros 6 a 8 dígitos de la tarjeta que hacen elegible el descuento. pattern: "^\\d{6,8}$" example: "411111" issuerName: type: string description: Nombre opcional del emisor para identificar la regla en tus herramientas internas. example: Banco Sponsor cardBrand: type: string description: Marca opcional de la tarjeta asociada al BIN. example: visa isActive: type: boolean description: Indica si la regla de BIN está activa. default: true example: true CouponPromotionCode: type: object properties: id: type: string readOnly: true description: Identificador único del código promocional. example: promo_abc123 code: type: string description: Código promocional asociado al cupón. ONVO lo almacena en mayúsculas. example: SUMMER25 isActive: type: boolean description: Indica si el código promocional está activo. default: true example: true timesRedeemed: type: integer readOnly: true description: Cantidad de veces que el código promocional ha sido redimido. example: 0 CouponRequest: type: object required: - name - type properties: name: type: string description: Nombre interno del cupón. Se usa para identificarlo en el dashboard, reportes y respuestas de descuento. example: Banco Sponsor 10% isActive: type: boolean description: Indica si el cupón está activo y puede aplicarse. default: true example: true type: type: string description: Tipo de descuento. Usá `percentage` con `percentOff` o `fixed_amount` con `amountOff` y `currency`. enum: - fixed_amount - percentage example: percentage scope: type: string description: Alcance del cupón. Para enlaces de un solo uso usá `checkout_session`. default: checkout_session example: checkout_session appliesTo: type: array description: Superficies donde se puede usar el cupón. Para enlaces de un solo uso incluí `one_time_links`. items: type: string default: - one_time_links example: - one_time_links percentOff: type: number description: Porcentaje de descuento para cupones `percentage`. Debe ser mayor que `0` y menor o igual que `100`. minimum: 0 maximum: 100 example: 10 amountOff: type: integer description: Monto fijo del descuento en la menor denominación de la moneda. Requerido para cupones `fixed_amount`. minimum: 0 example: 250000 currency: type: string description: Moneda del cupón de monto fijo. Debe coincidir con la moneda del enlace de pago. example: CRC enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL maxRedemptions: type: integer description: Cantidad máxima de pagos exitosos que pueden consumir este cupón. Omitilo para no definir un límite. minimum: 0 example: 100 redeemBy: type: string format: date-time description: Fecha límite para redimir el cupón. Podés enviar una fecha ISO completa o una fecha `YYYY-MM-DD`; las fechas sin hora se normalizan a medianoche de Costa Rica. example: "2026-06-30" duration: type: string description: Duración del cupón. Para enlaces de un solo uso usualmente se usa `once` o se omite. enum: - once - repeating - forever example: once durationInMonths: type: integer description: Cantidad de meses cuando `duration` es `repeating`. minimum: 0 example: 3 binRules: type: array description: Reglas de BIN que hacen elegible el cupón cuando el comprador paga con una tarjeta cuyo BIN coincide. items: $ref: "#/components/schemas/CouponBinRule" promotionCodes: type: array description: Códigos promocionales iniciales a crear junto con el cupón. items: $ref: "#/components/schemas/CouponPromotionCode" Coupon: allOf: - $ref: "#/components/schemas/CouponRequest" - type: object properties: id: type: string readOnly: true description: Identificador único del cupón. example: cpn_abc123 accountId: type: string readOnly: true description: Identificador único del negocio. example: acct_abc123 mode: type: string readOnly: true description: El modo en el que existe el cupón. Puede ser `test` o `live`. enum: - test - live example: test timesRedeemed: type: integer readOnly: true description: Cantidad de pagos exitosos que han consumido este cupón. example: 0 createdAt: type: string format: date-time readOnly: true description: Fecha y hora en la que fue creado el cupón. example: 2026-05-13T18:25:43.511Z updatedAt: type: string format: date-time readOnly: true description: Fecha y hora en la que fue actualizado por última vez el cupón. example: 2026-05-13T18:25:43.511Z ConfirmCheckoutSession: type: object properties: pm: type: string description: Identificador del método de pago usado para confirmar la sesión. example: cl502zv0d0127ebdp3zt27651 setupFutureUsage: type: boolean description: Indica si ONVO debe guardar el método de pago para uso futuro. example: false shippingRateId: type: string description: Identificador de la tarifa de envío seleccionada. example: shr_123 customer: $ref: "#/components/schemas/Customer" billing: type: object description: Información de facturación asociada a la confirmación. cvv: type: string description: Código de seguridad de la tarjeta, cuando el método de pago lo requiere. example: "123" merchantName: type: string description: Nombre del comercio que se muestra durante la confirmación. example: ONVO Store credixInstallmentMonths: type: number description: Cantidad de cuotas a utilizar cuando el método de pago es Credix. Usá 1 para pago contado o uno de los plazos de cuotas (3, 6, 10, 12, 18, 24); los plazos disponibles dependen de la configuración de tu comercio en el dashboard. example: 3 UpdateCheckoutSessionLineItem: type: object properties: priceId: type: string description: Identificador único del precio asociado al item. example: price_123 quantity: type: number description: Cantidad actualizada del item. example: 2 unitAmount: type: integer description: Monto unitario actualizado, en la menor denominación de la moneda. example: 2099 PatchCheckoutSessionCustomer: type: object properties: customerEmail: type: string format: email description: Correo electrónico del cliente. example: test@onvopay.com customerPhone: type: string description: Teléfono del cliente. example: "+50688880000" customerName: type: string description: Nombre completo del cliente. example: John Doe CheckoutSession: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 accountId: type: string description: Identificador único del negocio. readOnly: true example: cl2bf0cex38477agdpxiocx3vb url: type: string description: La URL de la sesión de checkout. readOnly: true example: https://checkout.onvopay.com/pay/cl502zv0d0127ebdp3zt27651 updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z billingAddressCollection: type: boolean description: Bandera que indica si existe una lista de direcciones de facturación del método de pago. readOnly: true example: true allowPromotionCodes: type: boolean description: Bandera que indica si están habilitados los códigos promocionales. readOnly: true example: false successUrl: type: string readOnly: true description: La URL a la que se redirigirá al cliente en caso de que el pago sea exitoso. example: https://example.com/success cancelUrl: type: string readOnly: true description: La URL a la que se redirigirá al cliente en caso de que el pago sea cancelado. example: https://example.com/cancel status: type: string readOnly: true description: El estado de la sesión de Checkout. Puede ser `open`, `complete` o `expired`. example: open enum: - open - complete - expired lineItems: type: array readOnly: true items: description: | Objeto que contiene los productos asociados al one time link. properties: id: type: string description: Identificador único del precio. readOnly: true example: cl502zv0d0127sffdp3zt27651 price: type: object readOnly: true description: | Objeto que contiene los productos asociados al one time link. properties: id: type: string description: Identificador único del producto. readOnly: true example: cl502sd4d0127sffdp3zt27651 currency: type: string description: El tipo de moneda de precio. readOnly: true example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live isActive: type: boolean readOnly: true default: true description: Indica si el precio está activo. example: true type: type: string description: El tipo de precio. Puede ser `one_time` o `recurring`, dependiendo de si el precio es para una compra one-time o recurrente. enum: - one_time - recurring unitAmount: type: integer description: | El monto de precio unitario. Se muestra en un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor será `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor será `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. example: 2099 readOnly: true product: type: object readOnly: true description: | Objeto que contiene el detalle del producto asociados al precio. properties: id: type: string description: Identificador único del producto. readOnly: true example: cl502ssdfg0127sffdp3zt27651 name: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Producto de prueba" readOnly: true mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live isActive: type: boolean readOnly: true default: true description: Indica si el precio está activo. example: true quantity: type: integer description: Cantidad de productos. example: 10 priceId: type: string description: Identificador único del precio asociado a un producto existente. example: 10 unitAmount: type: integer description: | El monto de precio unitario. Debe de ser un número entero positivo representando el monto en la menor denominación posible de la moneda (centavos para el caso de `USD` y céntimos para `CRC`). Por ejemplo, si la moneda es `USD` y el monto a cobrar es $1.50, el valor indicado debe ser `150`. De igual forma, si la moneda es `CRC` y el monto a cobrar es ₡2,100.89, el valor indicado debe ser `210089`. El monto mínimo es $0.50 para `USD` y el correspondiente equivalente en colones para `CRC`. example: 2099 currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL description: type: string description: Texto arbitrario adjunto al objeto. Comúnmente útil para mostrar a usuarios. example: "Producto de prueba" mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live shippingAddressCollection: type: boolean description: Bandera que indica si existe una lista de direcciones de facturación del método de pago. readOnly: true example: true shippingCountries: type: array readOnly: true description: | Objeto que contiene la lista de paises de envío. example: [] shippingRates: type: array readOnly: true description: | Objeto que contiene la lista de tarifase de envío. example: [] paymentStatus: type: string readOnly: true description: El estado actual de la Sesión de Checkout. Al momento de crearse, inicia con status `unpaid` y, una vez que el pago sea satisfactorio, pasa a status `paid`. example: "unpaid" enum: - paid - unpaid paymentIntentId: type: string description: Identificador único del intento de pago. readOnly: true example: "clcl69c7m0011jhtrfs04kwfw" onBehalfOfId: type: string description: Identificador de la cuenta de [marketplace](#tag/Marketplaces) asociada a la sesión de Checkout. readOnly: true example: ma502zv0d0127ebdp3zt27651 account: type: object readOnly: true description: | Objeto que contiene los detalles del negocio para el cual el One Time Link es creado. Subscription: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 billingCycleAnchor: type: string format: date-time description: | La fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se genere el ciclo de facturación, si se desea que el ciclo de facturación no se inicie en la fecha y hora en la que el cliente se suscribe, sino en la fecha y hora indicada en este atributo. Por ejemplo, si se desea que el ciclo de facturación del cargo recurrente sea los 15 de cada mes, al indicar esa fecha en este atributo, ONVO determinará cuánto debe pagar el cliente al momento de la transacción, con base en los días restantes a la fecha indicada y siguiente cobro será el 15 de dicho mes y así ya quedará fijado. Si no se indica ninguna fecha, el ciclo de facturación se iniciará en el momento en que el cliente se realice el pago de forma satisfactoria. example: 2022-09-31T00:00:00.000Z status: type: string readOnly: true description: El estado actual de la suscripción. Puede ser `active`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing`. example: "trialing" enum: - active - past_due - canceled - unpaid - incomplete - incomplete_expired - trialing cancelAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se cancele el cargo recurrente. Esta fecha debera ser mayor a la fecha actual y podria generar diferentes escenarios que se detallan a continuación. - Si se usa una fecha menor al inicio del siguiente ciclo de facturación, se cancelara el cargo recurrente inmediatamente, sin generar un nuevo monto a cobrar. - Si se usa una fecha menor a la finalización del siguiente período, al ejecutar el ciclo de facturación, se cancelara el cargo recurrente, pero además un nuevo monto sera calculado, utilizando el costo diario calculado y la cantidad de días diferencia generados por la fecha de cancelación. - Si se usa una fecha mayor a la finalización del siguiente período, se ejecutara el ciclo de facturación actual, pero además un nuevo monto sera calcualdo para el siguiente ciclo de facturación, esto basado en el costo diario calculado y la cantidad de días diferencia generados por la fecha de cancelación. example: 2022-06-12T21:21:10.587Z cancelAtPeriodEnd: type: boolean description: Indica si el cargo recurrente se cancela al finalizar el período de facturación. El valor por defecto es `false`. example: true canceledAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se canceló el cargo recurrente. example: 2022-06-12T21:21:10.587Z readOnly: true createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z currentPeriodStart: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que inició el periodo de facturación actual. example: 2022-06-12T21:21:10.587Z readOnly: true currentPeriodEnd: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que finaliza el periodo de facturación actual. example: 2022-06-12T21:21:10.587Z readOnly: true customerId: type: string description: Identificador único del cliente asociado al cargo recurrente example: cl502zv0d0127ebdp3zt27651 description: type: string description: Una descripción arbitraria del cargo recurrente. example: "Cargo recurrente de prueba" metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre el cargo recurrente. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres, no puede incluir corchetes, y los valores una longitud máxima de `500` caracteres. additionalProperties: type: string maxProperties: 50 example: orderId: "123456789" plan: "pro_monthly" onBehalfOf: type: string description: Identificador opcional de la cuenta de [marketplace](#tag/Marketplaces) a la que pertenece el cargo recurrente. ONVO usa esta cuenta para calcular la comisión marketplace en el primer cobro y en cada renovación. example: ma502zv0d0127ebdp3zt27651 onBehalfOfId: type: string description: Identificador de la cuenta de [marketplace](#tag/Marketplaces) asociada al cargo recurrente. readOnly: true example: ma502zv0d0127ebdp3zt27651 paymentBehavior: type: string description: | El comportamiento del cargo recurrente. Puede ser `allow_incomplete` o `default_incomplete`, siendo el último el valor por defecto, si no se envía. Si se envía `allow_incomplete`, el cargo recurrente se creará en forma inmediata, pero no se cobrará hasta que el cargo recurrente se confirme. Si no se envía, el cargo recurrente se creará en forma inmediata y se cobrará inmediatamente al método de pago indicado. example: "default_incomplete" enum: - allow_incomplete - default_incomplete startDate: type: string description: | Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se inicie el cargo recurrente. Si no se envía, el cargo recurrente se iniciará en el momento en que el cliente realice el pago de forma satisfactoria. Este atributo no es compatible si `paymentBehavior` es `allow_incomplete`. example: 2026-01-10T21:21:10.587Z paymentMethodId: type: string description: Identificador único del método de pago asociado al cargo recurrente. Si `paymentBehavior` es diferente a `allow_incomplete`, este atributo es obligatorio. example: cl502zv0d0127ebdp3zt27651 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live items: type: array description: Lista de items asociados al cargo recurrente. Cada item representa un [precio](#tag/Precios) de tipo `recurring`. items: $ref: "#/components/schemas/SubscriptionItem" trialPeriodDays: type: integer description: El número de días de prueba que se desean brindar al cliente. example: 7 trialStart: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se inicia el periodo de prueba, si el atributo de `trialPeriodDays` fue indicado. example: 2022-06-12T21:21:10.587Z readOnly: true trialEnd: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se finaliza el periodo de prueba, si el atributo de `trialPeriodDays` fue indicado. example: 2022-06-12T21:21:10.587Z readOnly: true updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z latestInvoice: type: object readOnly: true description: Objeto que contiene la información de la última renovación generada para el cargo recurrente. $ref: "#/components/schemas/Invoice" Invoice: type: object readOnly: true properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL attemptCount: type: number description: El número de intentos de cobro que se han realizado para la renovación. example: 1 readOnly: true attempted: type: boolean description: Bandera que indica si se han realizado intentos de cobro para la renovación. example: true readOnly: true description: type: string description: Una descripción de la renovación. example: "Renovación de prueba" total: type: number description: El monto total de la renovación en centavos. example: 2099 readOnly: true subTotal: type: number description: El subtotal de la renovación en centavos. example: 2099 readOnly: true originalTotal: type: number description: El monto total original de la renovación en centavos, antes de aplicarle items adicionales. example: 1099 readOnly: true status: type: string description: El estado de la renovación. Puede ser `draft`, `open`, `paid`, `void` o `uncollectible`. example: "paid" enum: - draft - open - paid - void - uncollectible createdAt: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z updatedAt: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z lastPaymentAttempt: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que ocurrió el último intento de pago. readOnly: true example: 2022-06-12T21:21:10.587Z nextPaymentAttempt: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que ocurrirá el siguiente intento de pago. readOnly: true example: 2022-06-12T21:21:10.587Z periodStart: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que inicia el período facturado. readOnly: true example: 2022-06-12T21:21:10.587Z periodEnd: type: string description: Fecha y hora, en formato ISO 8601 y con zona horaria en UTC, en la que finaliza el período facturado. readOnly: true example: 2022-07-12T21:21:10.587Z paymentIntentId: type: string description: Identificador único de la intención de pago asociada a la renovación. example: cl502zv0d0127ebdp3zt27651 customerId: type: string description: Identificador único del cliente asociado a la renovación. example: cl502zv0d0127ebdp3zt27651 subscriptionId: type: string description: Identificador único del cargo recurrente asociado a la renovación. example: cl502zv0d0127ebdp3zt27651 onBehalfOfId: type: string description: Identificador de la cuenta de [marketplace](#tag/Marketplaces) asociada a la renovación. readOnly: true example: ma502zv0d0127ebdp3zt27651 accountId: type: string description: Identificador único de la cuenta asociada a la renovación. readOnly: true example: cl502zv0d0127ebdp3zt27651 metadata: type: object description: Conjunto de pares llave-valor asociados a la renovación. additionalProperties: true example: orderId: order_123 paymentIntent: type: object description: Intención de pago expandida cuando se solicita con `expand=payment_intent`. readOnly: true additionalProperties: true subscription: type: object description: Cargo recurrente expandido cuando se solicita con `expand=subscription`. readOnly: true additionalProperties: true invoiceAdditionalItems: type: array description: Lista de items adicionales a cobrar en la renovación. items: $ref: "#/components/schemas/SubscriptionAditionalItem" SubscriptionAditionalItem: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 mode: type: string description: El modo en el que existen los datos del objeto. Ya sea `test` o `live`. readOnly: true enum: - test - live description: type: string description: Una descripción correspondiente al item adicional del cargo recurrente. example: "Item adicional de prueba" amount: type: number description: El precio total del item adicional en centavos. example: 2099 readOnly: true currency: type: string description: El tipo de moneda de precio. example: "USD" enum: - USD - CRC - GTQ quantity: type: number description: "La cantidad de unidades del item adicional." example: 2 minimum: 1 updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z SubscriptionItem: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z priceId: type: string description: Identificador único del [precio](#tag/Precios) al que pertenece el cargo recurrente. example: cl502zv0d0127ebdp3zt27651 quantity: type: number description: "La cantidad de unidades del precio indicado en `priceId`. Por ejemplo, si el precio asociado es de $10 cada mes y se envía `quantity` como `2`, se generará un cargo de $20." example: 2 minimum: 1 updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z ConfirmSubscription: type: object properties: paymentMethodId: type: string description: Identificador único del método de pago asociado al cargo recurrente. Si `paymentBehavior` es diferente a `allow_incomplete`, este atributo es obligatorio. example: cl502zv0d0127ebdp3zt27651 UpdateSubscription: type: object properties: billingCycleAnchor: type: string format: date-time description: | La fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se genere el ciclo de facturación, si se desea que el ciclo de facturación no se inicie en la fecha y hora en la que el cliente se suscribe, sino en la fecha y hora indicada en este atributo. Por ejemplo, si se desea que el ciclo de facturación del cargo recurrente sea los 15 de cada mes, al indicar esa fecha en este atributo, ONVO determinará cuánto debe pagar el cliente al momento de la transacción, con base en los días restantes a la fecha indicada y siguiente cobro será el 15 de dicho mes y así ya quedará fijado. Si no se indica ninguna fecha, el ciclo de facturación se iniciará en el momento en que el cliente se realice el pago de forma satisfactoria. example: 2022-09-31T00:00:00.000Z cancelAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se cancele el cargo recurrente. Esta fecha debera ser mayor a la fecha actual y podria generar diferentes escenarios que se detallan a continuación. - Si se usa una fecha menor al inicio del siguiente ciclo de facturación, se cancelara el cargo recurrente inmediatamente, sin generar un nuevo monto a cobrar. - Si se usa una fecha menor a la finalización del siguiente período, al ejecutar el ciclo de facturación, se cancelara el cargo recurrente, pero además un nuevo monto sera calculado, utilizando el costo diario calculado y la cantidad de días diferencia generados por la fecha de cancelación. - Si se usa una fecha mayor a la finalización del siguiente período, se ejecutara el ciclo de facturación actual, pero además un nuevo monto sera calcualdo para el siguiente ciclo de facturación, esto basado en el costo diario calculado y la cantidad de días diferencia generados por la fecha de cancelación. example: 2022-06-12T21:21:10.587Z cancelAtPeriodEnd: type: boolean description: Indica si el cargo recurrente se cancela al finalizar el período de facturación. El valor por defecto es `false`. example: true customerId: type: string description: Identificador único del cliente asociado al cargo recurrente example: cl502zv0d0127ebdp3zt27651 description: type: string description: Una descripción arbitraria del cargo recurrente. example: "Cargo recurrente de prueba" metadata: type: object description: | Objeto opcional que puede ser utilizado para guardar información adicional sobre el cargo recurrente. Puede ser útil para guardar información como el ID de una orden de compra, el ID de un carrito de compras, etc. Podés especificar hasta `50` pares de llave-valor. Las llaves y valores deben ser de tipo `string`. El nombre de las llaves debe de tener una longitud máxima de `40` caracteres, no puede incluir corchetes, y los valores una longitud máxima de `500` caracteres. additionalProperties: type: string maxProperties: 50 example: orderId: "123456789" plan: "pro_monthly" paymentBehavior: type: string description: | El comportamiento del cargo recurrente. Puede ser `allow_incomplete` o `default_incomplete`, siendo el último el valor por defecto, si no se envía. Si se envía `allow_incomplete`, el cargo recurrente se creará en forma inmediata, pero no se cobrará hasta que el cargo recurrente se confirme. Si no se envía, el cargo recurrente se creará en forma inmediata y se cobrará inmediatamente al método de pago indicado. example: "default_incomplete" enum: - allow_incomplete - default_incomplete startDate: type: string description: | Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que se desea que se inicie el cargo recurrente. Si no se envía, el cargo recurrente se iniciará en el momento en que el cliente realice el pago de forma satisfactoria. Este atributo no es compatible si `paymentBehavior` es `allow_incomplete`. example: 2026-01-10T21:21:10.587Z paymentMethodId: type: string description: Identificador único del método de pago asociado al cargo recurrente. Si `paymentBehavior` es diferente a `allow_incomplete`, este atributo es obligatorio. example: cl502zv0d0127ebdp3zt27651 trialPeriodDays: type: integer description: El número de días de prueba que se desean brindar al cliente. example: 7 ShippingRate: type: object properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z amount: type: number description: El monto, en centavos, del precio de la tarifa de envío. Por ejemplo, si el precio de la tarifa de envío es de $10.00, el atributo deberá ser `1000`. Si se envía `amount` como `0`, el precio de la tarifa de envío será mostrada como `gratis`. example: 1000 minimum: 0 currency: type: string description: La moneda en la que se define el monto del envío. example: USD enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL displayName: type: string description: El nombre que se mostrará en la tarifa de envío. example: Envío a domicilio al siguiente día. isActive: type: boolean default: true description: Indica si el envío está activo. Si es `false`, el envío no se podrá utilizar para generar una compra. example: true deliveryEstimate: type: object description: El período de tiempo estimado para la entrega del envío. properties: minimumUnit: type: string description: El tipo de unidad de tiempo estimado para la entrega del envío. example: days enum: - hour - day - business_day - week - month minimumValue: type: integer description: El número de unidades de tiempo estimado para la entrega del envío. Por ejemplo, si se envía `minimumUnit` como `day` y `minimumValue` como `2`, el período de tiempo estimado para la entrega del envío será de dos días. example: 2 minimum: 1 maximumUnit: type: string description: El tipo de unidad de tiempo estimado para la entrega del envío. example: days enum: - hour - day - business_day - week - month maximumValue: type: integer description: El número de unidades de tiempo estimado para la entrega del envío. Por ejemplo, si se envía `minimumUnit` como `day` y `minimumValue` como `2`, el período de tiempo estimado para la entrega del envío será de dos días. example: 2 minimum: 1 updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado por última vez el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z OneClick: type: object properties: consumer: type: object description: El objeto con la información del comprador un solo click. properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 email: type: string format: email description: La dirección de correo electrónico del comprador. example: "john.doe@onvopay.com" fullName: type: string description: Nombre completo del comprador. readOnly: true example: "John Doe" phone: type: string description: "El número de teléfono del comprador, incluyendo código de área (Ej: +50688880000)" example: "+50688880000" redactedPhone: type: string description: "El número de teléfono protegido del comprador (Ej: +5********00)" example: "+5********00" countryId: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z shipping: type: object description: La dirección de entrega a domicilio del comprador. properties: address: type: object description: La dirección del cliente. properties: city: type: string description: Nombre de ciudad o pueblo. example: null country: type: string description: El código de país en dos caracteres (ISO 3166-1 alpha-2). example: "CR" line1: type: string description: "Primera línea de la dirección. (Ej: Calle, nombre de empresa)." example: null line2: type: string description: "Segunda línea de la dirección. (Ej: Edificio, apartamento, número de casa)." example: null postalCode: type: string description: Código postal o código ZIP. example: null state: type: string description: Estado, provincia o región. example: null session: type: object description: El objeto con la información de la sesión del comprador. properties: id: type: string description: Identificador único del objeto. readOnly: true example: cl502zv0d0127ebdp3zt27651 consumerId: type: string description: Identificador único del comprador. readOnly: true example: cl502zv0d0127ebdp3zt27651 secret: type: string description: Llave secreta de la sesión. readOnly: true example: 609c2997f5cf346b1ebcf24e17e3f9ad932d943318f969f5b721 status: type: string description: El estado de la sesión. Puede ser `started` o `verified`. example: verified enum: - started - verified type: type: string description: El método que se uso para verificar la sesión. Puede ser `email` o `sms`. example: sms enum: - email - sms expiresAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que expira la sesión. readOnly: true example: 2022-06-12T21:21:10.587Z createdAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue creado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z updatedAt: type: string description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, en la que fue actualizado el objeto. readOnly: true example: 2022-06-12T21:21:10.587Z requestBodies: CreateConnectedAccount: required: true content: application/json: schema: type: object additionalProperties: false required: - businessName properties: businessName: type: string minLength: 1 maxLength: 50 description: Nombre comercial del vendedor. ONVO elimina espacios al inicio y al final. example: Tienda Conectada marketplaceAppFee: type: number format: double minimum: 0 maximum: 100 multipleOf: 0.01 description: Porcentaje de comisión del marketplace, con un máximo de dos decimales. Si se omite, ONVO guarda y retorna `0`. example: 5 examples: default: summary: Crear una cuenta conectada value: businessName: Tienda Conectada marketplaceAppFee: 5 UpdateConnectedAccount: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: businessName: type: string minLength: 1 maxLength: 50 description: Nuevo nombre comercial del vendedor. ONVO elimina espacios al inicio y al final. example: Tienda Conectada Actualizada marketplaceAppFee: type: number format: double minimum: 0 maximum: 100 multipleOf: 0.01 description: Nuevo porcentaje de comisión del marketplace, con un máximo de dos decimales. example: 6.25 examples: default: summary: Actualizar una cuenta conectada value: businessName: Tienda Conectada Actualizada marketplaceAppFee: 6.25 ConfigureConnectedAccountWeeklyFee: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: marketplaceWeeklyFeeEnabled: type: boolean description: Activa o desactiva el cobro semanal. Para activarlo, la configuración efectiva debe incluir monto y moneda. example: true marketplaceWeeklyFeeAmount: type: integer minimum: 1 maximum: 2147483647 description: Monto semanal en la unidad menor de la moneda. example: 1000 marketplaceWeeklyFeeCurrency: type: string description: Moneda en la que se cobra la tarifa. Debe estar soportada para el país de la cuenta conectada. enum: - USD - CRC - GTQ - PEN example: CRC examples: activar: summary: Activar una tarifa semanal value: marketplaceWeeklyFeeEnabled: true marketplaceWeeklyFeeAmount: 1000 marketplaceWeeklyFeeCurrency: CRC desactivar: summary: Desactivar una tarifa semanal value: marketplaceWeeklyFeeEnabled: false AddItem: content: application/json: schema: allOf: - description: Item a agregar. title: Item - $ref: "#/components/schemas/AdditionalItem" UpdateItem: content: application/json: schema: allOf: - description: Item a actualizar. title: Item - $ref: "#/components/schemas/UpdateItem" CreateCheckoutSessionOneTimeLink: content: application/json: schema: allOf: - description: One Time Link a crear. title: Sesiones de Checkout - $ref: "#/components/schemas/CreateOneTimeLink" examples: fixedAmountWithCoupon: summary: Sesión con cupón aplicado value: lineItems: - quantity: 1 unitAmount: 250000 currency: CRC description: "Orden #1001" customerEmail: comprador@example.com redirectUrl: https://example.com/success cancelUrl: https://example.com/cancel discounts: - coupon: cpn_abc123 metadata: orderId: "1001" openAmountSession: summary: Sesión donde el cliente elige qué pagar value: lineItems: - priceId: price_abc123 quantity: 1 redirectUrl: https://example.com/gracias cancelUrl: https://example.com/cancelado metadata: campaignId: donaciones-2026 CreateCoupon: content: application/json: schema: allOf: - description: Cupón a crear o actualizar. title: Cupón - $ref: "#/components/schemas/CouponRequest" examples: percentageBinCoupon: summary: Cupón porcentual por BIN value: name: Banco Sponsor 10% type: percentage percentOff: 10 scope: checkout_session appliesTo: - one_time_links maxRedemptions: 100 redeemBy: "2026-06-30" binRules: - bin: "411111" fixedAmountCoupon: summary: Cupón de monto fijo value: name: Descuento CRC 2,500 type: fixed_amount amountOff: 250000 currency: CRC scope: checkout_session appliesTo: - one_time_links binRules: - bin: "545454" ConfirmCheckoutSession: content: application/json: schema: allOf: - description: Sesión de Checkout a confirmar. title: Sesiones de Checkout - $ref: "#/components/schemas/ConfirmCheckoutSession" UpdateCheckoutSessionLineItem: content: application/json: schema: allOf: - description: Item de sesión de Checkout a actualizar. title: Sesiones de Checkout - $ref: "#/components/schemas/UpdateCheckoutSessionLineItem" PatchCheckoutSessionCustomer: content: application/json: schema: allOf: - description: Datos del cliente de la sesión de Checkout. title: Sesiones de Checkout - $ref: "#/components/schemas/PatchCheckoutSessionCustomer" CreateCustomer: content: application/json: schema: allOf: - description: Cliente a crear. title: Cliente - $ref: "#/components/schemas/Customer" CreateRefund: content: application/json: schema: allOf: - description: Reembolso a crear. title: Reembolso - $ref: "#/components/schemas/Refund" VerifyPaymentMethod: content: application/json: schema: allOf: - description: Método de pago a verificar. title: Método de pago - $ref: "#/components/schemas/VerifyPaymentMethod" BankAccountCheckInfo: content: application/json: schema: allOf: - description: Cuenta bancaria a validar. title: Cuenta bancaria - $ref: "#/components/schemas/BankAccountCheckInfo" CreatePaymentMethod: content: application/json: schema: allOf: - description: Método de pago a crear. title: Método de pago - $ref: "#/components/schemas/CreatePaymentMethod" UpdatePaymentMethod: content: application/json: schema: allOf: - description: Método de pago a actualizar. title: Método de pago - $ref: "#/components/schemas/UpdatePaymentMethod" CreatePaymentIntent: content: application/json: schema: allOf: - description: Intención de pago a crear. title: Intención de pago - $ref: "#/components/schemas/PaymentIntent" ConfirmPaymentIntent: content: application/json: schema: allOf: - description: Intención de pago a confirmar. title: Intención de pago - $ref: "#/components/schemas/ConfirmPaymentIntent" CapturePaymentIntent: content: application/json: schema: allOf: - description: Intención de pago a capturar. title: Intención de pago - $ref: "#/components/schemas/CapturePaymentIntent" CreateProduct: content: application/json: schema: allOf: - description: Producto a crear. title: Producto - $ref: "#/components/schemas/Product" examples: openAmountProduct: summary: Producto para que el cliente elija qué pagar value: name: Donación Fundación Azul description: Aporte voluntario para campaña anual images: - https://example.com/donacion.png CreatePrice: content: application/json: schema: allOf: - description: Precio a crear. title: Precio - $ref: "#/components/schemas/Price" examples: openAmount: summary: Precio donde el cliente elige qué pagar value: currency: CRC type: one_time productId: prod_abc123 customUnitAmount: preset: 1000000 minimum: 500000 maximum: 5000000 CreateSubscription: content: application/json: schema: allOf: - description: Cargo recurrente a crear. title: Cargo recurrente - $ref: "#/components/schemas/Subscription" ConfirmSubscription: content: application/json: schema: allOf: - description: Cargo recurrente a confirmar. title: Cargo recurrente - $ref: "#/components/schemas/ConfirmSubscription" UpdateSubscription: content: application/json: schema: allOf: - description: Cargo recurrente a actualizar. title: Cargo recurrente - $ref: "#/components/schemas/UpdateSubscription" CreateShippingRate: content: application/json: schema: allOf: - description: Tarifa de envío a crear. title: Tarifa de envío - $ref: "#/components/schemas/ShippingRate" paths: /v1/connected-accounts: post: tags: - Marketplaces summary: Crear una cuenta conectada description: | Crea una cuenta conectada para un vendedor desde una cuenta primaria estándar. Autenticá la solicitud con la Secret API Key de la cuenta primaria; la llave determina la cuenta propietaria y el modo `test` o `live`. La respuesta incluye el objeto público de la cuenta y el `onboardingUrl` alojado por ONVO. El vendedor debe completar ese flujo antes de operar. security: - SecretApiKey: [] requestBody: $ref: "#/components/requestBodies/CreateConnectedAccount" responses: "201": description: Cuenta conectada creada. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountCreateResponse" "400": description: Payload inválido, campo no soportado o configuración inválida de la cuenta primaria. content: application/json: schema: oneOf: - $ref: "#/components/schemas/MarketplaceValidationError" - $ref: "#/components/schemas/MarketplaceAPIError" examples: payloadInvalido: summary: Payload inválido value: statusCode: 400 message: - businessName must be longer than or equal to 1 characters error: Bad Request configuracionPrimariaInvalida: summary: Configuración inválida de la cuenta primaria value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.parent_configuration_invalid message: The parent account is not configured to manage connected accounts path: /v1/connected-accounts timestamp: 2026-07-25T17:00:00.000Z campoPublicoNoSoportado: summary: Campo no soportado por la API pública value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.unsupported_public_field message: The request contains fields that cannot be updated through the API path: /v1/connected-accounts timestamp: 2026-07-25T17:00:00.000Z "401": description: Secret API Key inválida, Publishable API Key no permitida o llave live de una cuenta primaria inactiva. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "500": description: Falló la creación del enlace de onboarding. La transacción no deja una cuenta conectada parcial. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: enlaceNoCreado: summary: No se pudo crear el enlace de onboarding value: statusCode: 500 type: OnvoAPIError code: marketplaces.error_creating_onboarding_link message: There was an error creating the onboarding link path: /v1/connected-accounts timestamp: 2026-07-25T17:00:00.000Z get: tags: - Marketplaces summary: Listar cuentas conectadas description: | Lista únicamente las cuentas conectadas que pertenecen a la cuenta primaria y al modo de la Secret API Key. Los parámetros `startingAfter` y `endingBefore` son mutuamente excluyentes y cada cursor debe pertenecer al mismo conjunto de cuenta, modo, tipo y filtro. La respuesta usa el envelope `{ data, meta }`. `onboardingUrl` nunca aparece en este listado. security: - SecretApiKey: [] parameters: - name: status in: query description: Estado exacto de la cuenta conectada. `restricted` no forma parte del contrato de Secret API Key. schema: type: string enum: - pending_onboarding - awaiting_approval - active - inactive - temporally_suspended - permanently_suspended - deleted - name: startingAfter in: query description: Cursor retornado en `meta.cursorNext`. No lo enviés junto con `endingBefore`. schema: type: string - name: endingBefore in: query description: Cursor retornado en `meta.cursorBefore`. No lo enviés junto con `startingAfter`. schema: type: string - name: limit in: query description: Cantidad máxima de cuentas conectadas por página. schema: type: integer minimum: 1 maximum: 100 default: 10 responses: "200": description: Lista paginada de cuentas conectadas. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountList" "400": description: Filtro, límite o combinación de cursores inválida. content: application/json: schema: oneOf: - $ref: "#/components/schemas/MarketplaceValidationError" - $ref: "#/components/schemas/MarketplaceAPIError" examples: limiteInvalido: summary: Límite inválido value: statusCode: 400 message: - limit must not be greater than 100 error: Bad Request cursorInvalido: summary: Cursor inválido o ajeno value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.invalid_cursor message: The connected account pagination cursor is invalid path: /v1/connected-accounts timestamp: 2026-07-25T17:00:00.000Z estadoInvalido: summary: Estado no soportado value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.invalid_status message: The connected account status filter is invalid path: /v1/connected-accounts timestamp: 2026-07-25T17:00:00.000Z "401": description: Secret API Key inválida, Publishable API Key no permitida o llave live de una cuenta primaria inactiva. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" /v1/connected-accounts/{id}: parameters: - name: id in: path required: true description: Identificador único de la cuenta conectada. schema: type: string get: tags: - Marketplaces summary: Obtener una cuenta conectada description: | Retorna el objeto público de una cuenta conectada que pertenece a la cuenta primaria y al modo de la Secret API Key. Un ID inexistente, de otra cuenta primaria o de otro modo produce la misma respuesta `404`. La respuesta no incluye datos bancarios, miembros, invitaciones, configuración de tarifa semanal ni `onboardingUrl`. security: - SecretApiKey: [] responses: "200": description: Cuenta conectada encontrada. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountPublic" "401": description: Secret API Key inválida o Publishable API Key no permitida. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "404": description: La cuenta conectada no existe en la cuenta primaria y el modo autenticados. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: cuentaNoEncontrada: summary: Cuenta conectada no encontrada value: statusCode: 404 type: OnvoAPIError code: marketplaces.connected_account_not_found message: The connected account was not found path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651 timestamp: 2026-07-25T17:00:00.000Z post: tags: - Marketplaces summary: Actualizar una cuenta conectada description: | Actualiza `businessName`, `marketplaceAppFee` o ambos. Debés enviar al menos uno. Esta operación no permite modificar estado, onboarding, frecuencia de liquidación, tarifas semanales ni datos bancarios. Repetir exactamente la misma actualización establece los mismos valores. La respuesta no incluye `onboardingUrl`. security: - SecretApiKey: [] requestBody: $ref: "#/components/requestBodies/UpdateConnectedAccount" responses: "200": description: Cuenta conectada actualizada. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountPublic" "400": description: Payload inválido, sin campos públicos o con campos no soportados. content: application/json: schema: oneOf: - $ref: "#/components/schemas/MarketplaceValidationError" - $ref: "#/components/schemas/MarketplaceAPIError" examples: payloadInvalido: summary: Payload inválido value: statusCode: 400 message: - marketplaceAppFee must not be greater than 100 error: Bad Request campoPublicoNoSoportado: summary: Campo no soportado por la API pública value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.unsupported_public_field message: The request contains fields that cannot be updated through the API path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651 timestamp: 2026-07-25T17:00:00.000Z "401": description: Secret API Key inválida o Publishable API Key no permitida. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "404": description: La cuenta conectada no existe en la cuenta primaria y el modo autenticados. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: cuentaNoEncontrada: summary: Cuenta conectada no encontrada value: statusCode: 404 type: OnvoAPIError code: marketplaces.connected_account_not_found message: The connected account was not found path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651 timestamp: 2026-07-25T17:00:00.000Z /v1/connected-accounts/{id}/weekly-fees: parameters: - name: id in: path required: true description: Identificador único de la cuenta conectada. schema: type: string post: tags: - Marketplaces summary: Configurar una tarifa semanal description: | Crea o actualiza la tarifa fija semanal de una cuenta conectada. La Secret API Key determina la cuenta primaria y el modo `test` o `live`; el ID debe pertenecer a esa misma cuenta primaria y modo. Podés enviar uno o más campos. Para activar el cobro, la configuración efectiva debe incluir monto y moneda, y tanto la cuenta primaria como la conectada deben tener una cuenta bancaria de liquidación en esa moneda. Los valores `null` no están permitidos. Omití un campo para conservar su valor actual; cada solicitud actualiza la configuración de forma atómica. Cada viernes a las `02:00` en `America/Costa_Rica`, ONVO crea la obligación si la tarifa está habilitada y la cuenta conectada está activa. Deshabilitarla detiene obligaciones futuras, pero no elimina saldos pendientes. security: - SecretApiKey: [] requestBody: $ref: "#/components/requestBodies/ConfigureConnectedAccountWeeklyFee" responses: "200": description: Tarifa semanal configurada. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountWeeklyFee" "400": description: Payload inválido o la tarifa semanal no cumple los requisitos de configuración. content: application/json: schema: oneOf: - $ref: "#/components/schemas/MarketplaceValidationError" - $ref: "#/components/schemas/MarketplaceAPIError" examples: payloadInvalido: summary: Monto inválido value: statusCode: 400 message: - marketplaceWeeklyFeeAmount must be an integer number error: Bad Request valorNulo: summary: Valores nulos no permitidos value: statusCode: 400 message: - marketplaceWeeklyFeeEnabled must be a boolean value error: Bad Request configuracionRequerida: summary: No se enviaron campos value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.configuration_required message: At least one weekly marketplace fee configuration field is required path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z montoRequerido: summary: Falta el monto para activar la tarifa value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.amount_required message: A weekly fee amount is required when the fee is enabled path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z monedaNoSoportada: summary: Moneda no soportada para el país value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.currency_not_supported message: The weekly fee currency is not supported for the connected account country path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z cuentaBancariaConectadaRequerida: summary: La cuenta conectada no tiene la cuenta bancaria requerida value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.child_bank_account_required message: The connected account needs a payout bank account in the weekly fee currency path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z cuentaBancariaPrimariaRequerida: summary: La cuenta primaria no tiene la cuenta bancaria requerida value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.parent_bank_account_required message: The parent account needs a payout bank account in the weekly fee currency path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z funcionNoHabilitada: summary: Tarifas semanales no habilitadas value: statusCode: 400 type: OnvoInvalidRequestError code: marketplaces.weekly_fee.feature_disabled message: Weekly marketplace fees are not enabled for this parent account path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z "401": description: Secret API Key inválida, Publishable API Key no permitida o llave live de una cuenta primaria inactiva. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "404": description: La cuenta conectada no existe en la cuenta primaria y el modo autenticados. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: cuentaNoEncontrada: summary: Cuenta conectada no encontrada value: statusCode: 404 type: OnvoAPIError code: marketplaces.connected_account_not_found message: The connected account was not found path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees timestamp: 2026-07-25T17:00:00.000Z /v1/connected-accounts/{id}/onboarding-link: parameters: - name: id in: path required: true description: Identificador único de la cuenta conectada. schema: type: string post: tags: - Marketplaces summary: Regenerar enlace de onboarding description: | Expira el enlace anterior y crea uno nuevo para una cuenta conectada que todavía no completó el onboarding. La operación se ejecuta en una transacción y serializa solicitudes concurrentes para dejar como máximo un enlace vigente. security: - SecretApiKey: [] responses: "200": description: Enlace de onboarding regenerado. content: application/json: schema: $ref: "#/components/schemas/ConnectedAccountOnboardingLink" "401": description: Secret API Key inválida o Publishable API Key no permitida. content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" "404": description: La cuenta conectada no existe en la cuenta primaria y el modo autenticados. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: cuentaNoEncontrada: summary: Cuenta conectada no encontrada value: statusCode: 404 type: OnvoAPIError code: marketplaces.connected_account_not_found message: The connected account was not found path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/onboarding-link timestamp: 2026-07-25T17:00:00.000Z "409": description: El vendedor ya completó el onboarding. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: onboardingCompleto: summary: Onboarding ya completado value: statusCode: 409 type: OnvoInvalidRequestError code: marketplaces.onboarding_already_completed message: Onboarding is already complete for this connected account path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/onboarding-link timestamp: 2026-07-25T17:00:00.000Z "500": description: No se pudo persistir el nuevo enlace; el enlace anterior conserva su validez. content: application/json: schema: $ref: "#/components/schemas/MarketplaceAPIError" examples: enlaceNoCreado: summary: No se pudo crear el enlace de onboarding value: statusCode: 500 type: OnvoAPIError code: marketplaces.error_creating_onboarding_link message: There was an error creating the onboarding link path: /v1/connected-accounts/cl502zv0d0127ebdp3zt27651/onboarding-link timestamp: 2026-07-25T17:00:00.000Z /v1/customers: post: tags: - Clientes summary: Crear un Cliente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Customer" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" x-codeSamples: - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } data = { 'name': 'John Doe', 'email': 'email@example.com', 'phone': '+50688880000', 'shipping': { 'name': 'John Doe', 'address': { 'line1': 'Calle 123', 'line2': 'Edificio A', 'city': 'Ciudad', 'state': 'Estado', 'country': 'AR', 'postalCode': '12345' } } } response = requests.post('https://api.onvopay.com/v1/customers', headers=headers, data=json.dumps(data)) print(response.json()) requestBody: $ref: "#/components/requestBodies/CreateCustomer" get: tags: - Clientes summary: Listar todos los Clientes description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: email in: query description: Identificador único del objeto. example: customer@onvopay.com schema: type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CustomerList" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/customers', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' }, }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.get('https://api.onvopay.com/v1/customers', headers=headers, data=json.dumps(data)) print(response.json()) - lang: "C#" source: | var headers = new Dictionary(); headers.Add("Content-Type", "application/json"); headers.Add("Authorization", "Bearer "); var data = new Dictionary(); data.Add("name", "John Doe"); data.Add("email", "email@example.com"); data.Add("phone", "+50688880000"); data.Add("shipping", new { name = "John Doe", address = new { line1 = "Calle 123", line2 = "Edificio A", city = "Ciudad", state = "Estado", country = "AR", postalCode = "12345" } }); var response = await httpClient.PostAsync("https://api.onvopay.com/v1/customers", new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json")); Console.WriteLine(response.Content.ReadAsStringAsync().Result); /v1/customers/{id}: get: tags: - Clientes summary: Obtener un Cliente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Customer" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.get('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', headers=headers, data=json.dumps(data)) print(response.json()) post: tags: - Clientes summary: Actualizar un Cliente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Customer" description: "" x-codeSamples: - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } data = { 'name': 'John Doe', 'email': 'email@example.com', 'phone': '+50688880000', 'shipping': { 'name': 'John Doe', 'address': { 'line1': 'Calle 123', 'line2': 'Edificio A', 'city': 'Ciudad', 'state': 'Estado', 'country': 'AR', 'postalCode': '12345' } } } response = requests.post('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', headers=headers, data=json.dumps(data)) print(response.json()) requestBody: $ref: "#/components/requestBodies/CreateCustomer" delete: tags: - Clientes summary: Borrar un Cliente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Customer" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', { method: 'DELETE', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.delete('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', headers=headers, data=json.dumps(data)) print(response.json()) /v1/customers/{id}/payment-methods: get: tags: - Clientes summary: Obtener los métodos de pago de un Cliente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: type: array items: $ref: "#/components/schemas/PaymentMethodResponse" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3/payment-methods', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) /v1/customers/{id}/subscriptions: get: tags: - Clientes summary: Obtener los cargos recurrentes de un Cliente description: Lista los cargos recurrentes asociados a un cliente. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cliente. required: true schema: type: string - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." schema: type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar." schema: type: number responses: "200": content: application/json: schema: $ref: "#/components/schemas/SubscriptionList" description: "Success" /v1/customers/{id}/payment-intents: get: tags: - Clientes summary: Obtener las intenciones de pago de un Cliente description: Lista las intenciones de pago asociadas a un cliente. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cliente. required: true schema: type: string - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." schema: type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar." schema: type: number responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentIntentList" description: "Success" /v1/payment-methods: post: tags: - Métodos de pago summary: Crear un Método de pago description: | Consultá la documentación de ONVO para ver detalles de integración y ejemplos. Para evitar errores `400` de validación al enviar `card`, validá que `card.holderName` sea texto no vacío, `card.number` sea un string de dígitos sin espacios ni separadores y que pase Luhn, `card.expMonth` sea un entero entre `1` y `12`, `card.expYear` sea un entero entre `2023` y `2100`, y `card.cvv` sea un string de `3` o `4` dígitos cuando lo enviés. Para cuentas de comercio creadas en Perú, el cliente asociado al método de pago debe tener correo electrónico al crear métodos de pago. Podés enviar `customer.email` en el payload para crear y asociar el cliente en la misma solicitud, o enviar `customerId` de un cliente creado previamente con el atributo `email`. Cuando creás un método de pago de tipo `card`, ONVO tokeniza y verifica la tarjeta antes de crear el objeto. Si la tokenización falla por datos inválidos, el endpoint responde `400` con `code: "cards.invalid_card_info"` y no se crea ningún método de pago. Para rechazos manejados, la respuesta puede incluir `details.card` con una categoría estable en `reason`, un `declineCode` seguro y un `declineMessage` informativo. Usá `reason` para lógica general y los campos superiores del error como respaldo cuando `details` no esté presente. `gateway_declined` identifica una regla no técnica del gateway/adquirente; `processor_error` identifica una falla técnica. security: - PublishableApiKey: [] - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" description: "Success" "400": content: application/json: schema: oneOf: - $ref: "#/components/schemas/ValidationError" - $ref: "#/components/schemas/OnvoAPIError" examples: tokenizacionTarjetaFallida: summary: Tokenización de tarjeta fallida value: code: cards.invalid_card_info path: /v1/payment-methods type: OnvoAPIError message: There was an error with the card information provided. Please review card number, expiration date and cvv details: card: reason: issuer_declined declineCode: "55" declineMessage: Incorrect PIN timestamp: 2026-04-29T17:36:28.477Z statusCode: 400 validacionFallida: summary: Validación fallida value: statusCode: 400 message: - "address.country must be a valid ISO31661 Alpha2 code" error: Bad Request validacionTarjetaFallida: summary: Validación de tarjeta fallida value: statusCode: 400 message: - "card.number Card number is invalid" error: Bad Request description: "Solicitud inválida. Al crear un método de pago de tipo `card`, también puede indicar que la tokenización de la tarjeta falló." "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" x-codeSamples: - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } data = { 'type': 'card', 'card': { 'number': '4242424242424242', 'expMonth': 12, 'expYear': 2026, 'cvv': '123', 'holderName': 'John Doe' }, 'billing': { 'address': { 'country': 'CR', }, 'name': 'John Doe', 'phone': '+50688880000' } } response = requests.post('https://api.onvopay.com/v1/payment-methods', headers=headers, data=json.dumps(data)) print(response.json()) - lang: "Ruby" source: | require 'net/http' require 'json' headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } data = { 'type': 'card', 'card': { 'number': '4242424242424242', 'expMonth': 12, 'expYear': 2026, 'cvv': '123', 'holderName': 'John Doe' }, 'billing': { 'address': { 'country': 'CR', }, 'name': 'John Doe', 'phone': '+50688880000' } } response = Net::HTTP.post_form(URI.parse('https://api.onvopay.com/v1/payment-methods'), data, headers) puts response.body - lang: "PHP" source: | $headers = array( 'Content-Type' => 'application/json', 'Authorization' => 'Bearer ' ); $data = array( 'type' => 'card', 'card' => array( 'number' => '4242424242424242', 'expMonth' => 12, 'expYear' => 2026, 'cvv' => '123', 'holderName' => 'John Doe' ), 'billing' => array( 'address' => array( 'country' => 'CR', ), 'name' => 'John Doe', 'phone' => '+50688880000' ) ); $response = curl_init('https://api.onvopay.com/v1/payment-methods'); curl_setopt($response, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($response, CURLOPT_POSTFIELDS, json_encode($data)); curl_setopt($response, CURLOPT_RETURNTRANSFER, true); curl_setopt($response, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($response); print_r(json_decode($response, true)); - lang: "C#" source: | using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using Newtonsoft.Json; using Newtonsoft.Json.Linq; using System.Collections.Generic; using System.Threading.Tasks; namespace OnvopaySamples { public class PaymentMethods { public static async Task CreatePaymentMethod() { var client = new HttpClient(); client.DefaultRequestHeaders.Accept.Clear(); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); client.DefaultRequestHeaders.Add("Authorization", "Bearer "); var data = new Dictionary(); data.Add("type", "card"); data.Add("card", new Dictionary()); data["card"].Add("number", "4242424242424242"); data["card"].Add("expMonth", 12); data["card"].Add("expYear", 2026); data["card"].Add("cvv", "123"); data["card"].Add("holderName", "John Doe"); data.Add("billing", new Dictionary()); data["billing"].Add("address", new Dictionary()); data["billing"]["address"].Add("country", "CR"); data["billing"].Add("name", "John Doe"); data["billing"].Add("phone", "+50688880000"); var json = JsonConvert.SerializeObject(data); var content = new StringContent(json, Encoding.UTF8, "application/json"); var response = await client.PostAsync("https://api.onvopay.com/v1/payment-methods", content); var responseString = await response.Content.ReadAsStringAsync(); return responseString; } } } requestBody: $ref: "#/components/requestBodies/CreatePaymentMethod" get: tags: - Métodos de pago summary: Listar todos los Métodos de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodList" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/payment-methods', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' }, }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.get('https://api.onvopay.com/v1/payment-methods', headers=headers, data=json.dumps(data)) print(response.json()) - lang: "C#" source: | var headers = new Dictionary(); headers.Add("Content-Type", "application/json"); headers.Add("Authorization", "Bearer "); var data = new Dictionary(); data.Add("name", "John Doe"); data.Add("email", "email@example.com"); data.Add("phone", "+50688880000"); data.Add("shipping", new { name = "John Doe", address = new { line1 = "Calle 123", line2 = "Edificio A", city = "Ciudad", state = "Estado", country = "AR", postalCode = "12345" } }); var response = await httpClient.PostAsync("https://api.onvopay.com/v1/payment-methods", new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json")); Console.WriteLine(response.Content.ReadAsStringAsync().Result); /v1/payment-methods/{id}/detach: post: tags: - Métodos de pago summary: Desconectar un Método de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/payment-methods/cl40muorw00493ndp0okzk2g3/detach', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.post('https://api.onvopay.com/v1/payment-methods/cl40muorw00493ndp0okzk2g3/detach', headers=headers, data=json.dumps(data)) print(response.json()) /v1/payment-methods/{id}: get: tags: - Métodos de pago summary: Obtener un Método de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/payment-methods/cl40muorw00493ndp0okzk2g3', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.get('https://api.onvopay.com/v1/payment-methods/cl40muorw00493ndp0okzk2g3', headers=headers, data=json.dumps(data)) print(response.json()) post: tags: - Métodos de pago summary: Actualizar un Método de pago description: | Consultá la documentación de ONVO para ver detalles de integración y ejemplos. Cuando actualizás los datos de un método de pago de tipo `card`, ONVO vuelve a verificar la tarjeta. Si la verificación falla, el endpoint responde `400` con `code: "cards.invalid_card_info"`. Para rechazos manejados, la respuesta puede incluir `details.card`. `gateway_declined` identifica una regla no técnica del gateway/adquirente; `processor_error` identifica una falla técnica. Usá los campos superiores del error como respaldo cuando `details` no esté presente. security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodResponse" description: "" "400": content: application/json: schema: oneOf: - $ref: "#/components/schemas/ValidationError" - $ref: "#/components/schemas/OnvoAPIError" examples: verificacionTarjetaFallida: summary: Verificación de tarjeta fallida value: code: cards.invalid_card_info path: /v1/payment-methods/cl40muorw00493ndp0okzk2g3 type: OnvoAPIError message: There was an error with the card information provided. Please review card number, expiration date and cvv details: card: reason: issuer_declined declineCode: "55" declineMessage: Incorrect PIN timestamp: 2026-04-29T17:36:28.477Z statusCode: 400 description: "Solicitud inválida. Al actualizar un método de pago de tipo `card`, también puede indicar que la verificación de la tarjeta falló." requestBody: $ref: "#/components/requestBodies/UpdatePaymentMethod" /v1/payment-methods/{id}/verify: post: tags: - Métodos de pago summary: Verificar un Método de pago description: Verifica un método de pago que requiere confirmación manual, como una cuenta bancaria. security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del método de pago. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/VerifyPaymentMethodResponse" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/VerifyPaymentMethodNotRequired" description: "Bad Request" requestBody: $ref: "#/components/requestBodies/VerifyPaymentMethod" /v1/payment-methods/{id}/verification: get: tags: - Métodos de pago summary: Obtener verificación de un Método de pago description: Retorna el estado de verificación asociado a un método de pago. security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del método de pago. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentMethodVerification" description: "Success" /v1/bank-accounts/check-info: post: tags: - Métodos de pago summary: Validar información de una cuenta bancaria description: Valida el estado, moneda y verificación de una cuenta bancaria antes de crear o confirmar un método de pago. security: - PublishableApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/BankAccountCheckInfoResponse" description: "Success" requestBody: $ref: "#/components/requestBodies/BankAccountCheckInfo" /v1/mobile-transfers/list: get: tags: - SINPE Móvil summary: Listar pagos por SINPE Móvil description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: sortOrder in: query description: Orden de los resultados por fecha de creación. Por defecto es `desc` (más recientes primero). example: desc schema: type: string enum: - asc - desc - name: status in: query description: "Filtra por estado del pago. Podés especificar múltiples estados separados por coma (ej: `received,pending`)." example: received schema: type: string - name: SINPERefNumber in: query description: Filtra por el número de referencia SINPE exacto. Este es un identificador único de 25 caracteres generado por el sistema SINPE para cada transferencia. example: "2025121616183220990502000" schema: type: string - name: originId in: query description: | Filtra por el número de identificación (cédula) del remitente. El formato varía según el tipo de identificación: - **Cédula física**: `0#-####-####` (Ej: `01-1393-1919`) - **DIMEX**: `1###########` (Ej: `1293817461127`) - **Cédula jurídica**: `2-###-######` o `3-###-######` (Ej: `3-101-212393`) - **NITE**: `4-000-######` (Ej: `4-000-042141`) - **DIDI**: `5###########` (Ej: `5123456789011`) - **Pasaporte/Otro**: `9###########` (Ej: `9CA9381461127`) example: "01-0000-0000" schema: type: string - name: originName in: query description: Búsqueda parcial por el nombre del remitente (no sensible a mayúsculas/minúsculas). example: "Juan" schema: type: string - name: description in: query description: Búsqueda parcial en la descripción del pago (no sensible a mayúsculas/minúsculas). example: "factura" schema: type: string - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2024-01-15T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2024-01-15T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2024-01-15T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2024-01-15T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: clm8x9abc0001jk08example12 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: clm8x9abc0001jk08example12 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/MobileTransferList" description: "Lista de pagos por SINPE Móvil" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request - La cuenta no tiene habilitado el número móvil personalizado" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" x-codeSamples: - lang: "cURL" source: | curl -X GET "https://api.onvopay.com/v1/mobile-transfers/list?status=received&limit=10" \ -H "Authorization: Bearer " - lang: "JavaScript" source: | fetch('https://api.onvopay.com/v1/mobile-transfers/list?status=received&limit=10', { method: 'GET', headers: { 'Authorization': 'Bearer ' } }) .then(response => response.json()) .then(data => console.log(data)); - lang: "Python" source: | import requests headers = { 'Authorization': 'Bearer ' } params = { 'status': 'received', 'limit': 10 } response = requests.get( 'https://api.onvopay.com/v1/mobile-transfers/list', headers=headers, params=params ) print(response.json()) - lang: "PHP" source: | "https://api.onvopay.com/v1/mobile-transfers/list?status=received&limit=10", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " ], ]); $response = curl_exec($curl); curl_close($curl); echo $response; /v1/payment-intents: post: tags: - Intenciones de pago summary: Crear una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreatePaymentIntent" /v1/refunds: post: tags: - Reembolsos summary: Crear un Reembolso description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Refund" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateRefund" /v1/refunds/{id}: get: tags: - Reembolsos summary: Obtener un Reembolso description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Refund" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/refunds/cl40muorw00493ndp0okzk2g3', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) /v1/payment-intents/account: get: tags: - Intenciones de pago summary: Listar todas las Intenciones de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentIntentList" description: "" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/payment-intents/account', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' }, }) - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } response = requests.get('https://api.onvopay.com/v1/payment-intents/account', headers=headers, data=json.dumps(data)) print(response.json()) - lang: "C#" source: | var headers = new Dictionary(); headers.Add("Content-Type", "application/json"); headers.Add("Authorization", "Bearer "); var data = new Dictionary(); data.Add("name", "John Doe"); data.Add("email", "email@example.com"); data.Add("phone", "+50688880000"); data.Add("shipping", new { name = "John Doe", address = new { line1 = "Calle 123", line2 = "Edificio A", city = "Ciudad", state = "Estado", country = "AR", postalCode = "12345" } }); var response = await httpClient.PostAsync("https://api.onvopay.com/v1/payment-intents/account", new StringContent(JsonConvert.SerializeObject(data), Encoding.UTF8, "application/json")); Console.WriteLine(response.Content.ReadAsStringAsync().Result); /v1/payment-intents/{id}: get: tags: - Intenciones de pago summary: Obtener una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" post: tags: - Intenciones de pago summary: Actualizar una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "" requestBody: $ref: "#/components/requestBodies/CreatePaymentIntent" /v1/payment-intents/{id}/confirm: post: tags: - Intenciones de pago summary: Confirmar una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "" requestBody: $ref: "#/components/requestBodies/ConfirmPaymentIntent" /v1/payment-intents/{id}/capture: post: tags: - Intenciones de pago summary: Capturar una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "" requestBody: $ref: "#/components/requestBodies/CapturePaymentIntent" /v1/payment-intents/{id}/cancel: post: tags: - Intenciones de pago summary: Cancelar una Intención de pago description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/PaymentIntent" description: "" /v1/products: post: tags: - Productos summary: Crear un Producto description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Product" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateProduct" get: tags: - Productos summary: Listar todos los Productos description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ProductList" description: "" /v1/products/{id}: get: tags: - Productos summary: Obtener un Producto description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Product" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" post: tags: - Productos summary: Actualizar un Producto description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Product" description: "" requestBody: $ref: "#/components/requestBodies/CreateProduct" delete: tags: - Productos summary: Borrar un Producto description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Product" description: "" /v1/prices: post: tags: - Precios summary: Crear un Precio description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Price" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreatePrice" get: tags: - Precios summary: Listar todos los Precios description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PriceList" description: "" /v1/prices/{id}: get: tags: - Precios summary: Obtener un Precio description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Price" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" post: tags: - Precios summary: Actualizar un Precio description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Price" description: "" x-codeSamples: - lang: "Python" source: | import requests import json headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } data = { 'name': 'John Doe', 'email': 'email@example.com', 'phone': '+50688880000', 'shipping': { 'name': 'John Doe', 'address': { 'line1': 'Calle 123', 'line2': 'Edificio A', 'city': 'Ciudad', 'state': 'Estado', 'country': 'AR', 'postalCode': '12345' } } } response = requests.post('https://api.onvopay.com/v1/customers/cl40muorw00493ndp0okzk2g3', headers=headers, data=json.dumps(data)) print(response.json()) requestBody: $ref: "#/components/requestBodies/CreatePrice" delete: tags: - Precios summary: Borrar un Precio description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Price" description: "" /v1/checkout/sessions/one-time-link: post: tags: - Sesiones de Checkout summary: Crear una Sesión de Checkout description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateCheckoutSessionOneTimeLink" /v1/checkout/sessions/link/{paymentLinkId}: get: tags: - Sesiones de Checkout summary: Crear una sesión desde un link de pago description: Crea una sesión de Checkout a partir de un link de pago existente. parameters: - name: paymentLinkId in: path description: Identificador único del link de pago. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" /v1/checkout/sessions/{id}: get: tags: - Sesiones de Checkout summary: Obtener una Sesión de Checkout description: Retorna una sesión de Checkout por su identificador. parameters: - name: id in: path description: Identificador único de la sesión de Checkout. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" /v1/checkout/sessions/one-time-link/{id}: get: tags: - Sesiones de Checkout summary: Obtener un link de pago description: Retorna un link de pago creado desde Checkout. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del link de pago. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" /v1/checkout/sessions/{id}/confirm: post: tags: - Sesiones de Checkout summary: Confirmar una Sesión de Checkout description: Confirma una sesión de Checkout con el método de pago seleccionado. security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único de la sesión de Checkout. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" requestBody: $ref: "#/components/requestBodies/ConfirmCheckoutSession" /v1/checkout/sessions/{id}/line-item: post: tags: - Sesiones de Checkout summary: Actualizar item de una Sesión de Checkout description: Actualiza el item seleccionado de una sesión de Checkout abierta. security: - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único de la sesión de Checkout. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" requestBody: $ref: "#/components/requestBodies/UpdateCheckoutSessionLineItem" /v1/checkout/sessions/{id}/customer: patch: tags: - Sesiones de Checkout summary: Actualizar cliente de una Sesión de Checkout description: Actualiza los datos de contacto del cliente en una sesión de Checkout. security: - PublishableApiKey: [] - SecretApiKey: [] parameters: - name: id in: path description: Identificador único de la sesión de Checkout. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" requestBody: $ref: "#/components/requestBodies/PatchCheckoutSessionCustomer" /v1/checkout/sessions/{id}/expire: post: tags: - Sesiones de Checkout summary: Expirar una Sesión de Checkout description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único de la sesión de Checkout. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/CheckoutSession" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" /v1/checkout/sessions/one-time-link/account: get: tags: - Sesiones de Checkout summary: Listar Sesiones de Checkout description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: onvo-on-behalf-of in: header description: Filtra la lista por la cuenta de [marketplace](#tag/Marketplaces) indicada. required: false schema: type: string responses: "200": content: application/json: schema: type: array items: $ref: "#/components/schemas/CheckoutSession" description: "OK" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/checkout/sessions/one-time-link/account', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) /v1/coupons: post: tags: - Cupones summary: Crear un Cupón description: Crea un cupón que después podés asociar a una sesión de Checkout de un solo uso. security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Coupon" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateCoupon" get: tags: - Cupones summary: Listar Cupones description: Lista los cupones creados en el modo de la API key. security: - SecretApiKey: [] responses: "200": content: application/json: schema: type: array items: $ref: "#/components/schemas/Coupon" description: "Success" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" /v1/coupons/{id}: get: tags: - Cupones summary: Obtener un Cupón description: Retorna un cupón por su identificador. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cupón. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Coupon" description: "Success" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "Not Found" post: tags: - Cupones summary: Actualizar un Cupón description: Actualiza un cupón. Cuando enviás `binRules` o `promotionCodes`, ONVO reemplaza la lista anterior por la lista enviada. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cupón. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Coupon" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "Not Found" requestBody: $ref: "#/components/requestBodies/CreateCoupon" delete: tags: - Cupones summary: Borrar un Cupón description: Borra un cupón por su identificador. security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cupón. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Coupon" description: "Success" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "Not Found" /v1/invoices: get: tags: - Renovaciones summary: Listar renovaciones description: |- Lista las renovaciones de la cuenta. Las renovaciones representan cada período de cobro de un cargo recurrente. ONVO crea una renovación al inicio de la suscripción y en cada renovación exitosa. Cada renovación está asociada a una intención de pago y permite consultar el cobro que corresponde a ese período. Ejemplos de URLs: - Paginación: `GET /v1/invoices?limit=25&startingAfter=cl40muorw00493ndp0okzk2g3` - Filtrar por cliente y estado: `GET /v1/invoices?customerId=cl40muorw00493ndp0okzk2g3&status=paid` - Filtrar por varios estados: `GET /v1/invoices?status=open,paid` - Filtrar por rango de fechas: `GET /v1/invoices?createdAt[gte]=2026-01-01T00:00:00.000Z&createdAt[lte]=2026-01-31T23:59:59.999Z` - Filtrar por rango de montos: `GET /v1/invoices?total[gte]=1000&total[lte]=5000` - Filtrar por metadata: `GET /v1/invoices?metadata[key]=orderId&metadata[value]=order_123` - Expandir objetos relacionados: `GET /v1/invoices?expand=payment_intent&expand=subscription` Si construís la URL manualmente, podés escribir filtros con corchetes como `createdAt[gte]` y `metadata[key]`. Los clientes HTTP suelen codificarlos como `createdAt%5Bgte%5D` y `metadata%5Bkey%5D` al enviar la solicitud. security: - SecretApiKey: [] parameters: - name: subscriptionId in: query description: Identificador único del cargo recurrente asociado a la renovación. example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: paymentIntentId in: query description: Identificador único de la intención de pago asociada a la renovación. example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: customerId in: query description: Identificador único del cliente asociado a la renovación. example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: status in: query description: Estado de la renovación. Podés enviar uno o varios estados separados por coma. example: paid schema: type: string enum: - draft - open - paid - void - uncollectible - name: currency in: query description: Moneda de la renovación. example: USD schema: type: string enum: - USD - CRC - GTQ - NIO - PAB - PEN - MXN - COP - HNL - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: total[gte] in: query description: Monto mínimo total de la renovación en centavos. example: 1000 schema: type: number - name: total[lte] in: query description: Monto máximo total de la renovación en centavos. example: 5000 schema: type: number - name: metadata[key] in: query description: Llave de metadata para filtrar renovaciones. example: orderId schema: type: string - name: metadata[value] in: query description: Valor de metadata para filtrar renovaciones. example: order_123 schema: type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 25." example: 25 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: expand in: query description: "Permite expandir objetos relacionados. Valores soportados: `payment_intent` y `subscription`." example: payment_intent schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InvoiceList" description: "OK" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" x-codeSamples: - lang: "JS" source: | const params = new URLSearchParams(); params.set('limit', '25'); params.set('status', 'paid'); params.set('customerId', 'cl40muorw00493ndp0okzk2g3'); params.set('createdAt[gte]', '2026-01-01T00:00:00.000Z'); params.set('createdAt[lte]', '2026-01-31T23:59:59.999Z'); params.set('metadata[key]', 'orderId'); params.set('metadata[value]', 'order_123'); params.append('expand', 'payment_intent'); params.append('expand', 'subscription'); fetch(`https://api.onvopay.com/v1/invoices?${params.toString()}`, { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) - lang: "Shell" source: | curl -G 'https://api.onvopay.com/v1/invoices' \ -H 'Authorization: Bearer ' \ --data-urlencode 'limit=25' \ --data-urlencode 'status=paid' \ --data-urlencode 'customerId=cl40muorw00493ndp0okzk2g3' \ --data-urlencode 'createdAt[gte]=2026-01-01T00:00:00.000Z' \ --data-urlencode 'createdAt[lte]=2026-01-31T23:59:59.999Z' \ --data-urlencode 'metadata[key]=orderId' \ --data-urlencode 'metadata[value]=order_123' \ --data-urlencode 'expand=payment_intent' \ --data-urlencode 'expand=subscription' - lang: "Python" source: | import requests headers = { 'Authorization': 'Bearer ' } params = { 'limit': 25, 'status': 'paid', 'customerId': 'cl40muorw00493ndp0okzk2g3', 'createdAt[gte]': '2026-01-01T00:00:00.000Z', 'createdAt[lte]': '2026-01-31T23:59:59.999Z', 'metadata[key]': 'orderId', 'metadata[value]': 'order_123', 'expand': ['payment_intent', 'subscription'] } response = requests.get( 'https://api.onvopay.com/v1/invoices', headers=headers, params=params ) print(response.json()) /v1/invoices/{id}: get: tags: - Renovaciones summary: Obtener una renovación description: "Devuelve una renovación específica. Las renovaciones representan cada período de cobro de un cargo recurrente. ONVO crea una renovación al inicio de la suscripción y en cada renovación exitosa. Cada renovación está asociada a una intención de pago y permite consultar el cobro que corresponde a ese período." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Invoice" description: "OK" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "Not Found" x-codeSamples: - lang: "JS" source: | fetch('https://api.onvopay.com/v1/invoices/cl40muorw00493ndp0okzk2g3', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' } }) /v1/subscriptions: post: tags: - Cargos recurrentes summary: Crear un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Subscription" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateSubscription" get: tags: - Cargos recurrentes summary: Listar todos los Cargos recurrentes description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: onvo-on-behalf-of in: header description: Filtra la lista por la cuenta de [marketplace](#tag/Marketplaces) indicada. required: false schema: type: string - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: customerId in: query description: Identificador único del cliente asociado al cargo recurrente. example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: status in: query description: "Corresponde a uno o varios estados del cargo recurrente, separados por coma. Valores permitidos: `active`, `past_due`, `canceled`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing`." example: active schema: type: string - name: email in: query description: "Corresponde al correo electronico de un [Cliente](#tag/Clientes) asociado a un cargo recurrente." example: test@onvopay.com schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SubscriptionList" description: "" /v1/subscriptions/{id}: get: tags: - Cargos recurrentes summary: Obtener un Cargo Recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Subscription" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" post: tags: - Cargos recurrentes summary: Actualizar un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Subscription" description: "" requestBody: $ref: "#/components/requestBodies/UpdateSubscription" delete: tags: - Cargos recurrentes summary: Cancelar un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Subscription" description: "" /v1/subscriptions/{id}/confirm: post: tags: - Cargos recurrentes summary: Confirmar un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/Subscription" description: "" requestBody: $ref: "#/components/requestBodies/ConfirmSubscription" /v1/subscriptions/{id}/items: post: tags: - Cargos recurrentes summary: Agregar item a un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único del cargo recurrente. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/SubscriptionAditionalItem" description: "" requestBody: $ref: "#/components/requestBodies/AddItem" /v1/subscriptions/{id}/items/{item}: patch: tags: - Cargos recurrentes summary: Actualizar item de un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] - PublishableApiKey: [] parameters: - name: id in: path description: Identificador único del cargo recurrente. required: true schema: type: string - name: item in: path description: Identificador único del item. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/SubscriptionAditionalItem" description: "" requestBody: $ref: "#/components/requestBodies/UpdateItem" /v1/subscriptions/{id}/items/{itemId}: delete: tags: - Cargos recurrentes summary: Borrar item de un Cargo recurrente description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del cargo recurrente. required: true schema: type: string - name: itemId in: path description: Identificador único del item. required: true schema: type: string responses: "200": description: "Success" /v1/shipping-rates: post: tags: - Tarifas de envío summary: Crear una tarifa de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShippingRate" description: "Success" "400": content: application/json: schema: $ref: "#/components/schemas/ValidationError" description: "Bad Request" "401": content: application/json: schema: $ref: "#/components/schemas/UnauthorizedError" description: "Unauthorized" "403": content: application/json: schema: $ref: "#/components/schemas/ForbiddenError" description: "Forbidden" requestBody: $ref: "#/components/requestBodies/CreateShippingRate" get: tags: - Tarifas de envío summary: Listar todas las tarifas de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] # "parameters":[{"name":"endingBefore","required":false,"in":"query","description":"endingBefore","schema":{"type":"string"}},{"name":"startingAfter","required":false,"in":"query","description":"startingAfter","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"limit","schema":{"type":"number"}},{"name":"email","required":false,"in":"query","description":"email","schema":{"type":"string"}},{"required":false,"name":"lt","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"lte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gte","in":"query","schema":{"format":"date-time","type":"string"}},{"required":false,"name":"gt","in":"query","schema":{"format":"date-time","type":"string"}} parameters: - name: createdAt[lt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[lte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es menor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gt] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: createdAt[gte] in: query description: Fecha y hora, en formato ISO 8901 y con zona horaria en UTC, que filtra los resultados donde `createdAt` es mayor o igual que el valor especificado. example: 2022-06-12T21:21:10.587Z schema: format: date-time type: string - name: endingBefore in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string - name: limit in: query description: "Un límite en la cantidad de objetos a retornar. Puede ser un valor entre 1 y 100, el valor por defecto es 10." example: 50 schema: type: number - name: startingAfter in: query description: "Un cursor usado para paginación. Corresponde al ID de un objeto existente." example: cl40muorw00493ndp0okzk2g3 schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShippingRateList" description: "" /v1/shipping-rates/{id}: get: tags: - Tarifas de envío summary: Obtener una tarifa de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShippingRate" description: "" "404": content: application/json: schema: $ref: "#/components/schemas/NotFoundError" description: "" post: tags: - Tarifas de envío summary: Actualizar una tarifa de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/ShippingRate" description: "" requestBody: $ref: "#/components/requestBodies/CreateShippingRate" delete: tags: - Tarifas de envío summary: Borrar una tarifa de envío description: "Consultá la documentación de ONVO para ver detalles de integración y ejemplos." security: - SecretApiKey: [] parameters: - name: id in: path description: Identificador único del objeto. required: true schema: type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ShippingRate" description: ""