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": "FIXED",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "PIX_TRANSFER_FEE",
        "calculationType": "FIXED",
        "calculationValue": "1.50",
        "creditAccount": "019606a3-5d6e-7f80-1a2b-345678901bcd"
      }
    ],
    "netAmount": "98.50",
    "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 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": "FIXED",
    "fees": [
      {
        "amount": "1.50",
        "feeLabel": "PIX_TRANSFER_FEE",
        "calculationType": "FIXED",
        "calculationValue": "1.50",
        "creditAccount": "019606a3-5d6e-7f80-1a2b-345678901bcd"
      }
    ],
    "netAmount": "98.50",
    "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 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"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same 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

required

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

Example:

"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

Example:

"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

Example:

"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

Example:

"OPS-4711"

Path Parameters

string

required

Transfer UUID

Example:

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

Response

amount

string

required

Example:

"100.00"

createdAt

string<date-time>

required

Example:

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

endToEndId

string

required

Example:

"E12345678202605061030abcdef12345"

string

required

Example:

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

status

string

required

Example:

"COMPLETED"

type

string

required

Example:

"OUTBOUND"

updatedAt

string<date-time>

required

Example:

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

accountId

string

Example:

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

aliasId

string

alreadyRefundedAmount

string

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

Example:

"60.00"

currency

string

Example:

"BRL"

deletedAt

string<date-time>

description

string

Example:

"Pagamento de aluguel"

destination

object

Show child attributes

feeCharge

object

Show child attributes

initiatedAt

string<date-time>

Example:

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

initiationType

string

Example:

"DICT"

ledger

object

Show child attributes

metadata

object

Show child attributes

paymentType

string

Example:

"PIX"

purpose

string

Example:

"IACT"

remainingRefundableAmount

string

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

Example:

"40.00"

source

object

Show child attributes

urgency

string

Example:

"HIGH"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Unblock a Pix transfer stuck in PROCESSING

Authorizations

Headers

Path Parameters

Response