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
integer
required
The cash-in ID (payin ID) for which the refund will be created.Example:
63730Request Body
integer
required
The refund amount.Example:
10string
required
Reason for the refund.Example:
"Teste"string
URL to receive webhook notifications about refund status changes.
Response
integer
Refund ID.
integer
The ID of the payin (cash-in) being refunded.
integer
Current status ID of the refund.Status codes:
2: Requested4: Paid (refund completed)5: Error
integer
Client ID.
integer
Refund amount.
array
string
End-to-end ID (for Pix transactions). Can be
null.string
Reason for the refund.
string
Error code from wallet (if any). Can be
null.string
URL for webhook notifications. Can be
null.string
Refund created date.
string
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

