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.

Experimente o Apidog hoje

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.

💡O Apidog simplifica os testes de API de pagamento. Teste endpoints de pagamento em modo sandbox, valide assinaturas de webhook, inspecione respostas de transações e depure problemas de integração em um único espaço de trabalho. Importe especificações de API, simule respostas e compartilhe cenários de teste com sua equipe.

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

Recurso	Descrição
API RESTful	Endpoints baseados em JSON
OAuth 2.0 + Chaves de API	Autenticação segura
Webhooks	Notificações de pagamento em tempo real
Tokenização	Armazenamento seguro de cartão
3D Secure	Conformidade com SCA
PCI DSS	Conformidade Nível 1 exigida
Multi-Moeda	Mais de 100 moedas suportadas
Ferramentas Anti-Fraude	Pontuação de risco, verificações de velocidade

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

Ambiente	URL	Caso de Uso
Sandbox	https://sandbox.ipay.com/api	Desenvolvimento, testes
Produção	https://api.ipay.com/api	Transações ao vivo

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

Passo 1: Criar Conta iPay

1. Acesse 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
4. Aguarde aprovação (1-3 dias úteis).

Passo 2: Obter Credenciais da API

1. Faça login no Painel do Comerciante iPay.
2. Vá em Configurações > Chaves de API.
3. Crie nova chave de API.
4. Copie as credenciais e armazene em local seguro.

# .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 diferentes para sandbox e produção.

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

Método	Melhor Para	Nível de Segurança
Autenticação Básica	Servidor para servidor	Alto
OAuth 2.0	Aplicativos multi-inquilino	Mais Alto
JWT	Microsserviços	Alto

Passo 4: Fazer Chamadas de API Autenticadas

Implemente 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

Inicialize o pagamento com este exemplo:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // 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',
    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',
  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

Método	Tipo	Caso de Uso
cartão	Crédito/Débito	Pagamentos padrão
transferência_bancária	ACH, SEPA	Transferências com taxas baixas
carteira_digital	Apple Pay, Google Pay	Checkout móvel
compre_agora_pague_depois	Klarna, Afterpay	Pagamentos parcelados

Tokenizando Detalhes do Cartão

Armazene cartões de forma segura:

const tokenizeCard = async (cardData) => {
  // 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 o fluxo 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: Use o SDK para apresentar o desafio 3DS

Gerenciamento de Reembolsos

Processando Reembolso Total

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

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // Centavos
    reason: reason || 'requested_by_customer'
  };

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

  return response;
};

// Exemplo: 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

Código do Motivo	Descrição
duplicado	Cobrança duplicada
fraudulento	Transação fraudulenta
solicitado_pelo_cliente	Solicitação do cliente
pedido_cancelado	Cancelamento do pedido
produto_nao_recebido	Item não entregue
produto_nao_conforme_descricao	Item diferente da descrição

Gerenciamento de Clientes

Criando um Cliente

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: '[e-mail]',
  name: 'João da Silva',
  phone: '[phone]',
  internalId: 'USR-12345',
  tier: 'premium'
});

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

Anexando Método de Pagamento ao Cliente

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

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

1. Faça login no Painel iPay.
2. Acesse Desenvolvedores > Webhooks.
3. Clique em Adicionar Endpoint.
4. Informe sua URL HTTPS.
5. Selecione os eventos desejados.

Eventos de Webhook

Evento	Gatilho
pagamento.bem_sucedido	Pagamento concluído
pagamento.falhou	Pagamento recusado
pagamento.reembolsado	Reembolso processado
pagamento.disputado	Estorno registrado
cliente.criado	Novo cliente
cliente.assinatura.atualizada	Assinatura alterada

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());

  // Direcione para o handler correto
  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);
  }

  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);

  // 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

Integre de acordo com PCI DSS:

Requisito	Implementação
Rede Segura	Use HTTPS, firewalls, configurações seguras
Proteção de Dados do Titular do Cartão	Nunca armazene CVV, criptografe PAN
Gerenciamento de Vulnerabilidades	Atualizações de segurança regulares, antivírus
Controle de Acesso	Menor privilégio, MFA, IDs únicas
Monitoramento	Registro (logging), detecção de intrusões
Política de Segurança	Políticas documentadas, treinamento regular

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

• 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

• 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

• 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.