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).

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.

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.

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). 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. 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.

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.

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

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

Response

Cuenta conectada creada

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

created_atdatetimeOptional

Fecha de creación

creator_namestringOptional

Nombre del usuario creador

creator_emailstringOptionalformat: "email"

Email del usuario creador

tax_idstring or nullOptional

ID fiscal de la cuenta

tax_namestring or nullOptional

Nombre fiscal de la cuenta

withdrawals_scheduleenum or nullOptional

Frecuencia configurada para retiros

onboarding_completedbooleanOptional

Indica si la cuenta completó onboarding

Errors

400

Bad Request Error