API Documentation

Alejo
Alejo
Last updated 

Authentication:

Nota: En Configuración, bajo Claves API puedes encontrar tus llaves públicas y privadas.

Para autenticarte con los endpoints, debes enviar los siguientes headers:

X-PUBLIC-KEY: <pk_Tu llave pública>
X-SECRET-KEY: <sk_Tu llave privada>

IMPORTANTE: Si estás haciendo llamadas desde el frontend, nunca utilices la llave privada.

Endpoints:


Checkouts:
[POST] Create a checkout
  • URL: https://app.recurrente.com/api/checkouts
  • Request:
    • { "items": [{ "price_id": "<priceId>" }] }
    • o en caso lo quieras asociar a un usuario ya existente:
    • { "items": [{ "price_id": "<priceId>" }], user_id: "<userId>" }
* El priceId lo puedes encontrar en la página de configurar producto dentro de tu cuenta de Recurrente.

[GET] Get a checkout

Subscriptions:
[GET] Get Subscription 

Users:
[POST] Create a User 

Products:
[POST] Create a product
  • URL: https://app.recurrente.com/api/products
  • Request:
    • Para un producto de cobro único:
      • { 
          "product": { 
            "name": "El nombre del producto",
            "description": "La descripción es opcional",
            "custom_terms_and_conditions": "Opcional",
            "phone_requirement": "required|optional|none",
            "address_requirement": "required|optional|none",
            "billing_info_requirement": "optional|none",
            "image_url": "https://picsum.photos/200",
            "cancel_url": "https://tu-website.com/pago-cancelado",
            "success_url": "https://tu-website.com/pago-exitoso",
            "adjustable_quantity": true|false,
            "prices_attributes": [
              { 
                "amount_as_decimal": "123.12", 
                "currency": "GTQ|USD", 
                "charge_type": "one_time" 
              }
            ]
          }
        }
    • Para un producto de cobro recurrente:
      • { 
          "product": { 
            "name": "El nombre del producto",
            "description": "La descripción es opcional",
            "custom_terms_and_conditions": "Opcional",
            "phone_requirement": "required|optional|none",
            "address_requirement": "required|optional|none",
            "billing_info_requirement": "optional|none",
            "image_url": "https://picsum.photos/200",
            "cancel_url": "https://tu-website.com/pago-cancelado",
            "success_url": "https://tu-website.com/pago-exitoso",
            "prices_attributes": [
              { 
                "amount_as_decimal": "123.12", 
                "currency": "GTQ|USD", 
                "charge_type": "recurring",
                "billing_interval_count": "1",
                "billing_interval": "week|month|year",
                "free_trial_interval_count": "1",
                "free_trial_interval": "week|month|year",
                "periods_before_automatic_cancellation": null,
                "periods_before_allowed_to_cancel": null,
              }
            ]
          }
        }
      • Para customizar métodos de pago
        • Debe ir incluido custom_payment_method_settings: true, de lo contrario, el producto regresa a utilizar los defaults de la cuenta.
        • Para no ofrecer cuotas, available_installments debe ser un empty array []
        • { 
            "product": { 
              "name": "El nombre del producto",
              "custom_payment_method_settings": "true|false",
              "card_payments_enabled": "true|false",
              "bank_transfer_payments_enabled": "true|false",
              "available_installments": [3, 6, 12, 18],
              "prices_attributes": [
                { 
                  "amount_as_decimal": "123.12", 
                  "currency": "GTQ|USD", 
                }
              ]
            }
          }
[GET] Get a product

Transfers:
[POST] Create a Transfer 
Nota: El recipient_id es el @ de la cuenta a la que quieres enviar dinero.
recipient_id 61.5 KB View full-size Download




Webhook Event Types


payment_intent.succeeded
Se emite con un cobro exitoso con tarjeta (crédito o débito). Los fondos ya están en tu balance de Recurrente.

Ejemplo de respuesta:
{
  "api_version": "2023-08-29",
  "checkout": {
    "id": "ch_id123"
  },
  "created_at": "2024-02-16T03:01:13.260Z",
  "customer": {
    "email": "hello@example.com",
    "full_name": "Max Rodriguez",
    "id": "us_id123"
  },
  "customer_id": "us_id123",
  "event_type": "payment_intent.succeeded",
  "id": "pa_id123",
  "payment": {
    "id": "pa_id123",
    "paymentable": {
      "id": "su_id123",
      "tax_id": null,
      "tax_name": null,
      "type": "Subscription"
    }
  },
  "product": {
    "id": "prod_id123"
  }
}

payment_intent.failed
Cobro fallido con tarjeta.

Ejemplo de respuesta:
{
  "api_version": "2023-08-29",
  "checkout": {
    "id": "ch_id123"
  },
  "created_at": "2024-02-09T01:00:57.242Z",
  "customer": {
    "email": "me@example.com",
    "full_name": "Max Example",
    "id": "us_id123"
  },
  "customer_id": "us_id123",
  "event_type": "payment_intent.failed",
  "failure_reason": "Tu banco ha rechazado la transacción. Llama a tu banco y pide que autoricen esta transacción.",
  "id": "pa_id123",
  "payment": {
    "id": "pa_id123",
    "paymentable": {
      "id": "su_id123",
      "tax_id": null,
      "tax_name": null,
      "type": "Subscription"
    }
  },
  "product": {
    "id": "prod_id123"
  }
}

subscription.create
Si el producto es recurrente, se emite además del payment.succeeded este evento con la información de la suscripción.

Ejemplo de respuesta:
{
  "api_version": "2023-08-29",
  "created_at": "2023-11-23T12:40:27.149-06:00",
  "customer_email": "me@example.com",
  "customer_id": "us_123",
  "customer_name": "Max Example",
  "event_type": "subscription.create",
  "id": "su_id123"
}

subscription.past_due
Se emite cuando el cobro automático de una suscripción falla por primera vez.

Nota: En una suscripción, cuando un pago falla, Recurrente intenta cobrarlo de nuevo 3 y 5 días después. Si ambos re-intentos son fallidos, en ese momento se cancela la suscripción.

Ejemplo de respuesta:
{
  "api_version": "2023-08-29",
  "created_at": "2023-10-30T16:46:21.208Z",
  "customer_email": "me@example.com",
  "customer_id": "us_j0v1i3tg",
  "customer_name": "Max Example",
  "event_type": "subscription.past_due",
  "id": "su_id123"
}

subscription.cancel
Se emite cuando el cobro automático de una suscripción falla por tercera vez.

Nota: En una suscripción, cuando un pago falla, Recurrente intenta cobrarlo de nuevo 3 y 5 días después. Si ambos re-intentos son fallidos, en ese momento se cancela la suscripción.

Ejemplo de respuesta:
{
  "api_version": "2023-08-29",
  "created_at": "2023-08-08T15:52:25.744-06:00",
  "customer_email": "me@example.com",
  "customer_id": "us_id123",
  "customer_name": "Max Example",
  "event_type": "subscription.cancel",
  "id": "su_id123"
}

bank_transfer_intent.pending
Se emite cuando se inicia un cobro con transferencia bancaria. En cuanto se reciba el dinero en la cuenta, se emitirá bank_transfer_intent.succeeded. De lo contrario, se emitirá bank_transfer_intent.failed.