# PIX

DICT keys, lookup, send, refund, status, charge, key portability (claims), MED (funds recovery) and DICT infractions. Every operation is scoped to a partner account. Input values in **cents**.

## Register DICT key

```http
POST /api/partner/v1/pix/keys
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "type": "evp" }
```

- **Scope:** `pix:write` · **Required:** `account_id` · **`type`:** `cpf`, `cnpj`, `phone`, `email` or `evp`

The outcome of the registration arrives through the `pix.key.registered` webhook; deletion, block and unblock arrive through `pix.key.deleted`, `pix.key.blocked` and `pix.key.unblocked`. Portability claims also emit the `pix.claim.created`, `pix.claim.acknowledged`, `pix.claim.confirmed`, `pix.claim.cancelled` and `pix.claim.completed` webhooks. All of them are described in [Webhooks](/en/endpoints/webhooks).

## List DICT keys

```http
GET /api/partner/v1/pix/keys
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read`

## Delete DICT key

```http
DELETE /api/partner/v1/pix/keys/{key}
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:write`

## Look up external key (DICT)

```http
GET /api/partner/v1/pix/dict/{key}
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read`

Resolves an external PIX key in the directory, to pay. Read-only lookup.

## Send PIX

```http
POST /api/partner/v1/pix/payments
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: 9f2a...

{ "account_id": 1042, "amount": 1500, "pixKey": "dest@example.com", "recipientIspb": "12345678", "description": "Payment" }
```

- **Scope:** `pix:write` · **Required:** `account_id`, `amount` (cents), `pixKey`, `recipientIspb`

**Response `202`:**

```json
{ "status": "accepted", "transactionId": "...", "endToEndId": "E...", "amount": 1500 }
```

## PIX status

```http
GET /api/partner/v1/pix/payments/{id}
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read`

## Refund PIX

Refunds a PIX **received** by the partner account. The refund is issued by Monetarie within the regulatory window of **90 days** from the original settlement. The refund of a PIX you **sent** is issued by the receiver and reaches you through the `pix.payout.returned` webhook, not through this endpoint.

```http
POST /api/partner/v1/pix/payments/{id}/refund
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "amount": 5000, "reason": "MD06", "description": "Devolução solicitada pelo pagador" }
```

- **Scope:** `pix:write` · The `id` in the path is the original received transaction. **Required:** `account_id`, `amount` (cents).
- `reason` is optional (default `MD06`) and restricted to the list `MD06`, `SL02`, `BE08`, `FR01`, `AC03`, `AC06`, `AC07`, `AC14`, `AG03`, `AG13`, `AM09`, `AM18`, `RR04`.
- **Partial** refunds are allowed, up to the refundable remainder of the transaction; pending refunds count against the remainder.

Response `202` (acknowledgement, not the outcome):

```json
{
  "data": {
    "refundId": "PIXRET20260718b1c2d3e4f5a6",
    "originalTransactionId": "PIXIN20260718abc123",
    "endToEndId": "E4602656220260718091500aa11bb22c",
    "amount": 5000,
    "remainingRefundable": 5000,
    "status": "processing",
    "message": "Devolução PIX enviada para processamento"
  }
}
```

Refusals: `404` when the original does not exist or belongs to another account; `422` outside the 90 day window, amount above the refundable remainder, reason outside the list, or insufficient balance. The outcome arrives through the `pix.refund.completed` and `pix.refund.failed` webhooks, described in [Webhooks](/en/endpoints/webhooks).

## Refund trail

```http
GET /api/partner/v1/pix/payments/{id}/refunds?account_id=1042
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read`

Returns the original transaction, the refundable remainder and the list of refunds already requested:

```json
{
  "data": {
    "original": { "transactionId": "PIXIN20260718abc123", "endToEndId": "E4602656220260718091500aa11bb22c", "amount": 10000, "status": "settled", "completedAt": "2026-07-18T09:15:01Z" },
    "remainingRefundable": 5000,
    "refunds": [
      { "refundId": "PIXRET20260718b1c2d3e4f5a6", "rtrId": "D46026562202607180920aabbccddeef", "amount": 5000, "status": "settled", "reasonCode": "MD06", "reasonDescription": "Devolução solicitada pelo pagador", "requestedAt": "2026-07-18T09:20:00Z", "completedAt": "2026-07-18T09:20:02Z" }
    ]
  }
}
```

The `rtrId` field stays null while the refund is processing. Values in **cents**. An unknown id, or one belonging to another account, responds `404`.

## Create PIX charge

```http
POST /api/partner/v1/pix/charges
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "amount": 1500, "description": "Charge" }
```

- **Scope:** `pix:write` · **Required:** `account_id`, `amount` (cents)

The response returns the BR Code (EMV), the QR image in base64 and the `locationUrl` (the dynamic payload URL that serves the signed JWS).

## Static QR (open value or fixed)

```http
POST /api/partner/v1/pix/qrcodes/static
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 1042, "description": "Donation" }
```

- **Scope:** `pix:write` · **Required:** `account_id`. · **Optional:** `amount` (cents), `pix_key`, `description`, `city`.

Without `amount` the QR is generated with an OPEN value (no EMV amount tag; the payer types the amount). With `amount` the value is fixed. Static QRs are reusable and never expire.

## PIX charge status

```http
GET /api/partner/v1/pix/charges/{id}
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read`

## Key portability (claims)

Brings a PIX key to a partner account. Every operation is scoped to the given `account_id`.

```http
POST /api/partner/v1/pix/claims                         # create (pix:write)
GET  /api/partner/v1/pix/claims?account_id=1042         # list (pix:read)
GET  /api/partner/v1/pix/claims/{id}?account_id=1042    # status (pix:read)
POST /api/partner/v1/pix/claims/{id}/confirm             # confirm (pix:write)
POST /api/partner/v1/pix/claims/{id}/complete            # complete (pix:write)
POST /api/partner/v1/pix/claims/{id}/cancel              # cancel (pix:write)
Authorization: Bearer {{access_token}}
```

**Required on creation:** `account_id`, `key`, `keyType`. The listing returns `{ "data": { "claims": [...], "total": 1 } }` only with claims that involve the given account, as claimer or donor (`claimer_account` or `donor_account`); optional filters `status`, `limit` (default 50) and `offset`. Confirm is the donor action; complete is the claimer action at the end of the portability or ownership claim. A claim that does not involve the account responds `403`; an unknown id responds `404`. Each step also emits the `pix.claim.*` webhooks described in [Webhooks](/en/endpoints/webhooks).

## MED (funds recovery)

MED is the PIX funds recovery mechanism. When a customer reports fraud or a scam on a PIX they sent, you open an intervention to try to recover the amount from the receiving institution.

### Open an intervention

```http
POST /api/partner/v1/pix/med
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "account_id": 10024270,
  "end_to_end_id": "E4602656220260714210000aabbccdd0",
  "fraud_category": "SCAM",
  "details": "Customer reports a scam in the negotiation"
}
```

- **Scope:** `pix:write` · Body: `account_id`, `end_to_end_id`, `fraud_category` and `details` (description of the case).
- `fraud_category` accepts `FRAUDULENT_ACCESS`, `SCAM`, `ACCOUNT_TAKEOVER` or `OTHER`.
- The transaction in `end_to_end_id` must belong to the given account; otherwise the response is `422`.

Response `202`:

```json
{
  "data": {
    "medId": "REC-...",
    "status": "CREATED",
    "rootTransactionId": "E4602656220260714210000aabbccdd0",
    "fraudCategory": "SCAM",
    "createdAt": "2026-07-14T21:05:00Z"
  }
}
```

### Query and list interventions

```http
GET /api/partner/v1/pix/med/{id}?account_id=10024270   # status (pix:read)
GET /api/partner/v1/pix/med?account_id=10024270        # list (pix:read)
Authorization: Bearer {{access_token}}
```

The query responds `404` when the intervention does not belong to the given account. The listing accepts `limit` (default 50) and returns `{ "data": { "recoveries": [ { medId, status, rootTransactionId, fraudCategory, createdAt } ], "total": 1 } }`, only with interventions whose root transaction involves the account.

### Cancel an intervention

```http
POST /api/partner/v1/pix/med/{id}/cancel
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 10024270 }
```

- **Scope:** `pix:write` · Responds `404` when the intervention does not belong to the given account.

The response carries the updated state in `data`. The cancellation is also notified through the `pix.med.cancelled` webhook.

### Tracking graph

```http
GET /api/partner/v1/pix/med/{id}/graph?account_id=10024270
Authorization: Bearer {{access_token}}
```

- **Scope:** `pix:read` · Responds `404` when the intervention does not belong to the given account.

Returns in `data` the funds tracking graph of the intervention, in the PIX network format.

### Request the funds return

```http
POST /api/partner/v1/pix/med/{id}/refund
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 10024270, "amount": 5000 }
```

- **Scope:** `pix:write` · `amount` (cents) is optional: without it, the return goes for the full value of the root transaction.

Response `202` with `data` (`refundId`, `recoveryId`, `status`, `amount`), the acceptance of the request, not the outcome.

You can track the interventions through the `pix.med.created`, `pix.med.completed` and `pix.med.cancelled` webhooks, described in [Webhooks](/en/endpoints/webhooks).

## DICT infractions

Infraction reports on PIX transactions of the account (fraud marking in the DICT), and the client defense when an infraction opened by another institution blocks funds precautionarily.

### Open a report

```http
POST /api/partner/v1/pix/infractions
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 10024270, "end_to_end_id": "E4602656220260714210000aabbccdd0", "details": "Customer reports fraud on the transaction" }
```

- **Scope:** `pix:write` · **Required:** `account_id`, `end_to_end_id`. `details` describes the case.
- The transaction in `end_to_end_id` must belong to the given account; otherwise the response is `422`.

Response `202` with `data` (`infractionId`, `status`, `endToEndId`, `debtorIspb`, `creditorIspb`, `analysisResult`, `analysisDetails`, `createdAt`, `updatedAt`), the acceptance of the report, not the outcome of the analysis.

### List and query

```http
GET /api/partner/v1/pix/infractions?account_id=10024270          # list (pix:read)
GET /api/partner/v1/pix/infractions/{id}?account_id=10024270     # status (pix:read)
Authorization: Bearer {{access_token}}
```

The listing accepts `limit` (default 50) and `offset`, and returns `{ "data": { "infractions": [...], "total": 1 } }`, only with reports on transactions of the account. An infraction that does not involve the account responds `404`.

### Cancel a report

```http
POST /api/partner/v1/pix/infractions/{id}/cancel
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 10024270 }
```

- **Scope:** `pix:write` · Same scoping as the query: an infraction that does not involve the account responds `404`.

### Submit a defense

When an infraction opened by another institution blocks funds of the account precautionarily, the client may submit a defense.

```http
POST /api/partner/v1/pix/infractions/{id}/defense
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_id": 10024270, "defense_text": "Service delivery proven, invoice 4210 attached to the case" }
```

- **Scope:** `pix:write` · **Required:** `account_id`, `defense_text`. The `id` accepts the infraction or the block identifier.

Response `200`:

```json
{ "data": { "infractionId": "b17c9a02-4a2f-4d5e-9b1a-77e0a1c2d3e4", "blockId": "3f21aa8c-1b2c-4d5e-8f90-0a1b2c3d4e5f", "status": "defense_submitted" } }
```

An infraction no longer in the defense phase responds `422`. The defense is also notified through the `pix.infraction.defense_submitted` webhook, and the outcome of the analysis through `pix.infraction.resolved`, described in [Webhooks](/en/endpoints/webhooks).