Cancel a funds recovery

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	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>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.text)

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "bacenFundsRecoveryId": "9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "createdAt": "2026-05-17T13:30:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CANCELLED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam"
}

{
  "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-0110",
  "title": "Not Found",
  "status": 404,
  "detail": "No funds recovery exists with the provided ID for this participant.",
  "code": "PIX-0110"
}

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

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0100",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Missing or malformed required fields.",
  "code": "PIX-0100"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

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

Cancel a funds recovery

Cancels a funds recovery within the authenticated participant scope, changing its status to CANCELLED from any non-terminal state from CREATED through REFUNDING. A recovery already in COMPLETED or CANCELLED returns 409. The request has no body and requires the X-Idempotency header. The response omits trackingGraph, trackingGraphParameters, and correlationId. When BACEN has not resolved the request yet, the operation answers 409 / PIX-0118; errors[] carries operationId and operationStatus when the provider sent valid values. The resource keeps its current status until BACEN’s change arrives. Do not retry blindly: a retry can keep returning this answer after BACEN resolves the operation. 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.

POST

dict

funds-recoveries

{id}

cancel

Cancel a funds recovery

curl --request POST \
  --url https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	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>', Authorization: 'Bearer <token>'}
};

fetch('https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/dict-hub/v1/dict/funds-recoveries/{id}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, headers=headers)

print(response.text)

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "bacenFundsRecoveryId": "9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f",
  "contactInformation": {
    "email": "user@example.com",
    "phone": "+5511999999999"
  },
  "createdAt": "2026-05-17T13:30:00Z",
  "id": "018f8c1d-1234-7abc-9def-000000000001",
  "participantId": "12345678",
  "reporterParticipant": "12345678",
  "rootTransactionId": "E12345678202605171530aB3xK9mWq2z",
  "situationType": "SCAM",
  "status": "CANCELLED",
  "updatedAt": "2026-05-17T13:30:00Z",
  "metadata": "<unknown>",
  "reportDetails": "Victim of a WhatsApp scam"
}

{
  "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-0110",
  "title": "Not Found",
  "status": 404,
  "detail": "No funds recovery exists with the provided ID for this participant.",
  "code": "PIX-0110"
}

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

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header was already used with a different request."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0100",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Missing or malformed required fields.",
  "code": "PIX-0100"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0000",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "code": "PIX-0000"
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0141",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "internal error",
  "code": "PIX-0141"
}

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

Required string length: 1 - 64

X-Correlation-Id

string

Best-effort business correlation id (observability only; never fabricated).

Example:

"7c9e6679742540de944be07fc1f90ae7"

Path Parameters

string

required

Funds recovery internal ID (UUID format)

Example:

"018f8c1d-1234-7abc-9def-000000000001"

Response

accountId

string

required

Example:

"550e8400-e29b-41d4-a716-446655440000"

bacenFundsRecoveryId

string

required

Example:

"9f3a8b7e-2c1d-4e5a-8b6f-1a2b3c4d5e6f"

contactInformation

object

required

Show child attributes

createdAt

string<date-time>

required

Example:

"2026-05-17T13:30:00Z"

string

required

Example:

"018f8c1d-1234-7abc-9def-000000000001"

participantId

string

required

Example:

"12345678"

reporterParticipant

string

required

Example:

"12345678"

rootTransactionId

string

required

Example:

"E12345678202605171530aB3xK9mWq2z"

situationType

enum<string>

required

Available options:

SCAM,

ACCOUNT_TAKEOVER,

COERCION,

FRAUDULENT_ACCESS,

OTHER,

UNKNOWN

Example:

"SCAM"

status

enum<string>

required

Available options:

CREATED,

TRACKED,

AWAITING_ANALYSIS,

ANALYSED,

REFUNDING,

COMPLETED,

CANCELLED

Example:

"CANCELLED"

updatedAt

string<date-time>

required

Example:

"2026-05-17T13:30:00Z"

metadata

any

reportDetails

string

Example:

"Victim of a WhatsApp scam"

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Pix Automático API

Error handling

Cancel a funds recovery

Authorizations

Headers

Path Parameters

Response