> ## 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. # Create a funds recovery > Opens a MED 2.0 funds recovery. A successful creation returns HTTP 201 with status CREATED. When BACEN has not resolved the creation yet, the recovery is stored as PENDING with an empty bacenFundsRecoveryId and returned with HTTP 202: keep its id and use it for every later operation. A PENDING recovery resolves when it is next read or operated on, or when the provider reports on it: it then reads as CREATED with its bacenFundsRecoveryId or, when BACEN never applied the creation, it is withdrawn and reads as 404 / PIX-0110, which frees the root transaction for a new creation. While it is PENDING, cancel, refund, and patch return 409 / PIX-0114, the tracking graph returns 404 / PIX-0110, and the linked lists are empty. Resending the same request under an X-Idempotency header within one hour returns the original 201 or 202 response, status included, with the header `X-Idempotency-Replayed: true`; a resend while the first request still runs answers 412 / PIX-0112 with `Retry-After: 1`; a failed creation is not cached, so repeating it runs the creation again. A duplicate recovery is rejected with 409 / PIX-0113. If the timestamp in rootTransactionId is outside the applicable MED contestation window, the request is rejected with 422 / PIX-0117. The window is determined by the funds recovery creation time: pacs.008 uses 80 calendar days; pacs.004 uses 30 calendar days before 2026-09-01T00:00:00Z and 80 calendar days from that instant onward. This timestamp validation does not confirm that the referenced transaction exists. The participant is determined by the authenticated tenant. participantId, reporterParticipant, rootTransactionType, and idempotencyKey are rejected when included in the body. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-dict.yaml post /dict/funds-recoveries openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Public API for Pix keys, claims, fraud markers, infraction reports, and MED funds recovery. license: name: Lerian Studio General License title: Pix Lerian — DICT version: 1.2.0 servers: - url: https://api.example.com/dict-hub/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Manage ownership and portability claims for Pix keys. name: Claims - description: Register, retrieve, list, update, and remove Pix keys. name: Entries - description: Create, query, list, and cancel DICT fraud markers. name: Fraud Markers - description: Manage participant-scoped MED 2.0 funds recoveries. name: Funds Recoveries - description: Manage MED 2.0 infraction reports for the authenticated organization. name: Infraction Reports - description: Look up Pix keys and check whether keys exist in the DICT directory. name: Keys - description: Create, query, cancel, and settle MED 2.0 refunds. name: Refunds - description: >- Read the state of key reconciliation against BACEN, and start a verification or a file reconciliation. name: VSync paths: /dict/funds-recoveries: post: tags: - Funds Recoveries summary: Create a funds recovery description: >- Opens a MED 2.0 funds recovery. A successful creation returns HTTP 201 with status CREATED. When BACEN has not resolved the creation yet, the recovery is stored as PENDING with an empty bacenFundsRecoveryId and returned with HTTP 202: keep its id and use it for every later operation. A PENDING recovery resolves when it is next read or operated on, or when the provider reports on it: it then reads as CREATED with its bacenFundsRecoveryId or, when BACEN never applied the creation, it is withdrawn and reads as 404 / PIX-0110, which frees the root transaction for a new creation. While it is PENDING, cancel, refund, and patch return 409 / PIX-0114, the tracking graph returns 404 / PIX-0110, and the linked lists are empty. Resending the same request under an X-Idempotency header within one hour returns the original 201 or 202 response, status included, with the header `X-Idempotency-Replayed: true`; a resend while the first request still runs answers 412 / PIX-0112 with `Retry-After: 1`; a failed creation is not cached, so repeating it runs the creation again. A duplicate recovery is rejected with 409 / PIX-0113. If the timestamp in rootTransactionId is outside the applicable MED contestation window, the request is rejected with 422 / PIX-0117. The window is determined by the funds recovery creation time: pacs.008 uses 80 calendar days; pacs.004 uses 30 calendar days before 2026-09-01T00:00:00Z and 80 calendar days from that instant onward. This timestamp validation does not confirm that the referenced transaction exists. The participant is determined by the authenticated tenant. participantId, reporterParticipant, rootTransactionType, and idempotencyKey are rejected when included in the body. If an earlier request for the same operation is still in progress at the provider, the request is rejected with 409 / PIX-0035 and nothing changes: retry after a short wait. operationId: createFundsRecovery parameters: - description: >- Idempotency key (at most 64 bytes); required on create. Enforced by the replay middleware, not the handler. in: header name: X-Idempotency required: true schema: description: >- Idempotency key (at most 64 bytes); required on create. Enforced by the replay middleware, not the handler. examples: - a1b2c3d4-0000-0000-0000-000000000001 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateFundsRecoveryBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: Created '202': content: application/json: schema: $ref: '#/components/schemas/FundsRecoveryOutput' description: >- The provider accepted the create but BACEN has not resolved it yet: the recovery is persisted as PENDING, with an empty bacenFundsRecoveryId, and resolves when it is next read or operated on. '400': content: 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' application/json: example: code: PIX-0010 title: Client Error message: The request could not be processed due to a client-side error. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Bad Request (PIX-0001, PIX-0002, PIX-0003, PIX-0017, PIX-0015, PIX-0020, PIX-0107). Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0110 title: Not Found status: 404 detail: >- No funds recovery exists with the provided ID for this participant. code: PIX-0110 schema: $ref: '#/components/schemas/Detail' description: Not Found (PIX-0110). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0113 title: Conflict status: 409 detail: A funds recovery already exists for this root transaction. code: PIX-0113 schema: $ref: '#/components/schemas/Detail' description: Conflict (PIX-0113, PIX-0114, PIX-0035). '412': content: application/json: example: code: PIX-0112 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: >- X-Idempotency reused with a different request -- another body, identity header among X-Account-Id / X-Reason / X-End-To-End-Id, or route: never reuse a key across routes -- or while the first request under it still runs (with Retry-After: 1: wait and resend with the same key), or within 1 hour of a create whose response carried X-Idempotency-Fenced: true (read the recovery by its id instead of resending) (PIX-0112). Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0100 title: Unprocessable Entity status: 422 detail: Missing or malformed required fields. code: PIX-0100 schema: $ref: '#/components/schemas/Detail' application/json: example: code: PIX-0100 title: Invalid Input message: Missing or malformed required fields. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Unprocessable Entity (PIX-0100, PIX-0117). Route-guard refusals (PIX-0100) answer in the legacy {code,title,message} envelope over application/json, NOT problem+json. '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: internal error code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Internal Server Error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0141 title: Bad Gateway status: 502 detail: internal error code: PIX-0141 schema: $ref: '#/components/schemas/Detail' description: Bad Gateway (PIX-0141). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateFundsRecoveryBody: additionalProperties: false properties: accountId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string contactInformation: $ref: '#/components/schemas/CreateFundsRecoveryBodyContactInformationStruct' metadata: {} reportDetails: examples: - Victim of a WhatsApp scam type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string trackingGraphParameters: {} userComplaintAt: description: >- The time the paying user's complaint was registered in your service channel, in RFC 3339. Required. A time later than the moment the recovery opens is refused with 422 (PIX-0100). Pix Lerian does not send it to BACEN; it relays it to the provider and stores it with the recovery. examples: - '2026-05-17T13:15:00Z' format: date-time type: string required: - accountId - rootTransactionId - situationType - contactInformation - userComplaintAt type: object FundsRecoveryOutput: additionalProperties: false properties: accountId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string bacenFundsRecoveryId: examples: - 9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f type: string description: Recovery id the provider assigned. Empty while status is PENDING. contactInformation: $ref: '#/components/schemas/ContactInformationOutput' correlationId: examples: - 7c9e6679742540de944be07fc1f90ae7 type: string createdAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string metadata: {} participantId: examples: - '12345678' type: string reportDetails: examples: - Victim of a WhatsApp scam type: string reporterParticipant: examples: - '12345678' type: string rootTransactionId: examples: - E12345678202605171530aB3xK9mWq2z type: string situationType: enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: enum: - PENDING - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - CREATED type: string trackingGraph: {} trackingGraphParameters: {} updatedAt: examples: - '2026-05-17T13:30:00Z' format: date-time type: string required: - id - bacenFundsRecoveryId - participantId - accountId - rootTransactionId - situationType - status - reporterParticipant - contactInformation - createdAt - updatedAt 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 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 CreateFundsRecoveryBodyContactInformationStruct: additionalProperties: false properties: email: examples: - user@example.com type: string phone: examples: - '+5511999999999' type: string required: - email - phone type: object ContactInformationOutput: additionalProperties: false properties: email: examples: - user@example.com type: string phone: examples: - '+5511999999999' type: string required: - email - phone 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 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.