Unblock a Pix refund stuck in PROCESSING

curl --request POST \
  --url https://api.example.com/spi/v1/refunds/{id}/unblock \
  --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}/unblock"

	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}/unblock', 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}/unblock"

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

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

print(response.text)

{
  "amount": "100.00",
  "createdAt": "2026-05-06T10:45:00Z",
  "id": "019606b1-3b4c-7d8e-9f01-234567890dee",
  "originalEndToEndId": "E12345678202605061030abcdef12345",
  "reasonCode": "MD06",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:45:30Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Estorno solicitado pelo pagador",
  "ledger": {
    "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
    "revert": {
      "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
      "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
      "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
    },
    "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
    "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
  },
  "metadata": {},
  "returnEndToEndId": "D12345678202605061045fedcba54321",
  "feeCharge": {
    "applied": true,
    "calculationType": "LEDGER",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "LEDGER_FEE",
        "calculationType": "LEDGER",
        "calculationValue": "<string>",
        "creditAccount": "@fees-pix"
      }
    ],
    "netAmount": "100.00",
    "totalAmount": "1.50"
  }
}

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

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

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

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

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

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

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

Unblock a Pix refund stuck in PROCESSING

Resolves ONE outbound refund that is stuck in PROCESSING. Pix Lerian asks the SPI for the outcome of the refund and applies it. The request has no field to state what happened.

The refund must have been in PROCESSING for at least 90 minutes. If the SPI reports the refund as completed, the refund becomes COMPLETED. If the SPI reports it as rejected or failed, the refund becomes FAILED and Pix Lerian reverses the debit. If the SPI has no final outcome yet, the call is refused with PIX-0556: retry later. If Pix Lerian cannot get the status from the SPI, the call answers 502 (PIX-0557) and Pix Lerian changes nothing.

A refund that is already in a final status is refused with PIX-0554. A refund in any other status is refused with PIX-0551.

The caller needs the refunds permission with the post action, the same permission that creates a refund.

The response is the refund as Get refund returns it.

POST

refunds

{id}

unblock

Unblock a Pix refund stuck in PROCESSING

curl --request POST \
  --url https://api.example.com/spi/v1/refunds/{id}/unblock \
  --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}/unblock"

	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}/unblock', 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}/unblock"

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

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

print(response.text)

{
  "amount": "100.00",
  "createdAt": "2026-05-06T10:45:00Z",
  "id": "019606b1-3b4c-7d8e-9f01-234567890dee",
  "originalEndToEndId": "E12345678202605061030abcdef12345",
  "reasonCode": "MD06",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:45:30Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Estorno solicitado pelo pagador",
  "ledger": {
    "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
    "revert": {
      "destinationOperationId": "019606a5-7f80-7182-3c4d-56789012cdf1",
      "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
      "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
    },
    "sourceOperationId": "019606a5-7f80-7182-3c4d-56789012cdf0",
    "transactionId": "019606a5-7f80-7182-3c4d-56789012cdef"
  },
  "metadata": {},
  "returnEndToEndId": "D12345678202605061045fedcba54321",
  "feeCharge": {
    "applied": true,
    "calculationType": "LEDGER",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "LEDGER_FEE",
        "calculationType": "LEDGER",
        "calculationValue": "<string>",
        "creditAccount": "@fees-pix"
      }
    ],
    "netAmount": "100.00",
    "totalAmount": "1.50"
  }
}

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

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

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

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

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

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

{
  "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 different URL, X-Account-Id, X-Actor-Id, X-Override-Reason or X-Override-Ticket is PIX-0031 @ 412.

Required string length: 1 - 64

X-Account-Id

string

requerido

Source account UUID. A refund that exists under a different account is answered 404.

Ejemplo:

"019606a1-3b4c-7d8e-9f01-234567890abc"

X-Actor-Id

string

Optional. Identifies the person in your back office who asked for the check. Pix Lerian does not use it to decide the outcome.

Maximum string length: 255

Ejemplo:

"ops-maria"

X-Override-Reason

string

Optional. Reason for the check. Pix Lerian does not use it to decide the outcome.

Maximum string length: 512

Ejemplo:

"outcome never arrived"

X-Override-Ticket

string

Optional. Ticket reference in your own back office. Pix Lerian does not use it to decide the outcome.

Maximum string length: 255

Ejemplo:

"OPS-4711"

Parámetros de ruta

string

requerido

Refund UUID

Ejemplo:

"0196080a-1234-7890-abcd-ef0123456789"

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

Unblock a Pix refund stuck in PROCESSING

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta