Guía de Pagos

Esta guía recorre el flujo completo para pagar a un beneficiario: crear el beneficiario, crear un lote de pago, enviarlo para aprobación y luego pasar a un humano en el paso maker/checker. Todos los ejemplos usan https://api.paguspay.com/api como base URL — reemplácela por el servidor de desarrollo para pruebas.

1. Crear un beneficiario

POST /v1/recipients requiere el scope write:recipients. PagusPay detecta el tipo de clave Pix (CPF, CNPJ, email, teléfono o EVP) en el servidor.

curl -X POST https://api.paguspay.com/api/v1/recipients \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria@example.com",
    "pixKey": "maria@example.com",
    "documentNumber": "12345678900"
  }'

Respuesta (201 Created):

{
  "id": 501,
  "organizationId": 12,
  "name": "Maria Silva",
  "email": "maria@example.com",
  "pixKeyType": "email",
  "pixKey": "maria@example.com",
  "documentNumber": "12345678900",
  "bankName": null,
  "accountOwnerName": "Maria Silva",
  "status": "active",
  "failureReason": null,
  "createdBy": 3,
  "createdAt": "2026-07-11T10:00:00.000Z",
  "updatedAt": "2026-07-11T10:00:00.000Z"
}

Si la clave Pix falla la validación, el beneficiario se crea igualmente en local, pero vuelve con status: "failed" y un failureReason — revise la respuesta 422.

2. Crear un lote de pago

POST /v1/payout-batches requiere write:payouts. Esto crea el lote en draft — no lo envía para aprobación.

curl -X POST https://api.paguspay.com/api/v1/payout-batches \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Pagos a contratistas - Julio 2026",
    "items": [
      { "recipientId": 501, "amountBrl": "1500.00" }
    ]
  }'

Respuesta (201 Created):

{
  "id": 88,
  "organizationId": 12,
  "label": "Pagos a contratistas - Julio 2026",
  "status": "draft",
  "createdBy": 3,
  "approvedBy": null,
  "executedAt": null,
  "totalBrlCents": 150000,
  "createdAt": "2026-07-11T10:05:00.000Z",
  "items": [
    {
      "id": 900,
      "batchId": 88,
      "recipientId": 501,
      "amountBrlCents": 150000,
      "status": "draft",
      "failureReason": null,
      "createdAt": "2026-07-11T10:05:00.000Z",
      "updatedAt": "2026-07-11T10:05:00.000Z"
    }
  ]
}

Los ítems inválidos (beneficiario ausente, valor fuera de rango) devuelven 400 con errores por ítem, en lugar de persistir un lote parcial.

3. Enviar para aprobación

POST /v1/payout-batches/{id}/submit requiere write:payouts. Esto transiciona el lote de draft a pending_approval.

curl -X POST https://api.paguspay.com/api/v1/payout-batches/88/submit \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Respuesta (200 OK):

{
  "id": 88,
  "organizationId": 12,
  "label": "Pagos a contratistas - Julio 2026",
  "status": "pending_approval",
  "createdBy": 3,
  "approvedBy": null,
  "executedAt": null,
  "totalBrlCents": 150000,
  "createdAt": "2026-07-11T10:05:00.000Z"
}

4. Aprobar en el panel (paso humano)

Aquí es donde la API se detiene. Una persona con permiso de aprobación inicia sesión en el panel de PagusPay, revisa el lote (beneficiarios, montos, total) y aprueba con un código 2FA enviado por email. Una vez aprobado, el lote avanza a approved → executing → completed (o completed_with_errors si algún ítem individual falla en el riel Pix).

No existe un endpoint approve, reject o execute — vea la Introducción para entender por qué.

Verificar el estado

Consulte GET /v1/payout-batches/{id} (read:payouts) para seguir el lote en su ciclo de vida:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.paguspay.com/api/v1/payout-batches/88

status avanza por: draft → pending_approval → approved → executing → completed | completed_with_errors | cancelled.

Vea la Referencia de la API para los esquemas completos de solicitud/respuesta.