Crear una suscripción

En Rekurra, una suscripción se crea con el checkout hospedado: una página de pago alojada por Rekurra que tokeniza la tarjeta sobre tu cuenta de Wompi y crea el Customer, el PaymentMethod y la Subscription en un solo flujo. No necesitas construir tu propio formulario de pago.

Así es como se crean las suscripciones en Rekurra: creas una checkout session, rediriges a tu cliente y Rekurra hace el resto. Ver el objeto y sus estados en el concepto Checkout.

Antes de empezar necesitas un plan y tu cuenta de Wompi conectada. ¿Prefieres probar en tu cliente de API? Descarga la colección de Postman.

Crea la sesión de checkout

POST /v1/checkout-sessions

Campo	Tipo	Requerido	Descripción
`plan_id`	string	Sí	Plan que se le cobrará al cliente. Créalo primero (ver Crear un plan).
`cycle`	string	Sí	Ciclo de cobro: `monthly` o `annual`.
`customer`	object	Sí*	Datos del cliente nuevo: `email` (requerido) y `name` (opcional).
`customer_id`	string	Sí*	ID de un cliente existente, en lugar de `customer`.
`success_url`	string	No	URL a la que Rekurra redirige tras el pago. Si la omites, el checkout muestra su propia pantalla de confirmación.
`cancel_url`	string	No	URL a la que se redirige si el cliente abandona o la sesión expira.
`metadata`	object	No	Pares clave-valor propios que quieras adjuntar a la sesión.

* Envía customer (cliente nuevo) o customer_id (cliente existente), no ambos.

Opción A — Cliente nuevo (`customer`)

Rekurra crea el cliente sobre la marcha con el objeto customer. Úsalo cuando la persona aún no existe en Rekurra.

curl -X POST https://api.rekurra.dev/v1/checkout-sessions \
  -H "Authorization: Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_01HZ...",
    "cycle": "monthly",
    "customer": { "email": "cliente@ejemplo.com", "name": "María Pérez" },
    "success_url": "https://tuapp.com/gracias",
    "cancel_url": "https://tuapp.com/checkout",
    "metadata": { "origen": "landing" }
  }'

const res = await fetch("https://api.rekurra.dev/v1/checkout-sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_id: "plan_01HZ...",
    cycle: "monthly",
    customer: { email: "cliente@ejemplo.com", name: "María Pérez" },
    success_url: "https://tuapp.com/gracias",
    cancel_url: "https://tuapp.com/checkout",
  }),
});
const { id, url } = await res.json();

import requests
 
res = requests.post(
    "https://api.rekurra.dev/v1/checkout-sessions",
    headers={
        "Authorization": "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={
        "plan_id": "plan_01HZ...",
        "cycle": "monthly",
        "customer": {"email": "cliente@ejemplo.com", "name": "María Pérez"},
        "success_url": "https://tuapp.com/gracias",
        "cancel_url": "https://tuapp.com/checkout",
    },
)
session = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "plan_id": "plan_01HZ...",
      "cycle": "monthly",
      "customer": { "email": "cliente@ejemplo.com", "name": "María Pérez" },
      "success_url": "https://tuapp.com/gracias",
      "cancel_url": "https://tuapp.com/checkout"
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/checkout-sessions"))
    .header("Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Text;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add(
    "Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var json = """
    {
      "plan_id": "plan_01HZ...",
      "cycle": "monthly",
      "customer": { "email": "cliente@ejemplo.com", "name": "María Pérez" },
      "success_url": "https://tuapp.com/gracias",
      "cancel_url": "https://tuapp.com/checkout"
    }
    """;
 
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await http.PostAsync(
    "https://api.rekurra.dev/v1/checkout-sessions", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Opción B — Cliente existente (`customer_id`)

Si el cliente ya existe en Rekurra (por ejemplo, porque le creaste un Customer antes o ya tuvo otra suscripción), reemplaza el objeto customer por su customer_id. Todo lo demás es idéntico.

curl -X POST https://api.rekurra.dev/v1/checkout-sessions \
  -H "Authorization: Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_01HZ...",
    "cycle": "monthly",
    "customer_id": "cus_01HZ...",
    "success_url": "https://tuapp.com/gracias",
    "cancel_url": "https://tuapp.com/checkout"
  }'

const res = await fetch("https://api.rekurra.dev/v1/checkout-sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan_id: "plan_01HZ...",
    cycle: "monthly",
    customer_id: "cus_01HZ...",
    success_url: "https://tuapp.com/gracias",
    cancel_url: "https://tuapp.com/checkout",
  }),
});
const { id, url } = await res.json();

import requests
 
res = requests.post(
    "https://api.rekurra.dev/v1/checkout-sessions",
    headers={
        "Authorization": "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX",
        "Content-Type": "application/json",
    },
    json={
        "plan_id": "plan_01HZ...",
        "cycle": "monthly",
        "customer_id": "cus_01HZ...",
        "success_url": "https://tuapp.com/gracias",
        "cancel_url": "https://tuapp.com/checkout",
    },
)
session = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
String body = """
    {
      "plan_id": "plan_01HZ...",
      "cycle": "monthly",
      "customer_id": "cus_01HZ...",
      "success_url": "https://tuapp.com/gracias",
      "cancel_url": "https://tuapp.com/checkout"
    }
    """;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/checkout-sessions"))
    .header("Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Text;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add(
    "Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var json = """
    {
      "plan_id": "plan_01HZ...",
      "cycle": "monthly",
      "customer_id": "cus_01HZ...",
      "success_url": "https://tuapp.com/gracias",
      "cancel_url": "https://tuapp.com/checkout"
    }
    """;
 
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await http.PostAsync(
    "https://api.rekurra.dev/v1/checkout-sessions", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

En ambos casos la respuesta trae el id de la sesión y la url hospedada a la que enviarás al cliente:

201 Created

{
  "id": "cs_01HZXK7QJ5M8Z9X2R3TVQ7A1B2",
  "url": "https://checkout.rekurra.dev/cs_01HZXK7QJ5M8Z9X2R3TVQ7A1B2"
}

Redirige a tu cliente

Envía a tu cliente a la url devuelta (por ejemplo, window.location.href = url). Ahí Wompi tokeniza su tarjeta usando la configuración de tu cuenta.

Recibe el resultado

Si enviaste success_url, Rekurra redirige ahí al completar el pago (o a cancel_url si el cliente abandona o la sesión expira), añadiendo como query params subscription_id, status, amount_in_cents y currency. Por seguridad, los datos personales del cliente (correo, tarjeta) no se añaden a la URL — consúltalos por subscription_id (ver API → Customers o el webhook).

Si omitiste success_url, no hay redirección: el checkout hospedado muestra su propia pantalla de confirmación con el resumen de la transacción (plan, monto, tarjeta, correo, estado).

⚠️

En paralelo, Rekurra dispara el webhook subscription.created (ver Webhooks). Usa el webhook —no solo la redirección ni la pantalla de confirmación— como fuente de verdad del resultado.

Consulta el estado si lo necesitas

GET /v1/checkout-sessions/{id} devuelve el status de la sesión (open · complete · expired) y, una vez completada, el subscription_id.

¿No te llegó el webhook subscription.created? Consulta el resultado con GET /v1/checkout-sessions/{id}/status — una superficie ligera con un límite dedicado de 20 solicitudes por minuto por API key para hacer polling tras el checkout. Ver API → Checkout sessions.

curl https://api.rekurra.dev/v1/checkout-sessions/cs_01HZ... \
  -H "Authorization: Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX"

const res = await fetch(
  "https://api.rekurra.dev/v1/checkout-sessions/cs_01HZ...",
  { headers: { Authorization: "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX" } }
);
const session = await res.json();

import requests
 
res = requests.get(
    "https://api.rekurra.dev/v1/checkout-sessions/cs_01HZ...",
    headers={"Authorization": "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX"},
)
session = res.json()

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.rekurra.dev/v1/checkout-sessions/cs_01HZ..."))
    .header("Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX")
    .GET()
    .build();
 
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
 
using var http = new HttpClient();
http.DefaultRequestHeaders.Add(
    "Authorization", "Bearer rk_test_XXXXXXXXXXXXXXXXXXXXXXXX");
 
var response = await http.GetAsync(
    "https://api.rekurra.dev/v1/checkout-sessions/cs_01HZ...");
Console.WriteLine(await response.Content.ReadAsStringAsync());

Siguiente paso

Gestiona la suscripción creada (cancelar, pausar, cambiar de plan) desde API → Subscriptions.
Deja que tu cliente administre su propia suscripción con el Portal de cliente.

Ver el detalle completo de la API en API → Checkout sessions.

Crear un plan Portal de cliente