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:
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
[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
- 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", } ] } }
- Para un producto de cobro único:
[GET] Get a product
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.
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:
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:
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:
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:
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:
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.