> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /en/openapi/v3-current/pix-lerian-spi.yaml post /transfers/{id}/credit openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /transfers/{id}/credit: post: tags: - Transfers summary: Credit a received Pix whose ledger credit is parked description: >- 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. operationId: creditParkedTransfer parameters: - description: >- 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. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: 'Transfer UUID: the id of the inbound_transfer.credit_parked event' in: path name: id required: true schema: description: 'Transfer UUID: the id of the inbound_transfer.credit_parked event' examples: - 01a18811-6b64-7a10-b2c3-d4e5f6071829 type: string - description: >- The credited account UUID: the accountId of the inbound_transfer.credit_parked event. It finds the transfer; it does not authorize the call in: header name: X-Account-Id required: true schema: description: >- The credited account UUID: the accountId of the inbound_transfer.credit_parked event. It finds the transfer; it does not authorize the call examples: - 019cadd4-5620-7c2d-8e3f-4a5b6c7d8e9f type: string - description: >- Who is acting. Declared by the caller; not verified against the access token in: header name: X-Actor-Id schema: description: >- Who is acting. Declared by the caller; not verified against the access token examples: - backoffice.ops@example.com type: string - description: Why the caller is acting in: header name: X-Override-Reason schema: description: Why the caller is acting examples: - manual devolution paid by Pix type: string - description: Ticket reference in: header name: X-Override-Ticket schema: description: Ticket reference examples: - MED-4821 type: string - description: Correlation id in: header name: X-Correlation-Id schema: description: Correlation id examples: - med-2026-000123 type: string - description: Request id in: header name: X-Request-Id schema: description: Request id examples: - 01a17e29-5302-7c0a-b5e1-94d2f6a83c17 type: string responses: '200': content: application/json: example: 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' schema: $ref: '#/components/schemas/TransferResponse' description: OK '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0001 title: Bad Request status: 400 detail: Your request is missing one or more required header params. code: PIX-0001 schema: $ref: '#/components/schemas/Detail' description: >- A missing (PIX-0001) or malformed (PIX-0017) X-Account-Id, a transfer id that is not a UUID (PIX-0015), or an attribution header over its length limit (PIX-0003). A duplicated or padded X-Account-Id or attribution header (PIX-0001). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001) answer in the legacy {code,title,message} envelope too. '404': content: application/problem+json: example: 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 schema: $ref: '#/components/schemas/Detail' description: >- No transfer with this id credits the X-Account-Id account (PIX-0340). '409': content: application/problem+json: example: 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 schema: $ref: '#/components/schemas/Detail' description: >- `PIX-0473`: not a parked inbound transfer. `PIX-0474`: the ledger cannot confirm the credit, so the transfer stays parked and the credit is reconciled by hand. '412': content: application/json: example: 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. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: example: 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 schema: $ref: '#/components/schemas/Detail' description: >- `PIX-0328`: the credited ledger account is blocked, and the transfer stays parked as `LEDGER_OUTCOME_UNKNOWN`: unblock it and retry within 45 minutes. `PIX-0475`: the ledger refused the credit for a cause that a retry does not clear (an account status that forbids receiving, a closed account, a usage limit, a missing alias, balance, asset, ledger or organization, or more than one ledger fee package matching the credit), and the transfer stays parked: fix the cause, then retry within 45 minutes. A closed account is final: no call credits it. When MED blocks wait for the credit, a refusal of the credit or of the hold of a block (`PIX-0013`, `PIX-0328`, `PIX-0329`, `PIX-0650`, `PIX-0655`) leaves the transfer parked: fix the cause, then call again. '500': content: application/json: example: code: PIX-0000 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: >- The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: >- Unexpected server error, a concurrent call posting the payment's blocks, a listed credit whose MED batch hold the ledger does not list yet, or a ledger configuration that did not load for the only send of a MED batch, which parks the transfer refused again (PIX-0000). The transfer is parked or already COMPLETED: call again. '502': content: application/problem+json: example: 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 schema: $ref: '#/components/schemas/Detail' description: >- `PIX-0472`: the ledger was unreachable, refused the credentials, failed the search or the post, or refused the post on a balance that another write moved; the transfer stays parked: retry within the 45-minute window, after you fix the credentials when the ledger refused them. `PIX-0652`: the ledger refused the fee skip (the detail names `overrides.allowFeeSkip`), or failed while posting the hold of a MED block that waits for the credit: call again within 45 minutes of the first refused call, once the setting is on when the detail names it. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: TransferResponse: additionalProperties: false properties: accountId: examples: - 019606a0-1a2b-7c3d-8e4f-567890123abc type: string aliasId: type: string alreadyRefundedAmount: description: >- Cross-mechanism settled and reserved refund amount. Returned only for INBOUND transfers. examples: - '60.00' type: string amount: examples: - '100.00' type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string currency: examples: - BRL type: string deletedAt: format: date-time type: string description: examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/SourceDestination' endToEndId: examples: - E12345678202605061030abcdef12345 type: string feeCharge: $ref: '#/components/schemas/FeeChargeResponse' description: >- 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. id: examples: - 019606a2-4c5d-7e8f-90a1-345678901bcd type: string initiatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string initiationType: examples: - DICT type: string ledger: $ref: '#/components/schemas/LedgerInfo' metadata: additionalProperties: {} type: object paymentType: examples: - PIX type: string purpose: examples: - IACT type: string remainingRefundableAmount: description: >- Amount minus alreadyRefundedAmount. Returned only for INBOUND transfers and can be negative. examples: - '40.00' type: string source: $ref: '#/components/schemas/SourceDestination' status: examples: - COMPLETED type: string type: examples: - OUTBOUND type: string updatedAt: examples: - '2026-05-06T10:30:05Z' format: date-time type: string urgency: examples: - HIGH type: string required: - id - endToEndId - status - type - amount - createdAt - updatedAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object SourceDestination: additionalProperties: false properties: account: $ref: '#/components/schemas/AccountDetails' key: examples: - '+5511999998888' type: string owner: $ref: '#/components/schemas/OwnerDetails' type: object FeeChargeResponse: additionalProperties: false properties: applied: examples: - true type: boolean description: >- Whether the ledger charged a fee on the create that moved the operation's money. When false, no other field is present. applied reports what the create did and the object is kept as its record. Where the operation carries ledger.revert (transfers only: REJECTED, or FAILED after the debit was reverted), the revert inverted the fee legs with the amount, so the fee was returned; on a transfer without ledger.revert, feeCharge says nothing about the fee's final position. calculationType: examples: - LEDGER type: string description: >- How the total fee was calculated. LEDGER when the ledger's fee package computed it. fees: items: $ref: '#/components/schemas/FeeEntryResponse' type: - array - 'null' description: >- Individual fee entries that make up the total, one per ledger fee leg. netAmount: examples: - '100.00' type: string description: >- Amount that reached the destination: on an outbound operation what the ledger moved to the rail, on an inbound one what it credited to the receiving account (the operation's amount when the ledger reported no such leg; on an outbound operation a deductible fee package, a misconfiguration on a Pix ledger, makes it lower than the amount). totalAmount: examples: - '1.50' type: string description: Sum of every fee entry the ledger charged on the operation. required: - applied type: object LedgerInfo: additionalProperties: false properties: destinationOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf1 type: string revert: $ref: '#/components/schemas/LedgerRevertInfo' sourceOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf0 type: string transactionId: examples: - 019606a5-7f80-7182-3c4d-56789012cdef type: string type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object AccountDetails: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object OwnerDetails: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string type: examples: - NATURAL_PERSON type: string required: - document - name type: object FeeEntryResponse: additionalProperties: false properties: amount: examples: - '1.50' type: string description: Amount of this fee entry. calculationType: examples: - LEDGER type: string description: >- How this entry was calculated. LEDGER when the ledger's fee package computed it. calculationValue: type: string description: >- Raw value the calculation was parameterised with. Absent when calculationType is LEDGER. creditAccount: examples: - '@fees-pix' type: string description: Ledger account credited with this fee entry. feeLabel: examples: - LEDGER_FEE type: string description: >- Label of this fee entry. LEDGER_FEE on every entry the ledger reported: its answer names no fee, so creditAccount is what distinguishes one entry from another. required: - feeLabel - amount type: object LedgerRevertInfo: additionalProperties: false properties: destinationOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf1 type: string sourceOperationId: examples: - 019606a5-7f80-7182-3c4d-56789012cdf0 type: string transactionId: examples: - 019606a5-7f80-7182-3c4d-56789012cdef type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.