Início Rápido

Este guia vai te ajudar a fazer sua primeira transação com o OnnixPay em menos de 5 minutos.

1. Obtenha suas Credenciais

Primeiro, você precisa de uma API Key. Faça login no painel e gere suas credenciais em Configurações > API Keys.

Dica

Use o ambiente Sandbox para seus testes. As transações não serão cobradas e você pode testar todos os fluxos.

2. Faça sua Primeira Requisição

Teste de Conectividade

Primeiro, vamos verificar se tudo está funcionando:

curl -X GET https://sandbox.onnixpay.com/sdk/status/health \
  -H "X-API-Key: seu_api_key_aqui"

Resposta esperada:

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-11-14T10:30:00Z",
    "version": "v1",
    "uptime": 123456
  }
}

3. Crie uma Cobrança PIX

Vamos criar sua primeira cobrança PIX:

curl -X POST https://sandbox.onnixpay.com/sdk/pix \
  -H "X-API-Key: seu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "description": "Teste de cobrança PIX",
    "externalId": "pedido-12345",
    "expirationMinutes": 30,
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900"
    }
  }'

Resposta:

{
  "success": true,
  "data": {
    "id": "pix_abc123xyz",
    "status": "PENDING",
    "amount": 50.00,
    "qrCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "expiresAt": "2025-11-14T11:00:00Z",
    "pixKey": "12345678-1234-1234-1234-123456789012"
  }
}

4. Exiba o QR Code

Você pode usar o qrCodeBase64 para exibir o QR Code ao seu cliente:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="QR Code PIX" />

Ou fornecer o código PIX para cópia (qrCode):

<input type="text" value="00020126580014br.gov.bcb.pix..." readonly />
<button onclick="copyToClipboard()">Copiar Código PIX</button>

5. Configure Webhooks

Para receber notificações quando o pagamento for confirmado:

curl -X POST https://sandbox.onnixpay.com/sdk/webhooks/test \
  -H "X-API-Key: seu_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-site.com/webhooks/onnixpay",
    "events": ["pix.paid", "pix.expired"]
  }'

Importante

Seu endpoint deve responder com status 200 para confirmar o recebimento do webhook.

6. Consulte o Status da Transação

A qualquer momento, você pode consultar o status:

curl -X GET https://sandbox.onnixpay.com/sdk/pix/pix_abc123xyz \
  -H "X-API-Key: seu_api_key_aqui"

Exemplos em Outras Linguagens

Node.js / TypeScript

import axios from 'axios';

const onnixpay = axios.create({
  baseURL: 'https://sandbox.onnixpay.com',
  headers: {
    'X-API-Key': process.env.ONNIXPAY_API_KEY,
    'Content-Type': 'application/json'
  }
});

// Criar cobrança PIX
async function createPixCharge() {
  try {
    const response = await onnixpay.post('/sdk/pix', {
      amount: 50.00,
      description: 'Teste de cobrança PIX',
      externalId: 'pedido-12345',
      expirationMinutes: 30,
      customer: {
        name: 'João Silva',
        email: 'joao@example.com',
        document: '12345678900'
      }
    });

    console.log('PIX criado:', response.data);
    return response.data;
  } catch (error) {
    console.error('Erro:', error.response?.data);
    throw error;
  }
}
// Comentario

Python

import requests
import os

ONNIXPAY_API_KEY = os.getenv('ONNIXPAY_API_KEY')
BASE_URL = 'https://sandbox.onnixpay.com'

def create_pix_charge():
    headers = {
        'X-API-Key': ONNIXPAY_API_KEY,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'amount': 50.00,
        'description': 'Teste de cobrança PIX',
        'externalId': 'pedido-12345',
        'expirationMinutes': 30,
        'customer': {
            'name': 'João Silva',
            'email': 'joao@example.com',
            'document': '12345678900'
        }
    }
    
    response = requests.post(
        f'{BASE_URL}/sdk/pix',
        headers=headers,
        json=payload
    )
    
    response.raise_for_status()
    return response.json()

# Criar cobrança
result = create_pix_charge()
print(f"PIX criado: {result['data']['id']}")

PHP

<?php

$apiKey = getenv('ONNIXPAY_API_KEY');
$baseUrl = 'https://sandbox.onnixpay.com';

function createPixCharge($apiKey, $baseUrl) {
    $data = [
        'amount' => 50.00,
        'description' => 'Teste de cobrança PIX',
        'externalId' => 'pedido-12345',
        'expirationMinutes' => 30,
        'customer' => [
            'name' => 'João Silva',
            'email' => 'joao@example.com',
            'document' => '12345678900'
        ]
    ];

    $ch = curl_init($baseUrl . '/sdk/pix');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200 && $httpCode !== 201) {
        throw new Exception('Erro na requisição: ' . $response);
    }

    return json_decode($response, true);
}

$result = createPixCharge($apiKey, $baseUrl);
echo "PIX criado: " . $result['data']['id'] . "\n";

Próximos Passos

Agora que você fez sua primeira transação:

1. Configure Webhooks para receber notificações
2. Explore todos os métodos de pagamento
3. Entenda os códigos de erro
4. Consulte o saldo da conta

Atenção

Quando for para produção, lembre-se de:

• Trocar a URL base para https://api.onnixpay.com
• Usar suas credenciais de produção
• Implementar tratamento de erros robusto
• Validar assinaturas de webhooks