Cuenta empresa / organización

Solicitud de cuenta empresa u organización sin fines de lucro desde la app, y estado de las solicitudes del usuario.

Endpoint

GET  /api/user/company
POST /api/user/company

Autenticación: Bearer Token del usuario (la empresa u organización queda vinculada a esa cuenta, que será su cuenta designada).

La misma solicitud puede hacerse desde la web en qvapay.com/enterprise. Ambos canales comparten validación, revisión y aprobación.

GET — Solicitudes del usuario

Devuelve hasta 10 solicitudes donde el usuario es el dueño (owner_id).

{
  "companies": [
    {
      "uuid": "…",
      "company_name": "Cáritas Cubana",
      "director_name": "María Pérez",
      "email": "[email protected]",
      "activity": "Asistencia social",
      "employee_count": "11-50",
      "country": "CU",
      "status": "pending",
      "statutes_sent": true,
      "created_at": "2026-11-01T12:00:00.000Z",
      "updated_at": "2026-11-01T12:00:00.000Z"
    }
  ]
}

status: pending · reviewing · contacted · approved · rejected.

POST — Nueva solicitud

multipart/form-data. Límite: 3 solicitudes por 10 minutos por IP; una sola solicitud en proceso por cuenta (409 si ya hay una).

Campos comunes

Campo	Tipo	Requerido	Descripción
`orgKind`	string	No	`business` (default) o `nonprofit`. Decide la rama: empresa con socios, u organización sin fines de lucro con directivos.
`country`	string	Sí	País de constitución, ISO-2. Jurisdicciones sancionadas rechazadas.
`directorName`	string	Sí	Director o presidente. En la rama `nonprofit` es el representante legal / persona de control (31 CFR 1010.230(e)(3)); su cuenta QvaPay verificada es la cuenta designada.
`email`	string	Sí	Email de contacto de la organización.
`companyName`	string	Sí	Razón social / nombre de la organización.
`activity`	string	Sí	Actividad o misión.
`employeeCount`	string	Sí	`1-10` · `11-50` · `51-200` · `201-500` · `500+`.
`taxId`	string	Sí*	US: EIN (`12-3456789`). CU: NIT (11 dígitos). Otros: identificador fiscal. *Opcional solo para `nonprofit` en Cuba.
`entityType`	string	US	Tipo de entidad (`LLC`, `C-Corp`, …). En la rama `nonprofit` se fija a `Nonprofit`.
`incState`	string	US	Estado de constitución (código de 2 letras).
`addrLine1`, `addrCity`, `addrState`, `addrZip`	string	US	Dirección registrada en EE. UU.
`statutes`	file (PDF ≤ 10 MB)	Sí	Estatutos / escritura. En `nonprofit`: documento de gobierno (bylaws) o, en Cuba, documento fundacional o autorizante.
`ref`	string	No	Usuario que invita (`?ref=`).
`inv`	string	No	Código de enlace de invitación limitado (`/i/<código>`).

Rama empresa (`orgKind` ausente o `business`)

Campo	Tipo	Requerido	Descripción
`owners`	JSON string	CU: sí · resto: puede ir vacío	`[{ "name", "pct", "email"?, "username"? }]`. Cuba: todos los socios de la escritura, cualquier %. Resto: solo socios con 25 % o más, `pct` obligatorio.

Rama organización sin fines de lucro (`orgKind=nonprofit`)

Sin socios ni porcentajes. En Cuba no se cruza con el listado MEP (no es una mipyme).

Campo	Tipo	Requerido	Descripción
`registrationKind`	string	Sí	US: `irs_501c3`. CU: `church_decree` · `asociaciones_registry` · `other_authorization`. Otros países: `local_registry`.
`registrationRef`	string	No	Número de registro, fecha del decreto, EIN de la carta… (≤ 191 caracteres).
`officers`	JSON string	No	`[{ "name", "title", "email"?, "username"? }]`, hasta 20 directivos y miembros de la junta. Cada uno se verifica contra listas de sanciones al recibir la solicitud. Un `username` que no exista responde 400.
`registrationDoc`	file (PDF ≤ 10 MB)	Sí	US: carta de determinación del IRS. Otros países: registro de la organización. Cuba: carta que nombra al representante legal.

Respuesta

{ "message": "Solicitud enviada con éxito. Nos pondremos en contacto contigo pronto.", "uuid": "…" }

Código	Significado
`200`	Solicitud creada.
`400`	Campo inválido o faltante (el mensaje dice cuál).
`409`	Ya hay una solicitud en proceso o la misma organización ya está aprobada.
`429`	Límite de solicitudes.

Qué pasa después

La razón social se verifica como entidad y el director, los socios o los directivos como personas contra las listas de sanciones.
El equipo revisa el expediente; una organización cubana sin fines de lucro se aprueba con diligencia reforzada (el oficial de cumplimiento deja constancia de la base legal).
Al aprobarse, la cuenta designada queda habilitada como cuenta empresa / organización. Si la organización fue invitada por una app integradora autorizada, esa app recibe el evento company.approved con el username de la cuenta designada (webhook firmado, mismo formato que los webhooks de app).

Webhook `company.approved`

Solo para organizaciones sin fines de lucro y solo a las apps autorizadas por QvaPay. Firmado con el secreto de la app (x-qvapay-signature: sha256=<hmac>, x-qvapay-timestamp).

{
  "event": "company.approved",
  "company": {
    "uuid": "…",
    "name": "Cáritas Cubana",
    "country": "CU",
    "kind": "ENTERPRISE_NONPROFIT_CU",
    "registration_kind": "church_decree",
    "approved_at": "2026-11-05T15:20:00.000Z"
  },
  "account": { "uuid": "…", "username": "caritascubana" },
  "referred_by": "godbless"
}

account.username es el destino de POST /api/transaction/transfer para pagarle a la organización.

Cuenta empresa / organización

EndpointCopy Anchor Link

GET — Solicitudes del usuarioCopy Anchor Link

POST — Nueva solicitudCopy Anchor Link

Campos comunesCopy Anchor Link

Rama empresa (orgKind ausente o business)Copy Anchor Link

Rama organización sin fines de lucro (orgKind=nonprofit)Copy Anchor Link

RespuestaCopy Anchor Link

Qué pasa despuésCopy Anchor Link

Webhook company.approvedCopy Anchor Link

On this page