Cargos recurrentes

Un cargo recurrente cobra a un cliente de forma periódica. El flujo empieza creando un producto y un precio recurrente; después asociás un método de pago al cliente y creás el cargo recurrente con ese precio.

Podés cobrar el primer período de inmediato o crear el cargo recurrente primero y confirmarlo en una solicitud adicional.

Referencia API relacionada

• Crear un producto
• Crear un precio
• Crear un método de pago
• Crear un cargo recurrente
• Confirmar un cargo recurrente
• Obtener un cargo recurrente
• Listar renovaciones

Flujo base

1. Creá un producto para representar lo que se vende.
2. Creá un precio con type: "recurring" y definí el intervalo de cobro.
3. Creá o recolectá un método de pago para el cliente.
4. Creá el cargo recurrente con el customerId, el paymentMethodId y el priceId.
5. Escuchá webhooks para confirmar el resultado del primer cobro y de cada renovación.

Crear un producto

curl https://api.onvopay.com/v1/products \
  -X POST \
  -H "Authorization: Bearer $ONVO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan Pro",
    "description": "Acceso mensual al Plan Pro",
    "isActive": true
  }'

Guardá el id del producto para crear el precio recurrente.

Crear un precio recurrente

El monto se envía en la denominación menor de la moneda. Por ejemplo, 250000 representa 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": "Plan Pro mensual",
    "recurring": {
      "interval": "month",
      "intervalCount": 1
    }
  }'

Guardá el id del precio. Ese valor se envía como priceId dentro de items.

Crear un método de pago

El método de pago debe pertenecer al mismo cliente que se usará en el cargo recurrente. Podés enviar un customerId existente o enviar customer para crear y asociar el cliente en la misma solicitud.

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": "María Rodríguez"
    },
    "billing": {
      "name": "María Rodríguez",
      "email": "maria@example.com",
      "address": {
        "country": "CR"
      }
    },
    "customer": {
      "name": "María Rodríguez",
      "email": "maria@example.com",
      "phone": "+50688880000"
    }
  }'

Guardá el id del método de pago y el customerId asociado.

Cobrar de inmediato

Para cobrar el primer período al crear el cargo recurrente, enviá paymentMethodId. Si omitís paymentBehavior, ONVO usa el comportamiento por defecto y confirma el primer cobro inmediatamente.

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": "Plan Pro mensual",
    "items": [
      {
        "priceId": "$PRICE_ID",
        "quantity": 1
      }
    ],
    "metadata": {
      "accountPlan": "pro",
      "internalSubscriptionId": "sub_123"
    }
  }'

ONVO crea la renovación inicial, genera una intención de pago para ese período y la confirma con el método de pago indicado. Revisá el estado del cargo recurrente, de la renovación y de la intención de pago antes de activar el servicio en tu sistema.

Diferir la confirmación

Usá paymentBehavior: "allow_incomplete" cuando querés crear el cargo recurrente primero y confirmar el cobro en una solicitud posterior. En este modo podés omitir paymentMethodId al crear el cargo recurrente.

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": "Plan Pro mensual",
    "items": [
      {
        "priceId": "$PRICE_ID",
        "quantity": 1
      }
    ],
    "metadata": {
      "accountPlan": "pro",
      "internalSubscriptionId": "sub_123"
    }
  }'

Cuando tengás el método de pago listo, confirmá el cargo recurrente:

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"
  }'

Renovaciones

Cada cargo recurrente genera renovaciones. La primera renovación se crea al inicio de la suscripción y las siguientes se crean con cada período exitoso. Cada renovación está asociada a una intención de pago, por lo que podés usarla para conciliar el período cobrado.

Buenas prácticas

• Guardá los IDs de producto, precio, cliente, método de pago y cargo recurrente en tu sistema.
• Usá metadata para asociar IDs internos, como el plan o la suscripción de tu plataforma.
• Escuchá subscription.renewal.succeeded y subscription.renewal.failed para sincronizar el estado local.
• Consultá las renovaciones para auditar cada período y su intención de pago asociada.