> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Informar dados bancários do reembolso
> Registra a conta de destino de um reembolso de boleto que aguarda dados bancários, quando é você que coleta esses dados do comprador.
`POST /refunds/:id/bank-details`
Faz parte do recurso [Reembolsos](/pt-BR/refunds) — o objeto, os status e o ciclo estão lá.
Boleto não estorna pela bandeira: o valor volta por transferência, e é preciso saber para qual
conta. Enquanto ninguém informa esse destino, o reembolso fica em `awaiting_bank_details`. Este
endpoint registra a conta e leva o reembolso a `bank_details_received`, disparando o webhook
`refund.bank_details_received`.
Por padrão quem pergunta ao comprador somos nós, por e-mail, e você não precisa fazer nada — mas a
sua conta pode ser configurada, no painel, para que esse e-mail não seja enviado. É o caso de quem
já atende o próprio comprador e prefere coletar a conta pelo canal dele. Aí este endpoint passa a
ser o caminho: sem ele, o reembolso esperaria um e-mail que não sai. Com o e-mail ligado ele também
funciona — vale quem responder primeiro, você ou o comprador.
**Cada método de transferência exige os seus campos, e a falta deles é `400`.** Com
`transferMethod: "pix"`, `pixKeyType` e `pixKey` são obrigatórios. Com `"bank_account"`, são
`bankCode`, `branch`, `accountNumber`, `accountDigit` e `accountType`. Não há preenchimento
parcial: uma conta sem destino utilizável seria um reembolso marcado como pronto que nunca liquida.
**Chave Pix só é aceita quando é a sua conta que devolve o dinheiro.** Quando a devolução é
executada pela plataforma — o padrão —, o destino tem de ser conta bancária, e `"pix"` responde
`400`. Quem executa a devolução é definido em contrato; a sua tela de configurações de reembolso
mostra qual dos dois vale para a sua conta.
**A conta é conferida antes de ser aceita, e as pendências vêm todas de uma vez.** São recusadas
com `400`: banco fora dos que atendemos, agência ou conta fora do formato daquele banco, valores
que não podem ser reais (`0000`, `99999`) e tipo de conta que não recebe crédito de terceiros —
conta salário não recebe. Leia `error.issues[]`: cada item traz o campo e o motivo, para você
corrigir a conta inteira numa rodada em vez de descobrir um problema por tentativa.
**O dígito da agência não se inventa.** Ele é exigido nos bancos cuja agência tem dígito — Banco
do Brasil e Bradesco, entre outros; Itaú e Nubank não têm — e o **valor** é conferido contra a
agência informada, não apenas a presença. Preencher `0` para "passar" acerta em cerca de um caso
em onze; nos outros dez a transferência era recusada pelo banco dias depois, com o reembolso já
registrado como pronto e o comprador esperando. O campo aceita um único caractere: `0`-`9`, ou
`X`/`P` nos bancos que usam letra no lugar do dez. O dígito está impresso no extrato.
**Reembolso que já tem destino registrado responde `409`, e reenviar não corrige.** O endpoint não
sobrescreve conta: se os dados estiverem errados, fale com o nosso time — a operação invalida o
registro, o reembolso volta para `awaiting_bank_details` e aí a conta certa é aceita. Não há
caminho automático para isso.
Endpoint idempotente. Envie o header `Idempotency-Key` para que um retry por timeout não registre
a conta duas vezes. Veja [Convenções](/pt-BR/convencoes).
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/refunds/rfd_j3cpkaysqmix17mxhcmv8qypl/bank-details \
-H "x-api-key: $Z2PAY_API_KEY" \
-H "Idempotency-Key: 4f8c1e9a-7b21-4c3d-9f10-2ab8c5d6e7f0" \
-H "Content-Type: application/json" \
-d '{
"transferMethod": "bank_account",
"holderName": "Maria Silva",
"holderDocument": "52998224725",
"bankCode": "237",
"branch": "1850",
"branchDigit": "3",
"accountNumber": "208734",
"accountDigit": "5",
"accountType": "checking"
}'
```
```json theme={null}
{
"id": "rfd_j3cpkaysqmix17mxhcmv8qypl",
"transactionId": "txn_aqbcw2lky42xfidw5pcdss8h1",
"paymentId": "pay_jxt9b5qv1x0h0h8ustleqjgr8",
"amount": 14990,
"currency": "BRL",
"status": "bank_details_received",
"reason": "Cliente solicitou cancelamento da compra",
"requestedByType": "api",
"paymentMethod": "boleto",
"customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
"customerName": "Maria Silva",
"customerEmail": "maria.silva@example.com",
"customerDocument": "12345678909",
"customerDocumentType": "cpf",
"additionalInfo": null,
"failureReason": null,
"reviewedAt": "2025-06-29T14:02:11.000Z",
"refundedAt": null,
"createdAt": "2025-06-29T13:45:30.000Z",
"updatedAt": "2025-06-29T15:10:44.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json POST /refunds/{id}/bank-details
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Receivables
description: >-
Recebíveis: o que cada venda vai depositar na carteira, por recebedor e
parcela, com data prevista e status
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/refunds/{id}/bank-details:
post:
tags:
- Refunds
summary: Informar dados bancários do reembolso
description: >-
Registra a conta de destino de um reembolso de boleto que aguarda dados
bancários (`awaiting_bank_details`). O reembolso avança para
`bank_details_received` e dispara o webhook
`refund.bank_details_received`.
operationId: RefundController_submitBankDetails
parameters:
- name: id
in: path
required: true
description: ID do refund
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
transferMethod:
type: string
enum:
- pix
- bank_account
description: >-
Destino do dinheiro: `bank_account` (TED) ou `pix`. `pix` só
é aceito quando a devolução é executada pela própria conta,
não pela plataforma.
holderName:
type: string
minLength: 3
description: Nome do titular da conta, como consta no banco.
holderDocument:
type: string
minLength: 11
maxLength: 14
description: CPF ou CNPJ do titular da conta, somente dígitos.
pixKeyType:
type: string
enum:
- cpf
- email
- phone
- random
pixKey:
type: string
bankCode:
type: string
description: 'Código COMPE do banco, três dígitos (ex: `341`).'
branch:
type: string
description: Agência sem o dígito, somente números.
branchDigit:
type: string
description: >-
Dígito da agência. Obrigatório nos bancos que o emitem — o
valor é conferido, então não preencha com `0` para "passar".
accountNumber:
type: string
description: Número da conta sem o dígito, somente números.
accountDigit:
type: string
description: Dígito verificador da conta.
accountType:
type: string
enum:
- checking
- savings
description: >-
`checking` (corrente) ou `savings` (poupança). Conta salário
não recebe crédito.
required:
- transferMethod
- holderName
- holderDocument
responses:
'200':
description: Dados bancários registrados
'400':
description: Dados bancários incompletos ou conta não aceita
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Refund não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Refund not found
'409':
description: >-
Refund não está aguardando dados bancários — ou a mesma
Idempotency-Key ainda está em curso
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: CONFLICT
message: No refundable payment found
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````