Revisiones de operaciones

Cuando tu organización tiene el firewall transaccional activado, algunas operaciones de dinero (payouts, retiros crypto, payins o transferencias banking) pueden quedar retenidas para revisión manual antes de ejecutarse — y si tu organización además activó la revisión de solicitudes, crear un perfil banking, registrar un tercero bancario o emitir una tarjeta puede quedar retenido de la misma forma. Esta guía te muestra cómo consultar esas revisiones y responder cuando te pidan información.

¿Pruebas de integración? En el ambiente de test (https://cryptobank.qbank.cl/platform, keys pk_test_) el firewall se comporta igual que en producción cuando tu org lo activa. Detalles en Ambientes y pruebas.

Qué verás

Cuando una operación tuya queda retenida:

El estado cambia a in_review — la operación no se ejecuta todavía. El POST que la creó responde 202 Accepted con review_id.
Recibes un webhook txn_review_status_changed con el estado nuevo.
Si te piden información, recibes un email con el motivo y un enlace para subir documentos.

Esto es normal. El firewall transaccional es una capa de control que tu organización activó para cumplir con políticas de compliance. La mayoría de las revisiones se resuelven en minutos u horas.

Consulta tus revisiones

Lista las operaciones tuyas que están o estuvieron en revisión:

curl "https://api.qbank.cl/platform/v1/me/txn-reviews?from=2026-07-01&to=2026-08-06" \
  -H "Authorization: Bearer pk_..."

Respuesta:

{
  "reviews": [
    {
      "id": "7a3f2b1c-0000-4000-8000-000000000001",
      "kind": "payout",
      "resource_id": "8b4c3d2e-1111-4111-8111-111111111111",
      "status": "info_requested",
      "amount_label": "1500.00",
      "asset": "USD",
      "country": "MX",
      "method": "spei",
      "counterparty": "Juan Pérez",
      "info_request": {
        "message": "Please upload the invoice that justifies this payment",
        "requested_at": "2026-08-06T15:20:00Z"
      },
      "created_at": "2026-08-06T14:32:00Z",
      "updated_at": "2026-08-06T15:20:00Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 1
}

Filtros

?status= — in_review, info_requested, released, rejected o all (vacío = abiertas: in_review + info_requested). Otro valor ⇒ 400 invalid_status.
?from= / ?to= — rango de fechas (YYYY-MM-DD, zona horaria de tu organización, ambos inclusive). Fecha inválida ⇒ 400 invalid_range.
?page= / ?page_size= — paginación (default 50, máximo 200).

Detalle de una revisión

curl https://api.qbank.cl/platform/v1/me/txn-reviews/7a3f2b1c-0000-4000-8000-000000000001 \
  -H "Authorization: Bearer pk_..."

Respuesta:

{
  "review": {
    "id": "7a3f2b1c-0000-4000-8000-000000000001",
    "kind": "payout",
    "resource_id": "8b4c3d2e-1111-4111-8111-111111111111",
    "status": "info_requested",
    "amount_label": "1500.00",
    "asset": "USD",
    "country": "MX",
    "method": "spei",
    "counterparty": "Juan Pérez",
    "info_request": {
      "message": "Please upload the invoice that justifies this payment",
      "requested_at": "2026-08-06T15:20:00Z"
    },
    "files": [
      {
        "id": "f1e2d3c4-0000-4000-8000-0000000000aa",
        "review_id": "7a3f2b1c-0000-4000-8000-000000000001",
        "file_name": "invoice-221.pdf",
        "content_type": "application/pdf",
        "size_bytes": 482110,
        "uploaded_by": "account",
        "created_at": "2026-08-06T15:40:00Z"
      }
    ],
    "created_at": "2026-08-06T14:32:00Z",
    "updated_at": "2026-08-06T15:40:00Z"
  }
}

Una revisión de otra cuenta responde 404 not_found (nunca 403, para no filtrar existencia). Cuando la revisión fue rechazada, el detalle incluye decision_note (el mismo texto del email de rechazo) y decided_at.

El motivo interno nunca se expone. Por seguridad y para no comprometer las investigaciones de compliance, la vista del usuario final solo muestra el estado y el mensaje de la solicitud de información — jamás el motivo interno de la retención ni las notas del equipo.

Estados de una revisión

Estado	Significado	Qué hacer
`in_review`	La operación está siendo revisada por el equipo de compliance	Espera — no necesitas hacer nada
`info_requested`	Te pidieron información adicional	Sube los documentos solicitados lo antes posible
`released`	La revisión aprobó la operación	La operación ya se ejecutó (o está en camino) — para una solicitud, el perfil banking o la tarjeta ya fueron creados
`rejected`	La revisión rechazó la operación	La operación se canceló; los fondos retenidos vuelven a tu saldo — y una solicitud rechazada reembolsa su fee

Rechazo automático por plazo. Si tu organización configuró un plazo de revisión, una revisión que nadie decide dentro de esa ventana (contada desde su último cambio de estado — subir evidencia reinicia el reloj) queda automáticamente rechazada por un barrido horario: la operación se cancela, los fondos retenidos vuelven a tu saldo y recibes el mismo email y webhook txn_review_status_changed que con un rechazo manual. En el detalle, el decision_note lleva el aviso estándar de plazo vencido. Las revisiones de solicitudes jamás se auto-rechazan: una solicitud banking o de tarjeta retenida siempre espera una decisión humana, sin plazo.

Solicitudes retenidas (banking y tarjetas)

Si tu organización activó la revisión de solicitudes (dos toggles separados, uno para banking y otro para tarjetas), estas llamadas también pueden quedar retenidas antes de procesarse:

POST /v1/banking/customer — apertura de tu propio perfil banking
POST /v1/banking/third-parties — registro de un tercero para banking
POST /v1/cards — emisión de una tarjeta (virtual o física)

Una solicitud retenida responde 202 Accepted en vez de 201:

{
  "status": "in_review",
  "kind": "card_application",
  "review_id": "7a3f2b1c-0000-4000-8000-000000000001",
  "message": "application received; it is pending review by our compliance team"
}

Un reintento con la misma idempotency_key devuelve el mismo 202 con idempotency_hit: true — jamás abre una segunda revisión.

El fee de la solicitud se cobra al retenerla. Si la revisión se rechaza, el fee se reembolsa automáticamente; si se aprueba, el perfil o la tarjeta se crean en ese momento.
Sigue el resultado con el webhook txn_review_status_changed (el kind será banking_application o card_application) o consultando GET /v1/me/txn-reviews.
La revisión también puede pedir información (info_requested) — sube los documentos igual que en una revisión transaccional.

Sube documentos cuando te los pidan

Si tu revisión está en info_requested, sube los archivos de respaldo. El body es el binario crudo del archivo, el nombre viaja en el query param name y el tipo en el header Content-Type:

curl -X POST "https://api.qbank.cl/platform/v1/me/txn-reviews/7a3f2b1c-0000-4000-8000-000000000001/files?name=invoice-221.pdf" \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/pdf" \
  --data-binary "@invoice-221.pdf"

Respuesta 201 — al subir un archivo la revisión vuelve a in_review para que el equipo la re-evalúe:

{
  "file": {
    "id": "f1e2d3c4-0000-4000-8000-0000000000aa",
    "review_id": "7a3f2b1c-0000-4000-8000-000000000001",
    "file_name": "invoice-221.pdf",
    "content_type": "application/pdf",
    "size_bytes": 482110,
    "uploaded_by": "account",
    "created_at": "2026-08-06T15:40:00Z"
  },
  "status": "in_review"
}

Límites:

Tipos permitidos: PDF, PNG, JPEG, WEBP, TXT, CSV, DOC(X), XLS(X) — se valida por el header Content-Type.
Tamaño máximo: 50 MB por archivo.
Máximo 20 archivos por revisión.

Descarga tus propios archivos

curl "https://api.qbank.cl/platform/v1/me/txn-reviews/7a3f2b1c-0000-4000-8000-000000000001/files/f1e2d3c4-0000-4000-8000-0000000000aa" \
  -H "Authorization: Bearer pk_..." \
  -o invoice-221.pdf

Devuelve el binario crudo con su Content-Type original (los archivos de otras cuentas responden 404 not_found).

Webhook `txn_review_status_changed`

Cada vez que el estado de una revisión tuya cambia, recibes este webhook:

{
  "event": "txn_review_status_changed",
  "account_id": "ae8cf540-1234-5678-9abc-def012345678",
  "review_id": "7a3f2b1c-0000-4000-8000-000000000001",
  "kind": "payout",
  "resource_id": "8b4c3d2e-1111-4111-8111-111111111111",
  "status": "released",
  "previous_status": "in_review",
  "amount": "1500.00",
  "asset": "USD",
  "timestamp": "2026-08-06T16:30:00Z"
}

El payload del webhook es neutro por diseño: incluye el estado y el resumen de la operación, pero jamás el motivo interno de la revisión ni notas de compliance.Para revisiones de solicitudes (kind: banking_application / card_application) el payload omite amount y asset; method lleva el flujo de la solicitud (self/third_party) o el tipo de tarjeta (virtual/physical).

Errores propios

HTTP	Código	Solución
400	`invalid_status`	El filtro `status` debe ser `in_review`, `info_requested`, `released`, `rejected` o `all`
400	`invalid_range`	Revisa el formato `YYYY-MM-DD` de `from`/`to`
400	`invalid_name`	Envía el nombre del archivo en el query param `name` (máx. 200 caracteres, sin separadores de ruta)
400	`empty_file`	El body del archivo llegó vacío
404	`not_found`	La revisión (o el archivo) no existe o no pertenece a tu cuenta
409	`not_awaiting_info`	La revisión no está en `info_requested` — solo puedes subir archivos cuando te los pidieron
413	`file_too_large`	El archivo supera los 50 MB
415	`unsupported_file_type`	Usa PDF, PNG, JPEG, WEBP, TXT, CSV, DOC(X) o XLS(X) con su `Content-Type`
422	`file_limit_reached`	La revisión ya tiene 20 archivos
503	`storage_unavailable`	El almacenamiento no está disponible; reintenta en unos segundos

Catálogo completo en Errores.

Preguntas frecuentes

¿Por qué mi operación quedó retenida?

Tu organización activó el firewall transaccional, una capa de control que retiene ciertas operaciones para revisión manual antes de ejecutarlas. Los criterios exactos dependen de la política de compliance de tu organización.

¿Cuánto tarda la revisión?

La mayoría de las revisiones se resuelven en minutos u horas. Si tu revisión lleva más de 24 horas sin respuesta, tu organización recibe una alerta automática. Si tu organización configuró un plazo de decisión, la revisión se rechaza automáticamente cuando el plazo vence — subir la evidencia pedida reinicia ese reloj.

¿Qué pasa si rechazan mi operación?

La operación se cancela. Si había fondos retenidos (por ejemplo, en un payout), se devuelven automáticamente a tu saldo disponible. Recibes un email con el motivo del rechazo.

¿Puedo cancelar una operación que está en revisión?

No directamente. Si necesitas cancelarla, contacta al equipo de compliance de tu organización — ellos pueden rechazarla desde su panel.

¿Por qué no veo el motivo de la retención?

Por seguridad y para no comprometer investigaciones de compliance, el motivo interno nunca se expone al usuario final. Solo verás el mensaje de información solicitada cuando te pidan documentos.

Creé un perfil banking o una tarjeta y recibí un 202 — ¿qué pasó?

Tu organización activó la revisión de solicitudes: la llamada quedó retenida antes de procesarse. Todavía no se crea nada — cuando compliance apruebe la revisión, el perfil o la tarjeta se crean automáticamente y recibes el webhook txn_review_status_changed con status: released. El fee de la solicitud se cobró al retenerla; si la revisión se rechaza, el fee se reembolsa a tu saldo automáticamente.

Comenzar

Conceptos

Flujos de integración

Productos

Integración

Recursos

Revisiones de operaciones

Qué verás

Consulta tus revisiones

Filtros

Detalle de una revisión

Estados de una revisión

Solicitudes retenidas (banking y tarjetas)

Sube documentos cuando te los pidan

Descarga tus propios archivos

Webhook `txn_review_status_changed`

Errores propios

Preguntas frecuentes

​Qué verás

​Consulta tus revisiones

​Filtros

​Detalle de una revisión

​Estados de una revisión

​Solicitudes retenidas (banking y tarjetas)

​Sube documentos cuando te los pidan

​Descarga tus propios archivos

​Webhook txn_review_status_changed

​Errores propios

​Preguntas frecuentes

Qué verás

Consulta tus revisiones

Filtros

Detalle de una revisión

Estados de una revisión

Solicitudes retenidas (banking y tarjetas)

Sube documentos cuando te los pidan

Descarga tus propios archivos

Webhook `txn_review_status_changed`

Errores propios

Preguntas frecuentes