# Getting Started

Integrate your application with the Monetarie API and perform your first PIX operation in just a few minutes.

## 1. Obtain your credentials

Request from your Monetarie account administrator:

- **Client ID** -- your API Key identifier (prefix `cli_`)
- **Client Secret** -- secret key for authentication and HMAC signing (prefix `sk_`)

::: warning Security
Never expose the `client_secret` in frontend code or public repositories. Use environment variables on your server.
:::

## 2. Configure authentication

All requests require the `Authorization` header with your API Key credentials:

```bash
# Header format:
Authorization: ApiKey {client_id}:{client_secret}
```

The API Key is permanent -- it does not expire. No token generation is required.

## 3. Check the balance

Test the integration by querying the account balance:

```bash
curl -X GET https://api.monetarie.com/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

**Response:**

```json
{
  "worked": true,
  "balance": 300000,
  "available": 300000,
  "pending": 0,
  "currency": "BRL"
}
```

::: danger Monetary values
**Request** values are in **centavos**: R$ 30.00 = `3000`.
**Response** values are in **base units**: `300000` / 10,000 = R$ 30.00.
**Never use floating point** -- always integers.
:::

## 4. Generate a PIX charge (Cash-In)

Create a QR Code to receive R$ 30.00:

```bash
BODY='{"amount":3000,"description":"Pedido #1234","external_id":"order-9876"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.monetarie.com/api/external/pix/cash-in \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"
```

**Response:**

```json
{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}
```

Note that you sent `3000` (centavos) and received `300000` (base units). Both represent R$ 30.00.

Display the `qr_code_image` or the copy-and-paste code (`qr_code`) to the payer.

## 5. Check the status

Track the payment by querying with the `transaction_id`:

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

When the payment is confirmed, the `status` changes to `completed`.

You can also query by `external_id`:

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## 6. Receive notifications (Webhooks)

To receive real-time notifications (recommended over polling):

```bash
BODY='{"url":"https://seusite.com.br/webhook","events":["pix.received","pix.completed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.monetarie.com/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"
```

## Next Steps

- [Authentication](/en/auth-token) -- API Key + HMAC (3 layers of security)
- [HMAC-SHA512](/en/hmac) -- how to sign transactional requests
- [PIX Cash-In](/en/pix-cashin) -- generate charges
- [PIX Cash-Out](/en/pix-cashout-key) -- send PIX by key
- [Statement](/en/bank-statement) -- query transactions
- [Webhooks](/en/webhooks) -- real-time notifications
- [Concepts](/en/guide/concepts) -- values, status, external_id, idempotency, and PIX keys