Create Refund
curl --request POST \
--url https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 123,
"reason": "<string>",
"notification_url": "<string>"
}
'import requests
url = "https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}"
payload = {
"amount": 123,
"reason": "<string>",
"notification_url": "<string>"
}
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({amount: 123, reason: '<string>', notification_url: '<string>'})
};
fetch('https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}', 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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}",
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([
'amount' => 123,
'reason' => '<string>',
'notification_url' => '<string>'
]),
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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}"
payload := strings.NewReader("{\n \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}")
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 \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"payin_id": 456,
"status_id": 2,
"user": {
"id": 789,
"name": "João Silva"
},
"client_id": 10,
"refund_amount": 10000,
"status_history": [
{
"id": 1,
"payin_refund_id": 123,
"statusId": 1,
"status_id": 1,
"name": "Check",
"notification": 1,
"created_at": "2026-02-19T12:34:56.000000Z"
}
],
"end_to_end_id": "E12345678202602191234567890AB",
"reason": "Customer requested cancellation",
"wallet_error_code": null,
"notification_url": "https://example.com/webhook",
"created_at": "2026-02-19T12:34:56.000000Z",
"updated_at": "2026-02-19T12:34:56.000000Z"
}
{
"message": "Bad request message"
}
{
"error": "Unauthorized"
}
{
"message": "Payin not found"
}
{
"message": "The given data was invalid.",
"errors": {
"amount": [
"The amount field is required."
]
}
}
{
"error": "Internal server error"
}
Refund
Create Refund
Create a new refund. To initiate the refund, you must provide the unique identifier of the Pix or credit card payment in the parameter.
POST
/
v2
/
payin
/
payments
/
payin-refund
/
{id}
Create Refund
curl --request POST \
--url https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 123,
"reason": "<string>",
"notification_url": "<string>"
}
'import requests
url = "https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}"
payload = {
"amount": 123,
"reason": "<string>",
"notification_url": "<string>"
}
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({amount: 123, reason: '<string>', notification_url: '<string>'})
};
fetch('https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}', 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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}",
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([
'amount' => 123,
'reason' => '<string>',
'notification_url' => '<string>'
]),
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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}"
payload := strings.NewReader("{\n \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\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.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id}")
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 \"amount\": 123,\n \"reason\": \"<string>\",\n \"notification_url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"payin_id": 456,
"status_id": 2,
"user": {
"id": 789,
"name": "João Silva"
},
"client_id": 10,
"refund_amount": 10000,
"status_history": [
{
"id": 1,
"payin_refund_id": 123,
"statusId": 1,
"status_id": 1,
"name": "Check",
"notification": 1,
"created_at": "2026-02-19T12:34:56.000000Z"
}
],
"end_to_end_id": "E12345678202602191234567890AB",
"reason": "Customer requested cancellation",
"wallet_error_code": null,
"notification_url": "https://example.com/webhook",
"created_at": "2026-02-19T12:34:56.000000Z",
"updated_at": "2026-02-19T12:34:56.000000Z"
}
{
"message": "Bad request message"
}
{
"error": "Unauthorized"
}
{
"message": "Payin not found"
}
{
"message": "The given data was invalid.",
"errors": {
"amount": [
"The amount field is required."
]
}
}
{
"error": "Internal server error"
}
Some important rules
- Only charges credited to the wallet can be refunded.
- The customer must have at least the refund amount available in the wallet.
- Pix: can only be returned with 90 days or less.
- Credit card: 180 days or less.
Sandbox Testing
To test refund scenarios in the sandbox environment, the field
amount must be one of the following values: 100, 1000, or 10000.Additionally, you must include the field reason with the value “APRO”.Path Parameters
The cash-in ID (payin ID) for which the refund will be created.Example:
63730Request Body
The refund amount.Example:
10Reason for the refund.Example:
"Teste"URL to receive webhook notifications about refund status changes.
Response
Refund ID.
The ID of the payin (cash-in) being refunded.
Current status ID of the refund.Status codes:
2: Requested4: Paid (refund completed)5: Error
Client ID.
Refund amount.
End-to-end ID (for Pix transactions). Can be
null.Reason for the refund.
Error code from wallet (if any). Can be
null.URL for webhook notifications. Can be
null.Refund created date.
Refund update date.
{
"id": 123,
"payin_id": 456,
"status_id": 2,
"user": {
"id": 789,
"name": "João Silva"
},
"client_id": 10,
"refund_amount": 10000,
"status_history": [
{
"id": 1,
"payin_refund_id": 123,
"statusId": 1,
"status_id": 1,
"name": "Check",
"notification": 1,
"created_at": "2026-02-19T12:34:56.000000Z"
}
],
"end_to_end_id": "E12345678202602191234567890AB",
"reason": "Customer requested cancellation",
"wallet_error_code": null,
"notification_url": "https://example.com/webhook",
"created_at": "2026-02-19T12:34:56.000000Z",
"updated_at": "2026-02-19T12:34:56.000000Z"
}
{
"message": "Bad request message"
}
{
"error": "Unauthorized"
}
{
"message": "Payin not found"
}
{
"message": "The given data was invalid.",
"errors": {
"amount": [
"The amount field is required."
]
}
}
{
"error": "Internal server error"
}
Important Information About the Webhook metadata
Refund Status
| Status | Description | Status ID |
|---|---|---|
| Requested | The refund has been requested. | 2 |
| Paid | The refund has been successfully paid. | 4 |
| Error | An error occurred during the refund process. | 5 |
If an error occurs during the refund process (status 5), the field
total_refund_amount will be decremented by the requested amount. When the refund is successfully paid, the amount will be incremented again.Webhook Payload Examples:
Requested:{
"id": 123,
"payin_id": 456,
"status": {
"id": 2,
"name": "Requested"
},
"metadata": {
"refund_amount": 100.50,
"total_refund_amount": 250.75
},
"reason": "Customer requested cancellation",
"updated_at": "2026-02-19T12:34:56.000000Z"
}
{
"id": 123,
"payin_id": 456,
"status": {
"id": 5,
"name": "Error"
},
"metadata": {
"refund_amount": 100.50,
"total_refund_amount": 150.25
},
"reason": "Customer requested cancellation",
"updated_at": "2026-02-19T12:35:10.000000Z"
}
{
"id": 123,
"payin_id": 456,
"status": {
"id": 4,
"name": "Paid"
},
"metadata": {
"refund_amount": 100.50,
"total_refund_amount": 250.75
},
"reason": "Customer requested cancellation",
"updated_at": "2026-02-19T12:36:22.000000Z"
}
Refund Status Flow
Success scenario:REQUESTED (2) → PAID (4) ✓
REQUESTED (2) → ERROR (5) ✗
Was this page helpful?
⌘I

