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

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

Required string length: 1 - 64

X-Account-Id

string

requerido

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

Ejemplo:

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

X-Actor-Id

string

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

Ejemplo:

"backoffice.ops@example.com"

X-Override-Reason

string

Why the caller is acting

Ejemplo:

"manual devolution paid by Pix"

X-Override-Ticket

string

Ticket reference

Ejemplo:

"MED-4821"

X-Correlation-Id

string

Correlation id

Ejemplo:

"med-2026-000123"

X-Request-Id

string

Request id

Ejemplo:

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

Parámetros de ruta

string

requerido

Transfer UUID: the id of the inbound_transfer.credit_parked event

Ejemplo:

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

Respuesta

amount

string

requerido

Ejemplo:

"100.00"

createdAt

string<date-time>

requerido

Ejemplo:

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

endToEndId

string

requerido

Ejemplo:

"E12345678202605061030abcdef12345"

string

requerido

Ejemplo:

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

status

string

requerido

Ejemplo:

"COMPLETED"

type

string

requerido

Ejemplo:

"OUTBOUND"

updatedAt

string<date-time>

requerido

Ejemplo:

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

accountId

string

Ejemplo:

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

aliasId

string

alreadyRefundedAmount

string

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

Ejemplo:

"60.00"

currency

string

Ejemplo:

"BRL"

deletedAt

string<date-time>

description

string

Ejemplo:

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

Ejemplo:

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

initiationType

string

Ejemplo:

"DICT"

ledger

object

Show child attributes

metadata

object

Show child attributes

paymentType

string

Ejemplo:

"PIX"

purpose

string

Ejemplo:

"IACT"

remainingRefundableAmount

string

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

Ejemplo:

"40.00"

source

object

Show child attributes

urgency

string

Ejemplo:

"HIGH"

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Credit a received Pix whose ledger credit is parked

Autorizaciones

Encabezados

Parámetros de ruta

Respuesta