# Bloopi API — Reference Documentation

## Overview

The Bloopi API is a REST API with JSON responses. Use it to integrate payments, query transactions, and manage products and subscriptions programmatically.

**Base URL:** https://api.bloopi.com.br/v1

**Authentication:** Bearer token — send your API Key in the header:
Authorization: Bearer your_api_key

**Generate API Keys:** app.bloopi.com.br → Settings → API

---

## Authentication

curl https://api.bloopi.com.br/v1/products \
  -H "Authorization: Bearer sk_live_your_key_here"

---

## Payment Intents

### Create Payment Intent

POST /v1/payment-intents

Body:
{
  "amount": 9700,
  "currency": "BRL",
  "payment_method": "credit_card",
  "customer_email": "buyer@email.com",
  "customer_name": "Buyer Name",
  "customer_document": "12345678901",
  "installments": 3,
  "description": "Digital Marketing Course"
}

Required fields:
- amount: value in cents (9700 = R$97,00)
- currency: currency code (BRL, USD)
- payment_method: credit_card, pix, or boleto

Response:
{
  "id": "pi_abc123xyz",
  "status": "requires_payment_method",
  "amount": 9700,
  "currency": "BRL",
  "created_at": "2026-03-15T00:00:00Z"
}

Possible statuses:
- requires_payment_method
- requires_confirmation
- processing
- succeeded
- failed
- canceled

### Retrieve Payment Intent

GET /v1/payment-intents/{id}

### List Payment Intents

GET /v1/payment-intents?limit=20&status=succeeded&from=2026-01-01

---

## Transactions

### List Transactions

GET /v1/transactions

Response:
{
  "data": [
    {
      "id": "txn_abc123",
      "amount": 9700,
      "currency": "BRL",
      "status": "succeeded",
      "payment_method": "credit_card",
      "customer_email": "buyer@email.com",
      "created_at": "2026-03-15T00:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "per_page": 20
}

### Retrieve Transaction

GET /v1/transactions/{id}

---

## Products

### List Products

GET /v1/products

### Retrieve Product

GET /v1/products/{id}

### Create Product

POST /v1/products

{
  "name": "Digital Marketing Course",
  "description": "Learn digital marketing from scratch",
  "type": "one_time"
}

---

## Prices

### Create Price — One-time

POST /v1/prices

{
  "product_id": "prod_abc123",
  "amount": 9700,
  "currency": "BRL",
  "type": "one_time"
}

### Create Price — Recurring

{
  "product_id": "prod_abc123",
  "amount": 9700,
  "currency": "BRL",
  "type": "recurring",
  "interval": "monthly",
  "interval_count": 1
}

Available intervals: daily, weekly, monthly, yearly

---

## Subscriptions

### List Subscriptions

GET /v1/subscriptions?status=active

### Retrieve Subscription

GET /v1/subscriptions/{id}

### Cancel Subscription

POST /v1/subscriptions/{id}/cancel

{
  "cancel_at_period_end": true
}

cancel_at_period_end true: access maintained until end of paid period
cancel_at_period_end false: immediate cancellation

### Pause Subscription

POST /v1/subscriptions/{id}/pause

### Resume Subscription

POST /v1/subscriptions/{id}/resume

---

## Customers

### List Customers

GET /v1/customers

### Create Customer

POST /v1/customers

{
  "name": "Customer Name",
  "email": "customer@email.com",
  "document": "12345678901",
  "phone": "11999999999"
}

---

## Refunds

### Create Refund

POST /v1/refunds

{
  "charge_id": "ch_abc123",
  "amount": 9700,
  "reason": "requested_by_customer"
}

Available reasons:
- requested_by_customer
- duplicate
- fraudulent

---

## Webhooks

### Event Structure

{
  "id": "evt_abc123",
  "type": "payment.approved",
  "created_at": "2026-03-15T00:00:00Z",
  "data": {
    "object": {}
  }
}

### Available Events

| Event | Description |
|-------|-------------|
| payment.approved | Payment approved |
| payment.declined | Payment declined |
| payment.refunded | Payment refunded |
| subscription.created | New subscription created |
| subscription.renewed | Subscription renewed |
| subscription.canceled | Subscription canceled |
| subscription.past_due | Renewal billing failed |
| subscription.paused | Subscription paused |

### Signature Verification — JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

### Signature Verification — Python

import hmac, hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

---

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Not found |
| 422 | Validation error |
| 429 | Rate limit reached |
| 500 | Server error |

---

## Rate Limiting

- 100 requests per minute per API key
- Response headers include X-RateLimit-Remaining and X-RateLimit-Reset

---

## Error Format

{
  "error": {
    "code": "invalid_amount",
    "message": "Amount must be a positive integer in cents",
    "param": "amount"
  }
}

---

## Code Examples

Node.js:

const response = await fetch('https://api.bloopi.com.br/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 9700,
    currency: 'BRL',
    payment_method: 'pix'
  })
});
const data = await response.json();

Python:

import requests

response = requests.post(
  'https://api.bloopi.com.br/v1/payment-intents',
  headers={'Authorization': 'Bearer sk_live_your_key'},
  json={'amount': 9700, 'currency': 'BRL', 'payment_method': 'pix'}
)
data = response.json()

---

## Links

- Dashboard: https://app.bloopi.com.br
- Generate API Key: https://app.bloopi.com.br/settings/api
- Support: suporte@bloopi.com.br
- LLM docs: https://ai.bloopi.com.br/en-US