curl --request POST \
--url https://api-gateway.pague.dev/v2/transactions/{id}/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "Cliente solicitou cancelamento"
}
'import requests
url = "https://api-gateway.pague.dev/v2/transactions/{id}/refund"
payload = { "reason": "Cliente solicitou cancelamento" }
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({reason: 'Cliente solicitou cancelamento'})
};
fetch('https://api-gateway.pague.dev/v2/transactions/{id}/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-gateway.pague.dev/v2/transactions/{id}/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([
'reason' => 'Cliente solicitou cancelamento'
]),
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-gateway.pague.dev/v2/transactions/{id}/refund"
payload := strings.NewReader("{\n \"reason\": \"Cliente solicitou cancelamento\"\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-gateway.pague.dev/v2/transactions/{id}/refund")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Cliente solicitou cancelamento\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-gateway.pague.dev/v2/transactions/{id}/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 \"reason\": \"Cliente solicitou cancelamento\"\n}"
response = http.request(request)
puts response.read_body{
"originalTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pspProvider": "<string>",
"pspRefundTransactionId": "<string>",
"status": "PENDING"
}{
"statusCode": 400,
"error": "BadRequest",
"message": "name must be longer than or equal to 2 characters",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication token is required",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 404,
"error": "NotFound",
"message": "Resource with id 550e8400-e29b-41d4-a716-446655440000 not found",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {
"resource": "Example",
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"traceId": "<string>"
}{
"statusCode": 500,
"error": "InternalError",
"message": "An unexpected error occurred",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "2771463d58840c8e116dc6dda1e1e5d0"
}Request Refund
Requests a full refund of the given payment transaction. The refund is asynchronous — confirmation arrives via the refund_completed webhook once the PSP processes it.
Required permission: REFUND:WRITE or FULL_ACCESS
curl --request POST \
--url https://api-gateway.pague.dev/v2/transactions/{id}/refund \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reason": "Cliente solicitou cancelamento"
}
'import requests
url = "https://api-gateway.pague.dev/v2/transactions/{id}/refund"
payload = { "reason": "Cliente solicitou cancelamento" }
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({reason: 'Cliente solicitou cancelamento'})
};
fetch('https://api-gateway.pague.dev/v2/transactions/{id}/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-gateway.pague.dev/v2/transactions/{id}/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([
'reason' => 'Cliente solicitou cancelamento'
]),
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-gateway.pague.dev/v2/transactions/{id}/refund"
payload := strings.NewReader("{\n \"reason\": \"Cliente solicitou cancelamento\"\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-gateway.pague.dev/v2/transactions/{id}/refund")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Cliente solicitou cancelamento\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-gateway.pague.dev/v2/transactions/{id}/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 \"reason\": \"Cliente solicitou cancelamento\"\n}"
response = http.request(request)
puts response.read_body{
"originalTransactionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pspProvider": "<string>",
"pspRefundTransactionId": "<string>",
"status": "PENDING"
}{
"statusCode": 400,
"error": "BadRequest",
"message": "name must be longer than or equal to 2 characters",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication token is required",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "<string>"
}{
"statusCode": 404,
"error": "NotFound",
"message": "Resource with id 550e8400-e29b-41d4-a716-446655440000 not found",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {
"resource": "Example",
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"traceId": "<string>"
}{
"statusCode": 500,
"error": "InternalError",
"message": "An unexpected error occurred",
"timestamp": "2025-12-15T22:00:00.000Z",
"details": {},
"traceId": "2771463d58840c8e116dc6dda1e1e5d0"
}Authorizations
Access token obtained from POST /auth (client_id + client_secret). Valid for 300 seconds.
Headers
Reference of the sub-account the operation runs against. When omitted, the operation happens on the main account; the reserved value principal also resolves to the main account and is equivalent to omitting the header. Accepted on every endpoint except POST /auth and the /sub-accounts endpoints themselves, which always operate on the main account.
Possible errors: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.
Requires the credential to have sub-account access enabled (Settings → Integration → API Credentials). It starts turned off and is not replaced by any permission, not even FULL_ACCESS: without it the response is 403 SUB_ACCOUNT_FORBIDDEN.
^[a-z0-9][a-z0-9_-]{1,31}$"loja-centro"
Path Parameters
ID of the payment transaction to be refunded
Body
Refund reason (optional, up to 255 characters)
255"Cliente solicitou cancelamento"
Response
Refund requested successfully. Status remains PENDING until confirmation via webhook.
ID of the original transaction being refunded
PSP provider that processed the refund
Refund transaction ID at the PSP
Status returned by the PSP. PENDING means the refund was accepted but not yet confirmed — confirmation arrives via the refund_completed webhook.
PENDING, CONFIRMED, ERROR "PENDING"

