Skip to main content
POST
/
api
/
v1
/
gateway
/
pix-refund
Realiza um reembolso PIX
curl --request POST \
  --url https://sandbox.ws.relaxpay.site/api/v1/gateway/pix-refund \
  --header 'Content-Type: application/json' \
  --header 'ci: <ci>' \
  --header 'cs: <cs>' \
  --data '
{
  "originalTransactionId": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "refundReason": "Cancelamento solicitado pelo cliente",
  "callbackUrl": "https://seu-site.com/webhook/relaxpay",
  "amount": 50
}
'
{
  "idTransaction": "3f8b2a5c-9e47-4d98-b6a1-7c432f89e21b",
  "originalTransactionId": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "amount": 100,
  "status": "PROCESSING",
  "response": "OK"
}
O endpoint de reembolso PIX permite devolver valores recebidos, facilitando a gestão de cancelamentos e estornos.

​
Visão Geral

O endpoint de reembolso PIX permite que você reembolse total ou parcialmente um pagamento PIX anteriormente recebido. Este recurso é útil para casos de cancelamento de serviços, devoluções ou ajustes de valores.

​
Endpoint

​
Parâmetros da Requisição

​
idTransaction
string
required
ID da transação original a ser reembolsada
​
amount
number
Valor a ser reembolsado (se não informado, reembolsa o valor total)
​
refundReason
string
required
Motivo do reembolso
​
callbackUrl
string
required
URL para receber notificações sobre o reembolso

​
Exemplos de Requisição

​
Resposta de Sucesso

​
200 - OK
object
{
  "idTransaction": "3f8b2a5c-9e47-4d98-b6a1-7c432f89e21b",
  "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
  "amount": 100.00,
  "status": "PROCESSING",
  "response": "OK"
}

​
Status do Reembolso

PROCESSING

Reembolso em processamento

COMPLETED

Reembolso concluído com sucesso

FAILED

Reembolso falhou

​
Códigos de Erro

Os parâmetros fornecidos são inválidos ou estão em formato incorreto.
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "INVALID_TRANSACTION_ID",
  "details": "O ID da transação original é inválido"
}
As credenciais fornecidas são inválidas ou não foram enviadas.
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "INVALID_CREDENTIALS",
  "details": "As credenciais fornecidas são inválidas"
}
A transação original com o ID fornecido não foi encontrada.
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "TRANSACTION_NOT_FOUND",
  "details": "A transação original não foi encontrada"
}
A transação não pode ser reembolsada devido a restrições de negócio.
{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "REFUND_NOT_ALLOWED",
  "details": "Não é possível reembolsar esta transação"
}

​
Notificações (Webhooks)

Você receberá notificações na URL de callback informada com o status atualizado do reembolso: 
{
  "event": "refund.status",
  "data": {
    "idTransaction": "3f8b2a5c-9e47-4d98-b6a1-7c432f89e21b",
    "idTransaction": "0b935d10-3c90-4af3-8776-dd18622a7941",
    "status": "COMPLETED",
    "amount": 100.00,
    "timestamp": "2024-12-15T14:30:45Z"
  }
}

​
Limitações e Boas Práticas

O reembolso deve ser solicitado dentro de 30 dias após o recebimento do pagamento.
1

Verifique o status da transação original

Apenas transações com status “PAID” podem ser reembolsadas
2

Informe um motivo claro

O motivo do reembolso ajuda na gestão financeira e auditoria
3

Implemente o webhook

Configure corretamente a URL de callback para receber atualizações em tempo real
4

Armazene o ID da transação de reembolso

Guarde o ID retornado para consultas futuras sobre o status do reembolso
Para reembolsos parciais, certifique-se de que o valor informado não exceda o valor original da transação.

Headers

​
ci
string
required

Client ID para autenticação

​
cs
string
required

Client Secret para autenticação

Body

application/json
​
originalTransactionId
string<uuid>
required

ID da transação original

Example:

"0b935d10-3c90-4af3-8776-dd18622a7941"

​
refundReason
string
required

Motivo do reembolso

Example:

"Cancelamento solicitado pelo cliente"

​
callbackUrl
string<uri>
required

URL para notificações

Example:

"https://seu-site.com/webhook/relaxpay"

​
amount
number

Valor do reembolso (para reembolso parcial)

Example:

50

Response

Reembolso iniciado com sucesso

​
idTransaction
string<uuid>

ID da transação de reembolso

Example:

"3f8b2a5c-9e47-4d98-b6a1-7c432f89e21b"

​
originalTransactionId
string<uuid>

ID da transação original

Example:

"0b935d10-3c90-4af3-8776-dd18622a7941"

​
amount
number

Valor do reembolso

Example:

100

​
status
enum<string>

Status do reembolso

Available options:
PROCESSING,
COMPLETED,
FAILED
Example:

"PROCESSING"

​
response
string

Status da resposta

Example:

"OK"