Crear una cuenta conectada | Documentación API de Recurrente

curl -X POST https://app.recurrente.com/api/connected_accounts \
     -H "X-SECRET-KEY: <apiKey>" \
     -H "Content-Type: multipart/form-data" \
     -F email="juan@example.com" \
     -F full_name="Juan Pérez" \
     -F phone_number="+50255555555" \
     -F name="Juan Pérez" \
     -F account_type="individual" \
     -F withdrawals_schedule="daily" \
     -F verification='{
  "tax_registration_document": "(archivo PDF — Recurrente extrae tax_id y tax_name de aquí)",
  "id_card_image": "(frente del DPI)",
  "id_card_image_back": "(reverso del DPI)"
}'

{
  "id": "ac_lmgbvesmihkqzma3",
  "status": "active",
  "name": "Acme Restaurant",
  "account_type": "business",
  "created_at": "2024-01-15T09:30:00Z",
  "creator_name": "Ana Perez",
  "creator_email": "owner@restaurant.example",
  "tax_id": "1234567",
  "tax_name": "Acme Restaurant, S.A.",
  "withdrawals_schedule": "daily",
  "onboarding_completed": true
}

Crea una cuenta administrada por tu plataforma, la conecta a tu cuenta y marca el onboarding como completado. Si ya tienes una cuenta conectada para el mismo email, Recurrente la reutiliza y actualiza sus datos (idempotencia por email del administrador).

Para reenviar documentos, usa este mismo POST con la llave de la plataforma en X-SECRET-KEY, el mismo email y los archivos que quieres reemplazar en verification. No necesitas X-ACCOUNT-ID: este endpoint administra las cuentas conectadas desde la plataforma. La respuesta es 200 y conserva el mismo ID de cuenta; crear una cuenta nueva devuelve 201. Los documentos omitidos se conservan. Si no envías documentos, reutilizar la cuenta no vuelve a ejecutar su verificación.

Recurrente extrae automáticamente el tax_id (NIT) y el tax_name (razón social) del documento tax_registration_document (RTU) que envías en verification — no necesitas enviarlos en el request.

Debes enviar la documentación requerida para el tipo de cuenta en verification. Si faltan documentos requeridos, Recurrente responde 400 y no completa el onboarding de la cuenta.

Una respuesta 200 o 201 no significa que los documentos estén aprobados. Si se rechaza un documento durante su procesamiento, se emite verification.rejected con document_errors, también para los reenvíos. Cuando la verificación es aceptada se emite verification.completed. No se emite ese evento por cada carga: tiene que ocurrir un rechazo. Un reemplazo rechazado conserva el documento previamente aceptado y no revierte por sí solo una verificación ya completada.

Usa los nombres del esquema: para el DPI del representante legal de una empresa, verification[company_representative_id] y verification[company_representative_id_back]. Los campos legal_representative_id y legal_representative_selfie no están admitidos.

Puedes enviar bank_account para configurar de una vez la cuenta bancaria externa que recibirá retiros. Si tu cuenta tiene pricing especial para referidos, ese pricing se aplica a las cuentas conectadas nuevas.

Al crear o reutilizar la conexión, Recurrente emite el webhook account_connection.create con los campos parent_account y child_account.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Request

This endpoint expects a multipart form.

emailstringRequiredformat: "email"

Email del usuario administrador de la cuenta hija. Sirve como llave de idempotencia: si vuelves a llamar este endpoint con el mismo email, Recurrente reutiliza la cuenta conectada existente.

full_namestringRequired

Nombre completo del usuario administrador

phone_numberstringOptional

Número de teléfono del usuario administrador

namestringRequired

Nombre comercial de la cuenta hija

account_typeenumRequired

Tipo de cuenta de negocio

Allowed values:

withdrawals_scheduleenumOptional

Frecuencia para retiros de la cuenta hija

Allowed values:

verificationobjectRequired

Documentos requeridos para poder marcar la cuenta como onboarded. Recurrente exige distintos documentos según account_type:

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.

bank_accountobjectOptional

Usa la misma validación bancaria que el formulario de la app, tanto al crear una cuenta conectada como al agregarle otro destino de retiro. Primero se valida el formato por banco, moneda y tipo; después se consulta al banco mediante Nexa. Un titular confirmado reemplaza holder_name. Una cuenta que el banco reporta como comprometida se rechaza con 400 y errors.number.

Si Nexa no está disponible, el banco no está soportado o se alcanzan 20 consultas por cuenta Recurrente en 24 horas, se conserva el titular enviado sin confirmar. También se permite guardar sin confirmar si el banco no encuentra la cuenta y envías holder_name, igual que en el formulario. Las respuestas se reutilizan durante una hora; reenviar un destino ya guardado no vuelve a consultarlo. Al crear una cuenta conectada nueva, la consulta usa el presupuesto de la cuenta padre y conserva la respuesta aunque falle la creación. Para una cuenta conectada existente se usa su propio presupuesto. Sandbox no consulta a Nexa.

checking significa monetaria y savings significa ahorro. Para Banrural en GTQ, monetaria admite prefijos 0 o 3 (10 o 14 dígitos) y ahorro admite 0 o 4 (10, 13 o 14 dígitos). Un número con prefijo 4 enviado como checking se rechaza antes de consultar Nexa. GET /api/banks lista bancos, no formatos de cuenta.

Response

Cuenta conectada existente reutilizada; los documentos enviados se procesan de nuevo

idstringOptional

ID único de la cuenta conectada

statusstringOptional

Estado de la cuenta

namestringOptional

Nombre comercial de la cuenta

account_typeenumOptional

Tipo de cuenta de negocio

Allowed values:

created_atdatetimeOptional

Fecha de creación

creator_namestringOptional

Nombre del usuario creador

creator_emailstringOptionalformat: "email"

Email del usuario creador

tax_idstring or nullOptional

NIT extraído del RTU; si no está disponible, se conserva el ID fiscal previamente guardado en la cuenta.

tax_namestring or nullOptional

Razón social extraída del RTU; si no está disponible, se conserva el nombre fiscal previamente guardado en la cuenta.

withdrawals_scheduleenum or nullOptional

Frecuencia configurada para retiros

Allowed values:

onboarding_completedbooleanOptional

Indica si la cuenta completó onboarding

Errors

400

Bad Request Error