Como Usar a API iPay para Integração de Pagamentos em 2026?

Resumo

A API iPay permite que desenvolvedores integrem processamento de pagamentos, faturamento e transações financeiras de forma programática. Ela utiliza autenticação OAuth 2.0 e chave de API, endpoints RESTful para pagamentos, reembolsos, transações e conciliação, com requisitos de conformidade PCI DSS e limites de taxa padrão da indústria. Este guia abrange a configuração de autenticação, processamento de pagamentos, integração de webhooks, conformidade de segurança e estratégias de implantação em produção.

Introdução

O processamento de pagamentos digitais movimenta mais de US$ 8 trilhões anualmente em todo o mundo. Para desenvolvedores que constroem plataformas de e-commerce, aplicativos SaaS ou soluções de marketplace, a integração de API de pagamento não é opcional – é essencial para aceitar pagamentos de clientes de forma segura e em conformidade.

A realidade é esta: empresas perdem de 5 a 10% da receita devido a pagamentos falhos, conciliação manual e fraudes de pagamento. Uma integração de API de pagamento robusta automatiza o processamento de pagamentos, reduz falhas com lógica de nova tentativa inteligente, permite conciliação automática e implementa detecção de fraude.

Este guia detalha todo o processo de integração da API de pagamento. Você aprenderá sobre configuração de autenticação, processamento de pagamentos, gerenciamento de reembolsos, tratamento de webhooks, conformidade PCI DSS, melhores práticas de segurança e estratégias de implantação em produção. Ao final, você terá uma integração de pagamento pronta para produção.

Nota: Este guia aborda padrões gerais de integração de API de pagamento aplicáveis ao iPay e processadores de pagamento semelhantes. URLs de endpoint específicas e detalhes de autenticação podem variar — sempre consulte a documentação oficial do iPay para detalhes de implementação.

O Que É a API iPay?

APIs de pagamento como a iPay fornecem interfaces RESTful para processamento de transações financeiras. A API gerencia:

• Autorização e captura de pagamento
• Reembolsos e estornos
• Histórico de transações e relatórios
• Tokenização de cliente (cofre)
• Assinatura e faturamento recorrente
• Geração e gerenciamento de faturas
• Conciliação e liquidação
• Detecção e prevenção de fraude

Principais Recursos

Visão Geral do Fluxo de Pagamento

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Cliente   │───▶│  Comerciante│───▶│  Gateway de │
│  (Navegador)│    │   (Servidor)│    │   Pagamento │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Inserir Cartão │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenizar      │                    │
     │───────────────────▶│  3. Criar Intenção │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Confirmar Pgto.│
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Resultado      │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Recibo         │                    │
     │◀───────────────────│                    │

Ambiente da API

Primeiros Passos: Configuração de Autenticação

Passo 1: Criar Conta iPay

Antes de acessar a API:

1. Visite o registro de comerciante iPay
2. Conclua a verificação de negócios (KYB)
3. Envie os documentos necessários:

• Registro comercial
• Detalhes da conta bancária
• Documento de identidade governamental

1. Aguarde aprovação (1-3 dias úteis)

Passo 2: Obter Credenciais da API

Gere credenciais da API:

1. Faça login no Painel do Comerciante iPay
2. Navegue para Configurações > Chaves de API
3. Crie nova chave de API
4. Copie as credenciais com segurança

# .env file (NUNCA faça commit para o git)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

Nota de segurança: Use chaves separadas para sandbox e produção.

Passo 3: Entender os Métodos de Autenticação

O iPay suporta múltiplos métodos de autenticação:

Passo 4: Fazer Chamadas de API Autenticadas

Crie um cliente de API reutilizável:

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Basic authentication (Base64 encoded)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Error: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Uso
const account = await ipayRequest('/account');
console.log(`Comerciante: ${account.business_name}`);

Processamento de Pagamento

Criando uma Intenção de Pagamento

Inicializar pagamento:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // Na menor unidade monetária (centavos)
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'automatic' ou 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MINHAEMPRESA'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Uso
const payment = await createPayment({
  amount: 2999, // R$ 29,99
  currency: 'BRL', // Ajustado para BRL para o exemplo
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Pedido #PED-001',
  orderId: 'PED-001',
  statementDescriptor: 'MINHAEMPRESA S.A.'
});

console.log(`Status do pagamento: ${payment.status}`);
console.log(`ID do pagamento: ${payment.id}`);

Fluxo de Status de Pagamento

requer_metodo_pagamento → requer_confirmacao → requer_acao
                         → processando → requer_captura → bem_sucedido
                                                        → falhou
                                                        → cancelado

Métodos de Pagamento

Tokenizando Detalhes do Cartão

Armazene o cartão com segurança para uso futuro:

const tokenizeCard = async (cardData) => {
  // NUNCA envie dados brutos do cartão para o seu servidor
  // Em vez disso, use a tokenização no lado do cliente

  // Lado do cliente (navegador/mobile)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // Envie token.id para o seu servidor
};

// Lado do servidor: Use o token para criar um método de pagamento
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

Autenticação 3D Secure

Implemente conformidade SCA:

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // Retorna o segredo do cliente para 3DS
  });

  if (payment.status === 'requires_action') {
    // O cliente deve completar o desafio 3DS
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Lado do cliente: Lidar com o desafio 3DS
// Use iPay.js ou SDK móvel para apresentar o desafio de autenticação

Gerenciamento de Reembolsos

Processando Reembolso Total

Reembolsar o pagamento inteiro:

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Uso
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Status do reembolso: ${refund.status}`);
console.log(`ID do reembolso: ${refund.id}`);

Processando Reembolso Parcial

Reembolsar parte do pagamento:

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // Na menor unidade monetária
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Uso - Reembolsar R$ 15,00 de um pagamento de R$ 29,99
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Reembolsado: R$${refund.amount / 100}`);

Motivos de Reembolso

Gerenciamento de Clientes

Criando um Cliente

Armazene o cliente para pagamentos recorrentes:

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Uso
const customer = await createCustomer({
  email: 'cliente@example.com',
  name: 'João da Silva',
  phone: '+55-11-98765-4321',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Cliente criado: ${customer.id}`);

Anexando Método de Pagamento ao Cliente

Salve o cartão para uso futuro:

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Uso
await attachPaymentMethod('pm_67890', 'cus_12345');

Listando Métodos de Pagamento do Cliente

Obter cartões salvos:

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Uso
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} terminando em ${method.card.last4}`);
  console.log(`Vence: ${method.card.exp_month}/${method.card.exp_year}`);
});

Webhooks

Configurando Webhooks

Configure endpoints de webhook:

1. Faça login no Painel iPay
2. Navegue para Desenvolvedores > Webhooks
3. Clique em Adicionar Endpoint
4. Insira sua URL HTTPS
5. Selecione os eventos para assinar

Eventos de Webhook

Lidando com Webhooks

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Verificar assinatura do webhook
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Assinatura de webhook inválida');
    return res.status(401).send('Não Autorizado');
  }

  const event = JSON.parse(payload.toString());

  // Direcionar para o manipulador apropriado
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('Tipo de evento não tratado:', event.type);
  }

  // Confirmar recebimento
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Pagamento bem-sucedido: ${data.id}`);

  // Atualizar status do pedido
  await db.orders.update(data.metadata.orderId, {
    status: 'pago',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Enviar e-mail de confirmação
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Pagamento falhou: ${data.id} - ${data.failure_code}`);

  // Notificar cliente
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Lógica de nova tentativa ou marcar pedido como falho
  await db.orders.update(data.metadata.orderId, {
    status: 'pagamento_falhou',
    failureReason: data.failure_message
  });
}

Segurança e Conformidade

Requisitos PCI DSS

Integrações de pagamento devem estar em conformidade com PCI DSS:

Melhores Práticas de Segurança

// 1. Use tokenização - NUNCA manipule dados brutos do cartão
const token = await tokenizeCard(cardData); // Lado do cliente

// 2. Implemente idempotência para todas as operações de pagamento
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Valide os valores no lado do servidor
if (req.body.amount !== calculatedAmount) {
  throw new Error('Incompatibilidade de valor - possível adulteração');
}

// 4. Registre todas as operações de pagamento (sem dados sensíveis)
logger.info('Tentativa de pagamento', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // NUNCA registre: números de cartão, CVV, detalhes completos do método de pagamento
});

// 5. Use variáveis de ambiente para segredos
const apiKey = process.env.IPAY_API_KEY; // Não codificado diretamente

// 6. Implemente limite de taxa (rate limiting) nos endpoints de pagamento
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 tentativas de pagamento por minuto
});

Checklist de Implantação em Produção

Antes de processar pagamentos ao vivo:

• [ ] Preencher o Questionário de Autoavaliação PCI DSS
• [ ] Usar HTTPS para todos os endpoints
• [ ] Armazenar chaves de API em gerenciamento seguro de segredos
• [ ] Implementar verificação de assinatura de webhook
• [ ] Adicionar idempotência para todas as operações de pagamento
• [ ] Configurar registro abrangente (sem dados sensíveis)
• [ ] Configurar regras de detecção de fraude
• [ ] Testar fluxos de reembolso e disputa
• [ ] Criar runbook para falhas de pagamento
• [ ] Configurar monitoramento e alertas
• [ ] Implementar processador de pagamento de backup

Casos de Uso no Mundo Real

Checkout de E-commerce

Um varejista online integra pagamentos:

• Desafio: Processamento manual de pagamentos, alta taxa de abandono
• Solução: Checkout em uma página com cartões tokenizados
• Resultado: Aumento de 35% na conversão, pagamentos instantâneos

Faturamento de Assinatura SaaS

Uma empresa de software automatiza o faturamento:

• Desafio: Geração e cobrança manual de faturas
• Solução: Pagamentos recorrentes com nova tentativa automática
• Resultado: 95% de pagamentos em dia, 80% de economia de tempo administrativo

Escrow de Marketplace

Uma plataforma gerencia pagamentos de múltiplas partes:

• Desafio: Pagamentos divididos complexos entre fornecedores
• Solução: Intenções de pagamento com agendamento de transferências
• Resultado: Pagamentos automatizados a fornecedores, fraude reduzida

Conclusão

A integração da API de pagamento exige atenção cuidadosa à segurança, conformidade e tratamento de erros. Principais pontos:

• Nunca manipule dados brutos de cartão — use tokenização
• Implemente idempotência para todas as operações de pagamento
• Verifique as assinaturas de webhook para prevenir fraudes
• Cumpra os requisitos PCI DSS
• Teste exaustivamente em sandbox antes da produção
• O Apidog otimiza os testes de API e a colaboração em equipe

Seção de Perguntas Frequentes

Como me autentico com a API iPay?

Use autenticação Básica com chave e segredo de API, ou OAuth 2.0 para aplicações multi-inquilino.

Posso armazenar detalhes de cartão de cliente?

Sim, mas você deve ser compatível com PCI DSS. Use tokenização para armazenar cartões de forma segura no cofre do iPay.

Como lido com pagamentos falhos?

Implemente lógica de nova tentativa com backoff exponencial, notifique os clientes e forneça métodos de pagamento alternativos.

O que é idempotência e por que é importante?

Idempotência garante que requisições duplicadas com a mesma chave produzam o mesmo resultado, prevenindo cobranças duplicadas.

Como testo pagamentos sem cobrar cartões?

Use o modo sandbox com números de cartão de teste fornecidos na documentação do iPay.

O que são assinaturas de webhook?

Assinaturas criptográficas que verificam se os webhooks vieram do iPay, e não de um ator mal-intencionado.