Subscriptions

Introduction

Recurring Payments with PixelPay makes it easy for merchants to send payments to multiple users, in order to subscribe them to a product or service and automatically renew payments on a weekly, bi-weekly, monthly, quarterly, semi-annual or semiannual, as defined by the merchant.

API functionality is in BETA version.

Requirements

You need to assign a merchant user with the permissions to Create recurring payments.

The merchant's administrator must activate the option in the user's respective panel, thus allowing access to manage the recurring payments tool.

Create a subscription

Route to send parameters for create a subscription

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

Field Index

All fields must be sent as parameters in the https query in Query String format or include content-type: x-www-form-urlencoded in the header.

Field Value Validation Description
name Short text Required, min: 5, max: 80 Name of subscription
description Short text Optional, min: 5, max: 120 Subscription description
type public or unique Required Subscription type:
- public: any user with the link can join the recurring payment.
- unique: only a user defined by the merchant can join.
recurrence weekly bimonthly monthly quarterly semiannual annual Required The length of time it will take for the recurring payment to be repeated
currency HNL or USD Required Currency in which the payment will be made
amount 0.00 Required, double Total amount of the charge in currency
limit 1 Optional, interger, min: 1, max: 100 Number of payments needed to complete the user's recurring payments
conversion true or false Optional The amount will be converted from Dollar to Lempira at the time of payment
auto_cancel true or false Optional Cancellation method:
- true: cancellation by the customer.
- false: ccancellation by the merchant.
lang es or en Optional Language code to be used, by default es for Spanish

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions

// DATA SENT IN "POST" REQUEST
{
  "name": "Medical insurance",
  "description": "This plan includes full medical coverage for individuals and families.",
  "type": "public",
  "recurrence": "monthly",
  "currency": "HNL",
  "amount": "1000.00",
  "conversion": "false",
  "auto_cancel": "false"
}

Succesful Response Example

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

Example response: Non-processable entity

{
  "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."
    ]
  }
}

Get Subscription Information

Route to send parameters fto get subscription information

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

Field Index

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}

// DATA SENT IN "GET" REQUEST
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17

Succesful Response Example

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

Example response: Subscription not found

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

Update a subscription

Using this request, we can update a subscription's information using the same fields we used when creating it, and in the request URL, the subscription ID we obtained in the response when creating it. The data sent will be replaced with the previous data.

Route to send parameters for update a subscription

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

Field Index

In the request the same fields are sent as shown in the index of fields when creating a subscription.

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}

// DATA SENT IN "POST" REQUEST
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17

{
  "name": "24/7 health insurance",
  "description": "This plan includes comprehensive medical coverage for families.",
  "type": "public",
  "recurrence": "monthly",
  "currency": "HNL",
  "amount": "1000.00",
  "conversion": "false",
  "auto_cancel": "true"
}

Succesful Response Example

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

Example response: Subscription not found

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

Update subscription status

Through this request we can deactivate or activate a subscription

Route to send parameters for update a subscription

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

Field Index

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription
activation_status activate or deactivate Required New subscription status:
- activate: activate recurring payment, all automatic payments will resume.
- deactivate: deactivate recurring payment, all automatic payments will stop being charged.

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/activation

// DATA SENT IN "POST" REQUEST
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/activation

{
  "activation_status": "deactivate"
}

Succesful Response Example

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

Example response: Subscription not found

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

Subscribe to a recurring payment

Through this request, you will be able to effectively enroll your customers in the recurring payment service. In this process, an active subscription will be established that will facilitate the ongoing management of payments, ensuring a smooth and seamless experience for everyone.

In the successful response, you will find the payment_url field containing the link to subscribe, which you must share to the user to make the payment flow through our Checkout.

Additionally, you will find the customer field which is the id of the customer subscribed to the recurring payment, which you will need if you want to cancel the subscription or check its status.

Route to send parameters to subscribe to a recurring payment

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

Field Index

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription
resubscribe true or false Optional Indicates if the user can subscribe more than once:
- true: allows a user already subscribed to recurring payment to join again.
- false: the user can only subscribe once.
subscription Alphanumeric Required This is the id obtained when creating the subscription
customer_name Text Required, min: 3, max: 160 Customer's full name
customer_email user@domain.com Required, email, max: 180 Customer's e-mail address
pay_date yyyy/mm/dd hh:mm Optional, date Date to be charged
redirect https://mywebsite.com Optional, URL Redirection URL on successful subscription

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/subscribe

// DATA SENT IN "POST" REQUEST
// 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"
}

Succesful Response Example

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

Example response: Subscription not found

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

Get subscribed customer data

Route to send parameters to get information form a customer subscribed to the recurring payment

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

Field Index

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription
customer_subscription_id Alphanumeric Required This is the id that was obtained when the customer subscribed to the recurring payment

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/customer/{customer_subscription_id}

// DATA SENT IN "GET" REQUEST
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/customer/c5ad6aec-3776-49b1-a957-88f00cb94f7e

Succesful Response Example

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

Example response: Subscription or customer not found

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

Cancel subscription to Recurring payment

Through this request, you will be able to unsubscribe a customer from an active recurring charge.

Route to send parameters to cancel the subscription from a recurring payment

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

Field Index

Field Value Validation Description
subscription_id Alphanumeric Required This is the id obtained when creating the subscription
customer_subscription_id Alphanumeric Required This is the id that was obtained when the customer subscribed to the recurring payment

Request Example

// REQUEST ROUTE
// https://pixel-pay.com/api/v2/subscriptions/{subscription_id}/{customer_subscription_id}/cancel

// DATA SENT IN "POST" REQUEST
// https://pixel-pay.com/api/v2/subscriptions/1944c0b5-53d2-45d5-b330-bfa1ee6cac17/c5ad6aec-3776-49b1-a957-88f00cb94f7e/cancel

Succesful Response Example

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

Example response: Subscription not found

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

Example response: Subscription with incorrect status

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

Webhooks

Webhooks allow you to monitor important events in your customers' recurring payments and automate workflows in your system.

If the merchant configuration has webhooks enabled, when a user makes a successful payment using the subscriptions service, your system will receive the following event in the form of an HTTP POST request:

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

Additionally, when a subscription changes status, your system will receive the following event in the form of an HTTP POST request:

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

Possible states for subscription

State Description
pending It was created and is pending the customer's initial payment.
active It has been paid and will be automatically charged according to the recurrence period.
failed Last automatic charge failed, multiple retries will be made every 24 hours until a limit is reached
on_hold Multiple unsuccessful payment retries were made, automatic charges will not be reinstated until the user manually retries or changes their card
cancelled The user or the merchant canceled the subscription and automatic payments will no longer be made.
finalized The limit of successful payments required to complete the recurrence has been reached, automatic charges will no longer be made