Tipos do extrato e códigos financeiros

Entenda statement_type, reference_type e os meios de pagamento retornados pela API.

Os campos desta página descrevem fatos diferentes. Confira sempre o recurso e o nome do campo antes de interpretar o código. Uma tarifa e um meio de pagamento não compartilham uma numeração universal.

No extrato, statement_type: 2 significa tarifa, enquanto reference_type: 2 significa referência a uma contestação. O primeiro classifica a movimentação; o segundo classifica o recurso relacionado.

Tipos de lançamento do extrato

statement_type informa a natureza do lançamento no Extrato. amount_cents mantém o sinal do valor em centavos de real.

Código ou valor	Significado	Como interpretar
`1`	Recebimento	Entrada de valor confirmada no extrato, apresentada com sinal positivo. Consulte a referência do lançamento para identificar sua origem; nem todo recebimento precisa apontar para uma cobrança.
`2`	Tarifa	Cobrança de tarifa, apresentada com valor negativo. Quando houver uma cobrança relacionada, o recebimento e a tarifa aparecem em lançamentos separados.
`3`	Tarifa de serviço	Valor cobrado por um serviço, com sinal negativo. A referência disponível ajuda a identificar a origem da cobrança; o tipo, sozinho, não informa qual serviço foi utilizado.
`4`	Saque	Saída de valor por saque, com sinal negativo. Use a referência do saque para consultar sua identificação e seu resultado.
`5`	Devolução	Saída confirmada de valor devolvido, com sinal negativo. Pode ser o lançamento que completa a devolução de uma cobrança após devoluções anteriores; consulte o histórico para conhecer o total devolvido.
`6`	Devolução parcial	Saída confirmada de parte do valor recebido, com sinal negativo. O restante devolvível depende também de outras devoluções e contestações vinculadas à cobrança.
`7`	Ajuste a crédito	Ajuste que acrescenta valor ao saldo, apresentado com sinal positivo. Consulte a referência e os detalhes disponíveis para entender o motivo; esse tipo não identifica um pagamento de cliente.
`8`	Ajuste a débito	Ajuste que retira valor do saldo, apresentado com sinal negativo. Consulte a referência e os detalhes disponíveis para entender o motivo; esse tipo não identifica necessariamente um saque ou estorno.
`9`	Bloqueio de saldo	Valor que passou a ficar indisponível para movimentação, apresentado com sinal negativo. O bloqueio não confirma despesa nem devolução de dinheiro; confira o saldo bloqueado e o caso relacionado, quando informado.
`10`	Liberação de saldo	Valor anteriormente bloqueado que voltou a ficar disponível, apresentado com sinal positivo. A liberação não é uma nova receita e não representa outro pagamento do cliente.

Um pagamento pode gerar mais de um lançamento, como recebimento e tarifa. Uma retenção reduz a disponibilidade do dinheiro, sem representar por si só uma despesa. Sua liberação não é uma nova receita.

O saldo atual tem consulta própria, com total, bloqueado e disponível. Somar uma página do extrato não substitui essa consulta nem fornece o saldo após cada lançamento.

Categorias de referência do extrato

reference_type explica a que categoria pertence reference_id. Ele não informa se o lançamento é entrada, saída, tarifa ou retenção.

Código ou valor	Significado	Como interpretar
`1`	Cobrança	O identificador de referência aponta para uma cobrança. Vários lançamentos, como recebimento, tarifa e devolução, podem se relacionar à mesma cobrança; confira também o tipo do lançamento e os vínculos de estorno ou contestação.
`2`	Contestação	O identificador de referência aponta para uma contestação. Consulte o caso para interpretar o vínculo; a referência, sozinha, não comprova perda, ganho ou devolução.
`3`	Saque	O identificador de referência aponta para um saque. A classificação indica a origem do lançamento e deve ser lida junto de seu valor e tipo.
`4`	Ajuste	O identificador de referência aponta para um ajuste financeiro. O sentido do ajuste é informado pelo tipo do lançamento e pelo sinal do valor.
`5`	Lançamento manual	A referência identifica um lançamento manual e pode não ter prefixo. Não a trate como identificador de cobrança nem presuma que exista um endpoint público para consultá-la.

reference_id e reference_type podem ser null. Os campos refund_id e dispute_id complementam os vínculos quando existe uma associação confirmada. Uma tarifa não recebe automaticamente o estorno de outra linha só porque ambas pertencem à mesma cobrança.

Meios de pagamento

Estes códigos identificam meios de pagamento no campo payment_method da API. A presença de um código na resposta não significa que ele esteja habilitado para criar uma cobrança ou pagar no checkout.

Código ou valor	Significado	Como interpretar
`0`	Não definido	A cobrança ainda não tem um meio de pagamento definido. As opções permitidas vêm da configuração da cobrança e do checkout; este valor não indica pagamento confirmado.
`1`	Pix	Identifica pagamento por Pix. A emissão de um código Pix permite pagar a cobrança, mas a confirmação depende do recebimento do pagamento.
`2`	Boleto	Identifica pagamento por boleto. Registro, compensação e liquidação são etapas diferentes; consulte o estado do boleto e o pagamento da cobrança.
`3`	Cartão de crédito	Identifica cartão de crédito em dados que usem esse código. A existência do valor no catálogo não habilita esse meio no checkout; para criar uma cobrança, use somente os meios aceitos pelo endpoint.
`4`	Débito	Identifica pagamento por débito em dados que usem esse código. A existência do valor no catálogo não habilita esse meio no checkout; para criar uma cobrança, use somente os meios aceitos pelo endpoint.

Para novas cobranças, consulte Meios de pagamento: o guia distingue payment_method, payment_method_types e checkout_payment_method. A lista aceita na criação segue as opções do endpoint, e a configuração de um link pode restringir as opções da cobrança. Emitir Pix ou boleto não confirma pagamento.

Motivos de falha do saque

Quando status de um saque é FAILED, failure_reason.code informa o motivo registrado. Nos demais estados, failure_reason é null. Esses códigos vêm da consulta de saques e são diferentes do status HTTP da requisição.

Código ou valor	Significado	Como interpretar
`INVALID_BANK_ACCOUNT`	Conta inválida	Os dados da conta de destino não foram aceitos.
`BANK_ACCOUNT_UNAVAILABLE`	Conta indisponível	A conta de destino estava indisponível.
`BANK_UNSUPPORTED`	Instituição não aceita	A instituição do destino não foi aceita para o saque.
`INVALID_ACCOUNT_TYPE`	Tipo de conta inválido	O tipo da conta de destino não foi aceito.
`INSUFFICIENT_BALANCE`	Saldo insuficiente	Não havia saldo suficiente para concluir o saque.
`BLOCKED_BALANCE`	Saldo bloqueado	Valores bloqueados impediram o saque.
`BELOW_MINIMUM_WITHDRAWAL`	Abaixo do mínimo	O valor solicitado era menor que o mínimo permitido.
`ABOVE_MAXIMUM_WITHDRAWAL`	Acima do máximo	O valor solicitado excedia o máximo permitido.
`WITHDRAWAL_LIMIT_REACHED`	Limite atingido	Um limite de saque impediu a solicitação.
`DUPLICATED_REQUEST`	Solicitação duplicada	Confira o histórico antes de solicitar outra transferência.
`RISK_POLICY_REJECTED`	Saque não autorizado	Confira os avisos da conta ou procure o suporte.
`WITHDRAWAL_TEMPORARILY_UNAVAILABLE`	Saque indisponível	A solicitação não pôde ser concluída naquele momento.
`BANK_PROCESSING_FAILURE`	Falha na transferência	Confira o histórico e procure o suporte se necessário.
`BANK_TIMEOUT`	Prazo excedido	Não houve conclusão no prazo esperado. Consulte o histórico antes de repetir.
`INTERNAL_ERROR`	Falha no processamento	Confira o histórico e procure o suporte se necessário.
`WITHDRAWAL_FAILURE_REASON_UNAVAILABLE`	Motivo não disponível	Não há motivo confirmado para apresentar. Procure o suporte se necessário.

Use o código para tratar a resposta no seu sistema. A mensagem em inglês complementa o diagnóstico e pode mudar sem alterar o código. Consulte o saque e o histórico antes de fazer outra solicitação; a consulta não repete a transferência nem confirma que uma nova tentativa será aceita.