API Documentation

Alejo

Last updated Feb 18, 2024

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

URL: https://app.recurrente.com/api/checkouts/{checkout_id}

Subscriptions:

[GET] Get Subscription

URL: https://app.recurrente.com/api/subscriptions/{subscription_id}

Users:
[POST] Create a User

URL: https://app.recurrente.com/api/users

Request:

{ "email": "string", "full_name": "string" }

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

URL: https://app.recurrente.com/api/products/{product_id}

Transfers:
[POST] Create a Transfer

URL: https://app.recurrente.com/api/transfers

Request:

{ 
  "currency": "GTQ|USD", 
  "amount_in_cents": 100, 
  recipient_id: "example"
}

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.