Pular para o conteúdo principal
POST
Reembolsar pagamento

Autorizações

Authorization
string
header
obrigatório

Chave secreta da conta: Authorization: Bearer sk_test_… ou sk_live_…. Use só no servidor.

Cabeçalhos

Idempotency-Key
string

Chave única por operação (um UUID serve). Repetir com a mesma chave devolve a resposta original.

Parâmetros de caminho

paymentID
string
obrigatório
Pattern: ^pay_[0-9A-Za-z]{22}$
Exemplo:

"pay_585vbbvnwDyuyeA3MTOitd"

Corpo

application/json
amount
string

Valor a devolver, em texto decimal. Vazio ou omitido devolve o valor total.

reasonCode
enum<string>
Opções disponíveis:
requested_by_customer,
duplicate,
fraudulent,
product_issue,
other
reason
string

Motivo do reembolso, para o seu registro.

Maximum string length: 1000
revokeAccess
boolean

Se o download do produto digital para de funcionar. Omita para o comportamento padrão, que serve em quase todo caso: reembolso total corta o acesso, parcial mantém. Envie false para devolver tudo e deixar o comprador com o arquivo; envie true para cortar o acesso num reembolso parcial. Com o acesso cortado, o link de download responde 410.

Resposta

O pagamento após o reembolso.

Uma tentativa de cobrança contra uma fatura. Uma fatura pode ter vários pagamentos.

id
string
obrigatório
Pattern: ^pay_[0-9A-Za-z]{22}$
Exemplo:

"pay_585vbbvnwDyuyeA3MTOitd"

invoiceId
string
obrigatório
Pattern: ^inv_[0-9A-Za-z]{22}$
Exemplo:

"inv_6yi30EKotIwGHZdePSdsFc"

provider
string
obrigatório

Processador por onde a cobrança passou. Em sandbox, sandbox.

method
enum<string>
obrigatório
Opções disponíveis:
pix,
card
amount
string
obrigatório

Valor cobrado, em texto decimal.

currency
string
obrigatório
status
enum<string>
obrigatório

pending aguarda pagamento; confirmed foi pago; failed não foi pago (veja failureCode); refunded foi reembolsado por inteiro; charged_back foi contestado pelo comprador no banco.

Opções disponíveis:
pending,
confirmed,
failed,
refunded,
charged_back
createdAt
string<date-time>
obrigatório
switchable
boolean
obrigatório

Se esta cobrança ainda pode ser abandonada para pagar a mesma fatura de outro jeito: true enquanto está pending, false depois de paga ou falhada. Vem só na resposta da criação da cobrança; trate ausência como false.

providerId
string | null

Referência da cobrança no processador, útil para suporte.

refundedAmount
string

Total já reembolsado, em texto decimal. Ausente quando nada foi reembolsado. Um reembolso parcial mantém o status em confirmed; só o reembolso do valor inteiro muda para refunded. Use este campo, e não o status, para saber quanto voltou.

failureCode
enum<string> | null

Por que a cobrança falhou. superseded não é recusa: o comprador trocou de meio de pagamento para pagar a mesma fatura. Nulo quando o pagamento não falhou ou quando o motivo não foi registrado. Novos códigos podem surgir; trate um valor desconhecido como falha genérica.

Opções disponíveis:
insufficient_funds,
do_not_honor,
card_declined,
authentication_required,
card_expired,
card_stolen,
card_invalid,
mandate_revoked,
mandate_refused,
brand_changed,
provider_error,
provider_timeout,
superseded,
null
failedAt
string<date-time> | null

Quando a cobrança passou para failed.

payer
object | null

Quem pagou. Em fatura avulsa, id é o ID do cliente; em fatura de assinatura, é o ID da inscrição do cliente no produto. Vem só em GET /billing/payments e GET /billing/payments/{paymentID}, e é nulo quando a fatura não identifica o cliente.

invoiceUrl
string

Página de pagamento hospedada. Vem só na resposta da criação da cobrança.

pixPayload
string

Código Pix copia e cola. Gere o QR a partir dele. Continua disponível nas consultas seguintes do pagamento.

pixQrImage
string

O QR do Pix em PNG, codificado em base64 (sem o prefixo data:), para quem prefere não gerar o QR.

pixExpiresAt
string<date-time> | null

Quando o código Pix expira (só cobranças Pix).

checkoutAction
object

Dados para montar o pagamento com cartão em venda internacional, pela BEINFI LTD. Em breve.