Estornar pagamento

Estornar payment

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "reason": "<string>",
  "amount": 1
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: '<string>', amount: 1})
};

fetch('https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund"

payload = {
    "reason": "<string>",
    "amount": 1
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "refund": {
    "id": "rfd_dt8xoet16jhqxrgn76f0x25vg",
    "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
    "paymentId": "pay_k0fg3q4jjcbi56hdhbi7xlj5e",
    "amount": 9995,
    "currency": "BRL",
    "status": "refunded",
    "reason": "Estorno parcial - produto avariado",
    "requestedByType": "api",
    "paymentMethod": "credit_card",
    "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
    "customerName": "Maria Silva",
    "customerEmail": "maria.silva@example.com",
    "customerDocument": "12345678909",
    "customerDocumentType": "cpf",
    "additionalInfo": {
      "checkoutLinkId": "chk_byd8p3p79re859jpkmr0j65n3"
    },
    "failureReason": null,
    "reviewedAt": null,
    "refundedAt": "2025-06-29T14:10:00.000Z",
    "createdAt": "2025-06-29T14:09:55.000Z",
    "updatedAt": "2025-06-29T14:10:00.000Z"
  },
  "processResult": {
    "success": true,
    "refund": {
      "id": "rfd_dt8xoet16jhqxrgn76f0x25vg",
      "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
      "paymentId": "pay_k0fg3q4jjcbi56hdhbi7xlj5e",
      "amount": 9995,
      "currency": "BRL",
      "status": "refunded",
      "reason": "Estorno parcial - produto avariado",
      "requestedByType": "api",
      "paymentMethod": "credit_card",
      "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
      "customerName": "Maria Silva",
      "customerEmail": "maria.silva@example.com",
      "customerDocument": "12345678909",
      "customerDocumentType": "cpf",
      "additionalInfo": {
        "checkoutLinkId": "chk_byd8p3p79re859jpkmr0j65n3"
      },
      "failureReason": null,
      "reviewedAt": null,
      "refundedAt": "2025-06-29T14:10:00.000Z",
      "createdAt": "2025-06-29T14:09:55.000Z",
      "updatedAt": "2025-06-29T14:10:00.000Z"
    },
    "message": "Refund processado com sucesso"
  }
}

{
  "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": "Payment not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "No refundable payment found"
  }
}

{
  "error": "Idempotency key already used with a different request body"
}

POST

transactions

{transactionId}

payments

{paymentId}

refund

Estornar payment

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "reason": "<string>",
  "amount": 1
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({reason: '<string>', amount: 1})
};

fetch('https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/transactions/{transactionId}/payments/{paymentId}/refund"

payload = {
    "reason": "<string>",
    "amount": 1
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "refund": {
    "id": "rfd_dt8xoet16jhqxrgn76f0x25vg",
    "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
    "paymentId": "pay_k0fg3q4jjcbi56hdhbi7xlj5e",
    "amount": 9995,
    "currency": "BRL",
    "status": "refunded",
    "reason": "Estorno parcial - produto avariado",
    "requestedByType": "api",
    "paymentMethod": "credit_card",
    "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
    "customerName": "Maria Silva",
    "customerEmail": "maria.silva@example.com",
    "customerDocument": "12345678909",
    "customerDocumentType": "cpf",
    "additionalInfo": {
      "checkoutLinkId": "chk_byd8p3p79re859jpkmr0j65n3"
    },
    "failureReason": null,
    "reviewedAt": null,
    "refundedAt": "2025-06-29T14:10:00.000Z",
    "createdAt": "2025-06-29T14:09:55.000Z",
    "updatedAt": "2025-06-29T14:10:00.000Z"
  },
  "processResult": {
    "success": true,
    "refund": {
      "id": "rfd_dt8xoet16jhqxrgn76f0x25vg",
      "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
      "paymentId": "pay_k0fg3q4jjcbi56hdhbi7xlj5e",
      "amount": 9995,
      "currency": "BRL",
      "status": "refunded",
      "reason": "Estorno parcial - produto avariado",
      "requestedByType": "api",
      "paymentMethod": "credit_card",
      "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
      "customerName": "Maria Silva",
      "customerEmail": "maria.silva@example.com",
      "customerDocument": "12345678909",
      "customerDocumentType": "cpf",
      "additionalInfo": {
        "checkoutLinkId": "chk_byd8p3p79re859jpkmr0j65n3"
      },
      "failureReason": null,
      "reviewedAt": null,
      "refundedAt": "2025-06-29T14:10:00.000Z",
      "createdAt": "2025-06-29T14:09:55.000Z",
      "updatedAt": "2025-06-29T14:10:00.000Z"
    },
    "message": "Refund processado com sucesso"
  }
}

{
  "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": "Payment not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "No refundable payment found"
  }
}

{
  "error": "Idempotency key already used with a different request body"
}

POST /transactions/:transactionId/payments/:paymentId/refund Faz parte do recurso Pagamentos — o ciclo de vida do pagamento está lá, e o do estorno em Reembolsos. Abre um pedido de estorno para um pagamento. É a rota a usar quando a transação tem mais de um pagamento e você quer devolver só um deles — para devolver a transação inteira, use POST /transactions/{id}/refund.

O 200 cria um pedido, não devolve o dinheiro. O estorno nasce como rfd_ e segue o próprio ciclo — pode precisar de aprovação, e o prazo de volta é da adquirente. Acompanhe por GET /refunds/{id}; tratar esta resposta como “estornado” antecipa um fato que ainda não aconteceu.

Se aprova sozinho ou não, é configuração da sua conta. Com auto-aprovação, o pedido já sai encaminhado; sem ela, fica aguardando decisão. A mesma chamada, portanto, tem desfechos diferentes em contas diferentes — não assuma um deles no código.

amount faz o estorno parcial. Omitido, devolve o valor total do pagamento. Em centavos, e nunca maior do que o que resta a estornar.

Os dois ids do caminho são conferidos juntos. Um paymentId que exista mas pertença a outra transação não é aceito — o transactionId da URL é afirmação sobre o pagamento, não enfeite.

Exemplo

curl -X POST https://api.sandbox.z2pay.com/v1/transactions/txn_ebgsvfsb4151nmbgvj4sek6ol/payments/pay_kd6z67zbp52rgtg2idms96fhm/refund \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "reason": "Cliente desistiu de um dos itens" }'

O reason é obrigatório — sem ele a chamada responde 400 de validação.

Resposta 200

{
  "refund": {
    "id": "rfd_z3w8qmc4nx1te7bkhjs0dvpra",
    "paymentId": "pay_kd6z67zbp52rgtg2idms96fhm",
    "transactionId": "txn_ebgsvfsb4151nmbgvj4sek6ol",
    "amount": 5000,
    "reason": "Cliente desistiu de um dos itens",
    "status": "pending",
    "createdAt": "2026-08-11T14:05:00.000Z"
  },
  "processResult": null
}

A resposta é o par { refund, processResult } — o mesmo formato, no singular, que o estorno da transação inteira devolve no plural. processResult vem preenchido quando o estorno é processado na hora (aprovação automática), com success e o estorno atualizado.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Headers

Idempotency-Key

string

Chave única para garantir idempotência da requisição

Path Parameters

paymentId

string

required

ID do payment

transactionId

string

required

ID da transação

Body

application/json

reason

string

required

Motivo do estorno (obrigatório, 1–4000 chars).

Required string length: 1 - 4000

amount

integer

Valor a estornar, em centavos; omitido estorna o valor total do payment (parciais não podem exceder o saldo disponível).

Required range: x > 0

Response

Refund criado e processado

refund

object

Dados do estorno relacionado ao pagamento.

Show child attributes

processResult

object

Resultado do processamento da operação.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Exemplo

Authorizations

Headers

Path Parameters

Body

Response

​Exemplo

Authorizations

Headers

Path Parameters

Body

Response

Exemplo