Credit a received Pix refund whose ledger credit is parked

curl --request POST \
  --url https://api.example.com/spi/v1/refunds/{id}/credit \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/refunds/{id}/credit"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>'
  }
};

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

import requests

url = "https://api.example.com/spi/v1/refunds/{id}/credit"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "id": "019a3c41-7e2b-7d10-9c4a-5b6e7f805678",
  "accountId": "019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f",
  "originalEndToEndId": "E12345678202610281015AbCdEf12345",
  "returnEndToEndId": "D87654321202610291430FeDcBa54321",
  "status": "COMPLETED",
  "type": "INBOUND",
  "amount": "40.00",
  "reasonCode": "MD06",
  "description": "Valor enviado em duplicidade",
  "ledger": {
    "transactionId": "019a3c52-1aff-7d11-a2b3-c4d5e6f70819",
    "sourceOperationId": "019a3c52-1aff-7d12-a2b3-c4d5e6f7081a",
    "destinationOperationId": "019a3c52-1aff-7d13-a2b3-c4d5e6f7081b"
  },
  "createdAt": "2026-10-29T14:30:05.412Z",
  "updatedAt": "2026-10-29T14:52:41.087Z"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0420",
  "title": "Not Found",
  "status": 404,
  "detail": "Refund ID does not exist for this organization.",
  "code": "PIX-0420"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0474",
  "title": "Conflict",
  "status": 409,
  "detail": "The ledger cannot confirm this credit; reconcile it by hand.",
  "code": "PIX-0474"
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0328",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The ledger account is blocked and cannot be used for the requested operation.",
  "code": "PIX-0328"
}

{
  "code": "PIX-0000",
  "title": "Internal Server Error",
  "message": "The server encountered an unexpected error. Please try again later."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0522",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0522"
}

{
  "code": "<string>",
  "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"
  }
}

Credit a received Pix refund whose ledger credit is parked

Credits a received Pix refund (a devolução that your institution received) that BACEN settled and whose ledger credit to the account of the original sender Pix Lerian parked. The refund is PROCESSING, and the refund.credit_parked event named it with its reason: the id of the event is {id}, and its accountId is X-Account-Id, which finds the refund and does not authorize the call. On success the refund is COMPLETED, and Pix Lerian sends refund.completed. The request has no body.

The call never credits twice, whoever calls it and however often. When the ledger already lists the credit, the call completes the refund without posting a second credit (200). Otherwise it posts the credit only while the ledger still answers the idempotency key of every earlier attempt, or after the ledger refused every earlier attempt. In any other case it answers 409 (PIX-0474): the ledger cannot confirm the credit, the refund stays parked, and the credit is reconciled by hand. Never credit by hand in the ledger outside that reconciliation.

The reason of the event decides who calls it. LEDGER_OUTCOME_UNKNOWN and SETTLE_INTERRUPTED: call it right away, by a person or by automation. A credit whose outcome is unknown can be completed for 45 minutes after the park: call at once, and retry a 502 until then. ACCOUNT_BLOCKED and LEDGER_REFUSED: do not call it automatically. Fix the cause first (unblock the account, or fix the account, alias, balance, credentials or ledger configuration). The first call then parks the refund again as LEDGER_OUTCOME_UNKNOWN and starts a one-way 45-minute clock.

A ledger without overrides.allowFeeSkip refuses the fee skip that the credit requires (502, PIX-0652; the detail names the setting) and posts nothing. Call again within 45 minutes of the first refused call, once the setting is on: after that, the refund falls to the PIX-0474 reconciliation. The caller needs the refunds permission with the post action, the same permission that creates a refund.

POST

refunds

{id}

credit

Credit a received Pix refund whose ledger credit is parked

curl --request POST \
  --url https://api.example.com/spi/v1/refunds/{id}/credit \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/refunds/{id}/credit"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>'
  }
};

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

import requests

url = "https://api.example.com/spi/v1/refunds/{id}/credit"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

{
  "id": "019a3c41-7e2b-7d10-9c4a-5b6e7f805678",
  "accountId": "019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f",
  "originalEndToEndId": "E12345678202610281015AbCdEf12345",
  "returnEndToEndId": "D87654321202610291430FeDcBa54321",
  "status": "COMPLETED",
  "type": "INBOUND",
  "amount": "40.00",
  "reasonCode": "MD06",
  "description": "Valor enviado em duplicidade",
  "ledger": {
    "transactionId": "019a3c52-1aff-7d11-a2b3-c4d5e6f70819",
    "sourceOperationId": "019a3c52-1aff-7d12-a2b3-c4d5e6f7081a",
    "destinationOperationId": "019a3c52-1aff-7d13-a2b3-c4d5e6f7081b"
  },
  "createdAt": "2026-10-29T14:30:05.412Z",
  "updatedAt": "2026-10-29T14:52:41.087Z"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0420",
  "title": "Not Found",
  "status": 404,
  "detail": "Refund ID does not exist for this organization.",
  "code": "PIX-0420"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0474",
  "title": "Conflict",
  "status": 409,
  "detail": "The ledger cannot confirm this credit; reconcile it by hand.",
  "code": "PIX-0474"
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0328",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The ledger account is blocked and cannot be used for the requested operation.",
  "code": "PIX-0328"
}

{
  "code": "PIX-0000",
  "title": "Internal Server Error",
  "message": "The server encountered an unexpected error. Please try again later."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0522",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0522"
}

{
  "code": "<string>",
  "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.

Encabezados

X-Idempotency

string

requerido

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Account-Id

string

requerido

The credited account UUID: the accountId of the refund.credit_parked event (the original payment's source account). It finds the refund; it does not authorize the call

Ejemplo:

"019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f"

X-Actor-Id

string

Who is acting. Declared by the caller; not verified against the access token

Ejemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Ejemplo:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Ejemplo:

"MED-4821"

X-Correlation-Id

string

Correlation id

Ejemplo:

"med-2026-000123"

X-Request-Id

string

Request id

Ejemplo:

"01a17e29-5302-7c0a-b5e1-94d2f6a83c17"

Parámetros de ruta

string

requerido

Refund UUID: the id of the refund.credit_parked event

Ejemplo:

"019a3c41-7e2b-7d10-9c4a-5b6e7f805678"

Respuesta

amount

string

requerido

Ejemplo:

"100.00"

createdAt

string<date-time>

requerido

Ejemplo:

"2026-05-06T10:45:00Z"

string

requerido

Ejemplo:

"019606b1-3b4c-7d8e-9f01-234567890dee"

originalEndToEndId

string

requerido

Ejemplo:

"E12345678202605061030abcdef12345"

reasonCode

string

requerido

Ejemplo:

"MD06"

status

string

requerido

Ejemplo:

"COMPLETED"

type

string

requerido

Ejemplo:

"OUTBOUND"

updatedAt

string<date-time>

requerido

Ejemplo:

"2026-05-06T10:45:30Z"

accountId

string

Ejemplo:

"019606a0-1a2b-7c3d-8e4f-567890123abc"

deletedAt

string<date-time>

description

string

Ejemplo:

"Estorno solicitado pelo pagador"

ledger

object

Show child attributes

metadata

object

Show child attributes

returnEndToEndId

string

Ejemplo:

"D12345678202605061045fedcba54321"

feeCharge

object

Fee the ledger reported on the create that moved the refund's money. Absent when no fee answer was recorded for this refund (its ledger create never landed, an error was logged at the time, or the refund was created before fees were read back); {"applied": false} when the ledger reported that no fee was charged; the full object when it charged one. A refund carries no ledger.revert field and needs none here: a FAILED refund that carries feeCharge was reverted first -- every path that writes a refund FAILED after its ledger create landed reverts the debit before marking it (a revert that does not complete leaves the refund PROCESSING), and every other path fails before any create -- so the fee was returned with the amount; applied reports what the create did and the object records the create.

Show child attributes

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Credit a received Pix refund whose ledger credit is parked

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta