Cobros Recurrentes

Introducción

Cobros Recurrentes con PixelPay facilita a los comercios enviar cobros a múltiples usuarios, con el fin de suscribirlos a un producto o servicio y automáticamente renovar los pagos de manera semanal, quincenal, mensual, trimestral, semestral o anual, según lo defina el comercio.

La funcionalidad en API se encuentra en versión BETA.

Requisitos

Necesitas asignar un usuario del comercio con los permisos para ver y crear cobros recurrentes.

El administrador del comercio debe activar la opción en el panel respectivo del usuario, de esa manera permitirá el acceso de manejar la herramienta de cobros recurrentes.

Crear un cobro recurrente

Ruta de envío de parámetros para crear un cobro recurrente

POST https://{endpoint}/api/v2/subscriptions

Índice de campos

Todos los campos deberán ser enviados como parámetros en la consulta https en formato Query String o incluir en el header tipo de formato content-type: x-www-form-urlencoded.

Campo Valor Validación Descripción
name Texto Requerido, min: 5, max: 80 Nombre del cobro recurrente
description Texto Opcional, min: 5, max: 120 Descripción para el cobro recurrente
type public o unique Requerido Tipo de cobro recurrente
recurrence weekly bimonthly monthly quarterly semiannual annual Requerido Periodo de recurrencia en que se ejecutará el cobro
currency HNL o USD Requerido Moneda en la cual se realizará el cobro
amount 0.00 Requerido, double Cantidad total del cobro en moneda
limit 1 Opcional, interger, min: 1, max: 100 Número de pagos necesarios para completar los cobros recurrentes del usuario
conversion true o false Opcional El monto se convertirá de Dólar a Lempira al realizar el pago
auto_cancel true o false Opcional Modalidad de cancelación
lang es o en Opcional Código de lenguaje que usará, por defecto es para español

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions

// DATOS ENVIADOS EN LA PETICIÓN "POST"
{
  "name": "Seguro médico",
  "description": "Este plan incluye cobertura médica completa para individuos y familias.",
  "type": "public",
  "recurrence": "monthly",
  "currency": "HNL",
  "amount": "1000.00",
  "conversion": "false",
  "auto_cancel": "false"
}

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "name": "Seguro médico",
    "description": "Este plan incluye cobertura médica completa para individuos y familias.",
    "type": "public",
    "recurrence": "monthly",
    "currency": "HNL",
    "amount": 10,
    "conversion": false,
    "auto_cancel": false,
    "merchant_id": 1,
    "lang": "es",
    "id": "1944c0b5-53d2-45d5-b330-bfa1ee6cac17",
    "updated_at": "2024-05-10T20:21:22.000000Z",
    "created_at": "2024-05-10T20:21:22.000000Z",
    "total": "10.00",
    "total_formatted": "L 10.00"
  }
}

Ejemplo de respuesta: Entidad no procesable

{
  "success": false,
  "message": "El campo recurrence debe ser igual a alguno de estos valores: weekly, bimonthly, monthly, quarterly, semiannual, annual.",
  "errors": {
    "recurrence": [
      "El campo recurrence debe ser igual a alguno de estos valores: weekly, bimonthly, monthly, quarterly, semiannual, annual."
    ]
  }
}

Obtener información de un Cobro Recurrente

Ruta de envío de parámetros para obtener infomación un cobro recurrente

GET https://{endpoint}/api/v2/subscriptions/{subscription_id}

Índice de campos

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}

// DATOS ENVIADOS EN LA PETICIÓN "GET"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "id": "1944c0b5-53d2-45d5-b330-bfa1ee6cac17",
    "merchant_id": 1,
    "name": "Seguro médico",
    "description": "Este plan incluye cobertura médica completa para individuos y familias.",
    "type": "public",
    "recurrence": "monthly",
    "limit": null,
    "is_enumerable": 0,
    "max_enumerable": null,
    "currency": "HNL",
    "amount": 10,
    "is_active": 1,
    "created_at": "2024-05-10T20:21:22.000000Z",
    "updated_at": "2024-05-10T20:21:22.000000Z",
    "deleted_at": null,
    "lang": "es",
    "auto_cancel": 0,
    "conversion": 0,
    "total": "10.00",
    "total_formatted": "L 10.00"
  }
}

Ejemplo de respuesta: Cobro recurrente no encontrado

{
  "success": false,
  "message": "No se encontró un cobro recurrente válido."
}

Actualizar un cobro recurrente

Por medio de este request podemos actualizar la información de un cobro recurrente utilizando los mismos campos que usamos al crearlo y en la URL de la petición el id del cobro recurrente que obtuvimos en la respuesta al crearlo. Los datos enviados serán reemplazados por los anteriores.

Ruta de envío de parámetros para actualizar un cobro recurrente

POST https://{endpoint}/api/v2/subscriptions/{subscription_id}

Índice de campos

En el request se envían los mismos campos como se muestra en el índice de campos al crear un cobro recurrente.

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}

// DATOS ENVIADOS EN LA PETICIÓN "POST"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17

{
  "name": "Seguro médico 24/7",
  "description": "Este plan incluye cobertura médica completa para familias.",
  "type": "public",
  "recurrence": "monthly",
  "currency": "HNL",
  "amount": "1000.00",
  "conversion": "false",
  "auto_cancel": "true"
}

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "El cobro recurrente se actualizó exitosamente.",
  "data": {
    "id": "1944c0b5-53d2-45d5-b330-bfa1ee6cac17",
    "merchant_id": 1,
    "name": "Seguro médico 24/7",
    "description": "Este plan incluye cobertura médica completa para familias.",
    "type": "public",
    "recurrence": "monthly",
    "limit": null,
    "is_enumerable": 0,
    "max_enumerable": null,
    "currency": "HNL",
    "amount": 10,
    "is_active": 1,
    "created_at": "2024-05-10T20:21:22.000000Z",
    "updated_at": "2024-05-11T03:49:24.000000Z",
    "deleted_at": null,
    "lang": "es",
    "auto_cancel": true,
    "conversion": 0,
    "total": "10.00",
    "total_formatted": "L 10.00"
  }
}

Ejemplo de respuesta: Cobro recurrente no encontrado

{
  "success": false,
  "message": "No se encontró un cobro recurrente válido."
}

Actualizar estado de un cobro recurrente

Por medio de este request podemos desactivar o activar un cobro recurrente.

Ruta de envío de parámetros para actualizar el estado de un cobro recurrente

POST https://{endpoint}/api/v2/subscriptions/{subscription_id}/activation

Índice de campos

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
activation_status activate o deactivate Requerido Nuevo estado del cobro recurrente

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/activation

// DATOS ENVIADOS EN LA PETICIÓN "POST"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/activation

{
  "activation_status": "deactivate"
}

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Se actualizó el estado del cobro recurrente."
}

Ejemplo de respuesta: Cobro recurrente no encontrado

{
  "success": false,
  "message": "No se encontró un cobro recurrente válido."
}

Suscribirse a un cobro recurrente

Por medio de este request, podrás inscribir a tus clientes de manera efectiva en el servicio de cobros recurrentes. En este proceso, se establecerá una suscripción activa que facilitará la gestión continua de los pagos, asegurando una experiencia fluida y sin interrupciones para todos.

En la respuesta exitosa, encontrarás el campo payment_url que contiene el enlace para suscribirse, el cuál debes compartir al usuario para que realice el flujo de pago por medio de nuestro Checkout.

Además, encontrás el campo customer que es el id del cliente suscrito al cobro recurrente, que necesitarás si deseas cancelar la suscripción o consultar su estado.

Ruta de envío de parámetros para suscribirse a un cobro recurrente

POST https://{endpoint}/api/v2/subscriptions/{subscription_id}/subscribe

Índice de campos

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
resubscribe true o false Opcional Es una nueva suscripción o resuscripción
subscription Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
customer_name Texto Requerido, min: 3, max: 160 Nombre completo del cliente
customer_email usuario@dominio.com Requerido, email, max: 180 Correo electrónico del cliente
pay_date yyyy/mm/dd hh:mm Opcional, date Fecha a ejecutarse el cobro

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/subscribe

// DATOS ENVIADOS EN LA PETICIÓN "POST"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/subscribe

{
  "resubscribe": "false",
  "subscription": "1944c0b5-53d2-45d5-b330-bfa1ee6cac17",
  "customer_name": "Juan Perez",
  "customer_email": "recurrentes@pixel.hn",
  "pay_date": "2024/05/15"
}

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Pago para aprobar cobro recurrente obtenido exitosamente.",
  "data": {
    "payment": {
      "ref": "SUB-0001-1715804970",
      "uuid": "P-e0a1cd9d-ad91-44ad-ae26-a62cb6ba786d",
      "status": "temp",
      "description": "Cobro Recurrente #0001 - Seguro médico 24/7",
      "note": null,
      "category": "subscription",
      "currency": "HNL",
      "tax_amount": 0,
      "amount": 10,
      "items": [
        {
          "title": "Seguro médico 24/7",
          "tax": 0,
          "qty": 1,
          "price": 10,
          "total": 10
        }
      ],
      "customer_name": "Juan Perez",
      "customer_email": "recurrentes@pixel.hn",
      "customer_phone": null,
      "client_ip": null,
      "client_device": null,
      "order": "SUB-0001-1715804970",
      "payment_hash": "fd8fc11e48728350c3bba5d724b78634",
      "created_at": "2024-05-15 08:05:30",
      "company_name": "PixelPay SA de CV",
      "company_slug": "pixel",
      "company_key": "2212294583",
      "is_overdue": false,
      "payment_url": "https://pixel-pay.com/pixel/P-e0a1cd9d-ad91-44ad-ae26-a62cb6ba786d/checkout",
      "attach_url": null,
      "extra": null
    },
    "content": [
      {
        "title": "Seguro médico 24/7",
        "tax": 0,
        "qty": 1,
        "price": 10,
        "total": 10
      }
    ],
    "properties": {
      "subscription": {
        "customer": "c5ad6aec-3776-49b1-a957-88f00cb94f7e",
        "approval": true
      },
      "hook": {
        "type": "subscription",
        "order": "SUB-0001-1715804970",
        "complete": "https://pixel-pay.com/pixel/subscription/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/c5ad6aec-3776-49b1-a957-88f00cb94f7e"
      }
    },
    "signature": "e60c4f81fa8acaf2a85c9f9917c6e65f43b1a27cc3dd5a8c32d8fa729c6e057e7478714f1d3d90e68bd0e93c2261502e201e9d17c14dfcc12fdbd988cd601f3b"
  }
}

Ejemplo de respuesta: Cobro recurrente no encontrado

{
  "success": false,
  "message": "El campo subscription no existe.",
  "errors": {
    "subscription": [
      "El campo subscription no existe."
    ]
  }
}

Obtener datos de clientes suscritos

Ruta de envío de parámetros para obtener infomación un cliente suscrito al cobro recurrente

GET https://{endpoint}/api/v2/subscriptions/{subscription_id}/{customer_subscription_id}

Índice de campos

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
customer_subscription_id Alfanumérico Requerido Es el id que se obtuvo al suscribir el usuario al cobro recurrente

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/{customer_subscription_id}

// DATOS ENVIADOS EN LA PETICIÓN "GET"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/customer/c5ad6aec-3776-49b1-a957-88f00cb94f7e

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Información obtenida con exito",
  "data": {
    "id": "c5ad6aec-3776-49b1-a957-88f00cb94f7e",
    "subscription_id": "1944c0b5-53d2-45d5-b330-bfa1ee6cac17",
    "customer_name": "Juan Perez",
    "customer_email": "recurrentes@pixel.hn",
    "status": "pending",
    "quantity": 1,
    "paid_count": 0,
    "failed_count": 0,
    "wants_to_cancel": 0,
    "extra": null,
    "pay_date": null,
    "last_failed_at": null,
    "created_at": "2024-05-15T20:29:30.000000Z",
    "updated_at": "2024-05-15T20:29:30.000000Z",
    "deleted_at": null,
    "confirm_cancellation": 0,
    "cancel_token": "Ix6SadKUzXqPEdtAqDcbSnGLjARG0ttSo3oOU7Fihiqn2YkPUML85qTWrB3x",
    "cancel_reason": null,
    "total": "10.00",
    "total_formatted": "L 10.00"
  }
}

Ejemplo de respuesta: Cobro recurrente o cliente no encontrado

{
  "success": false,
  "message": "No se encontró un cobro recurrente de cliente válido."
}

Cancelar suscripción a Cobro Recurrente

Por medio de este request, podrás cancelar la suscripción de un usuario a un cobro recurrente activo.

Ruta de envío de parámetros para cancelar la suscripción a un cobro recurrente

POST https://{endpoint}/api/v2/subscriptions/{subscription_id}/{customer_subscription_id}/cancel

Índice de campos

Campo Valor Validación Descripción
subscription_id Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
customer_subscription_id Alfanumérico Requerido Es el id que se obtuvo al suscribir el usuario al cobro recurrente
resubscribe true o false Opcional Es una nueva suscripción o resuscripción
subscription Alfanumérico Requerido Es el id que se obtuvo al crear el cobro recurrente
customer_name Texto Requerido, min: 3, max: 160 Nombre completo del cliente
customer_email usuario@dominio.com Requerido, email, max: 180 Correo electrónico del cliente
pay_date yyyy/mm/dd hh:mm Opcional, date Fecha a ejecutarse el cobro

Ejemplo del request

// RUTA DE LA PETICIÓN
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/subscribe

// DATOS ENVIADOS EN LA PETICIÓN "POST"
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/subscribe

Ejemplo de respuesta exitosa

{
  "success": true,
  "message": "Se canceló el cobro recurrente exitosamente."
}

Ejemplo de respuesta: Cobro recurrente no encontrado

{
  "success": false,
  "message": "No se encontró un cobro recurrente de cliente válido."
}

Ejemplo de respuesta: Cobro recurrente con estado incorrecto

{
  "success": false,
  "message": "El estado del cobro recurrente debe ser active, obtuvo pending."
}

Webhooks

A través de Webhooks es posible controlar eventos importantes en los cobros recurrentes de tus usuarios, y automatizar flujos de trabajo en tu sistema.

Si la configuración del comercio tiene webhooks habilitados, al momento de que un usuario realice un pago exitoso por medio del servicio de cobros recurrentes, tu sistema recibirá el siguiente evento en forma de una petición HTTP POST:

{
  "ref": "SUB-0001-1738165805",
  "uuid": "P-e48fa3e0-ddc9-43a4-ppk0-e602dkje473b",
  "status": "paid",
  "description": "Cobro Recurrente #0001 - Nombre del Producto",
  "note": null,
  "category": "subscription",
  "currency": "HNL",
  "tax_amount": 0,
  "amount": 100,
  "items": [
    {
      "title": "Nombre del Producto",
      "tax": 0,
      "qty": 1,
      "price": 100,
      "total": 100
    }
  ],
  "customer_name": "JANE DOE",
  "customer_email": "janedoe@gmail.com",
  "customer_phone": null,
  "client_ip": null,
  "client_device": "mac",
  "order": "SUB-0001-1738165805",
  "payment_hash": "8d583942de78ec329ca902eac50fd7c7",
  "created_at": "2025-01-29 09:01:05",
  "paid_at": "2025-01-29 09:01:30",
  "transaction_id": "7381660699936710503813",
  "card_account": "400000 \u2022\u2022\u2022\u2022\u2022\u2022 1000",
  "card_brand": "visa",
  "card_type": "CREDIT",
  "card_issuer": "INTL HDQTRS-CENTER OWNED",
  "authorization_id": "831000",
  "customer_subscription": {
    "id": "7cb70c1c-9a71-4476-91f1-415fa98d53ac",
    "customer_name": "JANE DOE",
    "customer_email": "janedoe@gmail.com",
    "status": "active",
    "total": "L 100.00",
    "subscription": {
      "id": "f038d283-9038-4cd1-c919-95866f22b688",
      "type": "public",
      "recurrence": "monthly",
      "name": "Nombre del Producto",
      "description": "Producto de Cobros Recurrentes del comercio",
      "currency": "HNL",
      "amount": 1
    }
  },
  "company_name": "TU COMERCIO SA DE CV",
  "company_slug": "tu-comercio",
  "company_key": "2298293471",
  "is_overdue": false,
  "payment_url": "https:\/\/pixel-pay.com\/tu-comercio\/P-e48fa3e0-ddc9-43a4-ppk0-e602dkje473b\/checkout",
  "attach_url": null,
  "extra": null
}

Adicionalmente, cuando un cobro recurrente cambia de estado, tu sistema recibirá el siguiente evento en forma de una petición HTTP POST:

{
  "type": "subscription",
  "payload": {
    "id": "7cb70c1c-9a71-4476-91f1-415fa98d53ac",
    "customer_name": "JANE DOE",
    "customer_email": "janedoe@gmail.com",
    "status": "active",
    "total": "L 100.00",
    "subscription": {
      "id": "f038d283-9038-4cd1-c919-95866f22b688",
      "type": "public",
      "recurrence": "monthly",
      "name": "Nombre del Producto",
      "description": "Producto de Cobros Recurrentes del comercio",
      "currency": "HNL",
      "amount": 1
    }
  }
}

Estados posibles para un cobro recurrente

Estado Descripción
pending Fue creado y está pendiente de que el usuario complete el pago inicial
active Ha sido pagado y estará realizando cobros automáticos según el periodo de recurrencia
failed El último cobro automático fallo, se harán múltiples reintentos cada 24 horas hasta llegar a un límite
on_hold Se hicieron múltiples reintentos de pago sin éxito, no se volverán a hacer cobros automáticos hasta que el usuario reintente manualmente o cambie su tarjeta
cancelled El usuario o el comercio cancelo el cobro recurrente y no se volverán a hacer cobros automáticos
finalized Se llegó al límite de pagos exitosos necesarios para completar la recurrencia, no se volverán a hacer cobros automáticos