Cuentas Conectadas

Si estás construyendo una plataforma o un marketplace, y quieres:

• Cobrar en nombre de alguien más, o
• Compartir los ingresos de las ventas con otras cuentas

La funcionalidad de Cuentas Conectadas es para ti.

Con Cuentas Conectadas puedes realizar cobros en nombre de otras cuentas utilizando tus propias Llaves API, sin necesidad de acceder ni utilizar las llaves API de esas cuentas.

Dos formas de conectar cuentas

Puedes trabajar con Cuentas Conectadas de dos formas:

1. Crear y administrar una cuenta conectada nueva desde tu plataforma. Este es el flujo recomendado cuando tu plataforma hace el onboarding del comercio, administra sus datos y configura su cuenta bancaria.
2. Conectar una cuenta de Recurrente existente. Este flujo sirve cuando el comercio ya usa Recurrente y solo quiere autorizar a tu plataforma para cobrar en su nombre.

Ambos caminos terminan con una cuenta hija conectada a tu cuenta. En los dos casos, usarás el ID de esa cuenta hija en account_id cuando crees checkouts.

Crear y conectar una cuenta por API

Puedes crear una cuenta conectada administrada por tu plataforma con POST /api/connected_accounts. Recurrente crea la cuenta hija, la conecta a tu cuenta, valida los documentos requeridos y marca el onboarding como completado.

Si ya existe una cuenta conectada para el mismo email, Recurrente reutiliza esa cuenta y actualiza los datos enviados. El tax_id y tax_name se extraen automáticamente del RTU enviado en verification[tax_registration_document]; no necesitas enviarlos en el request.

Documentos requeridos

Cada tipo de cuenta requiere distintos archivos en verification:

Ejemplo: cuenta individual

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -F "email=ana@example.com" \
>
  -F "full_name=Ana Perez" \
>
  -F "phone_number=+50255555555" \
>
  -F "name=Ana Perez" \
>
  -F "account_type=individual" \
>
  -F "withdrawals_schedule=daily" \
>
  -F "verification[tax_registration_document]=@/ruta/ana-rtu.pdf" \
>
  -F "verification[id_card_image]=@/ruta/ana-dpi-frente.jpg" \
>
  -F "verification[id_card_image_back]=@/ruta/ana-dpi-reverso.jpg"

Ejemplo: cuenta de empresa

Puedes enviar bank_account en el mismo request para configurar la cuenta bancaria externa que recibirá retiros. Usa GET /api/banks para ver los valores válidos de bank_name.

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -F "email=owner@restaurant.example" \
>
  -F "full_name=Ana Perez" \
>
  -F "phone_number=+50255555555" \
>
  -F "name=Acme Restaurant" \
>
  -F "account_type=business" \
>
  -F "withdrawals_schedule=daily" \
>
  -F "verification[tax_registration_document]=@/ruta/acme-rtu.pdf" \
>
  -F "verification[company_patent]=@/ruta/patente-sociedad.pdf" \
>
  -F "verification[commercial_patent]=@/ruta/patente-comercio.pdf" \
>
  -F "verification[company_representative_document]=@/ruta/representacion-legal.pdf" \
>
  -F "verification[company_representative_id]=@/ruta/representante-dpi-frente.jpg" \
>
  -F "verification[company_representative_id_back]=@/ruta/representante-dpi-reverso.jpg" \
>
  -F "bank_account[holder_name]=Acme Restaurant, S.A." \
>
  -F "bank_account[number]=1234567890" \
>
  -F "bank_account[bank_name]=Banco Industrial" \
>
  -F "bank_account[currency]=GTQ" \
>
  -F "bank_account[account_type]=checking" \
>
  -F "bank_account[is_preferred]=true"

Ejemplo: organización sin fines de lucro

$
curl -X POST https://app.recurrente.com/api/connected_accounts \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -F "email=admin@fundacion.example" \
>
  -F "full_name=Luis Garcia" \
>
  -F "phone_number=+50255555556" \
>
  -F "name=Fundacion Ejemplo" \
>
  -F "account_type=non_profit" \
>
  -F "withdrawals_schedule=weekly" \
>
  -F "verification[tax_registration_document]=@/ruta/fundacion-rtu.pdf" \
>
  -F "verification[articles_of_incorporation]=@/ruta/acta-constitutiva.pdf" \
>
  -F "verification[company_representative_document]=@/ruta/representacion-legal.pdf" \
>
  -F "verification[company_representative_id]=@/ruta/representante-dpi-frente.jpg" \
>
  -F "verification[company_representative_id_back]=@/ruta/representante-dpi-reverso.jpg"

Actualizar una cuenta conectada

Puedes actualizar el nombre público y la frecuencia de retiros de una cuenta conectada:

$
curl -X PATCH https://app.recurrente.com/api/connected_accounts/ac_123456 \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Acme Restaurant Zona 10",
>
    "withdrawals_schedule": "weekly"
>
  }'

Administrar cuentas bancarias

Para agregar otra cuenta bancaria externa a una cuenta conectada:

$
curl -X POST https://app.recurrente.com/api/connected_accounts/ac_123456/bank_accounts \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "holder_name": "Acme Restaurant, S.A.",
>
    "number": "1234567890",
>
    "bank_name": "Banco Industrial",
>
    "currency": "GTQ",
>
    "account_type": "checking",
>
    "is_preferred": true
>
  }'

Para cambiar la cuenta bancaria predeterminada, actualiza la cuenta bancaria deseada con is_preferred: true:

$
curl -X PATCH https://app.recurrente.com/api/connected_accounts/ac_123456/bank_accounts/ba_123456 \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "is_preferred": true }'

Para remover una cuenta bancaria, usa DELETE. Recurrente la archiva y deja de mostrarla en la API.

Conectar una cuenta existente

Si el comercio ya tiene una cuenta de Recurrente, no necesitas crear otra cuenta por API. Conecta las dos cuentas desde el UI de Recurrente siguiendo las instrucciones aquí.

Crear un checkout para una cuenta conectada

Una vez conectadas las cuentas, crea checkouts en nombre de la cuenta hija usando el parámetro account_id:

$
curl -X POST https://app.recurrente.com/api/checkouts \
>
  -H "X-SECRET-KEY: tu_llave_secreta" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "items": [
>
      {
>
        "currency": "GTQ",
>
        "amount_in_cents": 3000,
>
        "name": "Producto ejemplo"
>
      }
>
    ],
>
    "account_id": "ac_123456"
>
  }'

Distribución de fondos

Puedes distribuir los fondos entre cuentas usando transfer_setups. Cada elemento define una transferencia que Recurrente ejecuta automáticamente cuando el cobro se completa exitosamente:

• recipient_id es el ID de la cuenta de Recurrente que recibe los fondos (ej. ac_789012) — no es una cuenta bancaria. Los fondos se acreditan al balance de Recurrente de esa cuenta, y de ahí siguen su flujo normal de retiros.
• Si omites recipient_id, los fondos se transfieren a tu propia cuenta — útil para quedarte con una comisión cuando el checkout se crea a nombre de una cuenta conectada.
• Usa purpose: "platform_commission" cuando esa transferencia sea una comisión que la cuenta hija paga a tu plataforma. Si omites purpose, Recurrente usa fund_split y no la incluye en facturación de comisiones.
• En pagos únicos envía amount_in_cents: un monto fijo que se transfiere una sola vez. Puede llegar hasta el monto neto disponible después de fees, FEL e IVA.
• En suscripciones envía amount_percent: un porcentaje del total de cada factura (0–100, hasta 2 decimales), que se transfiere en cada cobro exitoso mientras la suscripción esté activa. Al crear el checkout validamos que el porcentaje quepa en el monto neto después de fees, FEL e IVA. Si la suscripción se cancela, las transferencias recurrentes se cancelan con ella.

1
{
2
  "items": [
3
    {
4
      "currency": "GTQ",
5
      "amount_in_cents": 3000,
6
      "name": "Producto ejemplo"
7
    }
8
  ],
9
  "account_id": "ac_123456",
10
  "transfer_setups": [
11
    {
12
      "amount_in_cents": 100,
13
      "recipient_id": "ac_789012",
14
      "purpose": "platform_commission"
15
    }
16
  ]
17
}

Facturación diaria de comisiones

Puedes pedir que Recurrente emita un DTE diario por moneda para las transferencias marcadas como platform_commission que cada cuenta conectada paga a tu plataforma. Tu plataforma tiene una configuración general (daily o none) y cada conexión puede reemplazarla. Solo cubre transferencias live completadas después de enabled_at; no clasifica ni factura transferencias históricas.

Para habilitarla, usa una API key live. Tu plataforma debe tener INFILE/FEL listo y la cuenta conectada debe tener NIT y nombre fiscal verificados:

$
curl -X PUT https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoicing \
>
  -H "X-SECRET-KEY: tu_llave_live" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "mode": "daily" }'

Recurrente procesa días cerrados en America/Guatemala de forma asíncrona. Cada documento suma exactamente las comisiones completadas de un día y moneda; no vuelve a mover el principal. Puedes consultar los documentos y reconciliar cada línea con su transferencia:

$
curl https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoices \
>
  -H "X-SECRET-KEY: tu_llave_live"
$
$
curl https://app.recurrente.com/api/connected_accounts/ac_123456/commission_invoices/pci_ab12cd34 \
>
  -H "X-SECRET-KEY: tu_llave_live"

El detalle expone transfer_setup_id, transfer_id, source_id, source_type y completed_at. Los webhooks partner_commission_invoice.issued y partner_commission_invoice.failed indican el resultado; failed solo se envía cuando ya no corresponde otro reintento automático.

Enviar { "mode": "none" } define un override que cierra el intervalo. Enviar { "mode": "default" } elimina el override y vuelve a heredar la configuración general. Recurrente todavía drena las comisiones completadas antes de disabled_at, y conserva todos los documentos y líneas existentes. La plataforma emisora puede seguir consultando ese historial aun después de desconectar la cuenta; la configuración sí requiere una conexión activa.

Webhooks

Cuando una cuenta hija se conecta a tu cuenta, Recurrente envía un webhook account_connection.create a tu cuenta. El payload incluye la conexión y las dos cuentas:

1
{
2
  "id": "a_con_123456",
3
  "event_type": "account_connection.create",
4
  "status": "active",
5
  "api_version": "2024-04-24",
6
  "created_at": "2026-06-17T18:00:00Z",
7
  "live_mode": true,
8
  "parent_account": {
9
    "id": "ac_parent",
10
    "status": "active",
11
    "name": "Tu plataforma",
12
    "account_type": "business",
13
    "created_at": "2026-06-17T17:00:00Z",
14
    "creator_name": "Ana Perez",
15
    "creator_email": "ana@example.com",
16
    "tax_id": "1234567",
17
    "tax_name": "Tu Plataforma, S.A.",
18
    "withdrawals_schedule": "daily",
19
    "onboarding_completed": true
20
  },
21
  "child_account": {
22
    "id": "ac_child",
23
    "status": "active",
24
    "name": "Comercio conectado",
25
    "account_type": "business",
26
    "created_at": "2026-06-17T18:00:00Z",
27
    "creator_name": "Juan Perez",
28
    "creator_email": "juan@example.com",
29
    "tax_id": "7654321",
30
    "tax_name": "Comercio Conectado, S.A.",
31
    "withdrawals_schedule": "daily",
32
    "onboarding_completed": true
33
  }
34
}

Cuando ocurren eventos en una cuenta hija, recibirás webhooks con los parámetros adicionales:

• connected: true indica que el evento fue generado por una cuenta conectada
• account_id: "ac_123456" es el ID de la cuenta que generó el evento

Con estos campos puedes identificar y procesar eventos de cuentas conectadas por separado.