Unblock a Pix transfer stuck in PROCESSING

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/{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/transfers/{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/transfers/{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/transfers/{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:30:00Z",
  "endToEndId": "E12345678202605061030abcdef12345",
  "id": "019606a2-4c5d-7e8f-90a1-345678901bcd",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:30:05Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "aliasId": "<string>",
  "alreadyRefundedAmount": "60.00",
  "currency": "BRL",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Pagamento de aluguel",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "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"
  },
  "initiatedAt": "2026-05-06T10:30:00Z",
  "initiationType": "DICT",
  "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": {},
  "paymentType": "PIX",
  "purpose": "IACT",
  "remainingRefundableAmount": "40.00",
  "source": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "urgency": "HIGH"
}

{
  "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 transfer stuck in PROCESSING

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

The transfer must have been in PROCESSING for at least 90 minutes. If the SPI reports the payment as completed, the transfer becomes COMPLETED. If the SPI reports it as rejected or failed, the transfer becomes REJECTED 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 transfer that is already in a final status is refused with PIX-0554. A transfer in any other status is refused with PIX-0551.

The caller needs the transfers permission with the post action, the same permission that initiates and processes a transfer.

The response is the transfer as Get transfer returns it.

POST

transfers

{id}

unblock

Unblock a Pix transfer stuck in PROCESSING

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/{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/transfers/{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/transfers/{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/transfers/{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:30:00Z",
  "endToEndId": "E12345678202605061030abcdef12345",
  "id": "019606a2-4c5d-7e8f-90a1-345678901bcd",
  "status": "COMPLETED",
  "type": "OUTBOUND",
  "updatedAt": "2026-05-06T10:30:05Z",
  "accountId": "019606a0-1a2b-7c3d-8e4f-567890123abc",
  "aliasId": "<string>",
  "alreadyRefundedAmount": "60.00",
  "currency": "BRL",
  "deletedAt": "2023-11-07T05:31:56Z",
  "description": "Pagamento de aluguel",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "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"
  },
  "initiatedAt": "2026-05-06T10:30:00Z",
  "initiationType": "DICT",
  "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": {},
  "paymentType": "PIX",
  "purpose": "IACT",
  "remainingRefundableAmount": "40.00",
  "source": {
    "account": {
      "branch": "0001",
      "number": "0007654321",
      "participant": "87654321",
      "type": "CACC"
    },
    "key": "+5511999998888",
    "owner": {
      "document": "12345678901",
      "name": "João da Silva",
      "tradeName": "Empresa Exemplo LTDA",
      "type": "NATURAL_PERSON"
    }
  },
  "urgency": "HIGH"
}

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

Transfer UUID

Exemplo:

"0196070b-1234-7890-abcd-ef0123456789"

Resposta

amount

string

obrigatório

Exemplo:

"100.00"

createdAt

string<date-time>

obrigatório

Exemplo:

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

endToEndId

string

obrigatório

Exemplo:

"E12345678202605061030abcdef12345"

string

obrigatório

Exemplo:

"019606a2-4c5d-7e8f-90a1-345678901bcd"

status

string

obrigatório

Exemplo:

"COMPLETED"

type

string

obrigatório

Exemplo:

"OUTBOUND"

updatedAt

string<date-time>

obrigatório

Exemplo:

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

accountId

string

Exemplo:

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

aliasId

string

alreadyRefundedAmount

string

Cross-mechanism settled and reserved refund amount. Returned only for INBOUND transfers.

Exemplo:

"60.00"

currency

string

Exemplo:

"BRL"

deletedAt

string<date-time>

description

string

Exemplo:

"Pagamento de aluguel"

destination

object

Show child attributes

feeCharge

object

Fee the ledger reported on the transfer. Absent when the ledger's fee answer was not recorded for this transfer (an error logged at the time, or a transfer created before fees were read back); {"applied": false} when the ledger reported that no fee was charged; the full object when it charged one.

Show child attributes

initiatedAt

string<date-time>

Exemplo:

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

initiationType

string

Exemplo:

"DICT"

ledger

object

Show child attributes

metadata

object

Show child attributes

paymentType

string

Exemplo:

"PIX"

purpose

string

Exemplo:

"IACT"

remainingRefundableAmount

string

Amount minus alreadyRefundedAmount. Returned only for INBOUND transfers and can be negative.

Exemplo:

"40.00"

source

object

Show child attributes

urgency

string

Exemplo:

"HIGH"

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

API de Pix Automático

Tratamento de erros

Unblock a Pix transfer stuck in PROCESSING

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta