Request refund of received payment (Refund-In)

POST /api/pix/refund-in/{id}

POST https://api.avista.global/api/pix/refund-in/{id}

Requires a Bearer token in the Authorization header. See Generate Token to obtain one.

Requests a refund of a received PIX payment. The refund can be partial or full, as long as it is within the 89-day deadline.

Authentication

Requires a Bearer token in the Authorization header.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	ID of the original transaction to be refunded

Request Body

Field	Type	Required	Description
`refundValue`	number	Yes	Amount to be refunded in BRL (can be partial). Minimum: 0.01
`reason`	string	No	Reason for the refund
`externalId`	string	No	External ID for identifying the refund. In the BACEN API, this corresponds to the `id` URL parameter

{
  "refundValue": 50.00,
  "reason": "Cliente solicitou devolução",
  "externalId": "D123456789"
}

Code Examples

cURL

curl -X POST "https://api.avista.global/api/pix/refund-in/12345" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refundValue": 50.00,
  "reason": "Cliente solicitou devolução",
  "externalId": "D123456789"
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/refund-in/12345',
  {
  "refundValue": 50.00,
  "reason": "Cliente solicitou devolução",
  "externalId": "D123456789"
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/pix/refund-in/12345',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "refundValue": 50.00,
  "reason": "Cliente solicitou devolução",
  "externalId": "D123456789"
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/refund-in/12345');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "refundValue": 50.00,
  "reason": "Cliente solicitou devolução",
  "externalId": "D123456789"
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "refundValue": 50.00,
      "reason": "Cliente solicitou devolução",
      "externalId": "D123456789"
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/refund-in/12345"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response (201)

Field	Type	Description
`transactionId`	string	ID of the generated refund transaction
`externalId`	string	External ID of the refund transaction
`status`	string	Current refund transaction status (`PENDING`, `CONFIRMED`, `ERROR`)
`refundValue`	number	Refund amount in BRL
`providerTransactionId`	string	Provider transaction ID (used for correlation with webhooks)
`generateTime`	string	Refund transaction generation date/time (ISO 8601)

{
  "transactionId": "789",
  "externalId": "D123456789",
  "status": "PENDING",
  "refundValue": 50.00,
  "providerTransactionId": "7ef4fc3f-a187-495e-857c-e84d70612761",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

Errors

Status	Description
400	Invalid data, transaction not found, deadline exceeded, or invalid amount
401	Missing or invalid token
404	Parent transaction not found
500	Error processing refund request