BytePay Logo

BytePay Checkout - Documentação

Introdução

O BytePay Checkout é uma solução white-label para processamento de pagamentos que pode ser facilmente integrada a qualquer plataforma de e-commerce. Esta documentação fornece instruções detalhadas sobre como integrar o checkout em sua loja online.

Estrutura do Banco de Dados

O BytePay Checkout utiliza um banco de dados PostgreSQL para armazenar informações sobre usuários, transações e configurações. Abaixo está a estrutura das tabelas necessárias:

Tabela: users

ColunaTipoDescrição
iduuidID único do usuário (chave primária)
emailtextEmail do usuário (único)
business_nametextNome da empresa
api_keytextChave de API para integração (única)
created_attimestampData de criação

Tabela: user_settings

ColunaTipoDescrição
iduuidID único (chave primária)
user_iduuidID do usuário (chave estrangeira)
pix_enabledbooleanSe o pagamento PIX está habilitado
credit_card_enabledbooleanSe o pagamento com cartão está habilitado
primary_colortextCor primária do checkout
logo_urltextURL do logo
created_attimestampData de criação
updated_attimestampData de atualização

Tabela: transactions

ColunaTipoDescrição
iduuidID único (chave primária)
user_iduuidID do usuário (chave estrangeira)
amountnumericValor da transação
statustextStatus da transação (pending, completed, failed)
payment_methodtextMétodo de pagamento (pix, credit_card)
customer_nametextNome do cliente
customer_emailtextEmail do cliente
customer_documenttextDocumento do cliente (CPF)
customer_phonetextTelefone do cliente
product_nametextNome do produto
product_pricenumericPreço unitário do produto
product_quantityintegerQuantidade do produto
transaction_idtextID da transação (para referência externa)
utmsjsonbParâmetros UTM para rastreamento
created_attimestampData de criação

Integração com Shopify

Para integrar o BytePay Checkout com sua loja Shopify, siga os passos abaixo:

1. Obtenha sua chave de API

Registre-se na plataforma BytePay e obtenha sua chave de API no painel do lojista.

2. Configure o redirecionamento de checkout

No painel administrativo do Shopify, vá para Configurações > Checkout e desative o checkout padrão do Shopify.

3. Adicione o script de integração

Adicione o seguinte script ao tema da sua loja Shopify:

// Adicione este código ao arquivo checkout.liquid
document.addEventListener('DOMContentLoaded', function() {
const checkoutButton = document.querySelector('.checkout-button');

checkoutButton.addEventListener('click', function(e) {
  e.preventDefault();
  
  // Obtenha os dados do carrinho
  const cart = {{ cart | json }};
  
  // Construa a URL do checkout BytePay
  const checkoutUrl = new URL('https://seu-dominio.com/checkout');
  
  // Adicione os parâmetros necessários
  checkoutUrl.searchParams.append('api_key', 'SUA_API_KEY');
  checkoutUrl.searchParams.append('name', cart.items[0].product_title);
  checkoutUrl.searchParams.append('price', cart.total_price / 100);
  checkoutUrl.searchParams.append('image', cart.items[0].image);
  checkoutUrl.searchParams.append('merchant', '{{ shop.name }}');
  checkoutUrl.searchParams.append('color', '22c55e');
  
  // Adicione parâmetros UTM para rastreamento
  const urlParams = new URLSearchParams(window.location.search);
  if (urlParams.has('utm_source')) checkoutUrl.searchParams.append('utm_source', urlParams.get('utm_source'));
  if (urlParams.has('utm_medium')) checkoutUrl.searchParams.append('utm_medium', urlParams.get('utm_medium'));
  if (urlParams.has('utm_campaign')) checkoutUrl.searchParams.append('utm_campaign', urlParams.get('utm_campaign'));
  if (urlParams.has('utm_term')) checkoutUrl.searchParams.append('utm_term', urlParams.get('utm_term'));
  if (urlParams.has('utm_content')) checkoutUrl.searchParams.append('utm_content', urlParams.get('utm_content'));
  
  // Redirecione para o checkout BytePay
  window.location.href = checkoutUrl.toString();
});
});

Parâmetros da URL de Checkout

A URL de checkout do BytePay aceita os seguintes parâmetros:

ParâmetroTipoObrigatórioDescrição
api_keystringSimSua chave de API BytePay
namestringSimNome do produto
pricenumberSimPreço do produto
imagestringNãoURL da imagem do produto
merchantstringNãoNome da loja
colorstringNãoCor primária do checkout (sem #)
logostringNãoURL do logo da loja
pix_enabledbooleanNãoSe o pagamento PIX está habilitado
card_enabledbooleanNãoSe o pagamento com cartão está habilitado
utm_sourcestringNãoFonte da campanha
utm_mediumstringNãoMeio da campanha
utm_campaignstringNãoNome da campanha
utm_termstringNãoTermos da campanha
utm_contentstringNãoConteúdo da campanha

Exemplo de URL

https://seu-dominio.com/checkout?api_key=BPC-12345&name=Produto%20Exemplo&price=99.90&image=https://exemplo.com/imagem.jpg&merchant=Minha%20Loja&color=22c55e&pix_enabled=true&card_enabled=true

API de Pagamento

O BytePay Checkout oferece uma API para processamento de pagamentos. Abaixo estão os endpoints disponíveis:

Gerar Pagamento PIX

Endpoint: POST /api/checkout/pix

Descrição: Gera um código PIX para pagamento.

Corpo da Requisição

{
"apiKey": "BPC-12345",
"amount": 99.90,
"client": {
  "name": "Nome do Cliente",
  "document": "123.456.789-00",
  "telefone": "(11) 98765-4321",
  "email": "cliente@exemplo.com"
},
"product": {
  "name": "Produto Exemplo",
  "price": 99.90,
  "quantity": 1
},
"utms": {
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "black_friday"
}
}

Resposta

{
"status": "success",
"message": "ok",
"paymentCode": "00020101021226790014br.gov.bcb.pix255/v2/be1920df6b714e4e84edd77d7f25204000039865802BR592**63042CA1",
"idTransaction": "52fc5262-XXXX-4900-933b-XXXXXXXX",
"paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAACwElEQVR4Xu2XS5IjIQwF4SJw..."
}

Processar Pagamento com Cartão

Endpoint: POST /api/checkout/card

Descrição: Processa um pagamento com cartão de crédito.

Corpo da Requisição

{
"apiKey": "BPC-12345",
"email": "cliente@exemplo.com",
"telefone": "(11) 98765-4321",
"nome": "Nome do Cliente",
"cpf": "123.456.789-00",
"valor": 99.90,
"id": "order-123456",
"installments": "1",
"card": {
  "number": "4111111111111111",
  "holderName": "NOME DO TITULAR",
  "expirationMonth": "12",
  "expirationYear": "2025",
  "cvv": "123"
},
"product": {
  "name": "Produto Exemplo",
  "price": 99.90,
  "quantity": 1
},
"utms": {
  "utm_source": "instagram",
  "utm_medium": "organic",
  "utm_campaign": "lancamento"
}
}

Resposta

{
"success": true,
"data": {
  "status": "success",
  "message": "Pagamento realizado com sucesso",
  "transactionId": "52fc5262-XXXX-4900-933b-XXXXXXXX"
}
}

Webhooks

O BytePay Checkout oferece webhooks para notificar sua aplicação sobre eventos de pagamento. Para configurar um webhook, acesse o painel do lojista e adicione a URL do seu endpoint.

Eventos Disponíveis

  • payment.success - Quando um pagamento é concluído com sucesso
  • payment.failed - Quando um pagamento falha
  • payment.pending - Quando um pagamento está pendente (aguardando confirmação PIX)
  • payment.refunded - Quando um pagamento é reembolsado

Formato do Payload

{
"event": "payment.success",
"data": {
  "transaction_id": "52fc5262-XXXX-4900-933b-XXXXXXXX",
  "amount": 99.90,
  "payment_method": "pix",
  "customer": {
    "name": "Nome do Cliente",
    "email": "cliente@exemplo.com"
  },
  "product": {
    "name": "Produto Exemplo",
    "price": 99.90,
    "quantity": 1
  },
  "timestamp": "2023-11-01T12:34:56Z"
}
}

Suporte

Para obter suporte ou esclarecer dúvidas sobre a integração, entre em contato conosco:

  • Email: suporte@bytepay.com
  • Telefone: (11) 1234-5678
  • Chat: Disponível no painel do lojista