Ir para o conteúdo

🤖 Explicar com IA

Integrando a API 4Geeks Payments em um aplicativo Node.js

Visão geral

4Geeks Payments é uma plataforma Merchant of Record (MoR) que lida com todo o ciclo de vida da transação - desde a aceitação de pagamentos até o gerenciamento de assinaturas, conformidade fiscal e prevenção de fraudes. Este tutorial mostra como integrar a API REST 4Geeks Payments em um aplicativo Node.js.

Neste tutorial, você irá:

  • Configure sua conta 4Geeks Payments e obtenha chaves API
  • Criar uma cobrança (pagamento único)
  • Criar e gerenciar clientes
  • Gerar links de pagamento
  • Lidar com webhooks para eventos de pagamento
  • Processar reembolsos

Pré-requisitos

  • Uma conta 4Geeks Payments ativada (ativar serviço)
  • Node.js 18+ instalado
  • gerenciador de pacotes npm ou fio
  • Compreensão básica de APIs REST e Express.js

Etapa 1: Obtenha suas chaves de API

  1. Faça login em console.4geeks.io
  2. Navegue até Pagamentos → Configurações → Chaves de API
  3. Clique em “Gerar chave de API”
  4. Copie e armazene com segurança:
  5. Chave Pública (para operações do lado do cliente)
  6. Chave secreta (para operações no lado do servidor — nunca exponha isso)

Importante: Use chaves de sandbox para testes. Mude para chaves de produção quando estiver pronto para entrar no ar.

Etapa 2: Configure seu projeto

mkdir my-payment-app && cd my-payment-app
npm init -y
npm install express axios dotenv cors

Crie a estrutura do seu projeto:

my-payment-app/
├── .env
├── server.js
├── routes/
│   └── payments.js
└── package.json

Etapa 3: Configurar variáveis de ambiente

Crie um arquivo .env:

FOURGEEKS_PAYMENTS_SECRET_KEY=sk_test_your_secret_key_here
FOURGEEKS_PAYMENTS_PUBLIC_KEY=pk_test_your_public_key_here
FOURGEEKS_PAYMENTS_API_URL=https://api.4geeks.io/v1
PORT=3000

Etapa 4: Crie o servidor expresso

Crie server.js:

CODE_BLOCO_3

Etapa 5: Crie rotas de pagamento

Crie routes/payments.js:

const express = require('express');
const axios = require('axios');
const router = express.Router();

const API_URL = process.env.FOURGEEKS_PAYMENTS_API_URL;
const SECRET_KEY = process.env.FOURGEEKS_PAYMENTS_SECRET_KEY;

const api = axios.create({
  baseURL: API_URL,
  headers: {
    'Authorization': `Bearer ${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
});

// Create a one-time charge
router.post('/charges', async (req, res) => {
  try {
    const { amount, currency, customer_id, description } = req.body;

    const response = await api.post('/charges', {
      amount,           // Amount in cents (e.g., 1000 = $10.00)
      currency,         // e.g., 'USD', 'EUR', 'CRC'
      customer_id,      // Existing customer ID or create new
      description,
      capture: true,    // Auto-capture the charge
    });

    res.json({ success: true, charge: response.data });
  } catch (error) {
    console.error('Charge error:', error.response?.data || error.message);
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create charge',
    });
  }
});

// Create a customer
router.post('/customers', async (req, res) => {
  try {
    const { email, name, phone, metadata } = req.body;

    const response = await api.post('/customers', {
      email,
      name,
      phone,
      metadata, // Optional: custom key-value pairs
    });

    res.json({ success: true, customer: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create customer',
    });
  }
});

// Generate a payment link
router.post('/payment-links', async (req, res) => {
  try {
    const { amount, currency, description, customer_email, success_url, cancel_url } = req.body;

    const response = await api.post('/payment-links', {
      amount,
      currency,
      description,
      customer_email,
      success_url,    // Redirect after successful payment
      cancel_url,     // Redirect if customer cancels
    });

    res.json({ success: true, payment_link: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to create payment link',
    });
  }
});

// Process a refund
router.post('/charges/:charge_id/refund', async (req, res) => {
  try {
    const { charge_id } = req.params;
    const { amount, reason } = req.body;

    const response = await api.post(`/charges/${charge_id}/refunds`, {
      amount,  // Optional: partial refund (in cents). Omit for full refund
      reason,  // e.g., 'duplicate', 'fraudulent', 'requested_by_customer'
    });

    res.json({ success: true, refund: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to process refund',
    });
  }
});

// Get charge details
router.get('/charges/:charge_id', async (req, res) => {
  try {
    const { charge_id } = req.params;
    const response = await api.get(`/charges/${charge_id}`);
    res.json({ success: true, charge: response.data });
  } catch (error) {
    res.status(error.response?.status || 500).json({
      success: false,
      error: error.response?.data || 'Failed to get charge',
    });
  }
});

module.exports = router;

Etapa 6: lidar com webhooks

Webhooks notificam seu servidor sobre eventos de pagamento (cobranças bem-sucedidas, falhas de pagamento, reembolsos, etc.).

Adicione ao server.js:

CODE_BLOCO_5

Etapa 7: teste sua integração

Inicie o servidor:

node server.js

Teste com ondulação:

# Create a customer
curl -X POST http://localhost:3000/api/payments/customers \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "name": "John Doe"}'

# Create a charge
curl -X POST http://localhost:3000/api/payments/charges \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "currency": "USD", "customer_id": "cus_xxx", "description": "Test charge"}'

# Generate a payment link
curl -X POST http://localhost:3000/api/payments/payment-links \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "currency": "USD", "description": "Premium Plan", "success_url": "https://yoursite.com/success", "cancel_url": "https://yoursite.com/cancel"}'

Cartões de teste

Use estes cartões de teste no modo sandbox:

Número do cartão Resultado
4242 4242 4242 4242 Pagamento bem sucedido
4000 0000 0000 9995 Recusado (fundos insuficientes)
4000 0000 0000 0002 Requer autenticação 3D Secure
4000 0000 0000 0010 Requer verificação CVC

Melhores práticas

Segurança

  • Nunca exponha sua chave secreta no código do lado do cliente
  • Use variáveis de ambiente para todas as credenciais
  • Verifique as assinaturas do webhook para evitar eventos falsificados
  • Implementar chaves de idempotência para criação de cobrança para evitar duplicatas

Tratamento de erros

  • Sempre verifique error.response?.data para mensagens de erro detalhadas
  • Implementar lógica de repetição para falhas transitórias
  • Registrar todos os eventos de pagamento para auditoria
  • Lidar com redirecionamentos 3D Secure normalmente

Conformidade

  • 4Geeks Payments é compatível com PCI DSS – os dados do cartão nunca chegam aos seus servidores
  • A conformidade fiscal é tratada automaticamente (IVA, imposto sobre vendas, GST)
  • Como Merchant of Record, a 4Geeks lida com a responsabilidade de estorno

O que vem a seguir?

Precisa de ajuda?

Ainda tem dúvidas? Pergunte na Discord or explore tutoriais