Pagos Recurrentes

Cobra a tus clientes de forma periodica (mensual, semanal, cada N dias, anual, un dia concreto de cada mes, con o sin fecha de fin) y gestiona todo el ciclo de vida desde tu sistema: alta, consulta, cambios, pausa, reactivacion, cambio de tarjeta y cancelacion.

Nombre tecnico: en la API cada pago recurrente es un recurso subscription (rutas /subscriptions, ids WEBCODE-SB-xxxxxxxx). En el panel aparecen en Transacciones > Pagos Recurrentes.

Reglas generales

• webcode obligatorio: en el body en POST/PATCH y en la query en GET. Debe coincidir con el de tu API key.
• Solo veras y modificaras los pagos recurrentes de tu webcode y de ese entorno. Cualquier recurso ajeno o del otro entorno responde 404.
• Importes siempre en centimos (2990 = 29,90 EUR). Monedas: EUR, USD, GBP.
• Idempotency-Key recomendada en todos los POST y PATCH (ver Autenticacion).

Flujo

1. POST /subscriptions crea un link de pago recurrente y devuelve paymentUrl.
2. Rediriges a tu cliente a paymentUrl. Paga el primer importe y se guarda su tarjeta.
3. Se crea el pago recurrente (subscriptionId) y recibes SUBSCRIPTION_CREATED. Tambien puedes consultarlo en GET /subscriptions/links/{linkId} (campo subscriptionId).
4. Avirato cobra cada periodo. Si un cobro falla se reintenta 3 veces (5 h, 8 h y 11 h despues); si sigue fallando el pago recurrente queda pausado (SUBSCRIPTION_ERROR).

Si el primer pago se rechaza

Se crea igualmente el pago recurrente en estado error (statusReason: initial_payment_failed) y recibes SUBSCRIPTION_FAILED. El link sigue pending y tu cliente puede reintentar con el mismo paymentUrl: cada intento crea un pago recurrente nuevo. El anterior queda en error, nunca se cobra y puedes ignorarlo. El valido es el del webhook SUBSCRIPTION_CREATED, que es tambien el que devuelve el detalle del link. El motivo del rechazo esta en refusalReason de GET /subscriptions/{id}/payments. Igual en Live y en Test.

Intervalos

• intervalCount minimo 1.
• billingDay (1-31) solo con month. En meses mas cortos se cobra el ultimo dia del mes.
• endAt futura (Y-m-d o Y-m-d H:i:s): el dia de fin ya no se cobra; esa noche el pago recurrente se cancela (statusReason: end_date_reached).
• initialAmount: primer pago distinto al recurrente (puede ser 0 para solo guardar la tarjeta).

Crear un pago recurrente

POST /external/v1/subscriptions → 201

{
  "webcode": "SHOP01",
  "amount": { "value": 2990, "currency": "EUR" },
  "intervalUnit": "month",
  "intervalCount": 1,
  "billingDay": 5,
  "endAt": "2027-06-30",
  "initialAmount": { "value": 990 },
  "returnUrl": "https://tu-web.com/pago-recurrente/ok",
  "description": "Plan Gold",
  "customReference": "PEDIDO-123",
  "planCode": "GOLD",
  "customerInternalId": "CLI-42",
  "customerInternalFolder": "EXP-2026-7",
  "customerExtraInfo": "Juan Perez",
  "metadata": { "contrato": "C-99" },
  "expiresAt": "2026-11-30 23:59:59",
  "countryCode": "ES",
  "shopperLocale": "es-ES"
}

Obligatorios: webcode, amount, intervalUnit, intervalCount, returnUrl (http/https). description maximo 255 caracteres; metadata debe ser un objeto JSON.

{
  "success": true,
  "data": {
    "linkId": "SHOP01-LK-1792068995050",
    "environment": "live",
    "status": "pending",
    "paymentUrl": "https://aviratopayments.com/pay/eyJ0eXAi...",
    "subscriptionId": null,
    "amount": { "value": 2990, "currency": "EUR" },
    "initialAmount": { "value": 990, "currency": "EUR" },
    "intervalUnit": "month",
    "intervalCount": 1,
    "billingDay": 5,
    "endAt": "2027-06-30 23:59:59",
    "planCode": "GOLD",
    "returnUrl": "https://tu-web.com/pago-recurrente/ok",
    "expiresAt": "2026-11-30 23:59:59",
    "createdAt": "2026-10-15 14:56:35"
  }
}

Al terminar el pago el cliente vuelve a returnUrl con ?linkId=...&subscriptionId=...&status=success|refused|error. No te fies solo del redirect: confirma con el webhook o consultando el link.

Endpoints

Consultas

Ciclo de vida (body siempre con webcode)

Estados y acciones permitidas

Entorno Test

Todo funciona igual que en Live pero sin dinero real. Los pagos recurrentes de test no aparecen en el panel; consultalos con la API.

Pago inicial: abre paymentUrl (/pay-subscription-test/...) y usa cualquier tarjeta valida (p. ej. 4111 1111 1111 1111, fecha futura en formato MM/AA, CVC 737). El titular decide el resultado:

Simuladores (solo /external/v1/test/...), body { "webcode", "result" } con result: success (def.), declined, not_enough_balance, card_expired, error:

Webhooks

Eventos SUBSCRIPTION_CREATED, SUBSCRIPTION_RENEWED, SUBSCRIPTION_FAILED, SUBSCRIPTION_ERROR, SUBSCRIPTION_PAUSED, SUBSCRIPTION_REACTIVATED, SUBSCRIPTION_CANCELLED y SUBSCRIPTION_CARD_UPDATED. Formato y ejemplos en Webhooks.

Errores habituales

Ver Errores > Pagos recurrentes. Resumen: 400 validacion o accion no permitida en el estado actual, 403 key/webcode/entorno, 404 no existe para tu webcode y entorno, 409 Idempotency-Key reutilizada.