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"
  }
}

Pagamentos Globais

Cobre compradores fora do Brasil pelo mesmo endpoint das cobranças PIX, mudando apenas o payment_method. Há dois trilhos:

• México — spei (transferência bancária via CLABE) e oxxo (pagamento em dinheiro na loja, com referência). Valor em pesos mexicanos (MXN); o crédito entra na sua conta em reais.
• Internacional (checkout hospedado) — internacional: cartão (com Apple Pay e Google Pay) e, em euro, Bizum e Klarna. Valor na moeda que você enviar; o crédito entra na sua carteira em dólar (USD).
• Portugal — mbway: pedido de pagamento enviado ao telemóvel do comprador, que aprova na app MB WAY. Sem checkout: você só informa o telefone. Valor em euro (EUR); o crédito entra na sua carteira em dólar (USD).

Resumo por país e método

O prazo de repasse é configurado por conta pela equipe Onyxpag; os valores acima são os padrões. Prazo 0 ou 1 = disponível na confirmação; acima disso o líquido fica "a liberar" e entra no saldo automaticamente na data.

Moedas: como amount e currency funcionam

México — SPEI e OXXO

Escolha entre spei (transferência via CLABE) e oxxo (pagamento em dinheiro com referência OXXO). O valor é cobrado em pesos mexicanos.

Exemplo de Requisição (SPEI)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 350.00,
    "payment_method": "spei",
    "description": "Compra de produto",
    "customer": {
      "name": "Juan Pérez",
      "email": "juan@example.com",
      "document": "GODE561231GR8"
    },
    "postbackUrl": "https://seusite.com/webhook",
    "metadata": {
      "order_id": "12345"
    }
  }'

Resposta (SPEI — CLABE)

{
  "success": true,
  "data": {
    "id": "PXB_6AB41D1E4720D_1790188830",
    "status": "pendente",
    "amount": "350.00",
    "currency": "MXN",
    "payment_method": "spei",
    "external_ref": "12345",
    "created_at": "2026-09-24 18:40:30",
    "customer": { "name": "Juan Pérez", "email": "juan@example.com" },
    "metadata": { "order_id": "12345" },
    "spei": {
      "clabe": "646180111812345678",
      "bank": "STP",
      "beneficiary": "ONYX",
      "expires_at": "2026-09-25 18:40:30"
    }
  }
}

Resposta (OXXO — referência)

{
  "success": true,
  "data": {
    "id": "PXB_6AB41D1E4720D_1790188831",
    "status": "pendente",
    "amount": "350.00",
    "currency": "MXN",
    "payment_method": "oxxo",
    "external_ref": "12345",
    "created_at": "2026-09-24 18:40:30",
    "customer": { "name": "Juan Pérez", "email": "juan@example.com" },
    "oxxo": {
      "reference": "98765432109876",
      "barcode_url": "https://.../barcode.png",
      "bank": "OXXO",
      "expires_at": "2026-09-27 18:40:30"
    }
  }
}

Internacional — cartão, Bizum e Klarna (checkout hospedado)

A resposta devolve uma URL de checkout hospedado: redirecione o comprador para ela. O formulário seguro apresenta os métodos elegíveis para a moeda e o país dele (cartão com Apple Pay e Google Pay; em euro, também Bizum e Klarna). Você não manuseia dados de cartão e não precisa enviar telefone ou dados bancários: o próprio checkout pede o que cada método exigir.

Exemplo de Requisição (cartão em USD)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "payment_method": "internacional",
    "currency": "USD",
    "description": "Global plan",
    "customer": { "name": "John Buyer", "email": "john@example.com" },
    "postbackUrl": "https://seusite.com/webhook",
    "metadata": { "order_id": "12345" }
  }'

Exemplo de Requisição (Bizum em EUR)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "payment_method": "internacional",
    "currency": "EUR",
    "only_methods": ["bizum"],
    "description": "Pedido 12346",
    "customer": { "name": "María García", "email": "maria@example.com" },
    "postbackUrl": "https://seusite.com/webhook",
    "metadata": { "order_id": "12346" }
  }'

Resposta (sucesso)

{
  "success": true,
  "data": {
    "id": "PXB_6AC512880F354_1791300232",
    "status": "pendente",
    "amount": "50.00",
    "currency": "EUR",
    "payment_method": "internacional",
    "external_ref": "12346",
    "created_at": "2026-10-06 12:23:52",
    "customer": { "name": "María García", "email": "maria@example.com" },
    "metadata": { "order_id": "12346" },
    "international": {
      "checkout_url": "https://pay.onyxpag.com/pay-intl.php?tx=PXB_6AC512880F354_1791300232"
    }
  }
}

Portugal — MB WAY (pedido no telemóvel)

Não há página de pagamento: ao criar a cobrança, o comprador recebe um pedido de pagamento na app MB WAY do telemóvel informado em customer.phone e aprova por lá. Use quando você já coletou o telefone no seu próprio checkout. O valor é sempre em euro.

Exemplo de Requisição (MB WAY)

curl -X POST "https://api.onyxpag.com" \
  -H "Authorization: Basic cGtfdGVzdF8xMjM0NTY6c2tfdGVzdF83ODkwMTI=" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "payment_method": "mbway",
    "description": "Pedido 12347",
    "customer": {
      "name": "Ana Silva",
      "email": "ana@example.pt",
      "phone": "+351 912 345 678"
    },
    "postbackUrl": "https://seusite.com/webhook",
    "metadata": { "order_id": "12347" }
  }'

Resposta (sucesso)

{
  "success": true,
  "data": {
    "id": "MBW_6AC5A1F2C3D4E_1791336000",
    "status": "pendente",
    "amount": "25.00",
    "currency": "EUR",
    "payment_method": "mbway",
    "external_ref": "12347",
    "created_at": "2026-10-06 22:20:00",
    "customer": { "name": "Ana Silva", "email": "ana@example.pt", "phone": "+351 912 345 678" },
    "metadata": { "order_id": "12347" },
    "mbway": {
      "phone_notified": "+351912345678",
      "message": "Confirme o pagamento na app MB WAY do seu telemóvel."
    }
  }
}

Status por método

Exemplos de webhook (postbackUrl)

A estrutura é a mesma do webhook PIX (veja Webhooks e PostbackURL). O que muda: currency e payment_method refletem a transação; no internacional, amount está na moeda cobrada e amount_usd traz o bruto convertido para a sua carteira; fee_amount e net_amount estão na moeda da sua carteira (USD no internacional, MXN no SPEI/OXXO).

SPEI pago

{
  "event": "transaction.paid",
  "timestamp": "2026-09-24T19:02:11-03:00",
  "data": {
    "transaction_id": "PXB_6AB41D1E4720D_1790188830",
    "external_id": "12345",
    "amount": "350.00",
    "fee_amount": "24.47",
    "net_amount": "325.53",
    "currency": "MXN",
    "payment_method": "spei",
    "status": "paid",
    "created_at": "2026-09-24T18:40:30-03:00",
    "updated_at": "2026-09-24T19:02:11-03:00",
    "paid_at": "2026-09-24T19:02:11-03:00",
    "customer": { "name": "Juan Pérez", "email": "juan@example.com", "phone": null, "document": "GODE561231GR8" },
    "items": [ { "title": "Compra de produto", "quantity": 1, "unit_price": "350.00" } ]
  }
}

Internacional pago (cartão em USD)

{
  "event": "transaction.paid",
  "timestamp": "2026-10-06T12:31:40-03:00",
  "data": {
    "transaction_id": "PXB_6AC51286D0D4B_1791300230",
    "external_id": "12345",
    "amount": "49.90",
    "fee_amount": "3.29",
    "net_amount": "46.61",
    "currency": "USD",
    "payment_method": "internacional",
    "amount_usd": "49.90",
    "status": "paid",
    "created_at": "2026-10-06T12:23:50-03:00",
    "updated_at": "2026-10-06T12:31:40-03:00",
    "paid_at": "2026-10-06T12:31:40-03:00",
    "customer": { "name": "John Buyer", "email": "john@example.com", "phone": null, "document": null },
    "items": [ { "title": "Global plan", "quantity": 1, "unit_price": "49.90" } ]
  }
}

Internacional pago (Bizum em EUR)

{
  "event": "transaction.paid",
  "timestamp": "2026-10-06T12:35:02-03:00",
  "data": {
    "transaction_id": "PXB_6AC512880F354_1791300232",
    "external_id": "12346",
    "amount": "50.00",
    "fee_amount": "3.66",
    "net_amount": "52.39",
    "currency": "EUR",
    "payment_method": "internacional",
    "amount_usd": "56.05",
    "status": "paid",
    "created_at": "2026-10-06T12:23:52-03:00",
    "updated_at": "2026-10-06T12:35:02-03:00",
    "paid_at": "2026-10-06T12:35:02-03:00",
    "customer": { "name": "María García", "email": "maria@example.com", "phone": null, "document": null },
    "items": [ { "title": "Pedido 12346", "quantity": 1, "unit_price": "50.00" } ]
  }
}

No exemplo em EUR: € 50,00 convertidos a US$ 56,05 pela cotação do dia; taxa de 6% + US$ 0,30 sobre o valor em USD = US$ 3,66; líquido creditado US$ 52,39.

MB WAY pago (EUR)

{
  "event": "transaction.paid",
  "timestamp": "2026-10-06T22:23:10-03:00",
  "data": {
    "transaction_id": "MBW_6AC5A1F2C3D4E_1791336000",
    "external_id": "12347",
    "amount": "25.00",
    "fee_amount": "1.98",
    "net_amount": "26.04",
    "currency": "EUR",
    "payment_method": "mbway",
    "amount_usd": "28.02",
    "status": "paid",
    "created_at": "2026-10-06T22:20:00-03:00",
    "updated_at": "2026-10-06T22:23:10-03:00",
    "paid_at": "2026-10-06T22:23:10-03:00",
    "customer": { "name": "Ana Silva", "email": "ana@example.pt", "phone": "+351912345678", "document": null },
    "items": [ { "title": "Pedido 12347", "quantity": 1, "unit_price": "25.00" } ]
  }
}

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,
    "currency": "BRL",
    "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/transactions/{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.]