Devolver uma cobrança PIX recebida (estorno ao pagador)

curl --request POST \
  --url https://api.paysurebr.com/v1/pix/refund \
  --header 'Content-Type: application/json' \
  --header 'ci: <api-key>' \
  --data '
{
  "external_id": "order-12345",
  "description": "Reembolso pedido cancelado"
}
'

import requests

url = "https://api.paysurebr.com/v1/pix/refund"

payload = {
    "external_id": "order-12345",
    "description": "Reembolso pedido cancelado"
}
headers = {
    "ci": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {ci: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({external_id: 'order-12345', description: 'Reembolso pedido cancelado'})
};

fetch('https://api.paysurebr.com/v1/pix/refund', 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.paysurebr.com/v1/pix/refund",
  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([
    'external_id' => 'order-12345',
    'description' => 'Reembolso pedido cancelado'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "ci: <api-key>"
  ],
]);

$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.paysurebr.com/v1/pix/refund"

	payload := strings.NewReader("{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("ci", "<api-key>")
	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.paysurebr.com/v1/pix/refund")
  .header("ci", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paysurebr.com/v1/pix/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["ci"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "refund": {
    "refund_id": "RF1179257B2CE641768AB17C",
    "status": "processing",
    "amount_cents": 10000,
    "reference_code": "PSR-3d47dc3f-4c5a-43c6-a057-c9db8816d9a6",
    "external_id": "order-12345"
  },
  "note": "Devolução aceita e em processamento. A confirmação será enviada por webhook."
}

{
  "message": "<string>",
  "ms": 123
}

{
  "message": "<string>",
  "ms": 123
}

Refund

Devolver PIX (estorno)

Devolve integralmente um cash-in recebido de volta para o pagador original.

Regras:

Só devolução total (o valor bruto original).
Nada é revertido: nem a taxa, nem eventuais splits/direct splits (permanecem nas wallets de destino). Sua conta é debitada o valor bruto integral — você precisa ter esse valor de saldo disponível (senão 422).
Apenas cash-ins pagos de até 3 dias.
Informe external_id ou e2e do cash-in a devolver.
Recurso liberado por conta — fale com o suporte para habilitar.

A resposta é 202 com status: processing: a liquidação é assíncrona. Quando a devolução liquidar (ou falhar), enviamos um webhook para o postbackUrl do cash-in original com o resultado (refunded ou failed) — veja o schema RefundWebhook. Em caso de failed, o valor debitado é devolvido automaticamente à sua wallet.

POST

pix

refund

Devolver uma cobrança PIX recebida (estorno ao pagador)

curl --request POST \
  --url https://api.paysurebr.com/v1/pix/refund \
  --header 'Content-Type: application/json' \
  --header 'ci: <api-key>' \
  --data '
{
  "external_id": "order-12345",
  "description": "Reembolso pedido cancelado"
}
'

import requests

url = "https://api.paysurebr.com/v1/pix/refund"

payload = {
    "external_id": "order-12345",
    "description": "Reembolso pedido cancelado"
}
headers = {
    "ci": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {ci: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({external_id: 'order-12345', description: 'Reembolso pedido cancelado'})
};

fetch('https://api.paysurebr.com/v1/pix/refund', 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.paysurebr.com/v1/pix/refund",
  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([
    'external_id' => 'order-12345',
    'description' => 'Reembolso pedido cancelado'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "ci: <api-key>"
  ],
]);

$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.paysurebr.com/v1/pix/refund"

	payload := strings.NewReader("{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("ci", "<api-key>")
	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.paysurebr.com/v1/pix/refund")
  .header("ci", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paysurebr.com/v1/pix/refund")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["ci"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"external_id\": \"order-12345\",\n  \"description\": \"Reembolso pedido cancelado\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "refund": {
    "refund_id": "RF1179257B2CE641768AB17C",
    "status": "processing",
    "amount_cents": 10000,
    "reference_code": "PSR-3d47dc3f-4c5a-43c6-a057-c9db8816d9a6",
    "external_id": "order-12345"
  },
  "note": "Devolução aceita e em processamento. A confirmação será enviada por webhook."
}

{
  "message": "<string>",
  "ms": 123
}

{
  "message": "<string>",
  "ms": 123
}

Devolve integralmente um cash-in recebido de volta para o pagador original.

Fluxo

Você faz POST /v1/pix/refund

Envie external_id ou e2e do cash-in que quer devolver.

Recebe HTTP 202 com status processing

A devolução foi aceita e está liquidando (assíncrono, via SPI). O valor bruto é debitado da sua wallet.

Paysure envia webhook com o resultado

Você recebe um POST no postbackUrl do cash-in original com refund.status:

refunded → devolução liquidada.
failed → rejeitada pelo SPI; o valor debitado é devolvido à sua wallet automaticamente.

Regras

Só devolução total (o valor bruto original).
Nada é revertido: nem a taxa, nem eventuais splits/direct splits (permanecem nas wallets de destino). Sua conta é debitada o valor bruto integral — você absorve a taxa e os splits.
Você precisa ter o valor bruto de saldo disponível (senão 422 saldo insuficiente).
Apenas cash-ins pagos de até 3 dias.
Informe external_id ou e2e.
Recurso liberado por conta — fale com o suporte para habilitar.

O valor debitado é o bruto (o que o pagador enviou), não o líquido que você recebeu. Se o cash-in teve taxa/splits, você devolve mais do que recebeu na wallet — o bruto cobre tudo.

A confirmação é assíncrona e chega por webhook. Não trate o 202 processing como concluído — aguarde o webhook com refund.status: "refunded".

Erros

Erros seguem o formato padrão { "message": "...", "ms": 123 }. Nos erros específicos de devolução vem também um campo code pra você diferenciar o motivo:

HTTP	`code`	Significado
403	—	Recurso de devolução não habilitado para a conta.
404	—	Cash-in não encontrado para esta conta.
422	`RF_INSUFFICIENT`	Saldo insuficiente para devolver o valor bruto.
422	`RF_ONLYU`	A adquirente recusou a devolução (ex: fora do prazo BACEN).
422	—	Cash-in não está pago / não é OnlyU / fora da janela de 3 dias.
409	`RF_LOCK`	Uma devolução deste cash-in já está em processamento.

Webhook de devolução

Payload enviado ao seu postbackUrl quando a devolução finaliza (uma vez por transição):

{
  "refund": {
    "reference_code": "PSR-3d47dc3f-4c5a-43c6-a057-c9db8816d9a6",
    "external_reference": "order-12345",
    "status": "refunded",
    "amount_cents": 10000,
    "end_to_end": "E10573521202607100056fw0B5CHeixU",
    "devolucao_e2e": "D29477089202607100059131981f0d63"
  }
}

Authorizations

string

header

required

Autenticação por par client-credentials. Envie dois headers em toda requisição:

ci: client_id (público)
cs: client_secret (privado — nunca exponha no frontend)

Gere as credenciais no painel da Paysure em API Keys. Você pode ter múltiplas chaves ativas.

Body

application/json

Informe external_id ou e2e do cash-in a devolver (pelo menos um).

external_id

string | null

external_id do cash-in original (o mesmo que você enviou ao gerar a cobrança).

Maximum string length: 191

e2e

string | null

End-to-end (E2E) do cash-in original. Alternativa ao external_id.

Maximum string length: 191

description

string | null

Descrição da devolução (aparece no comprovante). Máx 140 caracteres.

Maximum string length: 140

Response

Devolução já solicitada anteriormente (idempotente) — retorna a existente.

Cash-in

Cash-out

Refund

Recursos da conta

Devolver PIX (estorno)

Fluxo

Regras

Erros

Webhook de devolução

Authorizations

Body

Response

​Fluxo

​Regras

​Erros

​Webhook de devolução

Authorizations

Body

Response

Fluxo

Regras

Erros

Webhook de devolução