Nebula Payment

https://docs.nebulapayment.com
Admin
Nebula Payment is a PIX API platform that enables developers to integrate Brazilian instant...
Tokens:79,062
Snippets:354
Trust Score:2.1
Update:7 months ago
Show doc for...
Tokens:
Raw
### List All Webhooks (Bash cURL)

Source: https://docs.nebulapayment.com/pages/webhook/list

This example shows how to list all webhooks using the cURL command-line tool. It sends a GET request to the webhook endpoint with the necessary Authorization header. This is useful for scripting and automated checks.

```bash
curl -X GET 'https://api.nebulapayment.com/api/v1/webhook' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

--------------------------------

### Query Specific Webhook (Bash cURL)

Source: https://docs.nebulapayment.com/pages/webhook/list

This example demonstrates how to query a specific webhook using its ID via a cURL command. It sends a GET request to the `/api/v1/webhook/:id` endpoint, requiring the same Authorization header as listing all webhooks. This is useful for retrieving detailed information about a single webhook.

```bash
curl -X GET 'https://api.nebulapayment.com/api/v1/webhook/1' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

--------------------------------

### Consultar Saldo Disponível - Python Example

Source: https://docs.nebulapayment.com/api-reference/saldo/consultar-saldo-dispon%C3%ADvel

This Python code snippet illustrates how to retrieve the available balance using the requests library. It demonstrates setting the 'Authorization' header with a Bearer token.

```python
response = requests.get(
    'https://api.nebulapayment.com/api/v1/balance',
    headers={
        'Authorization': 'Bearer SEU_TOKEN_JWT_AQUI'
    }
)
```

--------------------------------

### Example API Authentication Request

Source: https://docs.nebulapayment.com/pages/auth/getting-started

This example shows a cURL command to authenticate with the Nebula Payment API using the Base64 encoded credentials. It sends a POST request to the authentication endpoint, including the Authorization header with the Basic token.

```bash
curl -X POST 'https://api.nebulapayment.com/api/auth' \
  -H 'Authorization: Basic cGtfdGVzdF9hYmMxMjM6c2tfdGVzdF94eXo3ODk='
```

--------------------------------

### Consultar Saldo Disponível - cURL Example

Source: https://docs.nebulapayment.com/api-reference/saldo/consultar-saldo-dispon%C3%ADvel

This code snippet demonstrates how to query the available balance using a cURL command. It requires an 'Authorization' header with a Bearer token.

```curl
curl -X GET 'https://api.nebulapayment.com/api/v1/balance' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'
```

--------------------------------

### Consultar Saldo Disponível - Node.js Example

Source: https://docs.nebulapayment.com/api-reference/saldo/consultar-saldo-dispon%C3%ADvel

This Node.js code snippet shows how to fetch the available balance using the axios library. It includes setting the 'Authorization' header with a Bearer token.

```javascript
const response = await
axios.get('https://api.nebulapayment.com/api/v1/balance', {
  headers: {
    'Authorization': 'Bearer SEU_TOKEN_JWT_AQUI'
  }
})
```

--------------------------------

### Nebula Payment Signature Header Example (HTTP)

Source: https://docs.nebulapayment.com/webhook

This example demonstrates the format of the 'Nebula Payment-Signature' HTTP header. It includes a timestamp and a signature generated using HMAC-SHA256, crucial for verifying webhook authenticity.

```http
Nebula Payment-Signature: t=1580306324381,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

--------------------------------

### Structured Logging for Debugging

Source: https://docs.nebulapayment.com/webhook

Example of structured JSON logging to track webhook processing performance and status for easier debugging.

```javascript
console.log({
  timestamp: new Date().toISOString(),
  webhookId: event.id,
  eventType: event.event,
  processed: true,
  processingTime: Date.now() - startTime
})
```

--------------------------------

### Calculate Transaction Fees

Source: https://docs.nebulapayment.com/pages/pix-in/overview

Example demonstrating how to represent transaction amounts and associated fees in the API response structure.

```javascript
// Exemplo de cálculo
const valorProduto = 5000 // R$ 50,00 em centavos
const taxa = 0 // Taxa aplicável

// Na resposta da API
{
  "data": {
    "amount": 5000,      // Valor total
    "fees": 0           // Taxa cobrada
  }
}
```

--------------------------------

### Install Nebula Payment CA Certificate on Server

Source: https://docs.nebulapayment.com/webhook

This bash script shows how to move the downloaded Nebula Payment CA certificate to a secure directory and set appropriate file permissions. This step is crucial for the web server to access and use the certificate for mTLS validation.

```bash
# Mover para diretório de certificados
sudo mkdir -p /etc/ssl/certs/nebula
sudo mv nebula-ca.crt /etc/ssl/certs/nebula/

# Definir permissões corretas
sudo chmod 644 /etc/ssl/certs/nebula/nebula-ca.crt
```

--------------------------------

### List All Webhooks (HTTP Request)

Source: https://docs.nebulapayment.com/pages/webhook/list

This snippet demonstrates how to list all webhooks configured for your company using an HTTP GET request. It requires an Authorization header with a Bearer token. The response includes a list of webhooks with their configurations and metrics.

```http
GET /api/v1/webhook HTTP/1.1
Host: api.nebulapayment.com
Authorization: Bearer <seu_token_bearer>
```

--------------------------------

### GET /api/v1/webhook

Source: https://docs.nebulapayment.com/api-reference/webhooks/listar-webhooks

Retrieves a list of all configured webhooks for your account. This endpoint allows you to view the details of each webhook, including its URL, associated events, and active status.

```APIDOC
## GET /api/v1/webhook

### Description
Lists all configured webhooks.

### Method
GET

### Endpoint
/api/v1/webhook

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **webhooks** (array) - A list of webhook objects.
  - **id** (string) - Unique ID of the webhook.
  - **url** (string) - URL of the webhook.
  - **events** (array of strings) - Events configured for the webhook.
  - **active** (boolean) - Whether the webhook is active.
  - **createdAt** (string) - Date and time of webhook creation.

#### Response Example
```json
{
  "webhooks": [
    {
      "id": "webhook_abc123xyz",
      "url": "https://exemplo.com.br/webhook",
      "events": [
        "transaction_paid",
        "transfer_completed"
      ],
      "active": true,
      "createdAt": "2024-12-31T12:00:00Z"
    }
  ]
}
```

#### Error Response (401)
- **error** (string) - Error code (e.g., UNAUTHORIZED).
- **message** (string) - Error message.

#### Error Response Example (401)
```json
{
  "error": "UNAUTHORIZED",
  "message": "Token de autenticação inválido ou expirado"
}
```

#### Error Response (429)
- **error** (string) - Error code (e.g., RATE_LIMITED).
- **message** (string) - Error message.

#### Error Response Example (429)
```json
{
  "error": "RATE_LIMITED",
  "message": "Muitas requisições. Tente novamente em alguns minutos."
}
```
```

--------------------------------

### Generate JWT Token using Basic Auth (Python)

Source: https://docs.nebulapayment.com/api-reference/autentica%C3%A7%C3%A3o/gerar-token-jwt

Generates a JWT token for authentication using API Key and API Secret. This Python example demonstrates making a POST request with the required Basic Auth header.

```python
response = requests.post(
    'https://api.nebulapayment.com/api/auth',
    headers={
        'Authorization': 'Basic SEU_BASIC_AUTH_AQUI'
    }
)
```

--------------------------------

### Secure Credential Configuration using Environment Variables

Source: https://docs.nebulapayment.com/pages/auth/getting-started

This example illustrates how to securely store Nebula Payment API credentials and base URL using environment variables. It shows a typical .env file format and a corresponding JavaScript configuration file that reads these variables.

```dotenv
# .env
NEBULA_API_KEY=pk_test_abc123def456ghi789
NEBULA_API_SECRET=sk_test_xyz789uvw012mno345
NEBULA_BASE_URL=https://api.nebulapayment.com
```

```javascript
// config.js
const config = {
  apiKey: process.env.NEBULA_API_KEY,
  apiSecret: process.env.NEBULA_API_SECRET,
  baseUrl: process.env.NEBULA_BASE_URL
}

export default config
```

--------------------------------

### JavaScript/Node.js PIX Payment Integration

Source: https://docs.nebulapayment.com/pages/pix-in/create-qrcode

Example implementation of the Nebula Payment PIX API using JavaScript/Node.js, demonstrating how to create QR codes for payments.

```APIDOC
## JavaScript/Node.js PIX Payment Integration

### Description
Example implementation of the Nebula Payment PIX API using JavaScript/Node.js, demonstrating how to create QR codes for payments.

### Method
POST (via SDK)

### Endpoint
/api/v1/pix/in/qrcode (internal SDK call)

### Parameters
See `POST /api/v1/pix/in/qrcode` for detailed parameter information.

### Request Example
```javascript
class PixPayment {
  constructor(apiKey, apiSecret, baseUrl) {
    this.auth = new Nebula Payment(apiKey, apiSecret, baseUrl)
  }

  async createQRCode(paymentData) {
    try {
      const response = await this.auth.makeAuthenticatedRequest(
        'POST',
        '/api/v1/pix/in/qrcode',
        paymentData
      )

      return response.data.data
    } catch (error) {
      throw new Error(`Erro ao criar QR Code: ${error.message}`)
    }
  }

  async createSimplePayment(amount, customerData, description = '') {
    const paymentData = {
      amountInCents: amount,
      description,
      customer: customerData
    }

    return await this.createQRCode(paymentData)
  }
}

// Uso
const pixPayment = new PixPayment(API_KEY, API_SECRET, BASE_URL)

const transaction = await pixPayment.createSimplePayment(
  5000, // R$ 50,00
  {
    name: "Cliente Exemplo",
    email: "cliente@exemplo.com",
    documentType: "cpf",
    document: "11122233344"
  },
  "Pagamento de produto"
)

console.log('QR Code criado:', transaction.id)
```

### Response
#### Success Response (200)
Returns the transaction data, including the PIX EMV code and QR Code image, as described in the `POST /api/v1/pix/in/qrcode` endpoint.

#### Response Example
```json
{
  "id": "trx_1a2b3c4d5e6f7g8h9i0j",
  "pix": {
    "emv": "00020126...SEU_CODIGO_EMV_AQUI...6304ABCD",
    "qrCode": "[BASE64_ENCODED_QRCODE_IMAGE]"
  },
  "status": "pending",
  "fees": 0
}
```
```

--------------------------------

### Delete Webhook Request Example (cURL)

Source: https://docs.nebulapayment.com/pages/webhook/delete

This example demonstrates how to send a DELETE request to the NebulaPayment API to remove a specific webhook using its ID. It includes the necessary authorization header and the endpoint URL.

```bash
curl -X DELETE 'https://api.nebulapayment.com/api/v1/webhook/3' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

--------------------------------

### POST /api/v1/pix/in/qrcode

Source: https://docs.nebulapayment.com/

Creates a PIX QR Code for receiving payments instantly.

```APIDOC
## POST /api/v1/pix/in/qrcode

### Description
Generates a PIX QR Code to receive payments from customers.

### Method
POST

### Endpoint
https://api.nebulapayment.com/api/v1/pix/in/qrcode

### Request Body
- **amountInCents** (integer) - Required - The payment amount in cents.
- **description** (string) - Required - Description of the transaction.
- **customer** (object) - Required - Customer details including name, email, documentType, and document.

### Request Example
{
  "amountInCents": 10000,
  "description": "Assinatura - Plano Exemplo",
  "customer": {
    "name": "Cliente Exemplo Silva",
    "email": "cliente@exemplo.com",
    "documentType": "cpf",
    "document": "11122233344"
  }
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the generated QR Code details.
```

--------------------------------

### GET /api/v1/balance

Source: https://docs.nebulapayment.com/api-reference/saldo/consultar-saldo-dispon%C3%ADvel

Retrieves the current available balance and pending transfers for the authenticated account.

```APIDOC
## GET /api/v1/balance

### Description
Returns the available balance and pending transfers for the authenticated company. Use this endpoint to verify funds before initiating PIX transfers.

### Method
GET

### Endpoint
/api/v1/balance

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None (Requires Bearer Token in Authorization header)

### Request Example
```bash
curl -X GET 'https://api.nebulapayment.com/api/v1/balance' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful
- **data** (object) - Contains balance details
  - **totalBalanceCents** (integer) - Total gross balance in cents
  - **availableBalanceCents** (integer) - Liquid available balance in cents
  - **pendingTransfersCents** (integer) - Total pending transfers in cents

#### Response Example
{
  "success": true,
  "data": {
    "totalBalanceCents": 150000,
    "availableBalanceCents": 125000,
    "pendingTransfersCents": 25000
  }
}
```

--------------------------------

### Initiate and Monitor Pix Transfers (JavaScript/Node.js)

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

This snippet demonstrates how to initiate a Pix transfer using the PixTransfer class in JavaScript/Node.js. It includes methods for sending funds to a Pix key, generating an idempotency key to prevent duplicate transactions, and polling for transfer completion. It requires an authentication instance and handles potential errors.

```javascript
class PixTransfer {
  constructor(auth) {
    this.auth = auth
  }

  async sendToPixKey(pixKey, amount, description = '', postbackUrl = '', idempotencyKey = null) {
    if (!idempotencyKey) {
      idempotencyKey = this.generateIdempotencyKey(pixKey, amount)
    }

    const transferData = {
      pixKey,
      amount,
      currency: 'BRL',
      description,
      postbackUrl
    }

    try {
      const response = await this.auth.makeAuthenticatedRequest(
        'POST',
        '/api/v1/pix/out/pixkey',
        transferData,
        { 'x-idempotency-key': idempotencyKey }
      )

      return response.data.data
    } catch (error) {
      throw new Error(`Erro na transferência: ${error.message}`)
    }
  }

  generateIdempotencyKey(pixKey, amount) {
    const timestamp = Date.now()
    const hash = require('crypto')
      .createHash('md5')
      .update(`${pixKey}_${amount}_${timestamp}`)
      .digest('hex')
    return `transfer_${hash.substring(0, 16)}`
  }

  async waitForCompletion(transferId, timeoutMs = 60000) {
    const startTime = Date.now()
    const checkInterval = 3000 // 3 segundos

    while (Date.now() - startTime < timeoutMs) {
      const transfer = await this.getTransfer(transferId)
      
      if (transfer.status === 'completed') {
        return transfer
      } else if (transfer.status === 'refused' || transfer.status === 'canceled') {
        throw new Error(`Transferência ${transfer.status}: ${transfer.reason}`)
      }

      await new Promise(resolve => setTimeout(resolve, checkInterval))
    }

    throw new Error('Timeout: transferência não foi concluída no tempo esperado')
  }

  async getTransfer(transferId) {
    const response = await this.auth.makeAuthenticatedRequest(
      'GET',
      `/api/v1/transfers/${transferId}`
    )
    return response.data.data
  }
}

// Uso
const pixTransfer = new PixTransfer(authInstance)

try {
  const transfer = await pixTransfer.sendToPixKey(
    'fornecedor@exemplo.com',
    20000,
    'Pagamento NF Exemplo',
    'https://exemplo.com.br/webhook/pix-out'
  )

  console.log('Transferência iniciada:', transfer.id)

  // Aguardar conclusão via webhook ou polling
  const completedTransfer = await pixTransfer.waitForCompletion(transfer.id)
  console.log('Transferência concluída:', completedTransfer.status)
} catch (error) {
  console.error('Erro:', error.message)
}
```

--------------------------------

### Webhook Notification Structure

Source: https://docs.nebulapayment.com/

Example of the JSON payload received via webhooks when a transaction status changes.

```json
{
  "id": "wh_64f8a2b1c3d4e5f6g7h8i9j0",
  "type": "transaction",
  "event": "transaction_paid",
  "transaction": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "amount": 29990,
    "status": "paid"
  }
}
```

--------------------------------

### GET /api/v1/balance

Source: https://docs.nebulapayment.com/pages/balance/reference

Retrieves the available balance, total balance, and pending transfers for the authenticated company.

```APIDOC
## GET /api/v1/balance

### Description
Returns the available balance, total balance, and pending transfers for the authenticated company. Values are returned in cents.

### Method
GET

### Endpoint
https://api.nebulapayment.com/api/v1/balance

### Parameters
#### Query Parameters
- None

### Request Body
- None (Requires Authorization header)

### Request Example
```bash
curl -X GET 'https://api.nebulapayment.com/api/v1/balance' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT_AQUI'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data.totalBalanceCents** (number) - Total gross balance in cents.
- **data.availableBalanceCents** (number) - Net balance available for use in cents.
- **data.pendingTransfersCents** (number) - Total of pending transfers in cents.

#### Response Example
{
  "success": true,
  "data": {
    "totalBalanceCents": 150000,
    "availableBalanceCents": 125000,
    "pendingTransfersCents": 25000
  }
}
```

--------------------------------

### Initiate and Monitor Pix Transfers (Python)

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

This snippet demonstrates how to initiate a Pix transfer using the PixTransfer class in Python. It includes methods for sending funds to a Pix key, generating an idempotency key to prevent duplicate transactions, and polling for transfer completion. It requires an authentication instance and handles potential errors.

```python
import time
import hashlib
from datetime import datetime

class PixTransfer:
    def __init__(self, auth_instance):
        self.auth = auth_instance

    def send_to_pix_key(self, pix_key, amount, description='', postback_url='', idempotency_key=None):
        if not idempotency_key:
            idempotency_key = self.generate_idempotency_key(pix_key, amount)

        transfer_data = {
            'pixKey': pix_key,
            'amount': amount,
            'currency': 'BRL',
            'description': description,
            'postbackUrl': postback_url
        }

        headers = {'x-idempotency-key': idempotency_key}

        response = self.auth.make_authenticated_request(
            'POST',
            '/api/v1/pix/out/pixkey',
            transfer_data,
            additional_headers=headers
        )

        if response.status_code == 200:
            return response.json()['data']
        else:
            raise Exception(f"Erro na transferência: {response.text}")

    def generate_idempotency_key(self, pix_key, amount):
        timestamp = str(int(time.time() * 1000))
        data = f"{pix_key}_{amount}_{timestamp}"
        hash_obj = hashlib.md5(data.encode())
        return f"transfer_{hash_obj.hexdigest()[:16]}"

    def wait_for_completion(self, transfer_id, timeout_seconds=60):
        start_time = time.time()
        check_interval = 3  # 3 segundos

        while time.time() - start_time < timeout_seconds:
            transfer = self.get_transfer(transfer_id)
            
            if transfer['status'] == 'completed':
                return transfer
            elif transfer['status'] in ['refused', 'canceled']:
                raise Exception(f"Transferência {transfer['status']}: {transfer.get('reason', 'Motivo não informado')}")

            time.sleep(check_interval)

        raise Exception('Timeout: transferência não foi concluída no tempo esperado')

    def get_transfer(self, transfer_id):
        response = self.auth.make_authenticated_request(
            'GET',
            f'/api/v1/transfers/{transfer_id}'
        )
        return response.json()['data']

```

--------------------------------

### GET /api/v1/transfers/{transferId}

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

Retrieves the status and details of a specific Pix transfer using its unique identifier.

```APIDOC
## GET /api/v1/transfers/{transferId}

### Description
Retrieves the status and details of a specific Pix transfer using its unique identifier.

### Method
GET

### Endpoint
/api/v1/transfers/{transferId}

### Parameters
#### Path Parameters
- **transferId** (string) - Required - The unique identifier of the transfer to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the transfer details.
  - **id** (string) - The unique identifier for the transfer.
  - **status** (string) - The current status of the transfer (e.g., 'completed', 'refused', 'canceled').
  - **reason** (string) - Optional - The reason for refusal or cancellation, if applicable.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "transfer_abc123xyz",
    "status": "completed"
  }
}
```

#### Error Response (e.g., 404)
- **success** (boolean) - Indicates if the request was successful.
- **message** (string) - A message describing the error (e.g., 'Transfer not found').
```
```

--------------------------------

### Create PIX QR Code for Receiving

Source: https://docs.nebulapayment.com/

Generates a PIX QR code for instant payments. Requires a valid Bearer token and accepts customer details and transaction amount in cents.

```curl
curl -X POST 'https://api.nebulapayment.com/api/v1/pix/in/qrcode' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <seu_token>' \
  -d '{
    "amountInCents": 10000,
    "description": "Assinatura - Plano Exemplo",
    "customer": {
      "name": "Cliente Exemplo Silva",
      "email": "cliente@exemplo.com",
      "documentType": "cpf",
      "document": "11122233344"
    }
  }'
```

--------------------------------

### POST /api/v1/pix/in/qrcode

Source: https://docs.nebulapayment.com/api-reference/pix-in/criar-qr-code-pix-para-recebimento

Creates a PIX QR Code for receiving instant payments. This endpoint allows you to generate a QR code for a specific amount, with optional details like description, postback URL, customer information, and itemized order details.

```APIDOC
## POST /api/v1/pix/in/qrcode

### Description
Creates a PIX QR Code for receiving instant payments.

### Method
POST

### Endpoint
/api/v1/pix/in/qrcode

### Parameters
#### Query Parameters
None

#### Request Body
- **amountInCents** (integer) - Required - Value in cents (minimum R$ 1,00) 
- **description** (string) - Optional - Description that will appear on the payer's statement (max 140 characters)
- **postbackUrl** (string) - Optional - URL to receive webhook notifications
- **customer** (object) - Required - Customer information
  - **name** (string) - Required - Full name of the customer
  - **email** (string) - Required - Customer's email
  - **documentType** (string) - Optional - Type of customer document (cpf or cnpj)
  - **document** (string) - Required - Customer's CPF or CNPJ
  - **phone** (string) - Required - Customer's phone number
- **items** (array) - Optional - List of order items
  - **name** (string) - Required - Item name
  - **quantity** (integer) - Required - Quantity (minimum 1)
  - **price** (integer) - Required - Unit price in cents
- **billingAddress** (object) - Optional - Billing address
  - **street** (string) - Optional - Street address
  - **city** (string) - Optional - City
  - **state** (string) - Optional - State
  - **zipCode** (string) - Optional - Zip code

### Request Example
```json
{
  "amountInCents": 5000,
  "description": "Pagamento de servicos",
  "postbackUrl": "https://exemplo.com.br/webhook",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@exemplo.com",
    "documentType": "cpf",
    "document": "11122233344",
    "phone": "(11) 91234-5678"
  },
  "items": [
    {
      "name": "Produto A",
      "quantity": 2,
      "price": 2500
    }
  ],
  "billingAddress": {
    "street": "Rua Exemplo, 100",
    "city": "Sao Paulo",
    "state": "SP",
    "zipCode": "00000-000"
  }
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful
- **message** (string) - Return message
- **data** (object) - Transaction data
  - **id** (string) - Unique transaction ID

#### Response Example
```json
{
  "success": true,
  "message": "Transacao criada com sucesso",
  "data": {
    "id": "pix_qrcode_id_12345"
  }
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **429** - Rate Limited
```

--------------------------------

### Exibir QR Code PIX em HTML

Source: https://docs.nebulapayment.com/pages/pix-in/overview

Exemplos de como exibir o QR Code gerado pela API em uma página web. Pode ser feito diretamente através de uma tag `<img>` utilizando a imagem codificada em Base64, ou apresentando o código EMV para cópia e colagem manual.

```html
<!-- Mostrar QR Code -->
<img src="[BASE64_ENCODED_QRCODE_IMAGE]" alt="QR Code PIX" style="width: 300px;">

<!-- Ou usar o código EMV -->
<div class="pix-code">
  <p>Copie e cole no seu banco:</p>
  <input type="text" value="00020126...SEU_CODIGO_EMV_AQUI...6304ABCD" readonly>
</div>
```

--------------------------------

### Authenticate and Make Request with Nebula Payment (Python)

Source: https://docs.nebulapayment.com/pages/auth/generate-token

This Python snippet demonstrates how to initialize the Nebula Payment client and make an authenticated POST request to create a PIX QR code. It requires NEBULA_API_KEY, NEBULA_API_SECRET, and NEBULA_BASE_URL environment variables.

```python
import os

# Assuming NebulaPayment class is defined elsewhere or imported
# from nebula_payment import NebulaPayment

# Placeholder for the actual NebulaPayment class if not imported
class NebulaPayment:
    def __init__(self, api_key, api_secret, base_url):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = base_url
        # In a real scenario, this would handle token acquisition

    def make_authenticated_request(self, method, endpoint, data=None):
        # This is a mock implementation for demonstration
        print(f"Making {method} request to {self.base_url}{endpoint} with data: {data}")
        # In a real scenario, this would handle authentication and the actual request
        return {"status": "success", "data": "mock_response"}


auth = NebulaPayment(
    os.getenv('NEBULA_API_KEY'),
    os.getenv('NEBULA_API_SECRET'),
    os.getenv('NEBULA_BASE_URL')
)

# Fazer requisição autenticada
response = auth.make_authenticated_request('POST', '/api/v1/pix/in/qrcode', {
    'amountInCents': 10000,
    'description': 'Teste'
})
```

--------------------------------

### Get Transaction Status

Source: https://docs.nebulapayment.com/pages/pix-in/overview

Retrieves the current status of a specific transaction using its ID. This is used for polling the payment status.

```APIDOC
## GET /api/v1/transactions/{transactionId}

### Description
Fetches the status of a specific transaction. Useful for polling the payment status after generating a QR code.

### Method
GET

### Endpoint
/api/v1/transactions/{transactionId}

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The unique identifier of the transaction to retrieve.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (string) - The transaction ID.
- **amount** (integer) - The transaction amount in cents.
- **status** (string) - The current status of the transaction (e.g., 'pending', 'paid', 'canceled', 'refunded').

#### Response Example
```json
{
  "id": "trx_1a2b3c4d5e6f7g8h9i0j",
  "amount": 5000,
  "status": "paid"
}
```
```

--------------------------------

### POST /pix/simulate

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

Simulates a transfer to verify feasibility, fees, and estimated completion time without executing the transaction.

```APIDOC
## POST /pix/simulate

### Description
Validates if a transfer would be successful and returns estimated fees and processing time.

### Method
POST

### Endpoint
/pix/simulate

### Request Body
- **pixKey** (string) - Required - The recipient's PIX key.
- **amount** (number) - Required - The value to simulate.

### Response
#### Success Response (200)
- **fees** (number) - Calculated transaction fees.
- **netAmount** (number) - The final amount after fees.
- **estimatedTime** (string) - Expected time for completion.
- **valid** (boolean) - Whether the simulation passed validation.
```

--------------------------------

### Create PIX Payment QR Code

Source: https://docs.nebulapayment.com/pages/pix-in/overview

Initiates a PIX payment by generating a QR code. This is the first step in the complete payment flow.

```APIDOC
## POST /api/v1/pix/in/qrcode

### Description
Generates a PIX payment QR code. This endpoint is used to start the payment process.

### Method
POST

### Endpoint
/api/v1/pix/in/qrcode

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be 'application/json'.

#### Request Body
- **dadosPagamento** (object) - Required - Object containing payment details.
  - **amount** (integer) - Required - The amount to be paid in cents.
  - **description** (string) - Optional - A description for the payment.
  - **customer** (object) - Optional - Customer information.
    - **email** (string) - Required if customer object is provided - Customer's email address.

### Request Example
```javascript
async function criarPagamentoPIX(dadosPagamento) {
  const token = 'YOUR_API_TOKEN'; // Replace with your actual token
  const response = await fetch('/api/v1/pix/in/qrcode', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(dadosPagamento)
  });

  const data = await response.json();
  return data.data;
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the generated payment details.
  - **id** (string) - The unique ID of the transaction.
  - **pix** (object) - PIX specific details.
    - **qrCode** (string) - The generated QR code in data URL format.
    - **emv** (string) - The EMV string for the QR code, which can be copied.

#### Response Example
```json
{
  "data": {
    "id": "trx_1a2b3c4d5e6f7g8h9i0j",
    "pix": {
      "qrCode": "data:image/png;base64,iVBORw0KGgo...",
      "emv": "00020126580014BR.GOV.BCB.PIX0136..."
    }
  }
}
```
```

--------------------------------

### POST /api/v1/pix/out/pixkey

Source: https://docs.nebulapayment.com/

Executes a PIX transfer to a specific PIX key programmatically.

```APIDOC
## POST /api/v1/pix/out/pixkey

### Description
Performs a PIX transfer to any valid PIX key.

### Method
POST

### Endpoint
https://api.nebulapayment.com/api/v1/pix/out/pixkey

### Parameters
#### Headers
- **X-Idempotency-Key** (string) - Required - Unique identifier to ensure idempotency.

### Request Body
- **pixKey** (string) - Required - The destination PIX key.
- **amount** (integer) - Required - The amount to transfer.
- **description** (string) - Optional - Transaction description.

### Request Example
{
  "pixKey": "contato@empresa.com.br",
  "amount": 150000,
  "description": "Pagamento de fornecedor"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the transfer was initiated successfully.
```

--------------------------------

### Retrieve Transfer Status via Polling

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

A cURL command to manually query the status of a specific transfer using a GET request. Requires a valid Bearer token for authentication.

```bash
curl -X GET 'https://api.nebulapayment.com/api/v1/transfers/transfer_abc123def456' \
  -H 'Authorization: Bearer SEU_TOKEN_AQUI'
```

--------------------------------

### Executar Transferência PIX via cURL

Source: https://docs.nebulapayment.com/pages/pix-out/send-pixkey

Exemplos práticos de como realizar uma transferência PIX via linha de comando, utilizando diferentes tipos de chaves de destino.

```bash
curl --location 'https://api.nebulapayment.com/api/v1/pix/out/pixkey' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'x-idempotency-key: idempotency_exemplo_001' \
  --data '{
    "pixKey": "11122233344",
    "amount": 10000,
    "currency": "BRL",
    "description": "Transfer PIX Exemplo",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
  }'
```

```bash
curl --location 'https://api.nebulapayment.com/api/v1/pix/out/pixkey' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'x-idempotency-key: idempotency_exemplo_002' \
  --data '{
    "pixKey": "fornecedor@exemplo.com",
    "amount": 20000,
    "currency": "BRL",
    "description": "Pagamento fornecedor - NF Exemplo",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
  }'
```

```bash
curl --location 'https://api.nebulapayment.com/api/v1/pix/out/pixkey' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'x-idempotency-key: idempotency_exemplo_003' \
  --data '{
    "pixKey": "11222333000144",
    "amount": 50000,
    "currency": "BRL",
    "description": "Pagamento parcela contrato Exemplo",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
  }'
```

```bash
curl --location 'https://api.nebulapayment.com/api/v1/pix/out/pixkey' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'x-idempotency-key: idempotency_exemplo_004' \
  --data '{
    "pixKey": "+5511912345678",
    "amount": 15000,
    "currency": "BRL",
    "description": "Comissão Exemplo - Afiliado",
    "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
  }'
```

--------------------------------

### Setup Development Webhook (JavaScript)

Source: https://docs.nebulapayment.com/pages/webhook/create

This function demonstrates how to set up a webhook for local development. It uses a tool like ngrok to expose a local server and then creates a webhook subscription pointing to the ngrok URL, specifying the events to listen for.

```javascript
// Configuração para desenvolvimento local
async function setupDevWebhook() {
  // Usar ngrok ou similar para expor localhost
  const ngrokUrl = await startNgrokTunnel(3000)
  
  const webhook = await webhookCreator.createWebhook({
    url: `${ngrokUrl}/webhooks/test`,
    name: 'Webhook Desenvolvimento',
    isActive: true,
    events: ['transaction_created', 'transaction_paid']
  })
  
  console.log(`Webhook dev criado: ${webhook.url}`)
  return webhook
}
```

--------------------------------

### Exemplos de Chave PIX (Bash)

Source: https://docs.nebulapayment.com/pages/pix-out/overview

Demonstração dos formatos aceitos para diferentes tipos de chaves PIX, incluindo CPF, CNPJ, Email, Telefone e Chave Aleatória (EVP).

```bash
# CPF (apenas números)
"pixKey": "11122233344"

# CNPJ (apenas números)  
"pixKey": "11222333000144"
```

```bash
# Email válido
"pixKey": "pagamentos@empresa.com.br"
"pixKey": "joao.silva@gmail.com"
```

```bash
# Formato: +5511999999999
"pixKey": "+5511987654321"
"pixKey": "+5521988888888"
```

```bash
# UUID gerado pelo banco
"pixKey": "123e4567-e89b-12d3-a456-426614174000"
"pixKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
```

--------------------------------

### Exemplo Completo de Requisição PIX IN

Source: https://docs.nebulapayment.com/pages/pix-in/overview

Um exemplo detalhado de um objeto JSON para a criação de uma transação PIX IN. Inclui todos os campos obrigatórios e opcionais, como dados do cliente, endereço de cobrança e itens da compra, demonstrando a flexibilidade da API.

```json
{
  "amountInCents": 10000,
  "description": "Assinatura - Plano Exemplo",
  "postbackUrl": "https://exemplo.com.br/webhooks/pix-payments",
  "customer": {
    "name": "Cliente Exemplo Silva",
    "email": "cliente@exemplo.com",
    "documentType": "cpf",
    "document": "11122233344",
    "phone": "11912345678",
    "billingAddress": {
      "street": "Rua Exemplo",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "00000000"
    }
  },
  "items": [
    {
      "title": "Produto Exemplo",
      "tangible": false,
      "quantity": 1,
      "amountInCents": 10000
    }
  ]
}
```

--------------------------------

### POST /api/v1/pix/out/pixkey

Source: https://docs.nebulapayment.com/api-reference/pix-out/enviar-transfer%C3%AAncia-pix

Endpoint to initiate a PIX transfer to a specific PIX key.

```APIDOC
## POST /api/v1/pix/out/pixkey

### Description
Realiza transferência PIX para qualquer chave PIX (CPF, CNPJ, email, telefone ou chave aleatória).

### Method
POST

### Endpoint
https://api.nebulapayment.com/api/v1/pix/out/pixkey

### Parameters
#### Header Parameters
- **x-idempotency-key** (string) - Required - Chave de idempotência para evitar duplicações.

#### Request Body
- **pixKey** (string) - Required - Chave PIX de destino.
- **amount** (integer) - Required - Valor da transferência em centavos.
- **currency** (string) - Optional - Moeda da transferência (padrão: BRL).
- **description** (string) - Optional - Descrição da transferência (máx 140 caracteres).
- **postbackUrl** (string) - Optional - URL para receber notificações de status.

### Request Example
{
  "pixKey": "fornecedor@exemplo.com",
  "amount": 10000,
  "currency": "BRL",
  "description": "Transfer PIX Exemplo",
  "postbackUrl": "https://exemplo.com.br/webhook/pix-out"
}

### Response
#### Success Response (201)
- **success** (boolean) - Indica se a operação foi bem-sucedida.
- **message** (string) - Mensagem de retorno.
- **data** (object) - Objeto contendo detalhes da transferência (id, status, amount, netAmount, fees, pixKey).

#### Response Example
{
  "success": true,
  "message": "Transferência criada com sucesso",
  "data": {
    "id": "transfer_abc123def456",
    "status": "queued",
    "amount": 10000,
    "netAmount": 10000,
    "fees": 0,
    "pixKey": "fornecedor@exemplo.com"
  }
}
```

--------------------------------

### Nebula Payment Token Caching Strategy (JavaScript)

Source: https://docs.nebulapayment.com/pages/auth/generate-token

This JavaScript example demonstrates a caching strategy for Nebula Payment API tokens using Redis. It shows how to set a token with an expiration time, ensuring that the token is cached for a specified duration (e.g., 25 minutes) with a buffer period.

```javascript
// Assuming 'redis' is an initialized Redis client and 'token' is the obtained JWT.
// 'EX' specifies the expiration time in seconds.
// Cache por 25 minutos (5 min de margem)
// await redis.set('nebula_token', token, 'EX', 1500);
console.log("Token cached for 1500 seconds.");
```
Tokens:
Raw