# PIX

Claves DICT, consulta, envío, devolución, estado, cobro, portabilidad de clave (claims), MED (recuperación de fondos) e infracciones DICT. Cada operación está acotada a una cuenta del socio. Valores de entrada en **centavos**.

## Registrar clave DICT

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

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

- **Alcance:** `pix:write` · **Obligatorio:** `account_id` · **`type`:** `cpf`, `cnpj`, `phone`, `email` o `evp`

El desenlace del registro llega por el webhook `pix.key.registered`; la eliminación, el bloqueo y el desbloqueo llegan por `pix.key.deleted`, `pix.key.blocked` y `pix.key.unblocked`. Las reivindicaciones de portabilidad también emiten los webhooks `pix.claim.created`, `pix.claim.acknowledged`, `pix.claim.confirmed`, `pix.claim.cancelled` y `pix.claim.completed`. Todos están descritos en [Webhooks](/es/endpoints/webhooks).

## Listar claves DICT

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

- **Alcance:** `pix:read`

## Eliminar clave DICT

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

- **Alcance:** `pix:write`

## Consultar clave externa (DICT)

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

- **Alcance:** `pix:read`

Resuelve una clave PIX externa en el directorio, para pagar. Consulta de solo lectura.

## Enviar 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": "destino@ejemplo.com", "recipientIspb": "12345678", "description": "Pago" }
```

- **Alcance:** `pix:write` · **Obligatorios:** `account_id`, `amount` (centavos), `pixKey`, `recipientIspb`

**Respuesta `202`:**

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

## Estado del PIX

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

- **Alcance:** `pix:read`

## Devolver PIX

Devuelve un PIX **recibido** por la cuenta del socio. La devolución es emitida por Monetarie dentro de la ventana regulatoria de **90 días** contados desde la liquidación original. La devolución de un PIX que usted **envió** la emite el receptor y le llega por el webhook `pix.payout.returned`, no por este 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" }
```

- **Alcance:** `pix:write` · El `id` en la ruta es la transacción original recibida. **Obligatorios:** `account_id`, `amount` (centavos).
- `reason` es opcional (por defecto `MD06`) y está restringido a la lista `MD06`, `SL02`, `BE08`, `FR01`, `AC03`, `AC06`, `AC07`, `AC14`, `AG03`, `AG13`, `AM09`, `AM18`, `RR04`.
- La devolución **parcial** está permitida, hasta el restante devolvible de la transacción; las devoluciones pendientes cuentan contra el restante.

Respuesta `202` (aceptación, no el desenlace):

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

Rechazos: `404` cuando la original no existe o pertenece a otra cuenta; `422` fuera de la ventana de 90 días, valor por encima del restante devolvible, razón fuera de la lista o saldo insuficiente. El desenlace llega por los webhooks `pix.refund.completed` y `pix.refund.failed`, descritos en [Webhooks](/es/endpoints/webhooks).

## Rastro de devoluciones

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

- **Alcance:** `pix:read`

Devuelve la transacción original, el restante devolvible y la lista de devoluciones ya solicitadas:

```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" }
    ]
  }
}
```

El campo `rtrId` queda nulo mientras la devolución procesa. Valores en **centavos**. Un id inexistente o de otra cuenta responde `404`.

## Crear cobro PIX

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

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

- **Alcance:** `pix:write` · **Obligatorios:** `account_id`, `amount` (centavos)

La respuesta devuelve el BR Code (EMV), la imagen del QR en base64 y la `locationUrl` (la URL del payload dinámico que sirve el JWS firmado).

## QR estático (valor abierto o fijo)

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

{ "account_id": 1042, "description": "Donación" }
```

- **Alcance:** `pix:write` · **Obligatorio:** `account_id`. · **Opcionales:** `amount` (centavos), `pix_key`, `description`, `city`.

Sin `amount`, el QR se genera con valor ABIERTO (sin la etiqueta de valor en el EMV; el pagador escribe el valor). Con `amount`, el valor queda fijo. Los QR estáticos son reutilizables y no expiran.

## Estado del cobro PIX

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

- **Alcance:** `pix:read`

## Portabilidad de clave (claims)

Trae una clave PIX a una cuenta del socio. Cada operación está acotada al `account_id` informado.

```http
POST /api/partner/v1/pix/claims                         # crear (pix:write)
GET  /api/partner/v1/pix/claims?account_id=1042         # listar (pix:read)
GET  /api/partner/v1/pix/claims/{id}?account_id=1042    # consultar (pix:read)
POST /api/partner/v1/pix/claims/{id}/confirm             # confirmar (pix:write)
POST /api/partner/v1/pix/claims/{id}/complete            # completar (pix:write)
POST /api/partner/v1/pix/claims/{id}/cancel              # cancelar (pix:write)
Authorization: Bearer {{access_token}}
```

**Obligatorios en la creación:** `account_id`, `key`, `keyType`. El listado devuelve `{ "data": { "claims": [...], "total": 1 } }` solamente con las reivindicaciones que involucran la cuenta informada, como reivindicadora o donante (`claimer_account` o `donor_account`); acepta los filtros opcionales `status`, `limit` (por defecto 50) y `offset`. Confirmar es la acción de la cuenta donante; completar es la acción de la reivindicadora al final de la portabilidad o reivindicación de posesión. Una reivindicación que no involucra la cuenta responde `403`; un id desconocido responde `404`. Cada etapa también emite los webhooks `pix.claim.*` descritos en [Webhooks](/es/endpoints/webhooks).

## MED (recuperación de fondos)

El MED es el mecanismo de recuperación de fondos del PIX. Cuando un cliente reporta un fraude o una estafa en un PIX enviado, usted abre una intervención para intentar recuperar el valor ante la institución receptora.

### Abrir intervención

```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": "Cliente reporta una estafa en la negociación"
}
```

- **Alcance:** `pix:write` · Cuerpo: `account_id`, `end_to_end_id`, `fraud_category` y `details` (descripción del caso).
- `fraud_category` acepta `FRAUDULENT_ACCESS`, `SCAM`, `ACCOUNT_TAKEOVER` u `OTHER`.
- La transacción del `end_to_end_id` debe pertenecer a la cuenta informada; de lo contrario la respuesta es `422`.

Respuesta `202`:

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

### Consultar y listar intervenciones

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

La consulta responde `404` cuando la intervención no pertenece a la cuenta informada. El listado acepta `limit` (por defecto 50) y devuelve `{ "data": { "recoveries": [ { medId, status, rootTransactionId, fraudCategory, createdAt } ], "total": 1 } }`, solamente con las intervenciones cuya transacción raíz involucra la cuenta.

### Cancelar intervención

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

{ "account_id": 10024270 }
```

- **Alcance:** `pix:write` · Responde `404` cuando la intervención no pertenece a la cuenta informada.

La respuesta trae el estado actualizado en `data`. La cancelación también se notifica por el webhook `pix.med.cancelled`.

### Grafo de rastreo

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

- **Alcance:** `pix:read` · Responde `404` cuando la intervención no pertenece a la cuenta informada.

Devuelve en `data` el grafo de rastreo de los fondos de la intervención, en el formato de la red PIX.

### Solicitar la devolución de los fondos

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

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

- **Alcance:** `pix:write` · `amount` (centavos) es opcional: sin él, la devolución sale por el valor íntegro de la transacción raíz.

Respuesta `202` con `data` (`refundId`, `recoveryId`, `status`, `amount`), la aceptación de la solicitud, no el desenlace.

Siga el avance de las intervenciones por los webhooks `pix.med.created`, `pix.med.completed` y `pix.med.cancelled`, descritos en [Webhooks](/es/endpoints/webhooks).

## Infracciones DICT

Reportes de infracción sobre transacciones PIX de la cuenta (marcación de fraude en el DICT), y la defensa del cliente cuando una infracción abierta por otra institución bloquea valores cautelarmente.

### Abrir reporte

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

{ "account_id": 10024270, "end_to_end_id": "E4602656220260714210000aabbccdd0", "details": "Cliente reporta fraude en la transacción" }
```

- **Alcance:** `pix:write` · **Obligatorios:** `account_id`, `end_to_end_id`. `details` describe el caso.
- La transacción del `end_to_end_id` debe pertenecer a la cuenta informada; de lo contrario la respuesta es `422`.

Respuesta `202` con `data` (`infractionId`, `status`, `endToEndId`, `debtorIspb`, `creditorIspb`, `analysisResult`, `analysisDetails`, `createdAt`, `updatedAt`), la aceptación del reporte, no el desenlace del análisis.

### Listar y consultar

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

El listado acepta `limit` (por defecto 50) y `offset`, y devuelve `{ "data": { "infractions": [...], "total": 1 } }`, solamente con reportes sobre transacciones de la cuenta. Una infracción que no involucra la cuenta responde `404`.

### Cancelar reporte

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

{ "account_id": 10024270 }
```

- **Alcance:** `pix:write` · Mismo alcance de la consulta: una infracción que no involucra la cuenta responde `404`.

### Enviar defensa

Cuando una infracción abierta por otra institución bloquea valores de la cuenta cautelarmente, el cliente puede presentar defensa.

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

{ "account_id": 10024270, "defense_text": "Prestación de servicio comprobada, factura 4210 adjunta al caso" }
```

- **Alcance:** `pix:write` · **Obligatorios:** `account_id`, `defense_text`. El `id` acepta el identificador de la infracción o del bloqueo.

Respuesta `200`:

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

Una infracción que ya no está en fase de defensa responde `422`. El registro de la defensa también se notifica por el webhook `pix.infraction.defense_submitted`, y el desenlace del análisis por `pix.infraction.resolved`, descritos en [Webhooks](/es/endpoints/webhooks).