POST
/
api
/
v1
/
gateway
/
pix-refund
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

​
originalTransactionId
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",
  "originalTransactionId": "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

​
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",
    "originalTransactionId": "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
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
required

URL para notificações

Example:

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

​
amount
number

Valor do reembolso (para reembolso parcial)

Example:

50

Response

200
application/json
Reembolso iniciado com sucesso
​
idTransaction
string

ID da transação de reembolso

Example:

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

​
originalTransactionId
string

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"