Ir para o conteúdo

Como Aceitar Pagamentos com Cartão de Crédito no Seu Site Usando a API do 4Geeks Payments

🤖 Explicar com IA

A API do 4Geeks Payments permite que os desenvolvedores criem experiências de checkout totalmente personalizadas. Esteja você gerenciando uma loja de e-commerce simples ou uma plataforma SaaS complexa, esta API permite processar transações de cartões de crédito, débito e carteiras digitais diretamente de sua aplicação.

Este guia fornece um passo a passo para integrar a API de Pagamentos, garantindo um processamento de transações seguro e eficiente.

Pré-requisitos

Antes de escrever qualquer código, certifique-se de ter o seguinte pronto:

  • Conta 4Geeks Verificada: Você deve ter acesso ao 4Geeks Console.
  • Serviço de Pagamentos Ativo: Certifique-se de que o módulo de Pagamentos (Payments) está habilitado nas configurações de sua conta.
  • Credenciais de API: Você precisará do seu Client ID e Client Secret (ou Chaves de API) obtidos no painel do desenvolvedor.
  • Certificado SSL: Seu site deve fornecer conteúdo via HTTPS para lidar com os dados das transações de forma segura.

Instruções Passo a Passo

Siga estas etapas para processar uma cobrança de pagamento padrão usando a API.

Passo 1: Obter suas Credenciais de API

Para se comunicar com a API, primeiro você precisa recuperar suas credenciais seguras.

  1. Faça login no 4Geeks Console.
  2. Navegue até Settings > API Keys no menu lateral.
  3. Localize seu Client ID e Client Secret.

Dica: Você verá dois conjuntos de chaves: “Test” e “Live”. Sempre use as chaves de Teste durante o desenvolvimento para simular transações sem movimentar dinheiro real. Mude para as chaves Live apenas quando estiver pronto para o lançamento.

Passo 2: Gerar um Token de Acesso

A API 4Geeks usa autenticação Bearer Token. Você deve trocar suas credenciais por um token de acesso temporário antes de fazer solicitações de pagamento.

Endpoint: POST /oauth/token

Corpo da Solicitação (Request Body): 

    {
        "client_id": "SEU_CLIENT_ID",
        "client_secret": "SEU_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }

Resposta: A API retornará um objeto JSON contendo um access_token. Você usará este token no cabeçalho de suas solicitações subsequentes.

Passo 3: Criar uma Cobrança de Pagamento

Agora que você está autenticado, pode iniciar uma transação. Esta solicitação envia os detalhes do pagamento para a 4Geeks para processamento.

Endpoint: POST /v1/payments/

Cabeçalhos (Headers):

  • Authorization: Bearer <SEU_TOKEN_DE_ACESSO>
  • Content-Type: application/json

Parâmetros do Corpo:

  • amount: O custo total (ex: 150.00).
  • currency: O código ISO de 3 letras (ex: USD, EUR).
  • description: Um breve resumo da compra.
  • return_url: A URL para onde seu cliente será redirecionado após o processo de pagamento (essencial para fluxos 3D Secure).

Exemplo de Solicitação:

{
  "amount": 150.00,
  "currency": "USD",
  "description": "Assinatura Anual Premium",
  "return_url": "https://seu-site.com/checkout/sucesso"
}

Passo 4: Tratar a Resposta

A API retornará o status da transação imediatamente.

  • Sucesso: Se o status for succeeded ou approved, o pagamento está concluído. Você deve mostrar uma mensagem de sucesso ao usuário e atualizar seu banco de dados.
  • Ação Necessária (Action Required): Se o status for action_required (comum em 3D Secure), a resposta incluirá uma redirect_url. Você deve redirecionar o cliente para esta URL para concluir a verificação bancária.

Casos de Uso Comuns

1. Checkout de E-commerce

Um cliente adiciona itens ao carrinho e clica em “Finalizar Compra”. Seu backend calcula o total e chama o endpoint /v1/payments/. Após uma resposta bem-sucedida, você aciona seu sistema de inventário (talvez gerenciado pelo 4Geeks Asset) para deduzir o estoque e enviar um e-mail de confirmação.

2. Faturamento de Assinatura SaaS

Para um serviço de software mensal, você pode tokenizar o cartão de um cliente durante o primeiro pagamento. Você pode então usar esse token para automatizar cobranças futuras via API sem pedir que o usuário insira novamente seus dados todos os meses. Isso se integra perfeitamente aos recursos de faturamento recorrente do 4Geeks Payments.

Solução de Problemas

Aqui estão as soluções para erros comuns que você pode encontrar durante a integração:

  • Erro 401 Unauthorized:

    • Causa: Seu Bearer Token está ausente, incorreto ou expirou.
    • Solução: Gere um novo token usando o endpoint /oauth/token e certifique-se de que ele esteja incluído corretamente no cabeçalho de Autorização.

  • Transação Recusada (Erro Genérico):

    • Causa: O emissor do cartão rejeitou a transação (ex: saldo insuficiente).
    • Solução: Verifique o error_code na resposta da API. Se você estiver no Modo de Teste, certifique-se de usar os números de cartão de teste válidos fornecidos na documentação.

  • Erro de CORS:

    • Causa: Você está tentando fazer chamadas de API diretamente do navegador (lado do cliente).
    • Solução: Por segurança, nunca exponha seu Client Secret no código de frontend. Sempre encaminhe as solicitações de pagamento por meio do seu próprio servidor de backend.

Conclusão

Integrar a API do 4Geeks Payments oferece controle total sobre seus fluxos de pagamento, permitindo uma experiência segura e personalizada para seus usuários. Seguindo estas etapas, você pode começar a aceitara cartões de crédito de forma segura e eficiente.

Para configurações mais avançadas, como salvar cartões para uso futuro ou lidar com webhooks, visite o 4Geeks Console ou explore nossa documentação para desenvolvedores.

Recursos Adicionais