Credit a received Pix whose ledger credit is parked

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/{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/transfers/{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/transfers/{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/transfers/{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": "01a18811-6b64-7a10-b2c3-d4e5f6071829",
  "accountId": "019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f",
  "endToEndId": "E87654321202610291430AbCdEf12345",
  "status": "COMPLETED",
  "type": "INBOUND",
  "initiationType": "DICT",
  "source": {
    "account": {
      "branch": "0001",
      "number": "1112223",
      "participant": "87654321",
      "type": "CACC"
    },
    "owner": {
      "document": "11144477735",
      "name": "Maria Souza",
      "type": "NATURAL_PERSON"
    }
  },
  "destination": {
    "account": {
      "branch": "0001",
      "number": "9988776",
      "participant": "12345678",
      "type": "CACC"
    },
    "owner": {
      "document": "52998224725",
      "name": "Joao Pereira",
      "type": "NATURAL_PERSON"
    }
  },
  "amount": "100.00",
  "currency": "BRL",
  "description": "Pagamento de aluguel",
  "ledger": {
    "transactionId": "01a18826-1aff-7d11-a2b3-c4d5e6f70819",
    "sourceOperationId": "01a18826-1aff-7d12-a2b3-c4d5e6f7081a",
    "destinationOperationId": "01a18826-1aff-7d13-a2b3-c4d5e6f7081b"
  },
  "createdAt": "2026-10-29T14:30:05.412Z",
  "updatedAt": "2026-10-29T14:52:41.087Z",
  "alreadyRefundedAmount": "0.00",
  "remainingRefundableAmount": "100.00"
}

{
  "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-0340",
  "title": "Not Found",
  "status": 404,
  "detail": "Transfer ID does not exist for this organization.",
  "code": "PIX-0340"
}

{
  "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-0472",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0472"
}

{
  "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 whose ledger credit is parked

Credits a received Pix that BACEN settled and whose ledger credit Pix Lerian parked. The transfer is PROCESSING, and the inbound_transfer.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 transfer and does not authorize the call. On success the transfer is COMPLETED, and Pix Lerian sends inbound_transfer.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 transfer 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 transfer 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 transfer 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 transfer falls to the PIX-0474 reconciliation. The caller needs the transfers permission with the post action, the same permission that initiates and processes a transfer. When MED blocks wait for the credit, the call posts the credit and their holds together.

POST

transfers

{id}

credit

Credit a received Pix whose ledger credit is parked

curl --request POST \
  --url https://api.example.com/spi/v1/transfers/{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/transfers/{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/transfers/{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/transfers/{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": "01a18811-6b64-7a10-b2c3-d4e5f6071829",
  "accountId": "019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f",
  "endToEndId": "E87654321202610291430AbCdEf12345",
  "status": "COMPLETED",
  "type": "INBOUND",
  "initiationType": "DICT",
  "source": {
    "account": {
      "branch": "0001",
      "number": "1112223",
      "participant": "87654321",
      "type": "CACC"
    },
    "owner": {
      "document": "11144477735",
      "name": "Maria Souza",
      "type": "NATURAL_PERSON"
    }
  },
  "destination": {
    "account": {
      "branch": "0001",
      "number": "9988776",
      "participant": "12345678",
      "type": "CACC"
    },
    "owner": {
      "document": "52998224725",
      "name": "Joao Pereira",
      "type": "NATURAL_PERSON"
    }
  },
  "amount": "100.00",
  "currency": "BRL",
  "description": "Pagamento de aluguel",
  "ledger": {
    "transactionId": "01a18826-1aff-7d11-a2b3-c4d5e6f70819",
    "sourceOperationId": "01a18826-1aff-7d12-a2b3-c4d5e6f7081a",
    "destinationOperationId": "01a18826-1aff-7d13-a2b3-c4d5e6f7081b"
  },
  "createdAt": "2026-10-29T14:30:05.412Z",
  "updatedAt": "2026-10-29T14:52:41.087Z",
  "alreadyRefundedAmount": "0.00",
  "remainingRefundableAmount": "100.00"
}

{
  "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-0340",
  "title": "Not Found",
  "status": 404,
  "detail": "Transfer ID does not exist for this organization.",
  "code": "PIX-0340"
}

{
  "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-0472",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "The server could not complete the request. Please try again later.",
  "code": "PIX-0472"
}

{
  "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 divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Account-Id

string

obrigatório

The credited account UUID: the accountId of the inbound_transfer.credit_parked event. It finds the transfer; it does not authorize the call

Exemplo:

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

X-Actor-Id

string

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

Exemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Exemplo:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Exemplo:

"MED-4821"

X-Correlation-Id

string

Correlation id

Exemplo:

"med-2026-000123"

X-Request-Id

string

Request id

Exemplo:

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

Parâmetros de caminho

string

obrigatório

Transfer UUID: the id of the inbound_transfer.credit_parked event

Exemplo:

"01a18811-6b64-7a10-b2c3-d4e5f6071829"

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

Credit a received Pix whose ledger credit is parked

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta