Create a PIX refund

curl --request POST \
  --url https://api.example.com/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "transactionId": "d1f9c0a2-...",
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Wrong amount"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/refunds"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 5000,\n  \"code\": \"MD06\",\n  \"endToEndId\": \"E1234567890\",\n  \"transactionId\": \"d1f9c0a2-...\",\n  \"clientRequestId\": \"req-2025-01-01-abc123\",\n  \"description\": \"Wrong amount\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 5000,
    code: 'MD06',
    endToEndId: 'E1234567890',
    transactionId: 'd1f9c0a2-...',
    clientRequestId: 'req-2025-01-01-abc123',
    description: 'Wrong amount'
  })
};

fetch('https://api.example.com/v1/refunds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/refunds"

payload = {
    "accountId": "acc-123",
    "amount": 5000,
    "code": "MD06",
    "endToEndId": "E1234567890",
    "transactionId": "d1f9c0a2-...",
    "clientRequestId": "req-2025-01-01-abc123",
    "description": "Wrong amount"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accountId": "ext-acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "endToEndRefundId": "D1234567890",
  "id": "a2f9c0d1-...",
  "status": "EXECUTED",
  "description": "Wrong amount"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Create a PIX refund

Creates a PIX refund (devolução) against an executed transaction. Bacen makes the refund the RECIPIENT’s operation, so the caller must be the party that RECEIVED the original payment: the requesting accountId’s document has to equal the original payee’s document. The original payer cannot refund a payment it sent — that is the MED/fraud path, not this one.

Identify the original with BOTH transactionId (the local UUID) and endToEndId, and it must still be EXECUTED. Partial refunds are allowed and they ACCUMULATE: the amount is checked against the original amount minus everything already refunded, under a row lock on the original, so two concurrent refunds cannot together exceed it. An on-us original is refunded as a synchronous ledger reversal from the refunder to the original payer; a payment received from another institution is submitted to JDPI first, and the refund’s own end-to-end id comes back from JD. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02.

⚠️ Send clientRequestId on an on-us refund. Without it a retry posts a SECOND reversal: each attempt mints a fresh refund end-to-end id, so nothing dedups them, and the money moves twice. With it, a retry replays the existing refund as a success. The cross-institution branch is already retry-safe on its own.

Refusals: 422 PIX-0036 when no EXECUTED transaction matches that (endToEndId, transactionId) pair; 400 PIX-0089 when the original is an outgoing payment (only the receiving institution can return what it received); 400 PIX-0087 when the caller is refunding its own outgoing payment; 400 PIX-0088 when the caller is not the original payee; 409 PIX-0032 when this amount plus the prior refunds would exceed the original; 422 PIX-0030 on a non-positive amount; 422 PIX-0108 when the requesting account is not bound to a ledger account; 400 PIX-0061 when accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values.

POST

refunds

Create a PIX refund

curl --request POST \
  --url https://api.example.com/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "transactionId": "d1f9c0a2-...",
  "clientRequestId": "req-2025-01-01-abc123",
  "description": "Wrong amount"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/refunds"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"amount\": 5000,\n  \"code\": \"MD06\",\n  \"endToEndId\": \"E1234567890\",\n  \"transactionId\": \"d1f9c0a2-...\",\n  \"clientRequestId\": \"req-2025-01-01-abc123\",\n  \"description\": \"Wrong amount\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    amount: 5000,
    code: 'MD06',
    endToEndId: 'E1234567890',
    transactionId: 'd1f9c0a2-...',
    clientRequestId: 'req-2025-01-01-abc123',
    description: 'Wrong amount'
  })
};

fetch('https://api.example.com/v1/refunds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/refunds"

payload = {
    "accountId": "acc-123",
    "amount": 5000,
    "code": "MD06",
    "endToEndId": "E1234567890",
    "transactionId": "d1f9c0a2-...",
    "clientRequestId": "req-2025-01-01-abc123",
    "description": "Wrong amount"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "accountId": "ext-acc-123",
  "amount": 5000,
  "code": "MD06",
  "endToEndId": "E1234567890",
  "endToEndRefundId": "D1234567890",
  "id": "a2f9c0d1-...",
  "status": "EXECUTED",
  "description": "Wrong amount"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Cuerpo

application/json

accountId

string

requerido

The requesting account (the original payee).

Ejemplo:

"acc-123"

amount

integer<int64>

requerido

Refund amount in centavos (must be greater than zero).

Ejemplo:

5000

code

string

requerido

PIX return reason (BE08/FR01/MD06/SL02).

Ejemplo:

"MD06"

endToEndId

string

requerido

The original transaction's end-to-end id.

Ejemplo:

"E1234567890"

transactionId

string

requerido

The original transaction id (UUID).

Ejemplo:

"d1f9c0a2-..."

clientRequestId

string

Optional client idempotency token. A retry carrying the same value replays the existing refund instead of creating a duplicate (intra-PSP double-refund protection); omit to opt out.

Ejemplo:

"req-2025-01-01-abc123"

description

string

Free-text refund description.

Ejemplo:

"Wrong amount"

Respuesta

Created

accountId

string

requerido

The refunding account id.

Ejemplo:

"ext-acc-123"

amount

integer<int64>

requerido

Refund amount in centavos.

Ejemplo:

5000

code

string

requerido

The PIX return reason.

Ejemplo:

"MD06"

endToEndId

string

requerido

The original transaction's end-to-end id.

Ejemplo:

"E1234567890"

endToEndRefundId

string

requerido

The refund's own end-to-end id.

Ejemplo:

"D1234567890"

string

requerido

The created refund id.

Ejemplo:

"a2f9c0d1-..."

status

string

requerido

eTransactionStatus name.

Ejemplo:

"EXECUTED"

description

string

Refund description.

Ejemplo:

"Wrong amount"

Asientos

Reclamaciones

Bancos

Indirectos

Transacciones

Límites

Códigos QR

Devoluciones

PIX Automatico

MED Infracciones

MED Devoluciones

MED Marcadores de Fraude

MED Recuperaciones

MED Crédito Entrante

Webhooks

Manejo de errores

Eventos

Create a PIX refund

Autorizaciones

Cuerpo

Respuesta