Confirmar reembolso realizado
curl --request POST \
--url https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{}'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm"
payload = {}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Refund not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "No refundable payment found"
}
}{
"error": "Idempotency key already used with a different request body"
}Reembolsos
Confirmar reembolso realizado
Encerra um reembolso de boleto depois que a sua própria conta devolveu o dinheiro ao comprador.
POST
/
refunds
/
{id}
/
confirm
Confirmar reembolso realizado
curl --request POST \
--url https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{}'const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({})
};
fetch('https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.sandbox.z2pay.com/v1/refunds/{id}/confirm"
payload = {}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"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)"
}
]
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid API key"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Refund not found"
}
}{
"error": {
"code": "CONFLICT",
"message": "No refundable payment found"
}
}{
"error": "Idempotency key already used with a different request body"
}POST /refunds/:id/confirm
Faz parte do recurso Reembolsos — o objeto, os status e o ciclo estão lá.
Reembolso de boleto sai por transferência feita à mão, e quem faz a transferência é quem sabe que
ela aconteceu. Este endpoint é a porta de quem devolveu: ele marca o reembolso como refunded e
dispara o webhook refund.refunded.
Ele existe apenas para as contas que assumem a devolução em contrato. Quando quem devolve é a
plataforma, a confirmação é nossa — e a resposta aqui é 409.
409 quando a devolução não é sua. Confirmar é declarar que o dinheiro saiu; se saiu do nosso
caixa, aceitar a declaração de fora inverteria quem responde pelo valor. A sua tela de
configurações de reembolso mostra quem devolve nesta conta.transferNote é obrigatória quando o reembolso não tem dados bancários registrados — ou seja,
quando ele ainda está em awaiting_bank_details porque a conta do comprador foi coletada no seu
sistema e nunca passou por aqui. Nesse caso a nota é o único registro de que a transferência
existiu; sem ela, a resposta é 400. Com os dados já registrados por
POST /refunds/:id/bank-details, ela é opcional e continua sendo o
melhor lugar para o identificador da transferência.A transação continua
paid depois desta confirmação. O dinheiro não passou por nós: o valor da
venda permanece no seu saldo e nada é debitado da sua carteira. Marcar a transação como estornada
diria que a venda foi desfeita nos nossos números, quando ela continua paga — então o reembolso
aparece no recurso de reembolsos e nos eventos refund.*, e não no status da transação. Isso vale
só para este modo; quando a plataforma devolve, a transação segue o desfecho normal do estorno.Status que aceitam confirmação:
bank_details_received, ted_processing, failed e —
exclusivamente neste modo — awaiting_bank_details. Qualquer outro responde 409. Um reembolso já
refunded não é reconfirmado: a segunda chamada falha, em vez de ser ignorada.Endpoint idempotente. Envie o header
Idempotency-Key para que um retry por timeout não confirme
duas vezes. Veja Convenções.Exemplo
curl -X POST https://api.sandbox.z2pay.com/v1/refunds/rfd_j3cpkaysqmix17mxhcmv8qypl/confirm \
-H "x-api-key: $Z2PAY_API_KEY" \
-H "Idempotency-Key: 9d2f7c30-5a18-4e6b-8c74-1f3b0a9e5d21" \
-H "Content-Type: application/json" \
-d '{
"transferNote": "Pix 10/09/2026, E12345678202609101430"
}'
{
"id": "rfd_j3cpkaysqmix17mxhcmv8qypl",
"transactionId": "txn_aqbcw2lky42xfidw5pcdss8h1",
"paymentId": "pay_jxt9b5qv1x0h0h8ustleqjgr8",
"amount": 14990,
"currency": "BRL",
"status": "refunded",
"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": "2025-06-30T09:31:02.000Z",
"createdAt": "2025-06-29T13:45:30.000Z",
"updatedAt": "2025-06-30T09:31:02.000Z"
}
Authorizations
API Key da Credential (gerada no Backoffice)
Headers
Chave única para garantir idempotência da requisição
Path Parameters
ID do refund
Body
application/json
Como a transferência foi feita — meio, data e identificador (ex: PIX 10/09, E12345678). Obrigatória quando o reembolso está em awaiting_bank_details.
Maximum string length:
1000Response
Reembolso confirmado