Skip to main content

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.

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​

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.

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.

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.

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.

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.

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:

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.
  • Listen for subscription.renewal.succeeded and subscription.renewal.failed to sync local state.
  • Query invoices to audit each period and its associated payment intent.