Empezar

La API v2 le permite cobrarle a una persona (pay-ins) y pagarle a una persona (payouts) con una sola integración: país, moneda y método viajan en el cuerpo del pedido, y lo que se puede hacer hoy lo dice GET /v2/capabilities. Usted no elige proveedor ni banco de salida: la API enruta cada operación por el mejor riel disponible.

En cinco pasos

Pida sus llaves. TuCapi le entrega dos: tuc_live_… para producción (https://api.tucapi.app) y tuc_test_… para probar sin mover dinero en el sandbox (https://api.tucapi.app/sandbox), con los alcances que necesite (payins:crear, payouts:crear, operaciones:leer, saldos:leer, webhooks:configurar). Ver Autenticación.
Lea el catálogo. GET /v2/capabilities le dice qué países, monedas y métodos tiene su llave, con los campos que cada método exige. Ver Catálogo.
Registre su webhook. POST /v2/webhook-endpoints con su url https; guarde el secreto, se muestra una sola vez. Ver Webhooks.
Cree su primera operación con un SDK o con curl, siempre con Idempotency-Key. Ver Cobros y Pagos.
Reciba el desenlace por webhook (payout.confirmed, payout.failed, payin.confirmed, payin.failed) o consúltelo con GET /v2/transactions/{id}.

Las tres reglas que conviene entender antes de escribir código

Idempotency-Key es obligatoria y es su red. Reenviar el mismo pedido con la misma clave devuelve LA MISMA operación. Es lo que hace seguro reintentar. Ver Idempotencia y reintentos.
Los estados públicos son tres: pending, confirmed y failed. Un failed siempre trae failure.code, un valor cerrado sobre el que puede hacer un switch. Un 201 no significa “cobrado”: mire status.
Los importes son texto con punto decimal ("1500.50"), nunca números JSON.

Un pago en tres líneas

curl -X POST https://api.tucapi.app/v2/payouts \
  -H "Authorization: Bearer $LLAVE" \
  -H "Idempotency-Key: orden-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1500.50",
    "beneficiary": {
      "account_number": "04121234567",
      "bank_code": "0102",
      "document": {
        "number": "12345678",
        "type": "V"
      },
      "name": "Nombre Apellido"
    },
    "country": "VE",
    "currency": "VES",
    "metadata": {
      "orden": "B-2"
    },
    "method": "mobile_payment",
    "purpose": "remittance",
    "reference": "remesa 456"
  }'

{
  "amount": "1500.50",
  "bank_reference": null,
  "country": "VE",
  "created_at": "2026-09-23T14:59:05Z",
  "created_by": "company",
  "currency": "VES",
  "failure": null,
  "id": "6f1c2a9e-3b4d-4c5e-8f70-1a2b3c4d5e6f",
  "metadata": {
    "orden": "A-1"
  },
  "method": "mobile_payment",
  "pending_reason": "processing",
  "purpose": "remittance",
  "reference": "factura 123",
  "status": "pending",
  "type": "payout",
  "updated_at": "2026-09-23T14:59:05Z"
}

Dónde está todo

Empezar: Qué es la API v2, cómo funciona un cobro y un pago, y los cinco pasos para la primera integración.
Autenticación: La llave de API, los alcances y el ambiente sandbox.
Idempotencia y reintentos: Cómo reintentar sin pagar dos veces; qué se reintenta y qué no.
Cobros (pay-ins): Cobrarle a una persona con código de un solo uso, por débito domiciliado, o esperar el Pago Móvil o la transferencia que ella manda.
Pagos (payouts): Pagarle a una persona por pago móvil o transferencia, el saldo, y la cancelación.
Webhooks y eventos: Cómo recibir el desenlace de cada operación, verificar la firma y consultar los eventos.
Errores y fallos: El sobre de error, los códigos de error de la API y los códigos de fallo de una operación.
Catálogo: Países, monedas, métodos con sus campos y límites, bancos y disponibilidad.
Los SDK: Los clientes oficiales de Go, Node y Python: qué resuelven y cómo se usan.
Servidor MCP: Cómo conectar un asistente de IA (Claude, ChatGPT, Gemini, Codex) a su cuenta por MCP, sólo lectura.