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

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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

obrigatório

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

Exemplo:

"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

Exemplo:

"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

Exemplo:

"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

Exemplo:

"OPS-4711"

Parâmetros de caminho

string

obrigatório

Refund UUID

Exemplo:

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

Resposta

amount

string

obrigatório

Exemplo:

"100.00"

createdAt

string<date-time>

obrigatório

Exemplo:

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

string

obrigatório

Exemplo:

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

originalEndToEndId

string

obrigatório

Exemplo:

"E12345678202605061030abcdef12345"

reasonCode

string

obrigatório

Exemplo:

"MD06"

status

string

obrigatório

Exemplo:

"COMPLETED"

type

string

obrigatório

Exemplo:

"OUTBOUND"

updatedAt

string<date-time>

obrigatório

Exemplo:

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

accountId

string

Exemplo:

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

deletedAt

string<date-time>

description

string

Exemplo:

"Estorno solicitado pelo pagador"

ledger

object

Show child attributes

metadata

object

Show child attributes

returnEndToEndId

string

Exemplo:

"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 e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Unblock a Pix refund stuck in PROCESSING

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta