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. Delivery 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.

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

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Body

application/json

endToEndIdDevolucao

string

required

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

Example:

"E2E-DEVO"

endToEndIdOriginal

string

required

End-to-end id of the original CASH_OUT.

Example:

"E2E-ORIG"

idReqJdPi

string

required

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

Example:

"JDPI-1"

valor

number<double>

required

Return amount in reais (a JSON number).

Example:

50.25

codigoDevolucao

string

Return reason code (eRefundCode).

Example:

"MD06"

infEntreClientes

string

Free-text inter-client info.

Example:

"note"

motivoDevolucao

string

Free-text return reason.

Example:

"customer request"

Response

dtHrCreditoSgct

string

SGCT credit timestamp (ISO-8601).

Example:

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

dtHrValidacao

string

Validation timestamp (ISO-8601).

Example:

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

idCreditoSgct

string

SGCT credit id.

Example:

"SGCT-1"

idReqJdPi

string

Echoed JDPI request id.

Example:

"JDPI-1"

motivo

string

Reason code (on a rejected return).

Example:

"BE01"

motivoComplemento

string

Reason complement.

Example:

"..."

resultado

integer<int64>

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

Example:

1

Key DICT API

Key Claims API

Banks API

Indirect participants API

Transactions API

Transaction Limits API

QR Codes API

Refunds API

Pix Automático · Authorization requests

Pix Automático · Authorization management

Pix Automático · Composite QR codes

Pix Automático · Authorization events

Pix Automático · Schedule events

Pix Automático · Schedules and payment instructions

Pix Automático · Settlement

MED · Refunds

MED · Fraud markers

MED · Infractions

MED · Value recovery

Webhooks API

Error handling

Events

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

Authorizations

Body

Response