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:

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.
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 custom_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:

Tipo	Documentos
`individual`	`tax_registration_document`, `id_card_image`, `id_card_image_back`
`business`	`tax_registration_document`, `company_patent`, `commercial_patent`, `company_representative_document`, `company_representative_id`, `company_representative_id_back`
`non_profit`	`tax_registration_document`, `articles_of_incorporation`, `company_representative_document`, `company_representative_id`, `company_representative_id_back`

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 custom_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"
>       }
>     ],
>     "custom_account_id": "ac_123456"
>   }'

Parámetro	Descripción
`custom_account_id`	El ID de la cuenta hija conectada que va a recibir el pago
`transfer_setups`	Opcional. Configuración de distribución de fondos entre cuentas

Distribución de fondos

Puedes distribuir los fondos entre cuentas usando transfer_setups:

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

Webhooks

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.