---
title: Postman Collection
---

# API Collections

Ready-to-import collection for Postman, Insomnia, or any compatible HTTP client.

::: tip Which to use?
- **Postman** (JSON below) -- 21 requests covering the 18 external endpoints (PIX Cash-Out has 3 variants: key, email, copy-and-paste), plus a `GET /health` example (endpoint outside the `/api/external` namespace, useful for availability probing). Static snapshot updated when needed.
:::

## Postman Download

<a href="/downloads/monetarie-api-externa.postman_collection.json" download>Download Postman Collection (JSON)</a>

## What's included

| Category | Endpoints |
|----------|-----------|
| PIX Cash-Out | Send by key, email, copy-and-paste (3 variants of the same endpoint `POST /pix/cash-out`) |
| PIX Cash-In | Generate QR Code (`POST /pix/cash-in`) |
| Queries | By ID, E2E, tag, external_id, receipt |
| Statement | `GET /statement` |
| Transactions | `GET /transactions` (list with filters) |
| Balance | `GET /balance` |
| PIX Keys | `GET /pix/keys` |
| Refund | `POST /pix/refund` |
| Webhooks | `POST /webhooks`, `GET /webhooks`, `DELETE /webhooks/:id` |
| MED | `GET /med`, `GET /med/:id` |
| Validation | `POST /cpf/validate` |
| Health | `GET /health` (outside `/api/external`, availability probe) |

**Total: 21 requests covering the 18 External API endpoints + 1 `GET /health` probe.**


## Setup

### 1. Import in Postman

1. Open Postman
2. Click **Import** (top left corner)
3. Drag the JSON file or click **Upload Files**
4. The "Monetarie - API Externa" collection appears in the left panel

### 2. Configure variables

Click the collection > **Variables** tab and fill in:

| Variable | Value | Description |
|----------|-------|-------------|
| `base_url` | `https://api.monetarie.com/api/external` | API base URL (production) |
| `client_id` | Your `cli_...` | API key Client ID |
| `client_secret` | Your `sk_...` | API key Client Secret |

For staging, request the URL and credentials from the Monetarie team.

### 3. Automatic HMAC

The collection has a global **pre-request script** that automatically generates the `hmac` header (HMAC-SHA512) for all POST requests. The script does `JSON.parse(body)` + `JSON.stringify(parsed, Object.keys(parsed).sort())` to ensure the body is serialized with **keys in alphabetical order** before computing the HMAC -- this matches the backend `Jason.decode + Jason.encode!` normalization. No manual computation needed.

::: warning HMAC only on POST
`GET` and `DELETE` requests **do not** receive an `hmac` header -- they have no body to sign. The pre-request script ignores these methods automatically.
:::

### 4. Automatic variables

Test scripts automatically capture:
- `last_transaction_id` - from cash-out response
- `last_e2e_id` - from cash-out response
- `last_qr_tx_id` - from cash-in response

These variables are reused in subsequent queries.

## Monetary values

::: warning Attention
**Request**: values in centavos (R$ 1.00 = `100`)

**Response**: values in subcentavos (R$ 1.00 = `10000`)

To convert response to BRL: divide by 10,000.
:::

## Suggested workflow

1. **Balance** - `GET /balance` to check available balance (no rate limit)
2. **Cash-In** - `POST /pix/cash-in` to generate QR Code
3. **Cash-Out** - `POST /pix/cash-out` to send PIX
4. **Query** - `GET /transactions/:id` (by internal ID) or `GET /transactions/e2e/:e2e_id` (by BACEN E2E) to track status
5. **Query by external_id** - `GET /transactions/ref/:external_id` to locate by your system reference
6. **Receipt** - `GET /transactions/:id/receipt` available only when `status: "settled"` (PIX Cash-Out) or `paid_at` filled in (Cash-In)
7. **Webhooks** - `POST /webhooks` to receive asynchronous status notifications (recommended alternative to polling)

## Import in Insomnia

1. Open Insomnia
2. **Application > Preferences > Data > Import Data**
3. Select **From File** and choose the JSON
4. Set up environment variables with the same values above