Solicitar estorno de pagamento recebido (Refund-In)

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

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

Requer um Bearer token no header Authorization. Veja Gerar Token para obter um.

Solicita a devolução de um pagamento PIX recebido. O estorno pode ser parcial ou total, desde que dentro do prazo de 89 dias.

Autenticação

Requer token Bearer no header Authorization.

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	ID da transação original a ser estornada

Request Body

Campo	Tipo	Obrigatório	Descrição
`refundValue`	number	Sim	Valor a ser estornado em reais (pode ser parcial). Mínimo: 0.01
`reason`	string	Não	Motivo do estorno
`externalId`	string	Não	ID externo para identificação da devolução. Na API BACEN, corresponde ao parâmetro `id` da URL

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

Exemplos de Código

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)

Campo	Tipo	Descrição
`transactionId`	string	ID da transação de estorno gerada
`externalId`	string	ID externo da transação de estorno
`status`	string	Status atual da transação de estorno (`PENDING`, `CONFIRMED`, `ERROR`)
`refundValue`	number	Valor do estorno em reais
`providerTransactionId`	string	ID da transação no provedor (usado para correlação com webhooks)
`generateTime`	string	Data/hora de geração da transação de estorno (ISO 8601)

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

Erros

Status	Descrição
400	Dados inválidos, transação não encontrada, prazo excedido, ou valor inválido
401	Token não fornecido ou inválido
404	Transação pai não encontrada
500	Erro ao processar solicitação de estorno