Status e erros
Referência rápida dos status de transação e saque e dos códigos de erro da API.
Status de transação
| Status | Significado |
|---|---|
| PENDING | Cobrança criada, aguardando pagamento (PIX e boleto nascem assim) |
| WAITING_PAYMENT | Equivalente a PENDING em alguns provedores |
| IN_PROCESS | Pagamento em análise pelo provedor |
| AUTHORIZED | Pago e confirmado — libere o pedido |
| APPROVED | Equivalente a AUTHORIZED |
| REJECTED | Recusado pelo provedor ou pelo emissor do cartão |
| CANCELED | Cancelado ou expirado sem pagamento |
| REFUNDED | Estornado ao comprador |
| CHARGEBACK | Contestação aceita: o valor voltou ao comprador |
| IN_DISPUTE | Contestação aberta (MED do PIX ou disputa de cartão) |
Status de saque
| Status | Significado |
|---|---|
| pending | Saque criado, aguardando aprovação |
| approved | Aprovado — o PIX foi enviado e confirmado |
| processing | Enviado ao provedor, aguardando confirmação |
| gateway_error | O provedor recusou o envio; veja gateway_error_message |
| refused | Recusado na análise |
Formato dos erros
Resposta de erro
{
"hasError": true,
"error": "Erro na validação dos campos",
"errorFields": ["property description should not exist"],
"statusCode": 400,
"timestamp": "2026-09-16T12:00:00.000Z",
"path": "/api/v1/direct-payments"
}| Código | Quando acontece |
|---|---|
| 400 | Corpo inválido, campo desconhecido ou regra de negócio recusada |
| 401 | Chave ausente ou inválida, assinatura inválida, timestamp fora da janela ou nonce repetido |
| 403 | IP não autorizado, permissão faltando ou chave PIX não autorizada |
| 404 | Recurso não encontrado (transação, saque ou produto) |
| 409 | Conflito: saque duplicado ou já em processamento |
| 429 | Limite de requisições atingido |
| 500 | Erro interno; tente de novo e, se persistir, fale com o suporte |
| 503 | Indisponibilidade temporária na validação da chave assinada |
Campos desconhecidos
A API recusa o corpo inteiro quando ele traz um campo que não existe no contrato, com a mensagem property X should not exist. Envie apenas os campos documentados.