Pagamentos

Pix recebidos pela unidade, com ou sem cobrança associada.

Listar pagamentos

GET /v1/payments

Requer o escopo payments:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`limit`	consulta	integer
`starting_after`	consulta	string	Cursor — ID do último objeto da página anterior.
`ending_before`	consulta	string	Cursor — ID do primeiro objeto da página seguinte.
`created_gte`	consulta	string (date-time)
`created_lte`	consulta	string (date-time)
`charge_id`	consulta	string
`match_status`	consulta	PaymentMatchStatus
`e2e_id`	consulta	string

Respostas

200 Lista paginada de pagamentos.
400 Requisição inválida (formato ou campos).
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/payments?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.payments.list

Consultar pagamento

GET /v1/payments/{payment_id}

Requer o escopo payments:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`payment_id` obrigatório	caminho	string

Respostas

200 Pagamento.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/payments/pay_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.payments.retrieve

Aceitar pagamento sem cobrança

POST /v1/payments/{payment_id}/accept

Aceita um pagamento unmatched (recebido sem cobrança correspondente, ex.: Pix pago após expiração ou cancelamento). O pagamento passa a accepted e deixa de ser elegível à devolução automática. Para recusar, crie uma devolução em POST /refunds. Requer o escopo refunds:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

Nome	Onde	Tipo	Descrição
`payment_id` obrigatório	caminho	string

Respostas

200 Pagamento aceito.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
409 Conflito de estado: `idempotency-key-in-progress`, `charge-not-active`, `payment-not-unmatched`,
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.
500 Erro interno. É seguro repetir com a mesma `Idempotency-Key`.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/payments/pay_01J9Z3F0A1B2C3D4E5F6G7H8J9/accept" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.payments.accept