Skip to main content
Use Cursor to accelerate your integration with the Owem API. This guide shows how to configure Cursor to write code that consumes the PIX payments API.

​
Prerequisites

  • Cursor installed
  • Owem API credentials (API Key + Secret)
  • Project set up (Node.js, Python, or other language)

​
Rules Configuration

Create project rules so Cursor understands the Owem API. In your project root: 
mkdir -p .cursor
Create the file .cursor/rules.md: 
# Owem API Rules

You are an assistant specialized in integrating applications with the Owem PIX payments API.

## Owem API Context

- **Base URL**: `https://api.owem.com.br`
- **Authentication**: Basic Auth with `API_KEY:API_SECRET` in Base64
- **Documentation**: https://docs.owem.com.br

## Main Endpoints

### PIX IN (Receiving)

- `POST /v4/i/pix/in/dynamic-qrcode` - Generate dynamic QR Code
- `GET /v4/i/pix/in/dynamic-qrcode/{txId}` - Query QR Code
- `POST /v4/i/pix/in/refund/{endToEndId}` - Refund PIX
- `GET /v4/i/pix/in/refund/{endToEndId}` - Query refund

### PIX OUT (Sending)

- `POST /v4/i/bank-accounts/{accountId}/transfer/external` - PIX transfer
- `GET /v4/i/bank-accounts/{accountId}/transfer/external/{endToEnd}` - Query transfer

### Ledger (Statement)

- `GET /v4/i/ledger` - List movements
- `GET /v4/i/ledger/external-id/{externalId}` - Search by external ID
- `GET /v4/i/ledger/end-to-end/{endToEndId}` - Search by E2E
- `GET /v4/i/ledger/entry-id/{entryId}` - Search by Entry ID

### Webhooks

- `POST /v4/i/webhooks/config` - Create webhook
- `GET /v4/i/webhooks/config` - List webhooks
- `PUT /v4/i/webhooks/config/{configId}` - Update webhook
- `DELETE /v4/i/webhooks/config/{configId}` - Delete webhook

## Code Patterns

### Authentication

Always use Basic Auth with Base64 token:

```javascript
const token = Buffer.from(`${API_KEY}:${API_SECRET}`).toString("base64")
const headers = {
  Authorization: `Basic ${token}`,
  "Content-Type": "application/json",
}
```

### Error Handling

The API returns errors in the format:

```json
{
  "requestId": "uuid",
  "success": false,
  "status": 400,
  "message": "Error message",
  "code": "ERROR_CODE"
}
```

### Idempotency

Use `externalId` to ensure transaction idempotency:

```javascript
{
  "amount": 100.00,
  "pixKey": "key@pix.com",
  "externalId": "order-12345" // Your unique ID
}
```

## Important Rules

1. **NEVER** expose API_KEY or API_SECRET in client code
2. **ALWAYS** validate webhooks by source IP (34.134.50.53, 35.238.101.57)
3. **ALWAYS** use HTTPS
4. Use `endToEndId` to track PIX transactions
5. Use `externalId` to correlate with your system

## Webhook Events

| Event                | Description        |
| -------------------- | ------------------ |
| `pix_in:qrcode_paid` | QR Code paid       |
| `pix_out:succeeded`  | Transfer completed |
| `pix_out:failed`     | Transfer failed    |
| `med:created`        | New dispute (MED)  |

​
Usage Example

With the rules configured, you can ask Cursor:

Generate QR Code

“Create a function to generate a dynamic PIX QR Code with the Owem API”

Process Webhook

“Create an Express endpoint to receive Owem webhooks”

Check Balance

“Make a function to check the bank account balance”

PIX Transfer

“Implement a function to make a PIX OUT transfer”

​
Tips

Use Owem’s llms.txt file at https://docs.owem.com.br/llms.txt to give Cursor extra context about the API.
Never include real credentials in code examples. Use environment variables.