Cancel a PIX refund

curl --request POST \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel

import requests

url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel', 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.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel"

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

	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.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel")

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

request = Net::HTTP::Post.new(url)

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

{
  "_id": "6710d2e4b4d3e80012c9a1f7",
  "environment": "LIVE",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "accountId": "66f2a1c7b4d3e80012c9a0b4",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "transactionId": "6710c9a1b4d3e80012c9a1e2",
  "status": "CANCELED",
  "originalEffectiveAt": "2026-10-16T18:40:11.000Z",
  "originalAmount": 50000,
  "originalCurrency": "986",
  "reversalReason": "USER_REQUESTED",
  "reversalDescription": "Pedido cancelado pelo cliente",
  "reversalEffectiveAt": null,
  "reversalAmount": 50000,
  "reversalCurrency": "986",
  "processingType": "INSTANT",
  "createdAt": "2026-10-17T14:21:40.000Z",
  "updatedAt": "2026-10-17T14:22:05.000Z",
  "requestedAt": "2026-10-17T14:22:03.000Z",
  "originalPixId": "6710c9a0b4d3e80012c9a1e0",
  "originalPixBillingId": "6710c5f2b4d3e80012c9a1d4",
  "originalReceipt": {
    "endToEndId": "E18236120202611021310s0123456789"
  },
  "originalCreditParty": {
    "_id": "6710d2e4b4d3e80012c9a1f8",
    "bankIspb": "18236120",
    "accountType": "CACC",
    "document": "12345678000190",
    "keyType": "EMAIL",
    "key": "financeiro@cliente.com.br",
    "name": "Cliente Exemplo Ltda",
    "street": "Rua das Flores, 100",
    "city": "Curitiba",
    "state": "PR",
    "postalCode": "80010000",
    "branch": "0001",
    "accountNumber": "123456"
  },
  "originalDebitParty": {
    "_id": "6710d2e4b4d3e80012c9a1f8",
    "bankIspb": "18236120",
    "accountType": "CACC",
    "document": "12345678000190",
    "keyType": "EMAIL",
    "key": "financeiro@cliente.com.br",
    "name": "Cliente Exemplo Ltda",
    "street": "Rua das Flores, 100",
    "city": "Curitiba",
    "state": "PR",
    "postalCode": "80010000",
    "branch": "0001",
    "accountNumber": "123456"
  },
  "reversalAdditionalInformation": "Estorno referente ao pedido 4471",
  "reversalReceipt": {
    "endToEndId": "E18236120202611021310s0123456789"
  },
  "errorCode": "AM04",
  "errorDescription": "Saldo insuficiente na conta do recebedor",
  "external": {
    "reversalId": "rev_6b8f0c2a9d1e4f3a"
  },
  "__v": 0
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "FORBIDDEN_WALLET",
  "origin": "BANKING",
  "message": "You do not have permission to perform this action on this wallet"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ACCOUNT_NOT_FOUND",
  "origin": "BANKING",
  "message": "Account not found"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "BANKING",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

POST

realms

{realmId}

organizations

{organizationId}

accounts

{accountId}

wallets

{walletId}

transactions

{transactionId}

reversals

{reversalId}

cancel

Cancel a PIX refund

curl --request POST \
  --url https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel

import requests

url = "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel', 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.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel"

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

	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.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/transactions/{transactionId}/reversals/{reversalId}/cancel")

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

request = Net::HTTP::Post.new(url)

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

{
  "_id": "6710d2e4b4d3e80012c9a1f7",
  "environment": "LIVE",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "accountId": "66f2a1c7b4d3e80012c9a0b4",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "transactionId": "6710c9a1b4d3e80012c9a1e2",
  "status": "CANCELED",
  "originalEffectiveAt": "2026-10-16T18:40:11.000Z",
  "originalAmount": 50000,
  "originalCurrency": "986",
  "reversalReason": "USER_REQUESTED",
  "reversalDescription": "Pedido cancelado pelo cliente",
  "reversalEffectiveAt": null,
  "reversalAmount": 50000,
  "reversalCurrency": "986",
  "processingType": "INSTANT",
  "createdAt": "2026-10-17T14:21:40.000Z",
  "updatedAt": "2026-10-17T14:22:05.000Z",
  "requestedAt": "2026-10-17T14:22:03.000Z",
  "originalPixId": "6710c9a0b4d3e80012c9a1e0",
  "originalPixBillingId": "6710c5f2b4d3e80012c9a1d4",
  "originalReceipt": {
    "endToEndId": "E18236120202611021310s0123456789"
  },
  "originalCreditParty": {
    "_id": "6710d2e4b4d3e80012c9a1f8",
    "bankIspb": "18236120",
    "accountType": "CACC",
    "document": "12345678000190",
    "keyType": "EMAIL",
    "key": "financeiro@cliente.com.br",
    "name": "Cliente Exemplo Ltda",
    "street": "Rua das Flores, 100",
    "city": "Curitiba",
    "state": "PR",
    "postalCode": "80010000",
    "branch": "0001",
    "accountNumber": "123456"
  },
  "originalDebitParty": {
    "_id": "6710d2e4b4d3e80012c9a1f8",
    "bankIspb": "18236120",
    "accountType": "CACC",
    "document": "12345678000190",
    "keyType": "EMAIL",
    "key": "financeiro@cliente.com.br",
    "name": "Cliente Exemplo Ltda",
    "street": "Rua das Flores, 100",
    "city": "Curitiba",
    "state": "PR",
    "postalCode": "80010000",
    "branch": "0001",
    "accountNumber": "123456"
  },
  "reversalAdditionalInformation": "Estorno referente ao pedido 4471",
  "reversalReceipt": {
    "endToEndId": "E18236120202611021310s0123456789"
  },
  "errorCode": "AM04",
  "errorDescription": "Saldo insuficiente na conta do recebedor",
  "external": {
    "reversalId": "rev_6b8f0c2a9d1e4f3a"
  },
  "__v": 0
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "FORBIDDEN_WALLET",
  "origin": "BANKING",
  "message": "You do not have permission to perform this action on this wallet"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "ACCOUNT_NOT_FOUND",
  "origin": "BANKING",
  "message": "Account not found"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "BANKING",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "organizationId",
      "message": "Invalid UUID",
      "code": "ORGANIZATIONID_UUID"
    }
  ]
}

Organization admins can cancel refunds of every wallet; other users of the wallets shared with them as OWNER or USER. Use default as walletId for the organization’s main wallet, and send x-environment: LIVE for production wallets.

Headers

x-environment

enum<string>

Environment of the wallet: LIVE (production) or TEST (sandbox). When you omit it, the request runs in TEST; any other value is rejected.

Available options:

LIVE,

TEST

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization the wallet belongs to.

Format: UUID

accountId

string

required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

walletId

string

required

ID of the wallet that received the Pix (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

transactionId

string

required

ID of the transaction of the Pix received (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

reversalId

string

required

ID of the refund (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

Response

Successful response

A refund of a PIX payment the wallet received: the money, in full or in part, goes back to whoever sent it.

_id

string

required

ID of the reversal.

Example:

"6710d2e4b4d3e80012c9a1f7"

environment

enum<string>

required

Environment of the reversal: LIVE or TEST.

Available options:

LIVE,

TEST

Example:

"LIVE"

realmId

string<uuid>

required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId

string<uuid>

required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId

string

required

ID of the account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId

string

required

ID of the wallet that received the payment and refunds it.

Example:

"66f2a3d1b4d3e80012c9a0d2"

transactionId

string

required

ID of the wallet transaction of the payment being refunded.

Example:

"6710c9a1b4d3e80012c9a1e2"

status

enum<string>

required

Status of the refund: INITIATED (created, not confirmed yet), REQUESTED (sent, waiting to settle), CONFIRMED (the money went back), FAILED (refused, see errorCode) or CANCELED (cancelled before it was confirmed).

Available options:

INITIATED,

REQUESTED,

CONFIRMED,

FAILED,

CANCELED

Example:

"CANCELED"

originalEffectiveAt

string<date-time>

required

When the payment being refunded was received.

Example:

"2026-10-16T18:40:11.000Z"

originalAmount

number

required

Amount of the payment being refunded, in cents.

Example:

50000

originalCurrency

string

required

Currency of that payment, as an ISO 4217 numeric code: 986 (Brazilian real).

Example:

"986"

reversalReason

string

required

Why the payment is refunded: USER_REQUESTED.

Example:

"USER_REQUESTED"

reversalDescription

string | null

required

Description of the refund. null when none was given.

Example:

"Pedido cancelado pelo cliente"

reversalEffectiveAt

string<date-time> | null

required

When the refund settled. null until it does.

Example:

null

reversalAmount

number

required

Amount refunded, in cents. At most the amount of the payment.

Example:

50000

reversalCurrency

string

required

Currency of the refund, as an ISO 4217 numeric code: 986 (Brazilian real).

Example:

"986"

processingType

enum<string>

required

How the refund is processed: INSTANT or DELAYED.

Available options:

INSTANT,

DELAYED

Example:

"INSTANT"

createdAt

string<date-time>

required

When the refund was created.

Example:

"2026-10-17T14:21:40.000Z"

updatedAt

string<date-time>

required

When it last changed.

Example:

"2026-10-17T14:22:05.000Z"

requestedAt

string<date-time>

When the refund was sent to the bank. Absent while it is INITIATED; it doesn't mean the refund settled.

Example:

"2026-10-17T14:22:03.000Z"

originalPixId

string

ID of the PIX payment being refunded, when it is known.

Example:

"6710c9a0b4d3e80012c9a1e0"

originalPixBillingId

string

ID of the PIX charge the payment paid, when it paid one.

Example:

"6710c5f2b4d3e80012c9a1d4"

originalReceipt

object

End-to-end identifier of the payment being refunded.

Show child attributes

originalCreditParty

object

Who received the payment being refunded: this wallet.

Show child attributes

originalDebitParty

object

Who sent the payment being refunded — and receives the refund.

Show child attributes

reversalAdditionalInformation

string

Extra information sent with the refund.

Example:

"Estorno referente ao pedido 4471"

reversalReceipt

object

End-to-end identifier of the refund. Present once it was sent.

Show child attributes

errorCode

string

Code of the error that made the refund fail. Only on FAILED refunds.

Example:

"AM04"

errorDescription

string

Description of that error.

Example:

"Saldo insuficiente na conta do recebedor"

external

object

References of the refund. Present once it was sent.

Show child attributes

__v

number

Internal revision counter of the refund.

Example:

0

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Cancel a PIX refund

Headers

Path Parameters

Response