Introdução

Autenticação

A API utiliza autenticação via Basic Authentication com suas chaves de API codificadas em Base64.

Formato de Autenticação

// 1. Combine suas chaves
const credentials = "pk_sua_chave_publica:sk_sua_chave_privada";

// 2. Codifique em Base64
const encodedCredentials = btoa(credentials);

// 3. Use no header Authorization
const headers = {
    "Authorization": `Basic ${encodedCredentials}`,
    "Content-Type": "application/json"
};

Headers Obrigatórios

Authorization: Basic cGtfc3VhX2NoYXZlX3B1YmxpY2E6c2tfc3VhX2NoYXZlX3ByaXZhZGE=
Content-Type: application/json

Criar Pagamento

Endpoint para criar uma nova transação PIX.

Parâmetros da Requisição

Estrutura do Campo Split (Opcional)

O campo split permite dividir o valor líquido da transação entre a empresa principal e uma empresa secundária. Útil para cenários de marketplace, parcerias ou revenda.

Estrutura do Campo Tracking (Opcional)

O campo tracking permite enviar dados de rastreamento de campanhas e origem do tráfego. Todos os subcampos são opcionais.

Estrutura do Campo Items

O campo items é opcional e permite especificar detalhes dos produtos/serviços da transação. Se não fornecido, será criado automaticamente um item com base na descrição.

"items": [
  {
    "title": "Plano Pro",
    "unitPrice": 2590,
    "quantity": 1,
    "tangible": false
  },
  {
    "title": "Taxa de Setup",
    "unitPrice": 500,
    "quantity": 1,
    "tangible": false
  }
]

Exemplo de Requisição (cURL)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.90,
    "payment_method": "pix",
    "description": "Compra de produto XYZ",
    "items": [
      {
        "title": "Plano Pro",
        "unitPrice": 2590,
        "quantity": 1,
        "tangible": false
      }
    ],
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    },
    "postbackUrl": "https://seu-site.com/webhook/pagamentos",
    "tracking": {
      "src": "google",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday_2024",
      "utm_term": "produto_xyz",
      "utm_content": "anuncio_1",
      "sck": "sck_123456",
      "client_reference_id": "ref_789",
      "xcode": "xcode_abc"
    },
    "source_url": "https://sua-loja.com/checkout/oferta-xyz",
    "source_label": "Oferta XYZ - Checkout"
  }'

Exemplo de Requisição com Split (cURL)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payment_method": "pix",
    "description": "Venda Marketplace - Produto ABC",
    "items": [
      {
        "title": "Produto ABC",
        "unitPrice": 10000,
        "quantity": 1,
        "tangible": true
      }
    ],
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": "987.654.321-00",
      "phone": "11988887777"
    },
    "metadata": {
      "order_id": "98765",
      "seller_id": "123"
    },
    "postbackUrl": "https://seu-site.com/webhook/pagamentos",
    "split": {
      "empresa_id": 123,
      "p_split": 30
    }
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "PXB_68E6C0A14DC3D_1759953057",
    "status": "pendente",
    "amount": 5,
    "payment_method": "pix",
    "pix_code": "00020126860014br.gov.bcb.pix2564pix.bancoe2.com.br/qr/v3/at/afa55845-f3f2-4275-8b31-e4abd...",
    "pix_qr_code": "iVBORw0KGgoAAAANSUhEUgAAAOwAAADsCAAAAABSuBXIAAAEn0lEQVR42u2dQXLjSAwE+f9Pcy9zmIkVUVltXw...",
    "external_ref": "12345",
    "created_at": "2025-10-08 19:50:57",
    "expires_at": "2025-10-09 19:50:57",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    },
    "split": {
      "empresa_id": 123,
      "p_split": 30,
      "valor_split": null,
      "valor_principal": null,
      "processado": false
    }
  }
}

Criar Pagamento com Cartão de Crédito

Endpoint para criar uma nova transação com cartão de crédito.

Parâmetros da Requisição

Estrutura do Campo Customer

Estrutura do Campo Card

Exemplo de Requisição

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payment_method": "credit_card",
    "installments": 3,
    "description": "Compra de produto",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900",
      "phone": "11999999999"
    },
    "card": {
      "number": "4111111111111111",
      "holder_name": "JOAO SILVA",
      "expiration_month": "12",
      "expiration_year": "2026",
      "cvv": "123"
    },
    "postbackUrl": "https://seusite.com/webhook",
    "metadata": {
      "order_id": "12345"
    }
  }'

Exemplo de Resposta (Sucesso)

{
  "success": true,
  "data": {
    "id": "CC_695C9F3731CED_1767677751",
    "status": "pago",
    "amount": 10,
    "payment_method": "credit_card",
    "card_brand": "mastercard",
    "card_last_digits": "4962",
    "installments": 1,
    "installment_amount": 10,
    "authorization_code": "TEST480561",
    "nsu": "NSU203601",
    "tid": "TID157592201",
    "created_at": "2026-01-06 13:35:51",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345"
    }
  }
}

Exemplo de Resposta (Recusada)

{
  "success": false,
  "error": "Pagamento recusado",
  "data": {
    "id": "CC_695C9F3731CED_1767677752",
    "status": "recusado",
    "amount": 10,
    "payment_method": "credit_card",
    "card_brand": "mastercard",
    "card_last_digits": "4962"
  }
}

Consultar Pagamento

Consulte o status de uma transação específica.

Parâmetros da URL

Exemplo de Requisição

curl -X GET "https://api.onyxpag.com/transactions/PXB_68E6C0A14DC3D_1759953057" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "PXB_68E6C0A14DC3D_1759953057",
    "status": "pago",
    "amount": 5,
    "payment_method": "pix",
    "created_at": "2025-10-08 19:50:57",
    "paid_at": "2025-10-08 19:51:18",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "document": "123.456.789-00",
      "phone": "11999999999"
    },
    "metadata": {
      "order_id": "12345",
      "product_id": "789"
    }
  }
}

Verificar 3DS Secure

Verifique se o 3D Secure está ativo para sua empresa. O 3DS (3D Secure) é uma camada adicional de segurança para transações com cartão de crédito.

Headers Obrigatórios

Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": {
    "empresa_id": 1,
    "empresa_nome": "Minha Empresa LTDA",
    "3ds_ativo": true,
    "3ds_status": "ATIVO - Transações terão autenticação 3D Secure",
    "configuracao_origem": "empresa"
  }
}

Resposta - Empresa sem Adquirente Configurado

{
  "success": true,
  "data": {
    "empresa_id": 1,
    "empresa_nome": "Minha Empresa LTDA",
    "3ds_ativo": false,
    "mensagem": "Empresa não possui adquirente de cartão configurado"
  }
}

Exemplo de Requisição

cURL

curl -X GET "https://api.onyxpag.com/?verificar_3ds" \
  -H "Authorization: Basic cGtfbGl2ZV9hYmMxMjM6c2tfbGl2ZV94eXo3ODk=" \
  -H "Content-Type: application/json"

JavaScript

const chavePublica = 'pk_live_abc123xyz';
const chavePrivada = 'sk_live_xyz789abc';
const credentials = btoa(`${chavePublica}:${chavePrivada}`);

fetch('https://api.onyxpag.com/?verificar_3ds', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => {
  if (data.success && data.data['3ds_ativo']) {
    console.log('3D Secure está ATIVO');
    console.log('Adquirente:', data.data.adquirente.nome);
  } else {
    console.log('3D Secure está DESATIVADO');
  }
})
.catch(error => console.error('Erro:', error));

PHP

$chavePublica = 'pk_live_abc123xyz';
$chavePrivada = 'sk_live_xyz789abc';
$credentials = base64_encode("$chavePublica:$chavePrivada");

$ch = curl_init('https://api.onyxpag.com/?verificar_3ds');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

if ($data['success'] && $data['data']['3ds_ativo']) {
    echo "3D Secure ATIVO\n";
    echo "Adquirente: " . $data['data']['adquirente']['nome'] . "\n";
} else {
    echo "3D Secure DESATIVADO\n";
}

Códigos de Erro

{
  "error": "Invalid API credentials"
}

{
  "error": "Internal server error: [mensagem]"
}

Consultar Empresa

Consulte os dados cadastrais da sua empresa autenticada. Esta rota retorna todas as informações da empresa, incluindo as chaves de API, mas não inclui o saldo.

Headers Obrigatórios

Exemplo de Requisição

curl -X GET "https://api.onyxpag.com/?empresa" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"

Exemplo de Resposta (200 OK)

{
  "success": true,
  "data": {
    "id": 117,
    "codigo_cliente": "EMP252073",
    "nome_empresa": "Minha Empresa LTDA",
    "tipo_pessoa": "juridica",
    "cnpj": "12.345.678/0001-90",
    "cpf": null,
    "email": "contato@minhaempresa.com",
    "telefone": "11999999999",
    "endereco": "Rua Exemplo, 123",
    "cidade": "São Paulo",
    "estado": "SP",
    "cep": "01234-567",
    "responsavel_nome": "João Silva",
    "responsavel_email": "joao@minhaempresa.com",
    "responsavel_telefone": "11988888888",
    "chave_publica": "pk_live_abc123xyz",
    "chave_privada": "sk_live_xyz789abc",
    "status": "aprovado",
    "created_at": "2025-01-01 10:00:00"
  }
}

Campos Retornados

Códigos de Erro

{
  "error": "Authorization header missing or invalid"
}

{
  "error": "Invalid API credentials"
}

{
  "error": "Internal server error: [mensagem]"
}

Exemplos de Integração

JavaScript (Fetch API)

const chavePublica = 'pk_live_abc123xyz';
const chavePrivada = 'sk_live_xyz789abc';
const credentials = btoa(`${chavePublica}:${chavePrivada}`);

fetch('https://api.onyxpag.com/?empresa', {
  method: 'GET',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Dados da empresa:', data.data);
  console.log('Nome:', data.data.nome_empresa);
  console.log('Email:', data.data.email);
  console.log('Código Cliente:', data.data.codigo_cliente);
})
.catch(error => console.error('Erro:', error));

PHP (cURL)

$chavePublica = 'pk_live_abc123xyz';
$chavePrivada = 'sk_live_xyz789abc';
$credentials = base64_encode("$chavePublica:$chavePrivada");

$ch = curl_init('https://api.onyxpag.com/?empresa');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);
    echo "Nome: " . $data['data']['nome_empresa'] . "\n";
    echo "Email: " . $data['data']['email'] . "\n";
    echo "Código: " . $data['data']['codigo_cliente'] . "\n";
} else {
    echo "Erro: " . $response . "\n";
}

Python (Requests)

import requests
import base64

chave_publica = 'pk_live_abc123xyz'
chave_privada = 'sk_live_xyz789abc'
credentials = base64.b64encode(f'{chave_publica}:{chave_privada}'.encode()).decode()

response = requests.get(
    'https://api.onyxpag.com/?empresa',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json'
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"Nome: {data['data']['nome_empresa']}")
    print(f"Email: {data['data']['email']}")
    print(f"Código: {data['data']['codigo_cliente']}")
else:
    print(f"Erro: {response.text}")

Listar Pagamentos

Liste todas as transações da sua conta com filtros opcionais.

Parâmetros de Query (Opcionais)

Exemplo de Requisição

curl -X GET "https://api.onyxpag.com/transactions?page=1&limit=10&status=pago" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "PXB_68E6C0A14DC3D_1759953057",
        "status": "pago",
        "amount": 5,
        "created_at": "2025-10-08 19:50:57",
        "customer": {
          "name": "João Silva",
          "email": "joao.silva@email.com"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20
    }
  }
}

Saques PIX

Solicite saques do seu saldo disponível via PIX de forma rápida e segura.

Solicitar Saque

Parâmetros da Requisição

Formatos de Chave PIX

Exemplo de Requisição com CPF (cURL)

curl -X POST "https://api.onyxpag.com/withdrawal" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 20.00,
    "pix_key_type": "cpf",
    "pix_key": "12345678900",
    "observacoes": "Saque via api"
  }'

Exemplo de Requisição com Telefone (cURL)

curl -X POST "https://api.onyxpag.com/withdrawal" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "pix_key_type": "telefone",
    "pix_key": "11999999999",
    "documento_responsavel_pix": "12345678900",
    "observacoes": "Saque para telefone"
  }'

Exemplo de Resposta

{
  "success": true,
  "message": "Withdrawal request created successfully",
  "data": {
    "id": 123,
    "amount": 20.00,
    "fee_amount": 0.00,
    "net_amount": 20.00,
    "pix_key_type": "cpf",
    "pix_key": "000.000.000-00",
    "status": "pendente",
    "created_at": "2025-01-07 10:30:00",
    "observacoes": "Saque via api"
  }
}

Consultar Saque

Exemplo de Consulta

curl -X GET "https://api.onyxpag.com/withdrawal?id=123" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json"

Listar Saques

Parâmetros de Query (Opcionais)

Status dos Saques

Resumo da Conta

Retorna um resumo dos saques da sua conta:

{
  "success": true,
  "data": {
    "total_saques": 15,
    "valor_pendente": 500.00,
    "valor_aprovado": 750.00,
    "valor_concluido": 2350.00,
    "valor_cancelado": 0.00
  }
}

Webhooks e PostbackURL

Receba notificações automáticas sobre mudanças de status das transações.

Eventos Enviados

Estrutura do Webhook

{
  "event": "transaction.paid",
  "timestamp": "2025-01-07T08:51:18-03:00",
  "data": {
    "transaction_id": "PXB_68E4FE71E4AF4_1759837809",
    "external_id": "12345",
    "amount": "25.90",
    "fee_amount": "1.30",
    "net_amount": "24.60",
    "currency": "BRL",
    "payment_method": "pix",
    "status": "paid",
    "created_at": "2025-01-07T08:50:11-03:00",
    "updated_at": "2025-01-07T08:51:18-03:00",
    "paid_at": "2025-01-07T08:51:18-03:00",
    "customer": {
      "name": "João Silva",
      "email": "joao.silva@email.com",
      "phone": "11999999999",
      "document": "12345678900"
    },
    "items": [
      {
        "title": "Nome do produto",
        "quantity": 1,
        "unit_price": "25.90"
      }
    ]
  }
}

Validação de Webhooks

Exemplo de Implementação

<?php
// webhook.php
$input = file_get_contents('php://input');
$data = json_decode($input, true);

if ($data['event'] === 'transaction.paid') {
    $transactionId = $data['data']['transaction_id'];
    $amount = $data['data']['amount'];
    
    // Processar pagamento confirmado
    updateOrderStatus($transactionId, 'paid');
    
    // Responder com sucesso
    http_response_code(200);
    echo json_encode(['status' => 'received']);
}
?>

Integre com IA

Cole o prompt abaixo em qualquer IA (ChatGPT, Claude, Gemini, etc.) e peça para ela gerar o código de integração completo na linguagem que você preferir.

Prompt Completo para Gerar PIX e Consultar Transação

Você é um especialista em integração de APIs de pagamento. Preciso integrar a API Onyxpag Hub na minha aplicação.

## Informações da API

Base URL: https://api.onyxpag.com
Autenticação: Basic Auth — combinar chave_publica:chave_privada e codificar em Base64
Content-Type: application/json

---

## 1. GERAR PIX

Método: POST https://api.onyxpag.com

Headers:
  Authorization: Basic {base64(chave_publica:chave_privada)}
  Content-Type: application/json

Body (JSON):
{
  "amount": 25.90,
  "payment_method": "pix",
  "source_url": "https://sua-loja.com/checkout/oferta-xyz",
  "description": "Descrição do pagamento",
  "items": [
    {
      "title": "Nome do Produto",
      "unitPrice": 2590,
      "quantity": 1,
      "tangible": false
    }
  ],
  "customer": {
    "name": "Nome do Cliente",
    "email": "cliente@email.com",
    "document": "000.000.000-00",
    "phone": "11999999999"
  },
  "postbackUrl": "https://seu-site.com/webhook",
  "metadata": {
    "order_id": "pedido_123"
  }
}

IMPORTANTE — o campo "source_url" é OBRIGATÓRIO: URL (http/https) da página onde a transação foi originada (o checkout/oferta do cliente). Serve para identificar a procedência da venda (segurança, conciliação e suporte em disputas). O código gerado DEVE sempre enviar a URL real da página de checkout em "source_url" — nunca deixe fixo/vazio. Opcionalmente, envie também "source_label" (string) descrevendo a oferta/produto.

Resposta de Sucesso (HTTP 201):
{
  "success": true,
  "data": {
    "id": "PXB_68E4FE71E4AF4_1759837809",
    "status": "pendente",
    "amount": "25.90",
    "payment_method": "pix",
    "pix_code": "00020126570014br.gov.bcb.pix...",
    "pix_qr_code": "data:image/png;base64,...",
    "external_ref": "pedido_123",
    "created_at": "2025-01-07 08:50:11",
    "expires_at": "2025-01-08 08:50:11"
  }
}

---

## 2. CONSULTAR TRANSAÇÃO PIX (verificar se foi pago)

Método: GET https://api.onyxpag.com?id={transaction_id}

Headers:
  Authorization: Basic {base64(chave_publica:chave_privada)}

Resposta de Sucesso:
{
  "success": true,
  "data": {
    "id": "PXB_68E4FE71E4AF4_1759837809",
    "status": "pago",
    "amount": "25.90",
    "payment_method": "pix",
    "customer": {
      "name": "Nome do Cliente",
      "email": "cliente@email.com"
    },
    "created_at": "2025-01-07 08:50:11",
    "paid_at": "2025-01-07 08:51:18"
  }
}

Status possíveis da transação:
  - "pendente"  → Aguardando pagamento
  - "pago"      → Pagamento confirmado
  - "expirado"  → PIX expirou sem pagamento
  - "cancelado" → Transação cancelada

---

## 3. WEBHOOK (Notificação automática quando pago)

Ao enviar "postbackUrl" na criação do PIX, o servidor notificará via POST quando o pagamento for confirmado:

{
  "event": "transaction.paid",
  "timestamp": "2025-01-07T08:51:18-03:00",
  "data": {
    "transaction_id": "PXB_68E4FE71E4AF4_1759837809",
    "external_id": "seu_order_id",
    "status": "paid",
    "amount": "25.90",
    "payment_method": "pix",
    "customer": {
      "name": "Nome do Cliente",
      "email": "cliente@email.com",
      "phone": "11999999999",
      "document": "12345678900"
    },
    "items": [
      { "title": "Nome do produto", "quantity": 1, "unit_price": "25.90" }
    ]
  }
}

---

Com base nessas informações, me ajude a implementar a integração completa em: [INFORME AQUI SUA LINGUAGEM/FRAMEWORK, ex: PHP, Node.js, Python, React, etc.]