Skip to main content

Payouts Walkthrough

This walks through the full flow for paying a recipient: create the recipient, create a payout batch, submit it for approval, then hand off to a human for the maker/checker step. All examples use https://api.paguspay.com/api as the base URL — swap in the development server for testing.

1. Create a recipient​

POST /v1/recipients requires the write:recipients scope. PagusPay detects the Pix key type (CPF, CNPJ, email, phone, or EVP) server-side.

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"
  }'

Response (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"
}

If the Pix key fails validation, the recipient is still created locally but comes back with status: "failed" and a failureReason — check the 422 response.

2. Create a payout batch​

POST /v1/payout-batches requires write:payouts. This creates the batch in draft — it does not submit it for approval.

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

Response (201 Created):

{
  "id": 88,
  "organizationId": 12,
  "label": "July 2026 contractor payouts",
  "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"
    }
  ]
}

Invalid items (missing recipient, amount out of range) return 400 with per-item errors instead of persisting a partial batch.

3. Submit for approval​

POST /v1/payout-batches/{id}/submit requires write:payouts. This transitions the batch from draft to pending_approval.

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

Response (200 OK):

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

4. Approve in the dashboard (human step)​

This is where the API stops. A person with approval rights logs in to the PagusPay dashboard, reviews the batch (recipients, amounts, total), and approves it with a 2FA code sent by email. Once approved, the batch moves to approved → executing → completed (or completed_with_errors if any individual item fails at the Pix rail).

There is no approve, reject, or execute endpoint — see Introduction for why.

Checking status​

Poll GET /v1/payout-batches/{id} (read:payouts) to track the batch through its lifecycle:

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

status moves through: draft → pending_approval → approved → executing → completed | completed_with_errors | cancelled.

See the API Reference for full request/response schemas.