Pular para o conteúdo principal

Guia de Pagamentos

Este guia percorre o fluxo completo para pagar um beneficiário: criar o beneficiário, criar uma folha de pagamento, submetê-la para aprovação e então passar para um humano na etapa maker/checker. Todos os exemplos usam https://api.paguspay.com/api como base URL — troque pelo servidor de desenvolvimento para testes.

1. Criar um beneficiário​

POST /v1/recipients exige o scope write:recipients. A PagusPay detecta o tipo de chave Pix (CPF, CNPJ, email, telefone ou EVP) no 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"
  }'

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

Se a chave Pix falhar na validação, o beneficiário ainda é criado localmente, mas retorna com status: "failed" e um failureReason — verifique a resposta 422.

2. Criar uma folha de pagamento​

POST /v1/payout-batches exige write:payouts. Isso cria a folha em draft — não a submete para aprovação.

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

Resposta (201 Created):

{
  "id": 88,
  "organizationId": 12,
  "label": "Pagamentos de contratados - Julho 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"
    }
  ]
}

Itens inválidos (beneficiário ausente, valor fora do intervalo) retornam 400 com erros por item, em vez de persistir uma folha parcial.

3. Submeter para aprovação​

POST /v1/payout-batches/{id}/submit exige write:payouts. Isso transiciona a folha de draft para pending_approval.

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

Resposta (200 OK):

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

4. Aprovar no painel (etapa humana)​

É aqui que a API para. Uma pessoa com permissão de aprovação faz login no painel da PagusPay, revisa a folha (beneficiários, valores, total) e aprova com um código 2FA enviado por email. Após aprovada, a folha avança para approved → executing → completed (ou completed_with_errors se algum item individual falhar no trilho Pix).

Não existe endpoint approve, reject ou execute — veja a Introdução para entender o porquê.

Verificando o status​

Consulte GET /v1/payout-batches/{id} (read:payouts) para acompanhar a folha em seu ciclo de vida:

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

status avança por: draft → pending_approval → approved → executing → completed | completed_with_errors | cancelled.

Veja a Referência da API para os schemas completos de requisição/resposta.