Saltar al contenido principal

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​

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.

Marketplace​

Si el cargo recurrente pertenece a un vendedor de tu marketplace, enviá onBehalfOf con el Account ID de esa cuenta marketplace al crear el cargo recurrente.

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

ONVO conserva esa cuenta marketplace en el cargo recurrente, en la renovación inicial y en las renovaciones futuras. Cada intención de pago generada para el cargo recurrente usa ese contexto para calcular la comisión marketplace.

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.
  • Usá onBehalfOf al crear cargos recurrentes de marketplace para que las renovaciones mantengan el mismo vendedor.
  • 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.