Process a payee-bank-initiated PIX devolução

curl --request POST \
  --url https://api.example.com/v1/webhooks/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endToEndIdDevolucao": "E2E-DEVO",
  "endToEndIdOriginal": "E2E-ORIG",
  "idReqJdPi": "JDPI-1",
  "valor": 50.25,
  "codigoDevolucao": "MD06",
  "infEntreClientes": "note",
  "motivoDevolucao": "customer request"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"endToEndIdDevolucao\": \"E2E-DEVO\",\n  \"endToEndIdOriginal\": \"E2E-ORIG\",\n  \"idReqJdPi\": \"JDPI-1\",\n  \"valor\": 50.25,\n  \"codigoDevolucao\": \"MD06\",\n  \"infEntreClientes\": \"note\",\n  \"motivoDevolucao\": \"customer request\"\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({
    endToEndIdDevolucao: 'E2E-DEVO',
    endToEndIdOriginal: 'E2E-ORIG',
    idReqJdPi: 'JDPI-1',
    valor: 50.25,
    codigoDevolucao: 'MD06',
    infEntreClientes: 'note',
    motivoDevolucao: 'customer request'
  })
};

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

import requests

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

payload = {
    "endToEndIdDevolucao": "E2E-DEVO",
    "endToEndIdOriginal": "E2E-ORIG",
    "idReqJdPi": "JDPI-1",
    "valor": 50.25,
    "codigoDevolucao": "MD06",
    "infEntreClientes": "note",
    "motivoDevolucao": "customer request"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrCreditoSgct": "2026-06-20T10:00:00Z",
  "dtHrValidacao": "2026-06-20T10:00:00Z",
  "idCreditoSgct": "SGCT-1",
  "idReqJdPi": "JDPI-1",
  "motivo": "BE01",
  "motivoComplemento": "...",
  "resultado": 1
}

{
  "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"
  }
}

{
  "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"
  }
}

Process a payee-bank-initiated PIX devolução

Registers a PIX devolução that the PAYEE’s bank initiated and JDPI has already executed (JDPI section 9.3.3). This participant does not initiate it and does not decide it: JDPI pushes it once the return has settled, and this call records the money coming back. It is idempotent on endToEndIdDevolucao, so a redelivery answers 409 PIX-0029 and credits nothing twice.

On success the returned amount is credited back to the account that funded the ORIGINAL payment, and the response carries the section 9.3.3 acknowledgement: idReqJdPi, idCreditoSgct (the identifier of the entry this participant recorded) and dtHrCreditoSgct. The original payment is located by endToEndIdOriginal; the payer’s identity and destination are read from the record written when that payment was created, never re-resolved, so a devolução always returns to where the money left from.

ONE SUCCESS SHAPE IS NOT A COMPLETED CREDIT, and it is the case an integrator must plan for. When the original payment is still PENDING here (its SPI outcome has not been reconciled yet), the devolução is ACCEPTED AND OWNED rather than credited: it is recorded as awaiting the original’s settlement, the acknowledgement is the same 200 shape with idCreditoSgct naming that record, and a background sweep completes the credit once the original settles. So a 200 asserts this participant has taken responsibility for the devolução, not that the money has already moved.

WHEN THE ORIGINAL PAYMENT BELONGED TO AN INDIRECT PARTICIPANT, the devolução follows it. This participant may serve indirect participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant’s ISPB. A payment originated for one of them was debited from its @pi_{ispb} settlement position, so the return credits that same position and the recorded devolução is stamped with the same institution as the original. Nothing in the section 9.3.3 payload says so — the linkage comes entirely from the original payment’s record — and the 200 body is identical either way.

An indirect-linked devolução also queues a NOTICE to that registration’s delivery.endpointUrl: one HTTPS POST forwarding this webhook’s JD body verbatim, carrying X-Lerian-Signature (‘sha256=’ followed by the hex HMAC-SHA256 of the exact body bytes under the registration’s shared secret) and X-Lerian-Timestamp. It is queued on the same conditions the cash-in notice is, and with the same asymmetry: a queued notice rides the devolução’s own database transaction, but a devolução can be credited and answered 200 with NO notice queued — when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding. Delivery of a queued notice is AT-LEAST-ONCE and independent of this 200: it can repeat, and it can fail permanently while the money stays booked. The institution must dedup on endToEndIdDevolucao and read GET /v1/indirects//transactions as the record of truth — which is also the only place a devolução whose notice was never queued becomes visible.

A devolução that CANNOT be registered is answered with an HTTP error carrying a distinct code in the problem body’s code member:

404 PIX-0063 - no original payment with this endToEndIdOriginal exists here. This participant never made that payment, so there is nothing to return.
409 PIX-0029 - this endToEndIdDevolucao was already registered. The redelivery credited nothing; the original devolução stands.
409 PIX-0032 - the returned amounts for this payment would exceed what was originally paid. The cap is cumulative across every devolução already booked against that payment, and it is evaluated under a lock, so two devoluções arriving at once cannot both pass it.
422 PIX-0030 - the devolução amount is not greater than zero.
400 PIX-0061 - the body failed schema validation at the edge, before any lookup ran.

None of those are specific to an indirect participant: an indirect-linked devolução is refused for exactly the same reasons as a direct one, because the linkage is read from the original payment rather than resolved from this request.

POST

webhooks

refunds

Process a payee-bank-initiated PIX devolução

curl --request POST \
  --url https://api.example.com/v1/webhooks/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endToEndIdDevolucao": "E2E-DEVO",
  "endToEndIdOriginal": "E2E-ORIG",
  "idReqJdPi": "JDPI-1",
  "valor": 50.25,
  "codigoDevolucao": "MD06",
  "infEntreClientes": "note",
  "motivoDevolucao": "customer request"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"endToEndIdDevolucao\": \"E2E-DEVO\",\n  \"endToEndIdOriginal\": \"E2E-ORIG\",\n  \"idReqJdPi\": \"JDPI-1\",\n  \"valor\": 50.25,\n  \"codigoDevolucao\": \"MD06\",\n  \"infEntreClientes\": \"note\",\n  \"motivoDevolucao\": \"customer request\"\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({
    endToEndIdDevolucao: 'E2E-DEVO',
    endToEndIdOriginal: 'E2E-ORIG',
    idReqJdPi: 'JDPI-1',
    valor: 50.25,
    codigoDevolucao: 'MD06',
    infEntreClientes: 'note',
    motivoDevolucao: 'customer request'
  })
};

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

import requests

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

payload = {
    "endToEndIdDevolucao": "E2E-DEVO",
    "endToEndIdOriginal": "E2E-ORIG",
    "idReqJdPi": "JDPI-1",
    "valor": 50.25,
    "codigoDevolucao": "MD06",
    "infEntreClientes": "note",
    "motivoDevolucao": "customer request"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrCreditoSgct": "2026-06-20T10:00:00Z",
  "dtHrValidacao": "2026-06-20T10:00:00Z",
  "idCreditoSgct": "SGCT-1",
  "idReqJdPi": "JDPI-1",
  "motivo": "BE01",
  "motivoComplemento": "...",
  "resultado": 1
}

{
  "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"
  }
}

{
  "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

endToEndIdDevolucao

string

requerido

JDPI-assigned return id (idempotency + dedup key).

Ejemplo:

"E2E-DEVO"

endToEndIdOriginal

string

requerido

End-to-end id of the original CASH_OUT.

Ejemplo:

"E2E-ORIG"

idReqJdPi

string

requerido

JDPI request id (GUID), echoed on the acknowledgement.

Ejemplo:

"JDPI-1"

valor

number<double>

requerido

Return amount in reais (a JSON number).

Ejemplo:

50.25

codigoDevolucao

string

Return reason code (eRefundCode).

Ejemplo:

"MD06"

infEntreClientes

string

Free-text inter-client info.

Ejemplo:

"note"

motivoDevolucao

string

Free-text return reason.

Ejemplo:

"customer request"

Respuesta

dtHrCreditoSgct

string

SGCT credit timestamp (ISO-8601).

Ejemplo:

"2026-06-20T10:00:00Z"

dtHrValidacao

string

Validation timestamp (ISO-8601).

Ejemplo:

"2026-06-20T10:00:00Z"

idCreditoSgct

string

SGCT credit id.

Ejemplo:

"SGCT-1"

idReqJdPi

string

Echoed JDPI request id.

Ejemplo:

"JDPI-1"

motivo

string

Reason code (on a rejected return).

Ejemplo:

"BE01"

motivoComplemento

string

Reason complement.

Ejemplo:

"..."

resultado

integer<int64>

Validation result (0=Inválido, 1=Válido).

Ejemplo:

1

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

Process a payee-bank-initiated PIX devolução

Autorizaciones

Cuerpo

Respuesta