List MED recoveries awaiting return

curl --request GET \
  --url https://api.example.com/v1/med/recoveries/awaiting-return \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

	url := "https://api.example.com/v1/med/recoveries/awaiting-return"

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

	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: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/med/recoveries/awaiting-return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "breached": false,
      "contactEmail": "ops@example.com",
      "contactPhone": "+5511999999999",
      "createdAt": "2024-01-01T12:00:00.000Z",
      "creatorIspb": "12345678",
      "idTransacaoRaiz": "E1234567820240101000000000000001",
      "recoveryId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "situationType": 0,
      "situationTypeDescription": "Golpe/Estelionato",
      "status": 0,
      "statusDescription": "Criada",
      "updatedAt": "2024-01-01T12:05:00.000Z",
      "details": "Suspected scam.",
      "dictCorrelationId": "a9f13566e19f5ca51329479a5bae60c5",
      "dictReturnedAt": "2025-08-27T10:30:05.025Z",
      "returnDeadline": "2024-01-04T12:00:00.000Z"
    }
  ]
}

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

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

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

List MED recoveries awaiting return

Lists the creator-side analyzed value recoveries this institution may still return (contract §2.22/§5, within 72h of the analysis stage closing), ordered by return deadline (earliest first). The creator ISPB is config-derived. Each row surfaces returnDeadline and a computed breached flag. Read projection — no JDPI round-trip; no action taken and no money moved. Optional ispb narrows the queue to that one direct participant (an ISPB this deployment does not act as is 422 PIX-0128); a token confined to one participant has to name it. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its value recoveries; indirectId narrows the listing to ONE indirect — only the value recoveries over a payment this deployment recorded for that indirect (the payment’s own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect’s, never one over the direct participant’s own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array.

GET

med

recoveries

awaiting-return

List MED recoveries awaiting return

curl --request GET \
  --url https://api.example.com/v1/med/recoveries/awaiting-return \
  --header 'Authorization: Bearer <token>'

package main

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

func main() {

	url := "https://api.example.com/v1/med/recoveries/awaiting-return"

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

	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: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.example.com/v1/med/recoveries/awaiting-return', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "breached": false,
      "contactEmail": "ops@example.com",
      "contactPhone": "+5511999999999",
      "createdAt": "2024-01-01T12:00:00.000Z",
      "creatorIspb": "12345678",
      "idTransacaoRaiz": "E1234567820240101000000000000001",
      "recoveryId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "situationType": 0,
      "situationTypeDescription": "Golpe/Estelionato",
      "status": 0,
      "statusDescription": "Criada",
      "updatedAt": "2024-01-01T12:05:00.000Z",
      "details": "Suspected scam.",
      "dictCorrelationId": "a9f13566e19f5ca51329479a5bae60c5",
      "dictReturnedAt": "2025-08-27T10:30:05.025Z",
      "returnDeadline": "2024-01-04T12:00:00.000Z"
    }
  ]
}

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

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

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

Query Parameters

limit

integer<int64>

Maximum number of rows to return; 0 uses the server default.

Example:

50

ispb

string

The ISPB of the direct participant whose queue is listed. OPTIONAL: omit it and every participant of this deployment is listed, exactly as before. Named, only that participant's rows come back, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it.

Pattern: ^[0-9]{8}$

Example:

"12345678"

indirectId

string<uuid>

The registered indirect participant (UUID) whose recoveries are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the recoveries over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061.

Example:

"3f2504e0-4f89-41d3-9a0c-0305e82c3301"

Response

data

object[] | null

required

The list of value recoveries.

Show child attributes

Direct participant APIs

Indirect participant APIs

List MED recoveries awaiting return

Authorizations

Query Parameters

Response