# ONVO Docs (English)

> Official documentation for integrating ONVO: payments, checkout, webhooks, authentication, testing, and API reference.

OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

# Authentication

URL: https://docs.onvopay.com/en/authentication
Markdown: https://docs.onvopay.com/en/authentication.md

# Authentication

ONVO authenticates requests with API keys sent as Bearer tokens.

```http
Authorization: Bearer onvo_test_secret_key_...
```

## Where to get your API keys

API keys are available from the ONVO Dashboard at [onvopay.com](https://onvopay.com/) after you register an account. When the account is created, ONVO automatically generates test API keys so you can integrate and validate your flow in test mode.

After you complete onboarding, your account can switch to live mode from the Dashboard and obtain live API keys.

## Related API reference

- [API introduction](/en/api)
- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)

## Key types

| Key | Use |
| --- | --- |
| `onvo_test_secret_key_...` | Server-side code in test mode. |
| `onvo_live_secret_key_...` | Server-side code in live mode. |
| `onvo_test_publishable_key_...` | Client-side code in test mode. |
| `onvo_live_publishable_key_...` | Client-side code in live mode. |

:::warning
Never expose secret keys in browsers, public mobile apps, or repositories.
:::

## HTTPS

All requests must use HTTPS. Requests without authentication or over HTTP fail.

---

# One-time links

URL: https://docs.onvopay.com/en/checkout/one-time-links
Markdown: https://docs.onvopay.com/en/checkout/one-time-links.md

# One-time links

One-time links create a direct Checkout session for a fixed charge. Use them when you already know the final amount and want to send a payment URL to the buyer.

For donations, tips, or charges where the buyer chooses the amount, use [Customer chooses what to pay](/en/checkout/open-amount).

## Related API reference

- [Create a Checkout session](/en/api/crear-una-sesion-de-checkout)
- [List Checkout sessions](/en/api/listar-sesiones-de-checkout)
- [Expire a Checkout session](/en/api/expirar-una-sesion-de-checkout)
- [Create a coupon](/en/api/crear-un-cupon)
- [List coupons](/en/api/listar-cupones)

## Create a fixed amount session

The endpoint receives `lineItems`. Each item can use an existing `priceId` or create an inline product with `unitAmount`, `currency`, and `description`. Amounts are sent in the currency's minor unit.

```bash
curl https://api.onvopay.com/v1/checkout/sessions/one-time-link \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "quantity": 1,
        "unitAmount": 250000,
        "currency": "CRC",
        "description": "Order #1001"
      }
    ],
    "customerEmail": "buyer@example.com",
    "redirectUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "discounts": [
      {
        "coupon": "cpn_abc123"
      }
    ],
    "metadata": {
      "orderId": "1001"
    }
  }'
```

The response includes `url`. Redirect the buyer to that URL or send it through the channel your sales flow uses.

## Marketplace

If the charge belongs to a seller in your marketplace, send `onBehalfOf` with that marketplace account's `Account ID` when creating the session. ONVO applies marketplace routing to the payment intent generated for that session.

## Coupons for one-time links

You can create coupons from the dashboard or from the API:

- In the dashboard, go to **Discounts** and create the coupon with the visual form. This works well for campaigns operated by commercial or support teams.
- In the API, create the coupon with `POST /v1/coupons`. This works well for campaigns generated by your backend, internal integrations, or bulk operations.

Both paths create the same `Coupon` object. To use it in a one-time link, keep the coupon `id` and send it in `discounts` when you create the Checkout session.

### Recommended flow

1. Create the coupon in the dashboard or with the API.
2. Configure its rules: discount type, redemption limit, expiration date, and eligible BINs.
3. Create the one-time link with `discounts: [{ "coupon": "cpn_..." }]`.
4. Checkout applies the discount during payment when the buyer's card matches an active BIN rule.

### Create a coupon with the API

This example creates a 10% coupon for cards whose BIN starts with `411111`.

```bash
curl https://api.onvopay.com/v1/coupons \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sponsor Bank 10%",
    "type": "percentage",
    "percentOff": 10,
    "scope": "checkout_session",
    "appliesTo": ["one_time_links"],
    "maxRedemptions": 100,
    "redeemBy": "2026-06-30",
    "binRules": [
      {
        "bin": "411111"
      }
    ]
  }'
```

The response includes the coupon `id`. Use that value in the link payload:

```json
{
  "discounts": [
    {
      "coupon": "cpn_abc123"
    }
  ]
}
```

### Main attributes

| Attribute | What it does |
| --- | --- |
| `name` | Internal name used to identify the coupon in the dashboard, reports, and Checkout responses. |
| `type` | Defines whether the discount is `percentage` or `fixed_amount`. |
| `percentOff` | Percentage discount when `type` is `percentage`. It must be greater than `0` and at most `100`. |
| `amountOff` | Fixed discount amount when `type` is `fixed_amount`. Send it in the currency's minor unit. |
| `currency` | Required currency for `fixed_amount` coupons. It must match the link currency. |
| `scope` | Coupon scope. For one-time links, use `checkout_session`. If omitted, ONVO uses that default. |
| `appliesTo` | Surfaces where the coupon can be used. For these links, include `one_time_links`. If omitted, ONVO uses that default. |
| `binRules` | Card BINs that make the discount eligible. |
| `maxRedemptions` | Total number of successful payments that can consume the coupon. Omit it for no limit. |
| `redeemBy` | Last date the coupon can be used. Send a full ISO date or `YYYY-MM-DD`; date-only values are normalized to Costa Rica midnight. |
| `isActive` | Enables or disables the coupon without deleting it. Defaults to `true`. |
| `promotionCodes` | Promotion codes associated with the coupon. In one-time links, these are used by your backend, not as a visible field where the buyer enters a code. |

### Discount types

Use `percentage` when you want to discount a percentage of the final amount:

```json
{
  "type": "percentage",
  "percentOff": 15
}
```

Use `fixed_amount` when you want to discount a specific amount:

```json
{
  "type": "fixed_amount",
  "amountOff": 250000,
  "currency": "CRC"
}
```

Amounts are sent in the currency's minor unit. For example, `250000` in `CRC` represents `CRC 2,500.00`.

### BIN rules

One-time link discounts are applied by BIN. A BIN is the first digits of a card; ONVO accepts `6` to `8` digit rules. In the dashboard, the BIN field is a simple list: paste or type the eligible BINs and ONVO stores them as rules. In the API, that same list is sent as `binRules`, where each item has at least `bin`.

Send digits only, without spaces or hyphens. When the buyer enters or selects a card, Checkout checks whether the BIN matches an active rule on the coupon.

```json
{
  "binRules": [
    {
      "bin": "411111"
    },
    {
      "bin": "41111112"
    }
  ]
}
```

If multiple eligible coupons match the BIN, ONVO applies the highest discount. If the discount amount ties, it uses the more specific BIN rule, meaning the one with more digits.

Real eligibility depends on `bin` and whether the rule is active.

Each rule can include `isActive`. This lets you pause a specific BIN without disabling the whole coupon. If you update a coupon through the API and send `binRules`, ONVO replaces the previous list with the list you sent, so include every rule you want to keep.

### Promotion codes

A coupon can have promotion codes attached:

```json
{
  "promotionCodes": [
    {
      "code": "SUMMER25"
    }
  ]
}
```

ONVO stores the code in uppercase. In the one-time link creation payload, `promotionCode` expects the promotion code object `id`, not the text code:

```json
{
  "discounts": [
    {
      "promotionCode": "promo_abc123"
    }
  ]
}
```

For new integrations, sending `coupon` directly is the simplest path. Use `promotionCode` when you already manage promotion codes as separate objects in your system.

If you update a coupon through the API and send `promotionCodes`, ONVO also replaces the previous list with the list you sent.

### Apply the coupon to the link

To create a discounted link, add `discounts` to the session payload. ONVO accepts one discount per session. That discount can point to a direct coupon or to a promotion code:

```json
{
  "discounts": [
    {
      "coupon": "cpn_abc123"
    }
  ]
}
```

Send `coupon` or `promotionCode`, but not both in the same object. The value must be the `id` of the coupon or promotion code.

The coupon must be active, belong to the same session mode (`test` or `live`), have `checkout_session` scope, and apply to `one_time_links`. If you use a fixed-amount coupon, the coupon currency must match the link currency.

For one-time links, do not use `allowPromotionCodes`: Checkout receives the specific discount from `discounts` and applies it during payment.

### Checklist

- The coupon and session must be in the same mode: `test` or `live`.
- The coupon must be active.
- For one-time links, use `scope: "checkout_session"` and `appliesTo: ["one_time_links"]`.
- For fixed-amount discounts, `currency` must match the link currency.
- Add at least one active BIN rule so Checkout can apply the discount to eligible cards.
- Copy the coupon `id` from the dashboard or from the `POST /v1/coupons` response.

---

# Customer chooses what to pay

URL: https://docs.onvopay.com/en/checkout/open-amount
Markdown: https://docs.onvopay.com/en/checkout/open-amount.md

# Customer chooses what to pay

Letting the customer choose what to pay does not require a third price type. In ONVO, a price still uses `type: "one_time"` or `type: "recurring"`; this experience is enabled with `customUnitAmount` on the price. For Checkout, use `type: "one_time"` when you want the buyer to choose an amount for a one-time payment.

This flow uses the same catalog model as a standard charge: create a product, create a price with `customUnitAmount` for that product, and create a Checkout session that references that price.

## When to use it

- Donations or voluntary contributions.
- Tips.
- Reservations or payments where the buyer defines the amount within a range.
- Forms where you want to suggest an initial amount but allow changes.

## 1. Create the product

Create the product that Checkout displays. The description and images help the buyer understand what they are paying for.

```bash
curl https://api.onvopay.com/v1/products \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blue Foundation donation",
    "description": "Voluntary contribution for the annual campaign",
    "images": [
      "https://example.com/donation.png"
    ]
  }'
```

Save the product `id` so you can create the price.

## 2. Create the price

Create a `one_time` price with `customUnitAmount`. Values are sent in the currency's minor unit: cents for `USD` and centimos for `CRC`.

```bash
curl https://api.onvopay.com/v1/prices \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "CRC",
    "type": "one_time",
    "productId": "prod_abc123",
    "customUnitAmount": {
      "preset": 1000000,
      "minimum": 500000,
      "maximum": 5000000
    }
  }'
```

In this example, Checkout suggests `CRC 10,000.00`, allows the buyer to go down to `CRC 5,000.00`, and allows the buyer to go up to `CRC 50,000.00`.

Do not send `unitAmount` on this price. When a price uses `customUnitAmount`, ONVO stores the fixed amount as `0` and uses `preset`, `minimum`, and `maximum` for the Checkout experience.

## 3. Create the Checkout session

Create the session with the `priceId` for the price you just created. Use a single line item with `quantity: 1`.

```bash
curl https://api.onvopay.com/v1/checkout/sessions/one-time-link \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      {
        "priceId": "price_abc123",
        "quantity": 1
      }
    ],
    "redirectUrl": "https://example.com/thanks",
    "cancelUrl": "https://example.com/canceled",
    "metadata": {
      "campaignId": "donations-2026"
    }
  }'
```

The session does not receive `customUnitAmount` directly. Checkout reads that configuration from the associated price and shows the suggested amount, minimum, and maximum to the buyer.

ONVO Checkout saves the amount the buyer chooses before confirming the payment. The merchant does not need to call an additional endpoint to apply that amount to the session.

## Important rules

- Do not send `unitAmount` and `customUnitAmount` on the same price.
- Send either `productId` or `productData` when creating the price, but not both.
- `preset` is required and must be within `minimum` and `maximum` when you send those limits.
- For this experience, use a single line item with `quantity: 1`.
- Use `type: "one_time"` when the customer chooses what to pay in Checkout. `recurring` is still for recurring charges.

---

# Checkout

URL: https://docs.onvopay.com/en/checkout/overview
Markdown: https://docs.onvopay.com/en/checkout/overview.md

# Checkout

Checkout lets you create a payment experience hosted by ONVO so you do not need to build the entire payment form.

## Related API reference

- [Create a Checkout session](/en/api/crear-una-sesion-de-checkout)
- [List Checkout sessions](/en/api/listar-sesiones-de-checkout)
- [Expire a Checkout session](/en/api/expirar-una-sesion-de-checkout)
- [Checkout sessions](/en/api/sesiones-de-checkout)

## When to use Checkout

- You want to reach production quickly.
- You prefer to delegate payment UI and validation.
- You need a payment URL to send to the buyer.
- You want to let the [customer choose what to pay](/en/checkout/open-amount) for donations, tips, or variable charges.

## Base flow

1. Create a session or payment link.
2. Redirect the buyer to the Checkout URL.
3. Receive the result by webhook.
4. Update your order internally.

---

# AI Markdown

URL: https://docs.onvopay.com/en/developer-tools/ai-markdown
Markdown: https://docs.onvopay.com/en/developer-tools/ai-markdown.md

# AI Markdown

ONVO publishes Markdown versions so agents, editors, and assistants can read the documentation without processing HTML.

## Available files

| File | Use |
| --- | --- |
| [`/en/llms.txt`](https://docs.onvopay.com/en/llms.txt) | Short index with the main pages. |
| [`/en/llms-full.txt`](https://docs.onvopay.com/en/llms-full.txt) | Full documentation context. |
| [`/openapi.yaml`](https://docs.onvopay.com/openapi.yaml) | Source OpenAPI schema. |
| `/en/*.md` | Markdown version of each English page. |

## Example

```bash
curl https://docs.onvopay.com/en/llms.txt
curl https://docs.onvopay.com/en/llms-full.txt
curl https://docs.onvopay.com/openapi.yaml
```

Every page includes an action to copy its Markdown.

---

# Getting started

URL: https://docs.onvopay.com/en/getting-started
Markdown: https://docs.onvopay.com/en/getting-started.md

# Getting started

This guide summarizes the base ONVO integration flow.

## Related API reference

- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Create a Checkout session](/en/api/crear-una-sesion-de-checkout)

## 1. Get your keys

Open the ONVO Dashboard and copy a test secret key and publishable key. Test keys do not interact with real banking networks.

```bash
export ONVO_SECRET_KEY="onvo_test_secret_key_..."
export ONVO_PUBLISHABLE_KEY="onvo_test_publishable_key_..."
```

## PCI and card data

To reduce PCI scope in card integrations, create the payment method client-side with the publishable key and send only the `paymentMethodId` to your backend. Do not pass PAN, CVV, or full card data through your server. If you prefer to delegate card collection to ONVO, use [Checkout](/en/checkout/overview) or the [web SDK](/en/integrations/sdk).

## 2. Create a payment intent

A payment intent represents the charge lifecycle for an order.

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "CRC",
    "description": "Order #1001"
  }'
```

## 3. Confirm the payment

Confirm the intent with the buyer's payment method, or use Checkout if you want ONVO to host the payment experience.

## 4. Listen for webhooks

Register an endpoint to receive events like `payment-intent.succeeded` and reconcile your order internally.

## 5. Move to live mode

After the account is activated, switch to an `onvo_live_` key and repeat end-to-end testing before opening the flow to buyers.

---

# Magento Extension

URL: https://docs.onvopay.com/en/integrations/magento
Markdown: https://docs.onvopay.com/en/integrations/magento.md

# Magento Extension

ONVO provides an extension for Magento sites. Use it to enable ONVO Pay payments in your e-commerce site.

## Related API reference

- [Create a Checkout session](/en/api/crear-una-sesion-de-checkout)
- [Payment intents](/en/api/intenciones-de-pago)
- [Refunds](/en/api/reembolsos)

## Prerequisites

- Magento `2.4.3` or later.
- PHP `7.1` or later.
- Secret key and publishable key from the ONVO Dashboard.

## Install with Composer

From the console, go to the Magento project root and run:

```bash
composer require logeek-io/onvo-magento
```

## Install by directory

Download the plugin and upload it to:

```text
/app/code/ONVO/
```

## Activation

Run the Magento commands:

```bash
bin/magento setup:upgrade
bin/magento setup:di:compile
```

Then open `Stores -> Configuration -> Sales -> Payment Methods -> ONVO Pay` and configure:

- Secret key.
- Publishable key.

Use test or live keys depending on the mode you want to operate.

---

# Web SDK

URL: https://docs.onvopay.com/en/integrations/sdk
Markdown: https://docs.onvopay.com/en/integrations/sdk.md

# Web SDK

The ONVO web SDK lets you render a payment component on your site using a publishable key and a resource created from your server.

## Related API reference

- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Create a subscription](/en/api/crear-un-cargo-recurrente)
- [Create a customer](/en/api/crear-un-cliente)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)

## Installation

Include the SDK script.

```html
<script src="https://sdk.onvopay.com/sdk.js"></script>
```

## Prerequisites

- Get your secret key and publishable key from the ONVO Dashboard.
- Create a payment intent or subscription from your server using the secret key.
- Pass the identifier to the frontend to render the SDK.

## One-time payment

Create the payment intent server-side.

```js
const { data, status } = await axios.post(
  "https://api.onvopay.com/v1/payment-intents",
  {
    currency: "USD",
    amount: 1000,
    description: "my first payment intent",
  },
  {
    headers: {
      Authorization: "Bearer your_secret_key",
    },
  },
);

if (status === 201) {
  console.log(data.id);
}
```

Render the component on the frontend.

```html
<div id="container"></div>

<script>
  onvo.pay({
    onError: (data) => {
      console.log("error", data);
    },
    onSuccess: (data) => {
      console.log("success", data);
    },
    publicKey: "public-key",
    paymentIntentId: "cl4de13uc457301lor2o0q9w1",
    paymentType: "one_time",
    customerId: "cl40wvnby1653akslv93ktgdk",
  }).render("#container");
</script>
```

## Handling card errors

When card verification fails, `onError(data)` can include `details.card`. The object is optional, so use the top-level fields as a fallback:

```js
onError: (data) => {
  const card = data?.details?.card;

  if (!card) {
    console.error(data.message);
    return;
  }

  switch (card.reason) {
    case "issuer_declined":
      showCardMessage("Contact the issuer or use another card.");
      break;
    case "gateway_declined":
      showCardMessage("The card could not be accepted.");
      break;
    default:
      showCardMessage(data.message);
  }
},
```

Use `reason` for general logic. `declineCode` is not part of a universal code namespace, and `declineMessage` is informational; do not parse it or depend on it for localization.

## Subscription

Create the subscription server-side.

```js
const { data, status } = await axios.post(
  "https://api.onvopay.com/v1/subscriptions",
  {
    customerId: "cl40wvnby1653akslv93ktgdk",
    paymentBehavior: "allow_incomplete",
    items: [
      {
        priceId: "cl4ojmusz299201ldilvdfs8y",
        quantity: 1,
      },
    ],
  },
  {
    headers: {
      Authorization: "Bearer your_secret_key",
    },
  },
);

if (status === 201) {
  console.log(data.id);
}
```

Render the SDK with `paymentType: "subscription"`.

```html
<div id="container"></div>

<script>
  onvo.pay({
    onError: (data) => {
      console.log("error", data);
    },
    onSuccess: (data) => {
      console.log("success", data);
    },
    publicKey: "public-key",
    subscriptionId: "cl4de13uc457301lor2o0q9w1",
    paymentType: "subscription",
    customerId: "cl40wvnby1653akslv93ktgdk",
  }).render("#container");
</script>
```

## Submit from an external button

Use `manualSubmit: true` to hide the form's internal button and call `submitPayment` from your own control.

```html
<div id="container"></div>
<button id="outside">Submit Payment</button>

<script>
  const onvoInstance = onvo.pay({
    onError: (data) => console.log("error", data),
    onSuccess: (data) => console.log("success", data),
    publicKey: "public-key",
    paymentIntentId: "cl4de13uc457301lor2o0q9w1",
    paymentType: "one_time",
    manualSubmit: true,
  });

  onvoInstance.render("#container");

  document.getElementById("outside").addEventListener("click", () => {
    onvoInstance.submitPayment();
  });
</script>
```

## Locale

You can send `locale: "es"` or `locale: "en"`. If you omit it, Spanish is the default.

---

# WordPress Plugin

URL: https://docs.onvopay.com/en/integrations/wordpress
Markdown: https://docs.onvopay.com/en/integrations/wordpress.md

# WordPress Plugin

ONVO provides a plugin for WordPress sites that use WooCommerce. Use it to enable ONVO Pay payments in your e-commerce site without building an API integration from scratch.

[View the WordPress plugin](https://wordpress.org/plugins/onvo-pay/)

## Related API reference

- [Create a Checkout session](/en/api/crear-una-sesion-de-checkout)
- [Payment intents](/en/api/intenciones-de-pago)
- [Refunds](/en/api/reembolsos)

## Prerequisites

- WordPress `4.0` or later.
- PHP `7.1` or later.
- WooCommerce installed.
- Secret key and publishable key from the ONVO Dashboard.

## Install from the dashboard

1. Go to `Plugins` and select `Add New Plugin`.
2. Search for `ONVO Pay`.
3. Install and activate the plugin.
4. In the ONVO Dashboard, copy your secret key and publishable key.
5. In WooCommerce, open `Payments` and select `ONVO Pay`.
6. Paste both keys into their corresponding fields.
7. Save the changes and start receiving payments.

## Direct server installation

1. Download the WordPress plugin.
2. Upload it to `/wp-content/plugins/`.
3. Activate the plugin from `Plugins`.
4. Configure the keys in WooCommerce under `Payments` and `ONVO Pay`.
5. Save the changes.

---

# Home

URL: https://docs.onvopay.com/en/
Markdown: https://docs.onvopay.com/en/index.md

# ONVO Documentation

Integrate payments with ONVO using clear guides, API examples, and AI-ready files.

ONVO exposes a REST API with JSON responses, test keys, and live mode. These docs are organized to help you move from a local integration to production with less friction.

## Quick paths

| I need to | Start here |
| --- | --- |
| Create my first integration | [Getting started](/en/getting-started) |
| Authenticate requests | [Authentication](/en/authentication) |
| Collect a payment | [Payment intents](/en/payments/payment-intents) |
| Use hosted Checkout | [Checkout](/en/checkout/overview) |
| Receive async events | [Webhooks](/en/webhooks) |
| Browse endpoints and schemas | [API reference](/en/api) |

## For developers and agents

Every page includes an action to copy its Markdown. We also publish:

- [`/en/llms.txt`](https://docs.onvopay.com/en/llms.txt): short AI index.
- [`/en/llms-full.txt`](https://docs.onvopay.com/en/llms-full.txt): full Markdown context.

## Environments

Use keys prefixed with `onvo_test_` for testing and `onvo_live_` for real transactions. The mode is determined by the key sent in the `Authorization` header.

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -H "Authorization: Bearer onvo_test_secret_key_..." \
  -H "Content-Type: application/json"
```

---

# Credix

URL: https://docs.onvopay.com/en/payments/credix
Markdown: https://docs.onvopay.com/en/payments/credix.md

# Credix

Credix lets you collect a payment when the buyer uses their Credix card to pay in monthly installments or in full.

Unlike SINPE, Credix is a card authorization: the charge is processed at the moment you confirm the payment intent, with no transfers or redirect to an external system. The intent moves straight to `succeeded` once the authorization is approved.

This payment method is available by request only and supports `CRC` and `USD` payments. The available installment terms and minimum amounts depend on your merchant configuration.

:::info Enablement
Credix must be enabled for your account by the ONVO team, along with the per-term fee configuration. Request enablement before integrating.
:::

## Related API reference

- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)
- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Webhooks](/en/webhooks)

## Before you start

- Request Credix enablement from the ONVO support team.
- Configure webhooks and listen for `payment-intent.succeeded`.
- Use `CRC` or `USD` as the payment intent currency.
- Keep in mind the per-term minimum amounts defined for your merchant account.
- Only Credix cards are accepted.

## Available installments

When you confirm the intent, you set the number of installments in `credixInstallmentMonths`:

- `1` — pay in full (a single charge with the Credix card, no financing).
- `3`, `6`, `10`, `12`, `18`, `24` — monthly installment plans.

The terms actually available depend on the fees your merchant account has configured in the dashboard and on the transaction amount. Each term can have a minimum amount, so not all of them are available for every amount.

## Flow

1. Create a payment intent for the exact amount to collect.
2. Create a payment method with `type: "credix"` and the Credix card details.
3. Confirm the intent with the `paymentMethodId` and `credixInstallmentMonths`.
4. Credix authorizes the payment immediately: the intent moves to `succeeded` if approved or to `failed` if declined.
5. Wait for the `payment-intent.succeeded` webhook before marking the payment as complete.

## Create the payment intent

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "Credix payment #1001"
  }'
```

## Create the payment method

Provide the Credix card details inside the `credix` object.

```bash
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credix",
    "credix": {
      "number": "4111111111111111",
      "expMonth": 12,
      "expYear": 2026,
      "cvv": "123",
      "holderName": "Maria Rodriguez"
    },
    "billing": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com"
    }
  }'
```

## Confirm the intent

When confirming an intent with a Credix payment method, the `credixInstallmentMonths` field is **required**. Use `1` to pay in full or one of the installment terms your merchant account has configured in the dashboard.

```bash
curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651",
    "credixInstallmentMonths": 3
  }'
```

The API validates the installments on confirmation:

- If you omit `credixInstallmentMonths`, it responds with the `payment_intents.credix_missing_installment_months` error (`400`).
- If you send a term that is not configured or enabled for your merchant account, or that does not meet that term's minimum amount, it responds with the `payment_intents.credix_fee_not_configured` error (`400`).

In that case, adjust the term (or the amount) according to the terms your merchant account has configured in the dashboard. Do not mark the payment as successful in your system until you receive `payment-intent.succeeded`.

## Checkout and SDK

If you collect through [Checkout](/en/checkout/overview) or the [SDK](/en/integrations/sdk), you do not need to implement this API flow. When Credix is enabled for your merchant account and the amount meets the minimums, it shows up automatically as a payment option and the buyer selects the installment plan within the payment interface. In that case, installment selection is handled in Checkout and you do not have to send `credixInstallmentMonths` manually.

Credix is not available for subscriptions or for unsupported currencies.

## Testing

In test mode, using `onvo_test_` keys, the numbers defined in [Credix test payment methods](/en/payments/testing#credix) simulate different authorization scenarios. You do not need to use a real Credix card.

Use those numbers to simulate approved and declined authorizations.

---

# Fraud Monitoring

URL: https://docs.onvopay.com/en/payments/fraud-monitoring
Markdown: https://docs.onvopay.com/en/payments/fraud-monitoring.md

# Fraud Monitoring

For 100% API integrations, we recommend adding the ONVO web library to collect browser signals from the buyer. These signals improve the accuracy of fraud prevention tools.

This implementation is optional, but highly recommended. It is not required for integrations that use plugins, payment links, or the embedded SDK, because those flows already include the necessary collection.

## Install the library

Include the script in the page `head`, preferably before other scripts.

```html
<script src="https://js.onvopay.com/v1/"></script>
```

## Start the signal session

Initialize the library with your publishable key. When you have the `paymentIntentId`, and before confirming the payment, call `startSignalSession`.

```html
<script>
  const onvo = ONVO("onvo_live_publishable_key_H4PG...");

  onvo.startSignalSession({
    paymentIntentId: "clrr934wl001mdpkhw2g82rlt",
  });
</script>
```

ONVO takes these signals into account during payment intent confirmation.

---

# Separate Authorization and Capture

URL: https://docs.onvopay.com/en/payments/manual-capture
Markdown: https://docs.onvopay.com/en/payments/manual-capture.md

# Separate Authorization and Capture

When you create a payment, you can authorize an amount and capture it later. This flow is useful when you need to reserve funds before completing the charge, for example in hotels, rentals, or orders that require final confirmation.

:::info
Manual capture is only available for card payments in 100% API integrations. It is not available for Checkout or the embedded payment SDK.
:::

## Related API reference

- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Capture a payment intent](/en/api/capturar-una-intencion-de-pago)
- [Cancel a payment intent](/en/api/cancelar-una-intencion-de-pago)

## Create the intent

Set `captureMethod: "manual"` when creating the payment intent.

```json
{
  "amount": 1000,
  "currency": "USD",
  "captureMethod": "manual"
}
```

Then confirm the intent with a card payment method.

If the authorization is approved, the intent moves to `requires_capture`. If it is declined, it returns to `requires_payment_method` and you can retry with another payment method.

## Capture funds

To capture the authorized amount, call the payment intent capture endpoint. By default, ONVO captures the full authorized amount.

To capture less than the original amount, send `amountToCapture`. A partial capture automatically releases the remaining amount.

```json
{
  "amountToCapture": 750
}
```

If the capture succeeds, the intent moves to `succeeded`. If the capture fails, the intent moves to `requires_payment_method` and you need to start a new authorization.

## Cancel an authorization

If you need to release the funds before capturing them, cancel the payment intent. If the authorization expires before capture, ONVO releases the funds and the intent moves to `canceled`.

---

# Marketplaces

URL: https://docs.onvopay.com/en/payments/marketplaces
Markdown: https://docs.onvopay.com/en/payments/marketplaces.md

# Marketplaces

Marketplaces allow merchants that operate as intermediaries between buyers and sellers to process payments and settle funds to sellers automatically and securely.

## Authentication and isolation

Use a Secret API Key from the standard primary account that manages the marketplace:

```text
Authorization: Bearer <YOUR_SECRET_API_KEY>
```

The key determines the primary account and the immutable `test` or `live` mode. Publishable API Keys are not allowed for these operations.

Every read and mutation validates the connected account ID together with the primary account, mode, and account type. A missing ID, an ID owned by another primary account, or an ID from another mode returns the same `404` error without revealing whether the resource exists.

Connected accounts do not receive their own API keys. To charge on behalf of the seller, keep using the primary account key and send the connected account ID in `onBehalfOf`.

## Create a connected account

You can create the account from the Marketplace section in the ONVO Dashboard or with [`POST /v1/connected-accounts`](/en/api/crear-una-cuenta-conectada).

```bash
curl https://api.onvopay.com/v1/connected-accounts \
  -X POST \
  -H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Connected Store",
    "marketplaceAppFee": 5
  }'
```

`businessName` is required, trimmed, and must contain 1 to 50 characters. `marketplaceAppFee` is an optional percentage from 0 through 100 with at most two decimal places. For example, `5` represents 5%. If you omit it, ONVO stores and returns `0`.

Creation returns HTTP `201`:

```json
{
  "id": "cl502zv0d0127ebdp3zt27651",
  "mode": "test",
  "status": "pending_onboarding",
  "businessName": "Connected Store",
  "marketplaceAppFee": 5,
  "createdAt": "2026-07-25T17:00:00.000Z",
  "onboardingUrl": "https://onvopay.com/setup/account_onboarding_test_example"
}
```

`onboardingUrl` is returned only when creating the account or regenerating the link. Treat this value as sensitive: give it to the correct seller and do not write it to logs.

## List, retrieve, and update

List the accounts in the authenticated mode with [`GET /v1/connected-accounts`](/en/api/listar-cuentas-conectadas). `limit` accepts 1 through 100 and defaults to `10`. `startingAfter` and `endingBefore` are mutually exclusive, and the cursor must belong to the same primary account, mode, and filter.

You can filter by `pending_onboarding`, `awaiting_approval`, `active`, `inactive`, `temporally_suspended`, `permanently_suspended`, or `deleted`. The `restricted` value is not part of the Secret API Key contract.

```bash
curl "https://api.onvopay.com/v1/connected-accounts?status=pending_onboarding&limit=10" \
  -H "Authorization: Bearer <YOUR_SECRET_API_KEY>"
```

The list returns the same public object in the `{ data, meta }` envelope:

```json
{
  "data": [
    {
      "id": "cl502zv0d0127ebdp3zt27651",
      "mode": "test",
      "status": "pending_onboarding",
      "businessName": "Connected Store",
      "marketplaceAppFee": 5,
      "createdAt": "2026-07-25T17:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "pages": 1,
    "limit": 10,
    "cursorNext": "cl502zv0d0127ebdp3zt27651",
    "cursorBefore": "cl502zv0d0127ebdp3zt27651"
  }
}
```

[`GET /v1/connected-accounts/{id}`](/en/api/obtener-una-cuenta-conectada) returns exactly the same public object. On legacy accounts without a business profile, `businessName` can be `null`; when marketplace fee settings are missing, `marketplaceAppFee` returns `0`.

Update `businessName`, `marketplaceAppFee`, or both with [`POST /v1/connected-accounts/{id}`](/en/api/actualizar-una-cuenta-conectada). You must send at least one:

```bash
curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651 \
  -X POST \
  -H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Updated Connected Store",
    "marketplaceAppFee": 6.25
  }'
```

This generic endpoint does not allow updates to status, onboarding, payout frequency, weekly fees, bank data, or processor configuration. List, retrieve, and update responses never include `onboardingUrl`.

## Configure a weekly fee

Create or update the fixed weekly fee with [`POST /v1/connected-accounts/{id}/weekly-fees`](/en/api/configurar-una-tarifa-semanal). Send at least one of `marketplaceWeeklyFeeEnabled`, `marketplaceWeeklyFeeAmount`, or `marketplaceWeeklyFeeCurrency`:

```bash
curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees \
  -X POST \
  -H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "marketplaceWeeklyFeeEnabled": true,
    "marketplaceWeeklyFeeAmount": 1000,
    "marketplaceWeeklyFeeCurrency": "CRC"
  }'
```

`marketplaceWeeklyFeeAmount` is an integer expressed in the currency's minor unit, from `1` through `2147483647`. The weekly fee is available for connected accounts in Costa Rica, Guatemala, and Peru. Supported currencies are `USD`, `CRC` for Costa Rica, `GTQ` for Guatemala, and `PEN` for Peru.

To enable the fee, the effective configuration must have an amount and currency. The primary account and connected account must also have a payout bank account in that same currency. You can save the amount and currency while the fee is disabled before meeting those requirements; to disable it later, send `marketplaceWeeklyFeeEnabled: false`.

`null` values are not allowed. To preserve a field's current value, omit it from the payload. Each request is applied atomically: the first creates the configuration, and later requests update only the supplied values.

The response returns only the public configuration:

```json
{
  "id": "cl502zv0d0127ebdp3zt27651",
  "marketplaceWeeklyFeeEnabled": true,
  "marketplaceWeeklyFeeAmount": 1000,
  "marketplaceWeeklyFeeCurrency": "CRC"
}
```

### Cutoff and collection

The fixed weekly fee is separate from `marketplaceAppFee`: it is created once per week, not once per payment.

Every Friday at `02:00` in `America/Costa_Rica`, ONVO snapshots the effective configuration. If the fee is enabled and the connected account is `active`, ONVO creates the full obligation in the configured currency. A change made after the cutoff applies to the following Friday. If the connected account is not `active` at the cutoff, ONVO does not create that week's fee.

Disabling the fee before the cutoff prevents a new obligation, but disabling it does not remove pending obligations. ONVO deducts them from future payouts in the same currency, after other deductions, and preserves at least `100` minor units in the payout. If the available balance is insufficient, ONVO collects a partial amount and carries the remainder to future payouts, applying the oldest obligations first.

ONVO credits the primary account only for the amount collected when the payout reaches `paid`. If a paid payout is reversed, ONVO reverses the corresponding credit and reopens the obligation balance. The `test` and `live` modes are processed separately.

The [weekly fee configuration reference](/en/api/configurar-una-tarifa-semanal) includes complete payloads for `null` values, an invalid amount, incomplete configuration, unsupported currency, missing bank accounts, a disabled feature, and a connected account that was not found.

## Seller onboarding

The seller must complete ONVO-hosted onboarding before receiving payments. During this process, they provide the IBAN accounts where settlements should be sent.

The link expires after 7 days. You can regenerate it from the Dashboard or with [`POST /v1/connected-accounts/{id}/onboarding-link`](/en/api/regenerar-enlace-de-onboarding); when you do, the previous link expires:

```bash
curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651/onboarding-link \
  -X POST \
  -H "Authorization: Bearer <YOUR_SECRET_API_KEY>"
```

```json
{
  "id": "cl502zv0d0127ebdp3zt27651",
  "onboardingUrl": "https://onvopay.com/setup/account_onboarding_test_example"
}
```

Regeneration is available only before onboarding is complete. If the account is already active, ONVO returns `409` with `marketplaces.onboarding_already_completed`.

Once onboarding is complete, the connected account is enabled to accept payments on its behalf.

## Errors

Marketplace domain errors use a typed payload with `statusCode`, `type`, `code`, `message`, `path`, and `timestamp`; validation and authentication errors use their own payloads. The [`POST /v1/connected-accounts`](/en/api/crear-una-cuenta-conectada), [`GET /v1/connected-accounts`](/en/api/listar-cuentas-conectadas), [`POST /v1/connected-accounts/{id}`](/en/api/actualizar-una-cuenta-conectada), and [`POST /v1/connected-accounts/{id}/weekly-fees`](/en/api/configurar-una-tarifa-semanal) references show the `400` and `401` cases. [`GET /v1/connected-accounts/{id}`](/en/api/obtener-una-cuenta-conectada) shows the `404` response, while [`POST /v1/connected-accounts/{id}/onboarding-link`](/en/api/regenerar-enlace-de-onboarding) includes the operation-specific `409` and `500` responses.

Here is a complete example payload for a domain error:

```json
{
  "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"
}
```

Handle at least these cases:

| HTTP | Stable code | Meaning |
| --- | --- | --- |
| `400` | `marketplaces.parent_configuration_invalid` | The primary account is missing required configuration. |
| `400` | `marketplaces.invalid_cursor` | The cursor is invalid, foreign, or does not match the filter. |
| `400` | `marketplaces.invalid_status` | The status filter is unsupported. |
| `400` | `marketplaces.unsupported_public_field` | The payload includes a field outside the public contract. |
| `400` | `marketplaces.weekly_fee.configuration_required` | No weekly configuration field was provided. |
| `400` | `marketplaces.weekly_fee.feature_disabled` | The feature is not enabled for the primary account. |
| `400` | `marketplaces.weekly_fee.amount_required` | The effective amount is missing when enabling the fee. |
| `400` | `marketplaces.weekly_fee.currency_required` | The effective currency is missing when enabling the fee. |
| `400` | `marketplaces.weekly_fee.currency_not_supported` | The currency is not supported for the connected account's country. |
| `400` | `marketplaces.weekly_fee.child_bank_account_required` | The connected account has no bank account in the configured currency. |
| `400` | `marketplaces.weekly_fee.parent_bank_account_required` | The primary account has no bank account in the configured currency. |
| `401` | — | The key is invalid or publishable, or a live key belongs to an inactive primary account. |
| `404` | `marketplaces.connected_account_not_found` | The ID does not belong to the authenticated primary account and mode. |
| `409` | `marketplaces.onboarding_already_completed` | The account has already completed onboarding. |
| `500` | `marketplaces.error_creating_onboarding_link` | ONVO could not persist the link; no partial writes remain. |

## Payment flow

Always use the API keys from the primary account, meaning the account that created the marketplace.

Payment methods, customers, products, and prices must also be created in the primary account. Send `onBehalfOf` with the seller's `Account ID` when the charge should belong to a marketplace account.

You can use marketplace with payment intents, one-time Checkout Sessions, and subscriptions.

### Payment intents

1. [Create a payment intent](/en/api/crear-una-intencion-de-pago) with the `onBehalfOf` attribute, using the `id` returned when you [create the connected account](/en/api/crear-una-cuenta-conectada).

```json
{
  "amount": 10000,
  "currency": "USD",
  "onBehalfOf": "cl502zv0d0127ebdp3zt27651"
}
```

2. [Confirm the payment intent](/en/api/confirmar-una-intencion-de-pago) with the `paymentMethodId` returned when you create the payment method in the primary account.

```json
{
  "paymentMethodId": "cl502zv0d0127ebdp3zt27652"
}
```

### Checkout Sessions

Create the Checkout Session with `onBehalfOf`. ONVO stores that account on the session and uses it on the payment intent generated for the charge.

```json
{
  "redirectUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "onBehalfOf": "ma502zv0d0127ebdp3zt27651",
  "lineItems": [
    {
      "quantity": 1,
      "unitAmount": 10000,
      "currency": "USD",
      "description": "Order #1001"
    }
  ]
}
```

### Subscriptions

Create the subscription with `onBehalfOf`. ONVO uses that marketplace account on the payment intent for the first period and on future renewals.

```json
{
  "customerId": "cus502zv0d0127ebdp3zt27651",
  "paymentMethodId": "pm502zv0d0127ebdp3zt27651",
  "description": "Monthly Pro Plan",
  "onBehalfOf": "ma502zv0d0127ebdp3zt27651",
  "items": [
    {
      "priceId": "price502zv0d0127ebdp3zt27651",
      "quantity": 1
    }
  ]
}
```

Checkout Session and subscription lists can also be filtered by seller with the `onvo-on-behalf-of` header.

If the charge succeeds, ONVO calculates ONVO fees, withholdings, and the marketplace commission on the gross amount.

You can then [retrieve a payment intent](/en/api/obtener-una-intencion-de-pago) by ID or [list payment intents](/en/api/listar-todas-las-intenciones-de-pago) for the account.

Example for a `100.00 USD` transaction:

| Concept | Amount |
| --- | --- |
| Gross amount | `100.00 USD` |
| ONVO fee 3.5% | `3.50 USD` |
| Withholding 2% | `2.00 USD` |
| Net amount | `94.50 USD` |
| Marketplace commission 5% | `5.00 USD` |
| Amount settled to seller | `89.50 USD` |

The marketplace commission is deposited into the primary account and the net amount is deposited to the seller.

## Test and live mode

You can create connected accounts in test or live mode based on the Secret API Key or the active Dashboard mode.

Accounts created in test mode only work with test keys. Accounts created in live mode only work with live keys. You cannot change an account's mode after it is created.

---

# Payments

URL: https://docs.onvopay.com/en/payments/overview
Markdown: https://docs.onvopay.com/en/payments/overview.md

# Payments

ONVO payment flows are built around payment intents, payment methods, refunds, and asynchronous events.

## Related API reference

- [Payment intents](/en/api/intenciones-de-pago)
- [Payment methods](/en/api/metodos-de-pago)
- [Subscriptions](/en/api/cargos-recurrentes)
- [Refunds](/en/api/reembolsos)
- [Checkout sessions](/en/api/sesiones-de-checkout)

## Main resources

| Resource | Description |
| --- | --- |
| Payment intent | Represents the attempt to charge an order. |
| Payment method | Instrument used by the buyer. |
| Subscription | Charges a customer periodically using a recurring price. |
| Refund | Full or partial return of a payment. |
| Webhook | Event sent by ONVO when state changes. |

For most integrations, create one intent per order and listen to webhooks to confirm the final result.

## Card verification declines {#card-declines}

When you create or update a `card` payment method, ONVO tokenizes and verifies the card before storing its details. If verification fails, the response preserves the general `cards.invalid_card_info` error and can include `details.card` with structured information for the merchant.

`details.card` is optional. When present, it contains these fields:

- `reason`: stable category for choosing the general treatment.
- `declineCode`: safe code from the gateway or issuer, or an ONVO fallback value.
- `declineMessage`: safe informational text for logging or support.

For example, a decline can return this response:

```json
{
  "statusCode": 400,
  "type": "OnvoAPIError",
  "code": "cards.invalid_card_info",
  "message": "There was an error with the card information provided. Please review card number, expiration date and cvv",
  "path": "/v1/payment-methods",
  "details": {
    "card": {
      "reason": "issuer_declined",
      "declineCode": "55",
      "declineMessage": "Incorrect PIN"
    }
  },
  "timestamp": "2026-04-29T17:36:28.477Z"
}
```

### How to interpret `reason`

| Value | When it is used |
| --- | --- |
| `issuer_declined` | The issuer declined verification, for example because of incorrect details or a card restriction. |
| `gateway_declined` | The gateway or acquirer explicitly reported a non-technical acceptance, authentication, merchant, or risk rule. |
| `onvo_declined` | ONVO applied an eligibility or security rule, such as a disallowed brand or BIN. |
| `processor_error` | A technical, communication, or configuration problem prevented verification from completing. |
| `unknown` | There was not enough information to attribute the decline safely. |

Use `reason` for general logic. `declineCode` is not part of a universal code namespace and can vary by provider; do not build global rules that assume the same code always has the same meaning. `declineMessage` is also informational: do not parse it for decisions or depend on it for localization.

When no specific decline information is available, ONVO returns the default values: `unknown` in `reason`, `generic_decline` in `declineCode`, and a generic message in `declineMessage`.

### Recommended handling

1. Check the top-level `code` first to identify `cards.invalid_card_info`.
2. If `details.card` exists, use `reason` to choose the general buyer experience.
3. Show your own safe guidance to the buyer; do not expose internal messages or promise that retrying will resolve the decline.
4. Record `declineCode` and `declineMessage` only as context for diagnostics and support.

### Reference and examples

- [Payment methods API reference](/en/api/metodos-de-pago)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)
- [Update a payment method](/en/api/actualizar-un-metodo-de-pago)
- [Complete response and recovery example](/en/payments/payment-intents#structured-decline-details)
- [SDK `onError` handling example](/en/integrations/sdk#handling-card-errors)

---

# Payment intents

URL: https://docs.onvopay.com/en/payments/payment-intents
Markdown: https://docs.onvopay.com/en/payments/payment-intents.md

# Payment intents

A payment intent guides the lifecycle of a payment. Use exactly one intent per payment to keep traceability clear.

## Related API reference

- [Create a payment method](/en/api/crear-un-metodo-de-pago)
- [Peru merchant account requirement](#peru-merchant-account-requirement)
- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Retrieve a payment intent](/en/api/obtener-una-intencion-de-pago)
- [Capture a payment intent](/en/api/capturar-una-intencion-de-pago)
- [Cancel a payment intent](/en/api/cancelar-una-intencion-de-pago)
- [List all payment intents](/en/api/listar-todas-las-intenciones-de-pago)

## Basic flow

1. Create or collect a payment method for the buyer.
2. Create a payment intent with the amount and currency.
3. Confirm the intent using the `paymentMethodId`.
4. Listen for webhooks before marking the payment as complete in your system.

## Create a payment method

Create the payment method client-side with a publishable key. For cards, the response returns an `id` that you later send as `paymentMethodId` when confirming the intent from your server.

:::warning PCI scope
To reduce PCI scope, collect card data client-side with a publishable key, [Checkout](/en/checkout/overview), or the [web SDK](/en/integrations/sdk). Do not pass untokenized card data through your server. If your backend receives or transmits PAN, CVV, or full card data, that integration is in your PCI scope and may require SAQ D validation.
:::

### Peru merchant account requirement {#peru-merchant-account-requirement}

:::important

For merchant accounts created in Peru, the customer attached to the payment method must have an email address when creating payment methods.

You can meet this requirement in two ways:

- Send `customer.email` in the payment method creation payload to create and attach the customer in the same request.
- Send the `customerId` of a customer previously created with the `email` attribute.

:::

### Card example and validation rules

```bash
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4242424242424242",
      "expMonth": 12,
      "expYear": 2028,
      "cvv": "123",
      "holderName": "Maria Rodriguez"
    },
    "billing": {
      "name": "Maria Rodriguez",
      "address": {
        "country": "CR"
      }
    },
    "customer": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com"
    }
  }'
```

To avoid `400` validation errors before the card is tokenized, validate these fields in your form:

- `card.holderName`: non-empty text.
- `card.number`: a digits-only string, without spaces or separators, and a number that passes Luhn validation.
- `card.expMonth`: integer between `1` and `12`.
- `card.expYear`: integer between `2023` and `2100`. Also validate that the card is not expired before sending it.
- `card.cvv`: string with `3` or `4` digits when you send it.

If the payload does not meet these rules, ONVO responds with `400` and a validation error. For example, an invalid card number can return:

```json
{
  "statusCode": 400,
  "message": ["card.number Card number is invalid"],
  "error": "Bad Request"
}
```

When you create a `card` payment method, ONVO tokenizes and verifies the card before creating the object. If tokenization fails because the card details are invalid, the endpoint responds with `400` and no payment method is created.

```json
{
  "statusCode": 400,
  "type": "OnvoAPIError",
  "code": "cards.invalid_card_info",
  "message": "There was an error with the card information provided. Please review card number, expiration date and cvv",
  "path": "/v1/payment-methods",
  "details": {
    "card": {
      "reason": "issuer_declined",
      "declineCode": "55",
      "declineMessage": "Incorrect PIN"
    }
  },
  "timestamp": "2026-04-29T17:36:28.477Z"
}
```

### Structured decline details

`details.card` is optional and only appears when ONVO has safe information about a handled card-verification decline. Use `reason` to choose the general treatment:

| Reason | Meaning |
| --- | --- |
| `issuer_declined` | The issuer declined the verification. |
| `gateway_declined` | The gateway or acquirer explicitly reported a non-technical acceptance, authentication, merchant, or risk rule. |
| `onvo_declined` | ONVO applied an eligibility or security rule. |
| `processor_error` | A technical failure occurred while processing the verification. |
| `unknown` | There was not enough information to attribute the decline. |

`declineCode` can come from the gateway or issuer, or be a stable ONVO fallback; it is not a universal code. `declineMessage` is informational: do not parse it for business logic or depend on it for localization.

When no specific decline information is available, ONVO returns the default values: `unknown` in `reason`, `generic_decline` in `declineCode`, and a generic message in `declineMessage`.

Show useful guidance to the buyer based on `reason`. Do not promise that a retry will resolve the decline; for `issuer_declined`, you can suggest checking the card details, contacting the issuer, or using another payment method.

## Create an intent

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "Order #1001"
  }'
```

## Confirm the intent

Use the intent `id` and the `id` from the payment method created earlier.

```bash
curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'
```

## Common states

| State | Meaning |
| --- | --- |
| `requires_payment_method` | Initial state. The intent also stays in this state if confirmation fails, for example because a card is declined. |
| `requires_action` | The payment method needs an additional buyer action, such as 3DS authentication. |
| `processing` | ONVO is processing the payment. |
| `succeeded` | The payment succeeded. |
| `canceled` | The intent was canceled. |

## Best practices

- Store the intent `id` with your payment.
- Use `metadata` for internal cart, payment, or customer IDs.
- Confirm the final state by webhook before delivering digital goods or marking the payment as complete.

---

# Refunds

URL: https://docs.onvopay.com/en/payments/refunds
Markdown: https://docs.onvopay.com/en/payments/refunds.md

# Refunds

A refund returns all or part of a successful payment intent amount.

## Related API reference

- [Create a refund](/en/api/crear-un-reembolso)
- [Retrieve a refund](/en/api/obtener-un-reembolso)
- [Refunds](/en/api/reembolsos)

```bash
curl https://api.onvopay.com/v1/refunds \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentIntentId": "pi_...",
    "amount": 100000
  }'
```

## Recommendations

- Validate that the order can be refunded in your system before calling ONVO.
- Store the refund ID for reconciliation.
- Listen for webhook events to know the final result.

---

# SINPE Movil

URL: https://docs.onvopay.com/en/payments/sinpe-mobile
Markdown: https://docs.onvopay.com/en/payments/sinpe-mobile.md

# SINPE Movil

SINPE Movil lets you collect a payment when the buyer sends a transfer to ONVO's mobile number and ONVO automatically associates it with a payment intent.

This flow currently supports `CRC` payments only.

## Related API reference

| Step | Reference | Payloads |
| --- | --- | --- |
| Create the intent | [POST /v1/payment-intents](/en/api/crear-una-intencion-de-pago) | [Request](/en/api/crear-una-intencion-de-pago#request) · [Response](/en/api/crear-una-intencion-de-pago#responses) |
| Create the payment method | [POST /v1/payment-methods](/en/api/crear-un-metodo-de-pago) | [Request](/en/api/crear-un-metodo-de-pago#request) · [Response](/en/api/crear-un-metodo-de-pago#responses) |
| Confirm the intent | [POST /v1/payment-intents/\{id\}/confirm](/en/api/confirmar-una-intencion-de-pago) | [Request](/en/api/confirmar-una-intencion-de-pago#request) · [Response](/en/api/confirmar-una-intencion-de-pago#responses) |
| Reconcile transfers | [GET /v1/mobile-transfers/list](/en/api/listar-pagos-por-sinpe-movil) | [Parameters](/en/api/listar-pagos-por-sinpe-movil#request) · [Response](/en/api/listar-pagos-por-sinpe-movil#responses) |
| Receive confirmation | [Webhooks](/en/webhooks) | [Event payloads](/en/webhooks#payloads-by-event) |

## Before you start

- Configure webhooks and listen for `payment-intent.succeeded`.
- Use `CRC` as the payment intent currency.
- Send the real identification of the person or entity that will make the transfer in the payment method.
- Ask the buyer to transfer from an account whose identification matches `mobileNumber.identification`.

ONVO tries to associate the incoming transfer by identification number first. If the bank reports a different identification than the one you sent, automatic association can fail.

The default destination number for receiving SINPE Movil transfers is `+506 70196686`. If your merchant account requested a custom number, use the number provided by the ONVO support team.

## Flow

1. Create a payment intent for the exact amount to collect.
2. Create a payment method with `type: "mobile_number"`.
3. Confirm the intent with the `paymentMethodId`.
4. Show the buyer the destination SINPE Movil number and the exact amount.
5. Wait for the `payment-intent.succeeded` webhook before marking the payment as complete.

When you confirm the intent with this payment method, the intent moves to `processing`. That state means ONVO is waiting to receive and associate the transfer.

## Create the payment intent

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "SINPE Movil payment #1001"
  }'
```

## Create the payment method

`mobileNumber.number` is the buyer's SINPE Movil number. The destination number the buyer should transfer to is ONVO's number shown in your payment instructions.

```bash
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_number",
    "mobileNumber": {
      "identification": "01-1393-1919",
      "identificationType": 0,
      "number": "+50688888888"
    },
    "billing": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com"
    }
  }'
```

## Confirm the intent

```bash
curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'
```

After confirmation, tell the buyer to transfer the exact amount to ONVO's SINPE Movil number. Do not mark the payment as successful in your system until you receive `payment-intent.succeeded`.

## Reconciliation

The SINPE Movil payments list reflects incoming transfers received on a SINPE Movil number. It is useful for reviewing transfers that could not be associated automatically.

If `paymentIntentId` is `null`, the transfer is not yet linked to a payment intent.

## Testing

In test mode, using `onvo_test_` keys, the numbers defined in [SINPE Movil test payment methods](/en/payments/testing#sinpe-movil) simulate different transfer scenarios. You do not need to make a real transfer or send funds to ONVO's SINPE Movil number.

Use those numbers to simulate successful, delayed, failed, and partial transfers.

---

# SINPE PIN

URL: https://docs.onvopay.com/en/payments/sinpe-pin
Markdown: https://docs.onvopay.com/en/payments/sinpe-pin.md

# SINPE PIN

SINPE PIN lets you collect a payment when the buyer sends a bank transfer to an IBAN provided by ONVO and ONVO automatically associates it with a payment intent.

This payment method is available by request only and currently supports `CRC` payments only.

:::warning Real-time transfers
SINPE PIN only works if the buyer sends the transfer in real time. If they use a scheduled, delayed, or non-immediate transfer, ONVO will not be able to associate it automatically and the payment will not complete with this flow.
:::

## Related API reference

| Step | Reference | Payloads |
| --- | --- | --- |
| Create the intent | [POST /v1/payment-intents](/en/api/crear-una-intencion-de-pago) | [Request](/en/api/crear-una-intencion-de-pago#request) · [Response](/en/api/crear-una-intencion-de-pago#responses) |
| Create the payment method | [POST /v1/payment-methods](/en/api/crear-un-metodo-de-pago) | [Request](/en/api/crear-un-metodo-de-pago#request) · [Response](/en/api/crear-un-metodo-de-pago#responses) |
| Confirm the intent | [POST /v1/payment-intents/\{id\}/confirm](/en/api/confirmar-una-intencion-de-pago) | [Request](/en/api/confirmar-una-intencion-de-pago#request) · [Response](/en/api/confirmar-una-intencion-de-pago#responses) |
| Receive confirmation | [Webhooks](/en/webhooks) | [Event payloads](/en/webhooks#payloads-by-event) |

## Before you start

- Request SINPE PIN enablement from the ONVO support team.
- Use the destination IBAN provided by ONVO so the buyer can make the transfer.
- Configure webhooks and listen for `payment-intent.succeeded`.
- Use `CRC` as the payment intent currency.
- Send the real identification of the person or entity that will make the transfer in the payment method.

ONVO tries to associate the incoming transfer by identification number first. The identification sent in `bankDeposit.identification` must match the identification reported by the bank in the incoming transfer.

## Flow

1. Create a payment intent for the exact amount to collect.
2. Create a payment method with `type: "bank_deposit"`.
3. Confirm the intent with the `paymentMethodId`.
4. Show the buyer the destination IBAN provided by ONVO, the exact amount, and the instruction to send the transfer in real time.
5. Wait for the `payment-intent.succeeded` webhook before marking the payment as complete.

When you confirm the intent with this payment method, the intent moves to `processing`. That state means ONVO is waiting to receive and associate the transfer.

## Create the payment intent

```bash
curl https://api.onvopay.com/v1/payment-intents \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "CRC",
    "description": "SINPE PIN payment #1001"
  }'
```

## Create the payment method

`bankDeposit.identification` must represent the person or entity that will make the bank transfer.

```bash
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_deposit",
    "bankDeposit": {
      "identification": "01-1393-1919",
      "identificationType": 1
    },
    "billing": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com"
    }
  }'
```

## Confirm the intent

```bash
curl https://api.onvopay.com/v1/payment-intents/$PAYMENT_INTENT_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "cl502zv0d0127ebdp3zt27651"
  }'
```

After confirmation, tell the buyer to transfer the exact amount to the IBAN provided by ONVO using a real-time transfer. Do not mark the payment as successful in your system until you receive `payment-intent.succeeded`.

## Testing

In test mode, using `onvo_test_` keys, the identifications defined in [SINPE PIN test payment methods](/en/payments/testing#bank-deposit-sinpe-pin) simulate different deposit scenarios. You do not need to make a real transfer or send funds to ONVO's IBAN.

Use those identifications to simulate successful, delayed, failed, and partial deposits.

---

# Subscriptions

URL: https://docs.onvopay.com/en/payments/subscriptions
Markdown: https://docs.onvopay.com/en/payments/subscriptions.md

# Subscriptions

A subscription charges a customer on a recurring schedule. The flow starts by creating a product and a recurring price; then you attach a payment method to the customer and create the subscription with that price.

You can charge the first period immediately or create the subscription first and confirm it in an additional request.

## Related API reference

- [Create a product](/en/api/crear-un-producto)
- [Create a price](/en/api/crear-un-precio)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)
- [Create a subscription](/en/api/crear-un-cargo-recurrente)
- [Confirm a subscription](/en/api/confirmar-un-cargo-recurrente)
- [Retrieve a subscription](/en/api/obtener-un-cargo-recurrente)
- [List invoices](/en/api/listar-renovaciones)

## Basic flow

1. Create a product to represent what you sell.
2. Create a price with `type: "recurring"` and define the billing interval.
3. Create or collect a payment method for the customer.
4. Create the subscription with the `customerId`, `paymentMethodId`, and `priceId`.
5. Listen for webhooks to confirm the first charge and every renewal.

## Create a product

```bash
curl https://api.onvopay.com/v1/products \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Plan",
    "description": "Monthly access to the Pro Plan",
    "isActive": true
  }'
```

Store the product `id` so you can create the recurring price.

## Create a recurring price

Amounts are sent in the smallest denomination of the currency. For example, `250000` represents CRC 2,500.00.

```bash
curl https://api.onvopay.com/v1/prices \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "$PRODUCT_ID",
    "unitAmount": 250000,
    "currency": "CRC",
    "type": "recurring",
    "nickname": "Monthly Pro Plan",
    "recurring": {
      "interval": "month",
      "intervalCount": 1
    }
  }'
```

Store the price `id`. You send it as `priceId` inside `items`.

## Create a payment method

The payment method must belong to the same customer used for the subscription. You can send an existing `customerId` or send `customer` to create and attach the customer in the same request.

```bash
curl https://api.onvopay.com/v1/payment-methods \
  -X POST \
  -H "Authorization: Bearer $ONVO_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4242424242424242",
      "expMonth": 12,
      "expYear": 2028,
      "cvv": "123",
      "holderName": "Maria Rodriguez"
    },
    "billing": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com",
      "address": {
        "country": "CR"
      }
    },
    "customer": {
      "name": "Maria Rodriguez",
      "email": "maria@example.com",
      "phone": "+50688880000"
    }
  }'
```

Store the payment method `id` and the associated `customerId`.

## Charge immediately

To charge the first period when creating the subscription, send `paymentMethodId`. If you omit `paymentBehavior`, ONVO uses the default behavior and confirms the first charge immediately.

```bash
curl https://api.onvopay.com/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "$CUSTOMER_ID",
    "paymentMethodId": "$PAYMENT_METHOD_ID",
    "description": "Monthly Pro Plan",
    "items": [
      {
        "priceId": "$PRICE_ID",
        "quantity": 1
      }
    ],
    "metadata": {
      "accountPlan": "pro",
      "internalSubscriptionId": "sub_123"
    }
  }'
```

ONVO creates the initial invoice, creates a payment intent for that period, and confirms it with the payment method. Check the status of the subscription, invoice, and payment intent before activating the service in your system.

## Marketplace

If the subscription belongs to a seller in your marketplace, send `onBehalfOf` with that marketplace account's `Account ID` when creating the subscription.

```json
{
  "customerId": "$CUSTOMER_ID",
  "paymentMethodId": "$PAYMENT_METHOD_ID",
  "description": "Monthly Pro Plan",
  "onBehalfOf": "$MARKETPLACE_ACCOUNT_ID",
  "items": [
    {
      "priceId": "$PRICE_ID",
      "quantity": 1
    }
  ]
}
```

ONVO keeps that marketplace account on the subscription, the initial invoice, and future renewals. Each payment intent generated for the subscription uses that context to calculate the marketplace commission.

## Defer confirmation

Use `paymentBehavior: "allow_incomplete"` when you want to create the subscription first and confirm the charge in a later request. In this mode, you can omit `paymentMethodId` when creating the subscription.

```bash
curl https://api.onvopay.com/v1/subscriptions \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "$CUSTOMER_ID",
    "paymentBehavior": "allow_incomplete",
    "description": "Monthly Pro Plan",
    "items": [
      {
        "priceId": "$PRICE_ID",
        "quantity": 1
      }
    ],
    "metadata": {
      "accountPlan": "pro",
      "internalSubscriptionId": "sub_123"
    }
  }'
```

When the payment method is ready, confirm the subscription:

```bash
curl https://api.onvopay.com/v1/subscriptions/$SUBSCRIPTION_ID/confirm \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethodId": "$PAYMENT_METHOD_ID"
  }'
```

## Invoices

Each subscription generates invoices. The first invoice is created at the start of the subscription and later invoices are created for each successful period. Each invoice is associated with a payment intent, so you can use it to reconcile the charged period.

## Best practices

- Store the product, price, customer, payment method, and subscription IDs in your system.
- Use `metadata` to attach internal IDs, such as your platform plan or subscription.
- Use `onBehalfOf` when creating marketplace subscriptions so renewals keep the same seller.
- Listen for `subscription.renewal.succeeded` and `subscription.renewal.failed` to sync local state.
- Query invoices to audit each period and its associated payment intent.

---

# Testing

URL: https://docs.onvopay.com/en/payments/testing
Markdown: https://docs.onvopay.com/en/payments/testing.md

# Testing

Keys prefixed with `onvo_test_` operate in test mode. Use them to validate flows, states, webhooks, and error handling.

The payment methods on this page only work in test mode. If you try to use them with `onvo_live_` keys, ONVO rejects the payment method creation.

## Related API reference

- [Create a payment method](/en/api/crear-un-metodo-de-pago)
- [Create a payment intent](/en/api/crear-una-intencion-de-pago)
- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Create a refund](/en/api/crear-un-reembolso)

## Checklist before production

- Create a payment intent.
- Confirm a successful payment.
- Test a payment-method error.
- Test a refund.
- Validate webhook delivery and signature verification.
- Confirm that your system handles idempotent retries.

## Cards

To create a test card, use `card` in the `type` attribute when creating a payment method and include the number in `card.number`.

Use any future expiration date, any valid CVV for the brand, and any cardholder name.

| Scenario | Brand | Number |
| --- | --- | --- |
| Approved | Visa | `4242424242424242` |
| 3DS challenge | Visa | `4000000000003220` |
| Approved | Mastercard | `5555555555554444` |
| Approved | American Express | `378282246310005` |
| Declined payment | Visa | `4000000000000002` |
| Creation fails due to invalid verification | Visa | `4000000000000127` |
| External card processor error | Visa | `4000000000000119` |

## Credix

To create a Credix test card, use `credix` in the `type` attribute and include the number in `credix.number`.

| Scenario | Number |
| --- | --- |
| Approved | `4111111111111111` |
| Declined | `4000000000000002` |

## Bank Deposit (SINPE PIN)

To create a bank deposit test method, use `bank_deposit` in `type` and include `identification` and `identificationType` in `bankDeposit`.

| Scenario | Identification | Behavior |
| --- | --- | --- |
| Successful | `00-0000-8888` | Simulates a successful deposit 15 seconds after confirming the payment intent. |
| Failed | `00-0000-9521` | Marks the charge as failed and the intent returns to `requires_payment_method`. |
| Successful with delay | `00-0000-4444` | Simulates a successful deposit 30 seconds later. |
| Partial | `00-0000-3333` | Simulates a 50% deposit followed by another deposit for the remaining 50%. |

## SINPE Movil

To create a SINPE Movil test method, use `mobile_number` in `type` and include the number in `mobileNumber.number`.

| Scenario | Number | Behavior |
| --- | --- | --- |
| Successful | `+50688888888` | Simulates a successful transfer 15 seconds later. |
| Successful with delay | `+50688884444` | Simulates a successful transfer 6 minutes later. |
| Failed | `+50688889521` | Does not simulate a transfer and the intent state does not change. |
| Partial | `+50688883333` | Simulates a 50% transfer followed by another transfer for the remaining 50%. |

## Zunify

To create a Zunify test method, use `zunify` in `type` and include `phoneNumber` and `pin` in the `zunify` object.

| Scenario | Number | PIN | Behavior |
| --- | --- | --- | --- |
| Successful | `11223344` | `1234` | Simulates a Zunify charge and marks the intent as successful approximately 10 seconds later. |

---

# 3DS Authentication

URL: https://docs.onvopay.com/en/payments/three-ds
Markdown: https://docs.onvopay.com/en/payments/three-ds.md

# 3DS Authentication

3D Secure adds an authentication layer for card payments. When the issuer requires it, the customer must complete a verification, usually on the bank's page or in a modal within your site.

In 100% API integrations, you identify this case when payment intent confirmation returns `requires_action` and a `nextAction` object.

## Related API reference

- [Confirm a payment intent](/en/api/confirmar-una-intencion-de-pago)
- [Retrieve a payment intent](/en/api/obtener-una-intencion-de-pago)
- [Create a payment method](/en/api/crear-un-metodo-de-pago)

## Redirect

Send `returnUrl` when confirming the payment intent.

```json
{
  "paymentMethodId": "cl502zv0d0127ebdp3zt27651",
  "returnUrl": "https://www.example.com/return"
}
```

If 3DS is required, the response includes the URL where you should redirect the customer.

```json
{
  "status": "requires_action",
  "nextAction": {
    "type": "redirect_to_url",
    "redirectToUrl": {
      "url": "https://checkout.onvopay.com/authorize/test_clv...",
      "returnUrl": "https://www.example.com/return"
    }
  }
}
```

After authentication is completed, ONVO redirects the customer to your `returnUrl` with the `payment_intent_id` parameter.

```text
https://www.example.com/return?payment_intent_id=cl502zv0d0127ebdp3zt27651
```

Retrieve the payment intent to confirm the final status before marking the order as paid.

## Modal

You can also handle 3DS with the ONVO web library.

```html
<script src="https://js.onvopay.com/v1/"></script>
```

Initialize the library with your publishable key and call `handleNextAction` when the intent requires action.

```html
<script>
  const onvo = ONVO("onvo_live_publishable_key_H4PG...");

  onvo.handleNextAction({
    paymentIntentId: "clrr934wl001mdpkhw2g82rlt",
  }).then(function (result) {
    if (result.error) {
      console.error(result.error);
    } else {
      console.log(result.paymentIntent);
    }
  });
</script>
```

Even if 3DS authentication succeeds, validate the final payment intent status. The transaction can still be declined for other reasons.

You can test this flow with card `4000000000003220` in test mode.

---

# Errors

URL: https://docs.onvopay.com/en/reference/errors
Markdown: https://docs.onvopay.com/en/reference/errors.md

# Errors

The ONVO API uses standard HTTP codes and JSON responses to describe errors.

| Code | Meaning |
| --- | --- |
| `400` | Invalid request. |
| `401` | Missing authentication or invalid key. |
| `403` | The key does not have permission for the action. |
| `404` | The resource does not exist. |
| `409` | State conflict. |
| `422` | The request could not be processed with the submitted data. |
| `500` | Internal error. |

Store the request identifier when contacting support.

---

# Pagination

URL: https://docs.onvopay.com/en/reference/pagination
Markdown: https://docs.onvopay.com/en/reference/pagination.md

# Pagination

List endpoints use cursor-based pagination. In the API reference, these fields appear as optional query parameters on list endpoints, for example `GET /v1/customers`, `GET /v1/payment-intents/account`, `GET /v1/products`, and other endpoints that return collections.

In the interactive API reference explorer, optional parameters appear under **Request > Parameters**.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `limit` | number | Number of objects to return. Accepts values from `1` to `100`. When omitted, the API uses `10`. |
| `startingAfter` | string | Cursor for the next page. Use the `id` of the last object received in the current page. |
| `endingBefore` | string | Cursor for the previous page. Use the `id` of the first object received in the current page. |

Send only one cursor per request. If you send both `startingAfter` and `endingBefore`, the API returns an error because the backend can only navigate one direction per request.

The request parameter names are `startingAfter` and `endingBefore`. In list responses, the API returns those cursor values under `meta.cursorNext` and `meta.cursorBefore`; use `meta.cursorNext` as `startingAfter` to move forward and `meta.cursorBefore` as `endingBefore` to move backward.

## Examples

First page:

```bash
curl "https://api.onvopay.com/v1/customers?limit=10" \
  -H "Authorization: Bearer onvo_test_secret_key_..."
```

Next page:

```bash
curl "https://api.onvopay.com/v1/customers?limit=10&startingAfter=cl40muorw00493ndp0okzk2g3" \
  -H "Authorization: Bearer onvo_test_secret_key_..."
```

Previous page:

```bash
curl "https://api.onvopay.com/v1/customers?limit=10&endingBefore=cl40muorw00493ndp0okzk2g3" \
  -H "Authorization: Bearer onvo_test_secret_key_..."
```

When the response includes `meta`, use the response cursors to build the next request.

## Recommendations

- Use filters to limit data volume.
- Process pages incrementally.
- Do not assume two consecutive pages are immutable if data changes while you are iterating through the list.

---

# Webhooks

URL: https://docs.onvopay.com/en/webhooks
Markdown: https://docs.onvopay.com/en/webhooks.md

# Webhooks

ONVO uses webhooks to notify your application when a result is produced while processing a payment intent, subscription, checkout session, or incoming transfer.

To receive them, configure a callback URL in your ONVO account. ONVO sends a `POST` request to that URL whenever a supported event is processed. The payload includes a `type` attribute that identifies the event and a `data` object with the related information.

## Related API reference

- [Payment intents](/en/api/intenciones-de-pago)
- [Subscriptions](/en/api/cargos-recurrentes)
- [Checkout sessions](/en/api/sesiones-de-checkout)
- [SINPE Movil](/en/api/sinpe-movil)

## Recommended flow

1. Expose an HTTPS endpoint.
2. Register the endpoint in the ONVO Dashboard under developers.
3. Verify the event origin with the webhook secret.
4. Process the event idempotently.
5. Respond with a `2xx` status when processing succeeds.

## Supported events

| Event | When it happens |
| --- | --- |
| `payment-intent.succeeded` | A payment intent is processed successfully. |
| `payment-intent.failed` | A payment intent fails. |
| `payment-intent.deferred` | A payment intent is waiting for approval, for example in a SINPE flow. |
| `subscription.renewal.succeeded` | A subscription renews successfully. |
| `subscription.renewal.failed` | A subscription renewal fails. |
| `checkout-session.succeeded` | A checkout session is processed successfully. |
| `mobile-transfer.received` | An incoming transfer is received on a custom SINPE Movil number. |

`mobile-transfer.received` is an additional notification for merchants with this capability enabled. It does not represent a successful payment by itself and is not sent by default. Contact support to enable it.

## Payload format

ONVO sends every webhook as a `POST` request with `Content-Type: application/json`. The body always has this structure:

```json
{
  "type": "payment-intent.succeeded",
  "data": {
    "id": "clpiment0001"
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `type` | `string` | Name of the event received. Use it to decide which logic to run. |
| `data` | `object` | Snapshot of the object related to the event. Its shape depends on `type`. |

Amounts are sent as integers in the smallest currency unit. For example, `500000` represents ₡5,000.00 in `CRC` and `5000` represents $50.00 in `USD`. Dates are sent as ISO 8601 timestamps in UTC. The examples show the most important fields for integrations; depending on the payment method or flow, `data` can include additional fields or `null` values.

## Payloads by event

### `payment-intent.succeeded`

`data` contains the updated payment intent. When available, it includes the customer and the list of charges generated for that intent.

```json
{
  "type": "payment-intent.succeeded",
  "data": {
    "id": "clpiment0001",
    "accountId": "clacct0001",
    "mode": "test",
    "amount": 500000,
    "baseAmount": 500000,
    "baseExchangeRate": 1,
    "capturableAmount": 0,
    "receivedAmount": 500000,
    "currency": "CRC",
    "status": "succeeded",
    "confirmationAttempts": 1,
    "description": "Order #1001",
    "paymentMethodId": "clpm0001",
    "customerId": "clcus0001",
    "metadata": {
      "orderId": "order_1001"
    },
    "customer": {
      "id": "clcus0001",
      "name": "Ana Mora",
      "email": "ana@example.com",
      "phone": "+50688888888"
    },
    "charges": [
      {
        "id": "clch0001",
        "amount": 500000,
        "baseAmount": 500000,
        "baseExchangeRate": 1,
        "refNumber": "123456",
        "mode": "test",
        "currency": "CRC",
        "status": "succeeded",
        "failureCode": null,
        "failureMessage": null,
        "isApproved": true,
        "isCaptured": true,
        "createdAt": "2026-04-29T16:10:00.000Z",
        "updatedAt": "2026-04-29T16:10:01.000Z"
      }
    ],
    "lastPaymentError": null,
    "createdAt": "2026-04-29T16:09:50.000Z",
    "updatedAt": "2026-04-29T16:10:01.000Z"
  }
}
```

### `payment-intent.failed`

`data` contains the payment intent and an `error` object with the failure reason.

```json
{
  "type": "payment-intent.failed",
  "data": {
    "id": "clpiment0002",
    "accountId": "clacct0001",
    "currency": "CRC",
    "capturableAmount": 0,
    "status": "requires_payment_method",
    "metadata": {
      "orderId": "order_1002"
    },
    "customer": {
      "id": "clcus0002",
      "name": "Luis Vega",
      "email": "luis@example.com",
      "phone": "+50688887777"
    },
    "error": {
      "id": "clerr0001",
      "mode": "test",
      "paymentMethodType": "card",
      "type": "processing_error",
      "code": "declined",
      "message": "Transaction declined due to test payment method used",
      "createdAt": "2026-04-29T16:12:00.000Z",
      "updatedAt": "2026-04-29T16:12:00.000Z"
    }
  }
}
```

### `payment-intent.deferred`

`data` contains the payment intent while it is waiting for external confirmation, for example when ONVO is waiting for a transfer confirmation.

```json
{
  "type": "payment-intent.deferred",
  "data": {
    "id": "clpiment0003",
    "accountId": "clacct0001",
    "mode": "test",
    "amount": 250000,
    "currency": "CRC",
    "status": "processing",
    "paymentMethodId": "clpm0003",
    "customerId": "clcus0003",
    "metadata": {
      "orderId": "order_1003"
    },
    "createdAt": "2026-04-29T16:13:00.000Z",
    "updatedAt": "2026-04-29T16:13:02.000Z"
  }
}
```

### `subscription.renewal.succeeded`

`data` contains the renewal associated with the charged period. Each renewal is tied to a subscription and to the payment intent created for that period.

```json
{
  "type": "subscription.renewal.succeeded",
  "data": {
    "id": "clinv0001",
    "accountId": "clacct0001",
    "mode": "test",
    "status": "paid",
    "currency": "CRC",
    "attemptCount": 1,
    "attempted": true,
    "description": "Monthly plan",
    "total": 1200000,
    "subTotal": 1200000,
    "originalTotal": null,
    "periodStart": "2026-04-01T00:00:00.000Z",
    "periodEnd": "2026-05-01T00:00:00.000Z",
    "paymentIntentId": "clpiment0004",
    "subscriptionId": "clsub0001",
    "customerId": "clcus0004",
    "metadata": {
      "plan": "pro"
    },
    "createdAt": "2026-04-01T00:00:00.000Z",
    "updatedAt": "2026-04-01T00:00:05.000Z"
  }
}
```

### `subscription.renewal.failed`

`data` contains the renewal status, the subscription status, the next retry date, and the error returned while processing the payment intent.

```json
{
  "type": "subscription.renewal.failed",
  "data": {
    "subscriptionId": "clsub0002",
    "paymentIntentId": "clpiment0005",
    "currency": "CRC",
    "lastPaymentAttempt": "2026-04-29T16:20:00.000Z",
    "attemptCount": 2,
    "invoiceStatus": "open",
    "subscriptionStatus": "past_due",
    "metadata": {
      "accountTier": "pro"
    },
    "invoiceMetadata": {
      "period": "2026-04"
    },
    "invoicePeriodStart": "2026-04-01T00:00:00.000Z",
    "invoicePeriodEnd": "2026-05-01T00:00:00.000Z",
    "currentPeriodStart": "2026-04-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
    "nextPaymentAttempt": "2026-04-30T16:20:00.000Z",
    "customer": {
      "id": "clcus0005",
      "name": "María Solís",
      "email": "maria@example.com",
      "phone": "+50688886666"
    },
    "error": {
      "id": "clerr0002",
      "mode": "test",
      "paymentMethodType": "card",
      "type": "processing_error",
      "code": "declined",
      "message": "Transaction declined due to test payment method used",
      "createdAt": "2026-04-29T16:20:00.000Z",
      "updatedAt": "2026-04-29T16:20:00.000Z"
    }
  }
}
```

### `checkout-session.succeeded`

`data` contains the completed Checkout Session, its line items, and the customer from the associated payment intent.

```json
{
  "type": "checkout-session.succeeded",
  "data": {
    "id": "clcs0001",
    "url": "https://checkout.onvopay.com/pay/clcs0001",
    "mode": "test",
    "status": "complete",
    "paymentStatus": "paid",
    "paymentMode": "payment",
    "amountSubTotal": 350000,
    "amountTotal": 350000,
    "currency": "CRC",
    "successUrl": "https://example.com/success",
    "cancelUrl": "https://example.com/cancel",
    "paymentIntentId": "clpiment0006",
    "customerId": "clcus0006",
    "metadata": {
      "cartId": "cart_123"
    },
    "customer": {
      "id": "clcus0006",
      "name": "Sofía Rojas",
      "email": "sofia@example.com",
      "phone": "+50688885555"
    },
    "lineItems": [
      {
        "name": "Test product",
        "description": "Product description",
        "currency": "CRC",
        "amount": 350000,
        "priceId": "clprice0001"
      }
    ],
    "createdAt": "2026-04-29T16:25:00.000Z",
    "updatedAt": "2026-04-29T16:25:10.000Z"
  }
}
```

### `mobile-transfer.received`

`data` contains the incoming transfer information. This event does not confirm a payment intent by itself.

```json
{
  "type": "mobile-transfer.received",
  "data": {
    "amount": 1450000,
    "currency": "CRC",
    "description": "PAGO DE SERVICIOS",
    "SINPERefNumber": "2025110312774577852010",
    "authorizationDate": "2026-04-29T16:30:00.000Z",
    "originId": "01-1393-1919",
    "originName": "JUAN PEREZ CASTRO",
    "originPhone": "72940567"
  }
}
```

## Security

Each webhook has an assigned secret. You can view it in the ONVO Dashboard next to the webhook configuration.

ONVO includes that value in the `X-Webhook-Secret` header. The backend generates secrets with the `webhook_secret_` prefix. Use it to verify that the request comes from ONVO before processing the event.

```http
X-Webhook-Secret: webhook_secret_...
```

## Responses and errors

When an event represents an error, the payload object can include an `error` attribute. That object can contain:

| Field | Description |
| --- | --- |
| `message` | Human-readable error description. |
| `code` | Error code, when available. |
| `type` | Error type, when available. |

Your endpoint should respond with a `2xx` status only when the event was received and processed correctly. If you respond with another status, ONVO records the delivery as failed.

Your system should tolerate events received out of order.

---

# Update a Checkout Session Customer

URL: https://docs.onvopay.com/en/api/actualizar-cliente-de-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/actualizar-cliente-de-una-sesion-de-checkout.md

# Update a Checkout Session Customer

Updates the customer's contact information in a Checkout Session.

Endpoint: `PATCH /v1/checkout/sessions/{id}/customer`

Human page: https://docs.onvopay.com/en/api/actualizar-cliente-de-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Subscription Item

URL: https://docs.onvopay.com/en/api/actualizar-item-de-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/actualizar-item-de-un-cargo-recurrente.md

# Update a Subscription Item

See the ONVO documentation for integration details and examples.

Endpoint: `PATCH /v1/subscriptions/{id}/items/{item}`

Human page: https://docs.onvopay.com/en/api/actualizar-item-de-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Checkout Session Item

URL: https://docs.onvopay.com/en/api/actualizar-item-de-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/actualizar-item-de-una-sesion-de-checkout.md

# Update a Checkout Session Item

Updates the selected item in an open Checkout Session.

Endpoint: `POST /v1/checkout/sessions/{id}/line-item`

Human page: https://docs.onvopay.com/en/api/actualizar-item-de-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Subscription

URL: https://docs.onvopay.com/en/api/actualizar-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/actualizar-un-cargo-recurrente.md

# Update a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/subscriptions/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Customer

URL: https://docs.onvopay.com/en/api/actualizar-un-cliente
Markdown: https://docs.onvopay.com/en/api/actualizar-un-cliente.md

# Update a Customer

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/customers/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Coupon

URL: https://docs.onvopay.com/en/api/actualizar-un-cupon
Markdown: https://docs.onvopay.com/en/api/actualizar-un-cupon.md

# Update a Coupon

Updates a coupon. When you send `binRules` or `promotionCodes`, ONVO replaces the previous list with the list you sent.

Endpoint: `POST /v1/coupons/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-cupon
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Payment Method

URL: https://docs.onvopay.com/en/api/actualizar-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/actualizar-un-metodo-de-pago.md

# Update a Payment Method

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-methods/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Price

URL: https://docs.onvopay.com/en/api/actualizar-un-precio
Markdown: https://docs.onvopay.com/en/api/actualizar-un-precio.md

# Update a Price

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/prices/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-precio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Product

URL: https://docs.onvopay.com/en/api/actualizar-un-producto
Markdown: https://docs.onvopay.com/en/api/actualizar-un-producto.md

# Update a Product

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/products/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-un-producto
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Connected Account

URL: https://docs.onvopay.com/en/api/actualizar-una-cuenta-conectada
Markdown: https://docs.onvopay.com/en/api/actualizar-una-cuenta-conectada.md

# Update a Connected Account

Updates the connected account business name, marketplace fee percentage, or both.

Endpoint: `POST /v1/connected-accounts/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-una-cuenta-conectada
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Payment Intent

URL: https://docs.onvopay.com/en/api/actualizar-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/actualizar-una-intencion-de-pago.md

# Update a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-intents/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Update a Shipping Rate

URL: https://docs.onvopay.com/en/api/actualizar-una-tarifa-de-envio
Markdown: https://docs.onvopay.com/en/api/actualizar-una-tarifa-de-envio.md

# Update a Shipping Rate

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/shipping-rates/{id}`

Human page: https://docs.onvopay.com/en/api/actualizar-una-tarifa-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Add an Item to a Subscription

URL: https://docs.onvopay.com/en/api/agregar-item-a-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/agregar-item-a-un-cargo-recurrente.md

# Add an Item to a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/subscriptions/{id}/items`

Human page: https://docs.onvopay.com/en/api/agregar-item-a-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Subscription Item

URL: https://docs.onvopay.com/en/api/borrar-item-de-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/borrar-item-de-un-cargo-recurrente.md

# Delete a Subscription Item

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/subscriptions/{id}/items/{itemId}`

Human page: https://docs.onvopay.com/en/api/borrar-item-de-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Customer

URL: https://docs.onvopay.com/en/api/borrar-un-cliente
Markdown: https://docs.onvopay.com/en/api/borrar-un-cliente.md

# Delete a Customer

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/customers/{id}`

Human page: https://docs.onvopay.com/en/api/borrar-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Coupon

URL: https://docs.onvopay.com/en/api/borrar-un-cupon
Markdown: https://docs.onvopay.com/en/api/borrar-un-cupon.md

# Delete a Coupon

Deletes a coupon by its identifier.

Endpoint: `DELETE /v1/coupons/{id}`

Human page: https://docs.onvopay.com/en/api/borrar-un-cupon
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Price

URL: https://docs.onvopay.com/en/api/borrar-un-precio
Markdown: https://docs.onvopay.com/en/api/borrar-un-precio.md

# Delete a Price

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/prices/{id}`

Human page: https://docs.onvopay.com/en/api/borrar-un-precio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Product

URL: https://docs.onvopay.com/en/api/borrar-un-producto
Markdown: https://docs.onvopay.com/en/api/borrar-un-producto.md

# Delete a Product

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/products/{id}`

Human page: https://docs.onvopay.com/en/api/borrar-un-producto
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Delete a Shipping Rate

URL: https://docs.onvopay.com/en/api/borrar-una-tarifa-de-envio
Markdown: https://docs.onvopay.com/en/api/borrar-una-tarifa-de-envio.md

# Delete a Shipping Rate

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/shipping-rates/{id}`

Human page: https://docs.onvopay.com/en/api/borrar-una-tarifa-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Cancel a Subscription

URL: https://docs.onvopay.com/en/api/cancelar-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/cancelar-un-cargo-recurrente.md

# Cancel a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `DELETE /v1/subscriptions/{id}`

Human page: https://docs.onvopay.com/en/api/cancelar-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Cancel a Payment Intent

URL: https://docs.onvopay.com/en/api/cancelar-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/cancelar-una-intencion-de-pago.md

# Cancel a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-intents/{id}/cancel`

Human page: https://docs.onvopay.com/en/api/cancelar-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Capture a Payment Intent

URL: https://docs.onvopay.com/en/api/capturar-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/capturar-una-intencion-de-pago.md

# Capture a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-intents/{id}/capture`

Human page: https://docs.onvopay.com/en/api/capturar-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Subscriptions

URL: https://docs.onvopay.com/en/api/cargos-recurrentes
Markdown: https://docs.onvopay.com/en/api/cargos-recurrentes.md

# Subscriptions

Cargos recurrentes

Human page: https://docs.onvopay.com/en/api/cargos-recurrentes
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Customers

URL: https://docs.onvopay.com/en/api/clientes
Markdown: https://docs.onvopay.com/en/api/clientes.md

# Customers

Clientes

Human page: https://docs.onvopay.com/en/api/clientes
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Configure a Weekly Fee

URL: https://docs.onvopay.com/en/api/configurar-una-tarifa-semanal
Markdown: https://docs.onvopay.com/en/api/configurar-una-tarifa-semanal.md

# Configure a Weekly Fee

Creates or updates the fixed weekly fee configuration for a connected account owned by the authenticated primary account and mode.

Endpoint: `POST /v1/connected-accounts/{id}/weekly-fees`

Human page: https://docs.onvopay.com/en/api/configurar-una-tarifa-semanal
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Confirm a Subscription

URL: https://docs.onvopay.com/en/api/confirmar-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/confirmar-un-cargo-recurrente.md

# Confirm a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/subscriptions/{id}/confirm`

Human page: https://docs.onvopay.com/en/api/confirmar-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Confirm a Payment Intent

URL: https://docs.onvopay.com/en/api/confirmar-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/confirmar-una-intencion-de-pago.md

# Confirm a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-intents/{id}/confirm`

Human page: https://docs.onvopay.com/en/api/confirmar-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Confirm a Checkout Session

URL: https://docs.onvopay.com/en/api/confirmar-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/confirmar-una-sesion-de-checkout.md

# Confirm a Checkout Session

Confirms a Checkout Session with the selected payment method.

Endpoint: `POST /v1/checkout/sessions/{id}/confirm`

Human page: https://docs.onvopay.com/en/api/confirmar-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Subscription

URL: https://docs.onvopay.com/en/api/crear-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/crear-un-cargo-recurrente.md

# Create a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/subscriptions`

Human page: https://docs.onvopay.com/en/api/crear-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Customer

URL: https://docs.onvopay.com/en/api/crear-un-cliente
Markdown: https://docs.onvopay.com/en/api/crear-un-cliente.md

# Create a Customer

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/customers`

Human page: https://docs.onvopay.com/en/api/crear-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Coupon

URL: https://docs.onvopay.com/en/api/crear-un-cupon
Markdown: https://docs.onvopay.com/en/api/crear-un-cupon.md

# Create a Coupon

Creates a coupon that you can later attach to a one-time Checkout Session.

Endpoint: `POST /v1/coupons`

Human page: https://docs.onvopay.com/en/api/crear-un-cupon
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Payment Method

URL: https://docs.onvopay.com/en/api/crear-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/crear-un-metodo-de-pago.md

# Create a Payment Method

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-methods`

Human page: https://docs.onvopay.com/en/api/crear-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Price

URL: https://docs.onvopay.com/en/api/crear-un-precio
Markdown: https://docs.onvopay.com/en/api/crear-un-precio.md

# Create a Price

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/prices`

Human page: https://docs.onvopay.com/en/api/crear-un-precio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Product

URL: https://docs.onvopay.com/en/api/crear-un-producto
Markdown: https://docs.onvopay.com/en/api/crear-un-producto.md

# Create a Product

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/products`

Human page: https://docs.onvopay.com/en/api/crear-un-producto
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Refund

URL: https://docs.onvopay.com/en/api/crear-un-reembolso
Markdown: https://docs.onvopay.com/en/api/crear-un-reembolso.md

# Create a Refund

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/refunds`

Human page: https://docs.onvopay.com/en/api/crear-un-reembolso
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Connected Account

URL: https://docs.onvopay.com/en/api/crear-una-cuenta-conectada
Markdown: https://docs.onvopay.com/en/api/crear-una-cuenta-conectada.md

# Create a Connected Account

Creates a connected seller account in the primary account and mode determined by the Secret API Key. The response includes the ONVO-hosted onboarding URL.

Endpoint: `POST /v1/connected-accounts`

Human page: https://docs.onvopay.com/en/api/crear-una-cuenta-conectada
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Payment Intent

URL: https://docs.onvopay.com/en/api/crear-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/crear-una-intencion-de-pago.md

# Create a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-intents`

Human page: https://docs.onvopay.com/en/api/crear-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Checkout Session

URL: https://docs.onvopay.com/en/api/crear-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/crear-una-sesion-de-checkout.md

# Create a Checkout Session

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/checkout/sessions/one-time-link`

Human page: https://docs.onvopay.com/en/api/crear-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Session from a Payment Link

URL: https://docs.onvopay.com/en/api/crear-una-sesion-desde-un-link-de-pago
Markdown: https://docs.onvopay.com/en/api/crear-una-sesion-desde-un-link-de-pago.md

# Create a Session from a Payment Link

Creates a Checkout Session from an existing payment link.

Endpoint: `GET /v1/checkout/sessions/link/{paymentLinkId}`

Human page: https://docs.onvopay.com/en/api/crear-una-sesion-desde-un-link-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Create a Shipping Rate

URL: https://docs.onvopay.com/en/api/crear-una-tarifa-de-envio
Markdown: https://docs.onvopay.com/en/api/crear-una-tarifa-de-envio.md

# Create a Shipping Rate

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/shipping-rates`

Human page: https://docs.onvopay.com/en/api/crear-una-tarifa-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Coupons

URL: https://docs.onvopay.com/en/api/cupones
Markdown: https://docs.onvopay.com/en/api/cupones.md

# Coupons

Create and manage coupons that can be applied to Checkout.

Human page: https://docs.onvopay.com/en/api/cupones
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Disconnect a Payment Method

URL: https://docs.onvopay.com/en/api/desconectar-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/desconectar-un-metodo-de-pago.md

# Disconnect a Payment Method

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/payment-methods/{id}/detach`

Human page: https://docs.onvopay.com/en/api/desconectar-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Expire a Checkout Session

URL: https://docs.onvopay.com/en/api/expirar-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/expirar-una-sesion-de-checkout.md

# Expire a Checkout Session

See the ONVO documentation for integration details and examples.

Endpoint: `POST /v1/checkout/sessions/{id}/expire`

Human page: https://docs.onvopay.com/en/api/expirar-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Payment Intents

URL: https://docs.onvopay.com/en/api/intenciones-de-pago
Markdown: https://docs.onvopay.com/en/api/intenciones-de-pago.md

# Payment Intents

Intenciones de pago

Human page: https://docs.onvopay.com/en/api/intenciones-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List Connected Accounts

URL: https://docs.onvopay.com/en/api/listar-cuentas-conectadas
Markdown: https://docs.onvopay.com/en/api/listar-cuentas-conectadas.md

# List Connected Accounts

Lists connected seller accounts owned by the primary account in the Secret API Key mode, using cursor pagination.

Endpoint: `GET /v1/connected-accounts`

Human page: https://docs.onvopay.com/en/api/listar-cuentas-conectadas
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List Coupons

URL: https://docs.onvopay.com/en/api/listar-cupones
Markdown: https://docs.onvopay.com/en/api/listar-cupones.md

# List Coupons

Lists coupons created in the API key mode.

Endpoint: `GET /v1/coupons`

Human page: https://docs.onvopay.com/en/api/listar-cupones
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List SINPE Movil Payments

URL: https://docs.onvopay.com/en/api/listar-pagos-por-sinpe-movil
Markdown: https://docs.onvopay.com/en/api/listar-pagos-por-sinpe-movil.md

# List SINPE Movil Payments

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/mobile-transfers/list`

Human page: https://docs.onvopay.com/en/api/listar-pagos-por-sinpe-movil
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Invoices

URL: https://docs.onvopay.com/en/api/listar-renovaciones
Markdown: https://docs.onvopay.com/en/api/listar-renovaciones.md

# List all Invoices

Lists invoices for the account. Invoices represent each billing period for a subscription. ONVO creates an invoice at the start of the subscription and on each successful renewal. Each invoice is associated with a payment intent and lets you inspect the charge for that period. The URL examples show how to send pagination, range, metadata, and expand filters.

Endpoint: `GET /v1/invoices`

Human page: https://docs.onvopay.com/en/api/listar-renovaciones
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List Checkout Sessions

URL: https://docs.onvopay.com/en/api/listar-sesiones-de-checkout
Markdown: https://docs.onvopay.com/en/api/listar-sesiones-de-checkout.md

# List Checkout Sessions

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/checkout/sessions/one-time-link/account`

Human page: https://docs.onvopay.com/en/api/listar-sesiones-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Payment Intents

URL: https://docs.onvopay.com/en/api/listar-todas-las-intenciones-de-pago
Markdown: https://docs.onvopay.com/en/api/listar-todas-las-intenciones-de-pago.md

# List all Payment Intents

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/payment-intents/account`

Human page: https://docs.onvopay.com/en/api/listar-todas-las-intenciones-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Shipping Rates

URL: https://docs.onvopay.com/en/api/listar-todas-las-tarifas-de-envio
Markdown: https://docs.onvopay.com/en/api/listar-todas-las-tarifas-de-envio.md

# List all Shipping Rates

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/shipping-rates`

Human page: https://docs.onvopay.com/en/api/listar-todas-las-tarifas-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Subscriptions

URL: https://docs.onvopay.com/en/api/listar-todos-los-cargos-recurrentes
Markdown: https://docs.onvopay.com/en/api/listar-todos-los-cargos-recurrentes.md

# List all Subscriptions

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/subscriptions`

Human page: https://docs.onvopay.com/en/api/listar-todos-los-cargos-recurrentes
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Customers

URL: https://docs.onvopay.com/en/api/listar-todos-los-clientes
Markdown: https://docs.onvopay.com/en/api/listar-todos-los-clientes.md

# List all Customers

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/customers`

Human page: https://docs.onvopay.com/en/api/listar-todos-los-clientes
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Payment Methods

URL: https://docs.onvopay.com/en/api/listar-todos-los-metodos-de-pago
Markdown: https://docs.onvopay.com/en/api/listar-todos-los-metodos-de-pago.md

# List all Payment Methods

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/payment-methods`

Human page: https://docs.onvopay.com/en/api/listar-todos-los-metodos-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Prices

URL: https://docs.onvopay.com/en/api/listar-todos-los-precios
Markdown: https://docs.onvopay.com/en/api/listar-todos-los-precios.md

# List all Prices

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/prices`

Human page: https://docs.onvopay.com/en/api/listar-todos-los-precios
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List all Products

URL: https://docs.onvopay.com/en/api/listar-todos-los-productos
Markdown: https://docs.onvopay.com/en/api/listar-todos-los-productos.md

# List all Products

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/products`

Human page: https://docs.onvopay.com/en/api/listar-todos-los-productos
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Marketplaces

URL: https://docs.onvopay.com/en/api/marketplaces
Markdown: https://docs.onvopay.com/en/api/marketplaces.md

# Marketplaces

Create and manage connected seller accounts from a standard primary account.

Human page: https://docs.onvopay.com/en/api/marketplaces
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Payment Methods

URL: https://docs.onvopay.com/en/api/metodos-de-pago
Markdown: https://docs.onvopay.com/en/api/metodos-de-pago.md

# Payment Methods

Métodos de pago

Human page: https://docs.onvopay.com/en/api/metodos-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List a Customer's Payment Intents

URL: https://docs.onvopay.com/en/api/obtener-las-intenciones-de-pago-de-un-cliente
Markdown: https://docs.onvopay.com/en/api/obtener-las-intenciones-de-pago-de-un-cliente.md

# List a Customer's Payment Intents

Lists the payment intents associated with a customer.

Endpoint: `GET /v1/customers/{id}/payment-intents`

Human page: https://docs.onvopay.com/en/api/obtener-las-intenciones-de-pago-de-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List a Customer's Subscriptions

URL: https://docs.onvopay.com/en/api/obtener-los-cargos-recurrentes-de-un-cliente
Markdown: https://docs.onvopay.com/en/api/obtener-los-cargos-recurrentes-de-un-cliente.md

# List a Customer's Subscriptions

Lists the subscriptions associated with a customer.

Endpoint: `GET /v1/customers/{id}/subscriptions`

Human page: https://docs.onvopay.com/en/api/obtener-los-cargos-recurrentes-de-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# List a Customer's Payment Methods

URL: https://docs.onvopay.com/en/api/obtener-los-metodos-de-pago-de-un-cliente
Markdown: https://docs.onvopay.com/en/api/obtener-los-metodos-de-pago-de-un-cliente.md

# List a Customer's Payment Methods

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/customers/{id}/payment-methods`

Human page: https://docs.onvopay.com/en/api/obtener-los-metodos-de-pago-de-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Subscription

URL: https://docs.onvopay.com/en/api/obtener-un-cargo-recurrente
Markdown: https://docs.onvopay.com/en/api/obtener-un-cargo-recurrente.md

# Retrieve a Subscription

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/subscriptions/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-cargo-recurrente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Customer

URL: https://docs.onvopay.com/en/api/obtener-un-cliente
Markdown: https://docs.onvopay.com/en/api/obtener-un-cliente.md

# Retrieve a Customer

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/customers/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-cliente
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Coupon

URL: https://docs.onvopay.com/en/api/obtener-un-cupon
Markdown: https://docs.onvopay.com/en/api/obtener-un-cupon.md

# Retrieve a Coupon

Returns a coupon by its identifier.

Endpoint: `GET /v1/coupons/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-cupon
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Payment Link

URL: https://docs.onvopay.com/en/api/obtener-un-link-de-pago
Markdown: https://docs.onvopay.com/en/api/obtener-un-link-de-pago.md

# Retrieve a Payment Link

Returns a payment link created from Checkout.

Endpoint: `GET /v1/checkout/sessions/one-time-link/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-link-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Payment Method

URL: https://docs.onvopay.com/en/api/obtener-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/obtener-un-metodo-de-pago.md

# Retrieve a Payment Method

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/payment-methods/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Price

URL: https://docs.onvopay.com/en/api/obtener-un-precio
Markdown: https://docs.onvopay.com/en/api/obtener-un-precio.md

# Retrieve a Price

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/prices/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-precio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Product

URL: https://docs.onvopay.com/en/api/obtener-un-producto
Markdown: https://docs.onvopay.com/en/api/obtener-un-producto.md

# Retrieve a Product

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/products/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-producto
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Refund

URL: https://docs.onvopay.com/en/api/obtener-un-reembolso
Markdown: https://docs.onvopay.com/en/api/obtener-un-reembolso.md

# Retrieve a Refund

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/refunds/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-un-reembolso
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Connected Account

URL: https://docs.onvopay.com/en/api/obtener-una-cuenta-conectada
Markdown: https://docs.onvopay.com/en/api/obtener-una-cuenta-conectada.md

# Retrieve a Connected Account

Returns the public connected account object when it belongs to the authenticated primary account and mode.

Endpoint: `GET /v1/connected-accounts/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-una-cuenta-conectada
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Payment Intent

URL: https://docs.onvopay.com/en/api/obtener-una-intencion-de-pago
Markdown: https://docs.onvopay.com/en/api/obtener-una-intencion-de-pago.md

# Retrieve a Payment Intent

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/payment-intents/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-una-intencion-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve an Invoice

URL: https://docs.onvopay.com/en/api/obtener-una-renovacion
Markdown: https://docs.onvopay.com/en/api/obtener-una-renovacion.md

# Retrieve an Invoice

Returns a specific invoice. Invoices represent each billing period for a subscription. ONVO creates an invoice at the start of the subscription and on each successful renewal. Each invoice is associated with a payment intent and lets you inspect the charge for that period.

Endpoint: `GET /v1/invoices/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-una-renovacion
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Checkout Session

URL: https://docs.onvopay.com/en/api/obtener-una-sesion-de-checkout
Markdown: https://docs.onvopay.com/en/api/obtener-una-sesion-de-checkout.md

# Retrieve a Checkout Session

Returns a Checkout Session by its identifier.

Endpoint: `GET /v1/checkout/sessions/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-una-sesion-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Shipping Rate

URL: https://docs.onvopay.com/en/api/obtener-una-tarifa-de-envio
Markdown: https://docs.onvopay.com/en/api/obtener-una-tarifa-de-envio.md

# Retrieve a Shipping Rate

See the ONVO documentation for integration details and examples.

Endpoint: `GET /v1/shipping-rates/{id}`

Human page: https://docs.onvopay.com/en/api/obtener-una-tarifa-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Retrieve a Payment Method Verification

URL: https://docs.onvopay.com/en/api/obtener-verificacion-de-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/obtener-verificacion-de-un-metodo-de-pago.md

# Retrieve a Payment Method Verification

Returns the verification status associated with a payment method.

Endpoint: `GET /v1/payment-methods/{id}/verification`

Human page: https://docs.onvopay.com/en/api/obtener-verificacion-de-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Prices

URL: https://docs.onvopay.com/en/api/precios
Markdown: https://docs.onvopay.com/en/api/precios.md

# Prices

Precios

Human page: https://docs.onvopay.com/en/api/precios
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Products

URL: https://docs.onvopay.com/en/api/productos
Markdown: https://docs.onvopay.com/en/api/productos.md

# Products

Productos

Human page: https://docs.onvopay.com/en/api/productos
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Refunds

URL: https://docs.onvopay.com/en/api/reembolsos
Markdown: https://docs.onvopay.com/en/api/reembolsos.md

# Refunds

Reembolsos

Human page: https://docs.onvopay.com/en/api/reembolsos
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Regenerate an Onboarding Link

URL: https://docs.onvopay.com/en/api/regenerar-enlace-de-onboarding
Markdown: https://docs.onvopay.com/en/api/regenerar-enlace-de-onboarding.md

# Regenerate an Onboarding Link

Expires the prior onboarding link and creates a new ONVO-hosted link for a connected account that has not completed onboarding.

Endpoint: `POST /v1/connected-accounts/{id}/onboarding-link`

Human page: https://docs.onvopay.com/en/api/regenerar-enlace-de-onboarding
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Invoices

URL: https://docs.onvopay.com/en/api/renovaciones
Markdown: https://docs.onvopay.com/en/api/renovaciones.md

# Invoices

Renovaciones

Human page: https://docs.onvopay.com/en/api/renovaciones
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Checkout Sessions

URL: https://docs.onvopay.com/en/api/sesiones-de-checkout
Markdown: https://docs.onvopay.com/en/api/sesiones-de-checkout.md

# Checkout Sessions

Sesiones de Checkout

Human page: https://docs.onvopay.com/en/api/sesiones-de-checkout
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# SINPE Movil

URL: https://docs.onvopay.com/en/api/sinpe-movil
Markdown: https://docs.onvopay.com/en/api/sinpe-movil.md

# SINPE Movil

SINPE Móvil

Human page: https://docs.onvopay.com/en/api/sinpe-movil
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Shipping Rates

URL: https://docs.onvopay.com/en/api/tarifas-de-envio
Markdown: https://docs.onvopay.com/en/api/tarifas-de-envio.md

# Shipping Rates

Tarifas de envío

Human page: https://docs.onvopay.com/en/api/tarifas-de-envio
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Validate Bank Account Information

URL: https://docs.onvopay.com/en/api/validar-informacion-de-una-cuenta-bancaria
Markdown: https://docs.onvopay.com/en/api/validar-informacion-de-una-cuenta-bancaria.md

# Validate Bank Account Information

Validates a bank account's status, currency, and verification before creating or confirming a payment method.

Endpoint: `POST /v1/bank-accounts/check-info`

Human page: https://docs.onvopay.com/en/api/validar-informacion-de-una-cuenta-bancaria
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# Verify a Payment Method

URL: https://docs.onvopay.com/en/api/verificar-un-metodo-de-pago
Markdown: https://docs.onvopay.com/en/api/verificar-un-metodo-de-pago.md

# Verify a Payment Method

Verifies a payment method that requires manual confirmation, such as a bank account.

Endpoint: `POST /v1/payment-methods/{id}/verify`

Human page: https://docs.onvopay.com/en/api/verificar-un-metodo-de-pago
OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

---

# ONVO API Reference

The ONVO API reference is generated from the OpenAPI document and rendered in the documentation site.

- API reference: https://docs.onvopay.com/en/api
- OpenAPI YAML: https://docs.onvopay.com/openapi.yaml

Use the OpenAPI file for code generation, API clients, and agentic integration workflows.