# Hub API Documentation

> Hub API for Pix payments, cashouts, balance management, and webhooks.

## Overview

Hub API allows you to integrate Pix payments, request cashouts, check balances, and receive real-time notifications via webhooks. All endpoints require `x-api-key` and `x-token` headers.

## Authentication

Every request must include:
- `Content-Type: application/json`
- `x-api-key: <YOUR_API_KEY>`
- `x-token: <YOUR_TOKEN>`

POST requests also require:
- `idempotency-key: <UNIQUE_KEY>`

Optional headers:
- `x-timezone: <TIMEZONE>` - Timezone for date/time fields (e.g., `America/Sao_Paulo`). Defaults to UTC if not specified.

## Endpoints Summary

### Transactions

- `POST /api/transactions` - Create a Pix transaction
- `GET /api/transactions` - Query transactions (filters: magic_id, status, external_ref, end_to_end, limit, resend)

### Cashout (Withdrawals)

- `POST /api/withdrawals` - Request a Pix cashout
- `GET /api/withdrawals` - Query cashouts (filters: magic_id, status, external_ref, end_to_end, limit, resend)

### Balance

- `GET /api/balance` - Retrieve current balance with breakdowns (balance, blocked, reserve, processing)

### Webhooks

- `POST /api/webhooks` - Register a webhook endpoint
- `GET /api/webhooks` - List all registered webhooks
- `DELETE /api/webhooks/{magic_id}` - Delete a webhook

### Exports

- `GET /api/export/charges` - Queue charges export (date_range: today, yesterday, current_month, last_seven_days, last_four_weeks, last_month, all)
- `GET /api/export/withdrawals` - Queue withdrawals export

---

## Transaction Statuses

| Status | Description |
|--------|-------------|
| PENDING | Awaiting completion or payment confirmation |
| CONFIRMED | Payment authorized/cleared and funds available |
| FAILED | Payment attempt did not complete |
| REFUNDED | Full amount returned to the payer |
| EXPIRED | Payment window closed without completion |
| DISPUTE_NEEDS_RESPONSE | Dispute opened, action required |
| DISPUTE_IN_REVIEW | Dispute under review |
| DISPUTE_WON | Dispute resolved in your favor |
| DISPUTE_LOST | Dispute resolved against you |

## Withdrawal Statuses

| Status | Description |
|--------|-------------|
| CREATED | Withdrawal request accepted and queued |
| PROCESSING | Bank transfer is being executed |
| CONFIRMED | Transfer completed successfully |
| FAILED | Transfer failed |
| CANCELED | Request canceled before completion |
| REFUNDED | Funds returned after completed transfer |

## Pix Key Formats

| Type | Format | Example |
|------|--------|---------|
| CPF | 11 digits only | 95876150096 |
| CNPJ | 14 digits only | 33400689000109 |
| PHONE | E.164 format | +5511999999999 |
| EMAIL | Standard email | finance@example.com |
| EVP | UUID | 17ce9060-b29d-4ab5-89cd-20550ce6e7ac |

## Webhook Events

Events: `transaction`, `withdraw`, `dispute`

### Webhook Headers

- `x-webhook-signature` - HMAC SHA256 signature of payload
- `x-webhook-event` - Event type (TRANSACTION, WITHDRAW)
- `x-user-reference` - User reference identifier

---

# CURL EXAMPLES

## Transactions

### POST /api/transactions - Create Transaction

```bash
curl --request POST \
  --url https://my.domain.io/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 4.00,
    "external_ref": "external_ref_order",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "expires_in": 3600,
    "description": "Order payment"
  }'
```

### GET /api/transactions - List Transactions

```bash
curl --request GET \
  --url 'https://my.domain.io/api/transactions?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/transactions - Query by External Ref

```bash
curl --request GET \
  --url 'https://my.domain.io/api/transactions?external_ref=external_ref_order&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/transactions - Query by Magic ID

```bash
curl --request GET \
  --url 'https://my.domain.io/api/transactions?magic_id=03UdoKvLNLHg' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/transactions - Query by Status

```bash
curl --request GET \
  --url 'https://my.domain.io/api/transactions?status=CONFIRMED&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/transactions - Query with Webhook Resend

```bash
curl --request GET \
  --url 'https://my.domain.io/api/transactions?magic_id=03UdoKvLNLHg&resend=true' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

---

## Withdrawals (Cashout)

### POST /api/withdrawals - Create Withdrawal

```bash
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 3.00,
    "key": "95876150096",
    "key_type": "cpf",
    "transfer_method": "Pix",
    "description": "Withdrawing",
    "external_ref": "Zc1ULDLzSYjMpolha11g3"
  }'
```

### POST /api/withdrawals - Create Withdrawal with CNPJ

```bash
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 1500.00,
    "key": "33400689000109",
    "key_type": "cnpj",
    "transfer_method": "Pix",
    "description": "Supplier payment",
    "external_ref": "supplier_payment_001"
  }'
```

### POST /api/withdrawals - Create Withdrawal with Email

```bash
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 250.00,
    "key": "finance@company.com",
    "key_type": "email",
    "transfer_method": "Pix",
    "description": "Refund"
  }'
```

### POST /api/withdrawals - Create Withdrawal with Phone

```bash
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 100.00,
    "key": "+5511999999999",
    "key_type": "phone",
    "transfer_method": "Pix"
  }'
```

### POST /api/withdrawals - Create Withdrawal with EVP

```bash
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 500.00,
    "key": "17ce9060-b29d-4ab5-89cd-20550ce6e7ac",
    "key_type": "evp",
    "transfer_method": "Pix"
  }'
```

### GET /api/withdrawals - List Withdrawals

```bash
curl --request GET \
  --url 'https://my.domain.io/api/withdrawals?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/withdrawals - Query by Magic ID

```bash
curl --request GET \
  --url 'https://my.domain.io/api/withdrawals?magic_id=9Wlp_2kGy4t9' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/withdrawals - Query with Multiple Filters

```bash
curl --request GET \
  --url 'https://my.domain.io/api/withdrawals?magic_id=9Wlp_2kGy4t9&status=CREATED&external_ref=Zc1ULDLzSYjMpolha11g3&end_to_end=E607894312025071873189DAHJSKH12&limit=20' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/withdrawals - Query with Webhook Resend

```bash
curl --request GET \
  --url 'https://my.domain.io/api/withdrawals?magic_id=9Wlp_2kGy4t9&resend=true' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

---

## Balance

### GET /api/balance - Retrieve Balance

```bash
curl --request GET \
  --url https://my.domain.io/api/balance \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/balance - Filter by Currency

```bash
curl --request GET \
  --url 'https://my.domain.io/api/balance?currency=BRL' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/balance - Filter by Type

```bash
curl --request GET \
  --url 'https://my.domain.io/api/balance?type=FIAT' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

---

## Webhooks

### POST /api/webhooks - Create Webhook

```bash
curl --request POST \
  --url https://my.domain.io/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/hub",
    "events": ["transaction", "withdraw", "dispute"]
  }'
```

### POST /api/webhooks - Create Webhook (Transaction Only)

```bash
curl --request POST \
  --url https://my.domain.io/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/transactions",
    "events": ["transaction"]
  }'
```

### POST /api/webhooks - Create Webhook (Withdraw Only)

```bash
curl --request POST \
  --url https://my.domain.io/api/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "url": "https://your-server.com/webhooks/withdrawals",
    "events": ["withdraw"]
  }'
```

### GET /api/webhooks - List Webhooks

```bash
curl --request GET \
  --url https://my.domain.io/api/webhooks \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### DELETE /api/webhooks/{magic_id} - Delete Webhook

```bash
curl --request DELETE \
  --url https://my.domain.io/api/webhooks/wh_03UdoKvLNLHg \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>'
```

---

## Exports

### GET /api/export/charges - Export All Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=all' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Today's Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=today' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Yesterday's Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=yesterday' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Current Month Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=current_month' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Last Seven Days Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=last_seven_days' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Last Four Weeks Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=last_four_weeks' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/charges - Export Last Month Charges

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/charges?date_range=last_month' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/withdrawals - Export All Withdrawals

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/withdrawals?date_range=all' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/withdrawals - Export Today's Withdrawals

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/withdrawals?date_range=today' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/withdrawals - Export Last Seven Days Withdrawals

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/withdrawals?date_range=last_seven_days' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

### GET /api/export/withdrawals - Export Last Month Withdrawals

```bash
curl --request GET \
  --url 'https://my.domain.io/api/export/withdrawals?date_range=last_month' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'
```

---

## Response Examples

### Transaction Created (201)

```json
{
  "code": 201,
  "content": {
    "magic_id": "18017579377364992",
    "amount": 4.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "Order payment",
    "payment_method": "Pix",
    "qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode...",
    "end_to_end": "38169107220140032",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "external_ref": "external_ref_order",
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Transaction created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}
```

### Withdrawal Created (201)

```json
{
  "code": 201,
  "content": {
    "magic_id": "wth_03UdoKvLNLHg",
    "fee": 0.15,
    "amount": 3.00,
    "currency": "BRL",
    "status": "CREATED",
    "transfer_method": "Pix",
    "external_ref": "Zc1ULDLzSYjMpolha11g3",
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Withdrawal created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}
```

### Balance Retrieved (200)

```json
{
  "code": 200,
  "content": {
    "currency": "BRL",
    "balance": 1250.75,
    "blocked": 120.00,
    "reserve": 80.00,
    "processing": 45.50
  },
  "message": "Balance returned",
  "timestamp": "2025-02-19T17:15:26.703Z"
}
```

### Webhook Created (201)

```json
{
  "code": 201,
  "content": {
    "magic_id": "wh_03UdoKvLNLHg",
    "url": "https://your-server.com/webhooks/hub",
    "secret": "whsec_2f1f9e5cbe7b4b3c9a6d",
    "events": ["transaction", "withdraw", "dispute"],
    "active": true,
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Webhook created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}
```

### Export Queued (202)

```json
{
  "code": 202,
  "content": {
    "job_id": "ylha4p50euonl2nrwbvl33pj",
    "date_range": "all",
    "kind": "charges"
  },
  "message": "Charges export queued",
  "timestamp": "2026-01-01T19:43:02.492155Z"
}
```

### Error Response (400)

```json
{
  "error": 400,
  "message": "Invalid request payload"
}
```

---

## Webhook Payloads

### Transaction Webhook

```json
{
  "data": {
    "magic_id": "T_123JKL114HJHDKSAH1JK23",
    "amount": 1.0,
    "currency": "BRL",
    "status": "CONFIRMED",
    "decline_reason": null,
    "description": "optional",
    "payment_method": "Pix",
    "qr_code": "00020101021126700014br.gov.bcb.pix...",
    "end_to_end": "E607894312025071873189DAHJSKH12",
    "external_ref": "external_ref_order",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "movement": {
      "payer": {
        "name": "Payer Name",
        "document": "12345678901",
        "bank": "BANCO INTER S.A.",
        "agency": "0001",
        "account": "123456-7"
      },
      "payee": {
        "name": "Payee Name",
        "document": "12345678000190",
        "bank": "BANCO INTER S.A.",
        "agency": "0001",
        "account": "765432-1"
      }
    },
    "created_at": "2025-12-14T01:03:06.467Z",
    "updated_at": "2025-12-14T01:03:06.467Z"
  },
  "event": "TRANSACTION"
}
```

### Withdrawal Webhook

```json
{
  "data": {
    "magic_id": "wth_03UdoKvLNLHg",
    "amount": 1.0,
    "currency": "BRL",
    "status": "CONFIRMED",
    "fee": 0.15,
    "decline_reason": null,
    "description": "Withdrawal",
    "transfer_method": "Pix",
    "end_to_end": "E607894312025071873189DAHJSKH12",
    "external_ref": "withdrawal_12345",
    "movement": {
      "payer": {
        "name": "Payer Name",
        "document": "12345678901",
        "bank": "BANCO INTER S.A.",
        "agency": "0001",
        "account": "123456-7"
      },
      "payee": {
        "name": "Payee Name",
        "document": "12345678000190",
        "bank": "BANCO INTER S.A.",
        "agency": "0001",
        "account": "765432-1"
      }
    },
    "created_at": "2025-12-16T20:44:25.618Z",
    "updated_at": "2025-12-16T20:44:25.618Z"
  },
  "event": "WITHDRAW"
}
```

---

## Webhook Signature Verification

### JavaScript

```javascript
const crypto = require('crypto');

const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const hash = crypto.createHmac('sha256', webhookSecret).update(payload).digest('hex');

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}
```

### Python

```python
import hmac
import hashlib
import json

signature = request.headers.get('x-webhook-signature')
payload = json.dumps(request.get_json())
hash = hmac.new(
    bytes(webhook_secret, 'ascii'),
    bytes(payload, 'ascii'),
    hashlib.sha256
).hexdigest()

if hash == signature:
    # Request is verified
else:
    # Request could not be verified
```

### PHP

```php
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$payload = file_get_contents('php://input');
$hash = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($hash, $signature)) {
    // Request is verified
} else {
    // Request could not be verified
}
```

---

## Documentation Pages

- /quickstart - Get started with your first transaction
- /transactions - Create and query Pix transactions
- /cashout - Request and query Pix withdrawals
- /balance - Check account balance
- /webhooks - Webhook guide and payload examples
- /webhooks-api - Webhook CRUD endpoints
- /exports - Export transactions and withdrawals
- /transaction-statuses - Transaction status reference
- /withdrawal-statuses - Withdrawal status reference
- /pix-key-formats - Pix key format reference

## Tips

- Use `magic_id` or `external_ref` for reconciliation
- Validate `x-webhook-signature` using HMAC SHA256
- Use `resend=true` query param to resend webhooks
- Keep webhook handlers idempotent
- Use `x-timezone` header for localized timestamps