Reembolsar Checkout Transparente
curl --request POST \
--url https://api.abacatepay.com/v2/transparents/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "bill_abc123xyz",
"reason": "Pedido cancelado pelo cliente."
}
'import requests
url = "https://api.abacatepay.com/v2/transparents/refund"
payload = {
"id": "bill_abc123xyz",
"reason": "Pedido cancelado pelo cliente."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({id: 'bill_abc123xyz', reason: 'Pedido cancelado pelo cliente.'})
};
fetch('https://api.abacatepay.com/v2/transparents/refund', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.abacatepay.com/v2/transparents/refund",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => 'bill_abc123xyz',
'reason' => 'Pedido cancelado pelo cliente.'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.abacatepay.com/v2/transparents/refund"
payload := strings.NewReader("{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.abacatepay.com/v2/transparents/refund")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.abacatepay.com/v2/transparents/refund")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"refundPublicId": "tran_refund789xyz"
},
"error": null,
"success": true
}{
"data": null,
"error": "TRANSACTION_UNDER_DISPUTE",
"success": false
}{
"error": "Token de autenticação inválido ou ausente."
}Checkout Transparente
Reembolsar Checkout Transparente
Reembolsa integralmente um pagamento transparente (PIX ou Cartão). O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados.
POST
/
transparents
/
refund
Reembolsar Checkout Transparente
curl --request POST \
--url https://api.abacatepay.com/v2/transparents/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "bill_abc123xyz",
"reason": "Pedido cancelado pelo cliente."
}
'import requests
url = "https://api.abacatepay.com/v2/transparents/refund"
payload = {
"id": "bill_abc123xyz",
"reason": "Pedido cancelado pelo cliente."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({id: 'bill_abc123xyz', reason: 'Pedido cancelado pelo cliente.'})
};
fetch('https://api.abacatepay.com/v2/transparents/refund', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.abacatepay.com/v2/transparents/refund",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'id' => 'bill_abc123xyz',
'reason' => 'Pedido cancelado pelo cliente.'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.abacatepay.com/v2/transparents/refund"
payload := strings.NewReader("{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.abacatepay.com/v2/transparents/refund")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.abacatepay.com/v2/transparents/refund")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"id\": \"bill_abc123xyz\",\n \"reason\": \"Pedido cancelado pelo cliente.\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"refundPublicId": "tran_refund789xyz"
},
"error": null,
"success": true
}{
"data": null,
"error": "TRANSACTION_UNDER_DISPUTE",
"success": false
}{
"error": "Token de autenticação inválido ou ausente."
}Reembolsa integralmente um pagamento transparente (PIX QR Code ou Cartão). O valor reembolsado é igual ao valor original da transação — não há reembolso parcial.
O campo
Exemplo mínimo:
Exemplo com motivo:
Resposta:
Exemplo de erro:
Obrigatório
Apenas
id é obrigatório — o ID público do recurso a reembolsar.id aceita:
| Prefixo | Recurso |
|---|---|
pix_char_... | ID público da cobrança PIX transparente |
card_... | ID público da cobrança no cartão |
char_... | ID público do payment intent (genérico) |
{
"id": "pix_char_abc123xyz"
}
{
"id": "pix_char_abc123xyz",
"reason": "Cliente pagou em duplicidade."
}
{
"data": { "refundPublicId": "tran_refund789xyz" },
"success": true,
"error": null
}
Chamar o endpoint para o mesmo
id retorna sempre o mesmo refundPublicId — não cria reembolsos duplicados.Regras de negócio
- Reembolso total apenas — o valor é sempre igual ao valor original da transação.
- Métodos suportados —
PIX,PIX_QRCODEeCARD. Boletos transparentes não são reembolsáveis via API. - Estado exigido:
PIX/PIX_QRCODE— transação precisa estarCOMPLETE.CARD— transação precisa estarAPPROVEDouCOMPLETE.
- Disputas — transações em disputa (
UNDER_DISPUTEoumetadata.underDispute=true) não podem ser reembolsadas por este endpoint. - Saldo — o valor é debitado do saldo
availableda loja (oupending, em casos específicos deCARD). Sem saldo, retornaINSUFFICIENT_FUNDS. - Modo dev (sandbox) — em
devModeo reembolso é confirmado instantaneamente, sem chamar o provider real. - Status final após o reembolso:
- A transação original vira
REFUNDED. - O payment intent vira
REFUNDED. - É criada uma nova transação
WITHDRAWrepresentando o reembolso (retornada emrefundPublicId).
- A transação original vira
Ao concluir, é disparado o webhook
transparent.refunded (ou checkout.refunded quando houver um billing associado à cobrança). Configure seu endpoint em Webhooks para receber a notificação.Códigos de erro
| Código | Significado |
|---|---|
LOCK_NOT_ACQUIRED | Outra operação está em andamento para esta loja — tente novamente em instantes. |
TRANSACTION_NOT_FOUND | O id informado não existe ou não pertence à loja. |
TRANSACTION_NOT_REFUNDABLE | A transação não está em um estado reembolsável (precisa estar COMPLETE, ou APPROVED/COMPLETE para CARD). |
TRANSACTION_UNDER_DISPUTE | Transação em disputa — não pode ser reembolsada. |
INVALID_METHOD | Apenas PIX, PIX_QRCODE e CARD podem ser reembolsados. |
INSUFFICIENT_FUNDS | Saldo da loja menor que o valor da transação. |
STORE_NOT_FOUND | Loja não encontrada. |
REFUND_REQUEST_FAILED | Falha ao criar a transação no ledger ou ao acionar o provider. |
REFUND_CONFIRMATION_FAILED | Falha ao confirmar o reembolso após a criação. |
{
"data": null,
"success": false,
"error": "TRANSACTION_NOT_REFUNDABLE"
}
Exemplo cURL
curl -X POST https://api.abacatepay.com/v2/transparents/refund \
-H "Authorization: Bearer $ABACATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "pix_char_abc123xyz",
"reason": "Cliente pagou em duplicidade."
}'
Authorizations
Todas as requisições devem incluir sua chave de API no header Authorization usando o formato Bearer <abacatepay-api-key>. Sem esse header a requisição será rejeitada.
Saiba mais sobre como criar e usar chaves de API na documentação de autenticação.
Body
application/json
ID público do recurso a reembolsar. Aceita os prefixos char_ / pix_char_ / card_ (payment intent) ou bill_ (billing — resolvido para o payment intent pago).
Example:
"bill_abc123xyz"
Motivo do reembolso. Aparece no histórico da transação.
Maximum string length:
500Example:
"Pedido cancelado pelo cliente."
Was this page helpful?