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.

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.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API

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

idstring

ID único de la cuenta conectada

statusstring

Estado de la cuenta

namestring

Nombre comercial de la cuenta

account_typeenum

Tipo de cuenta de negocio

created_atdatetime

Fecha de creación

creator_namestring

Nombre del usuario creador

creator_emailstringformat: "email"

Email del usuario creador

tax_idstring or null

ID fiscal de la cuenta

tax_namestring or null

Nombre fiscal de la cuenta

withdrawals_scheduleenum or null

Frecuencia configurada para retiros

onboarding_completedboolean

Indica si la cuenta completó onboarding

Errors

400

Bad Request Error