API 2Checkout: Guia Completo de Integração para Processamento de Pagamentos (2026)

TL;DR

A API do 2Checkout (agora Verifone) permite processar pagamentos, gerenciar assinaturas e administrar transações de e-commerce via endpoints RESTful, usando autenticação baseada em chaves de API. Este guia mostra desde a configuração inicial até o gerenciamento avançado de webhooks, com exemplos práticos.

Experimente o Apidog hoje

💡 O Apidog simplifica o teste de integração de APIs. Teste seus endpoints do 2Checkout, valide payloads de webhook e debuge problemas de autenticação em um único workspace. Importe a especificação OpenAPI do 2Checkout, simule respostas e compartilhe cenários de teste com sua equipe.

O Que É a API do 2Checkout?

2Checkout (agora Verifone Digital Commerce) fornece uma API RESTful robusta para:

• Pagamentos únicos e recorrentes
• Gerenciamento de clientes e produtos
• Rastreamento de pedidos e reembolsos
• Conformidade fiscal e automatizada
• Mais de 100 moedas suportadas

Principais Recursos

Recurso	Descrição
Design RESTful	HTTP (GET, POST, PUT, DELETE) e payloads JSON
Ambiente Sandbox	Teste de pagamentos sem afetar dados reais
Suporte a Webhooks	Notificações em tempo real para eventos
Tokenização	Dados de pagamento seguros sem armazenar cartões
Conformidade Global	PCI DSS Nível 1, GDPR, PSD2, 3D Secure 2.0

Visão Geral da Arquitetura

A API segue versões:

https://api.2checkout.com/1/
https://api.2checkout.com/2/

Use a versão 2 para recursos modernos de assinaturas e webhooks.

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

Passo 1: Crie Sua Conta 2Checkout

1. Registre-se no portal do 2Checkout (Verifone)
2. Envie documentos para verificação comercial
3. Aguarde a aprovação (24-48h)
4. Acesse o painel e gere as credenciais da API

Passo 2: Obtenha as Chaves da API

No painel, em Integrações > Chaves da API:

• Chave Privada: Para autenticação server-side (NUNCA exponha)
• Chave Pública: Para tokenização client-side
• Segredo do Webhook: Para validar assinaturas de webhooks

Dica de segurança: Use variáveis de ambiente, nunca faça commit das chaves.

# .env
TWOCHECKOUT_PRIVATE_KEY="sua_chave_privada"
TWOCHECKOUT_PUBLIC_KEY="sua_chave_publica"
TWOCHECKOUT_WEBHOOK_SECRET="seu_segredo_webhook"

Passo 3: Sandbox vs Produção

Ambiente	URL Base	Uso
Sandbox	https://sandbox.2checkout.com/api/	Testes/desenvolvimento
Produção	https://api.2checkout.com/	Processamento real

Sempre use as credenciais e URLs correspondentes ao ambiente.

Passo 4: Métodos de Autenticação

Método 1: Chave de API (Recomendado)

Adicione o header na requisição:

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Método 2: Assinatura HMAC

Para maior segurança:

const crypto = require('crypto');

function generateSignature(payload, privateKey) {
  return crypto
    .createHmac('sha256', privateKey)
    .update(JSON.stringify(payload))
    .digest('hex');
}

const payload = { order_id: '12345', amount: 99.99 };
const signature = generateSignature(payload, privateKey);

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Processando Pagamentos: Endpoints Principais

Criando um Pedido Único

const createOrder = async (customerData, productData) => {
  const payload = {
    currency: 'USD',
    customer: {
      email: customerData.email,
      first_name: customerData.firstName,
      last_name: customerData.lastName,
      phone: customerData.phone,
      billing_address: {
        address1: customerData.address,
        city: customerData.city,
        state: customerData.state,
        zip: customerData.zip,
        country: customerData.country
      }
    },
    items: [
      {
        name: productData.name,
        quantity: productData.quantity,
        price: productData.price,
        product_code: productData.sku
      }
    ],
    payment_method: {
      type: 'card',
      card_token: customerData.cardToken
    }
  };

  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Resposta Esperada

{
  "order_id": "ORD-2026-001234",
  "status": "approved",
  "amount": 99.99,
  "currency": "USD",
  "customer_id": "CUST-789456",
  "transaction_id": "TXN-9876543210",
  "created_at": "2026-03-20T10:30:00Z"
}

Tratando Erros de Pagamento

Sempre trate os principais casos de erro:

try {
  const result = await createOrder(customer, product);

  if (result.error) {
    switch (result.error.code) {
      case 'CARD_DECLINED':
        // Solicite outro cartão
        break;
      case 'INSUFFICIENT_FUNDS':
        // Informe o usuário
        break;
      case 'INVALID_CVV':
        // Peça novo CVV
        break;
      default:
        console.error('Pagamento falhou:', result.error);
    }
  }
} catch (error) {
  console.error('Falha na API:', error);
}

Códigos de Erro Comuns

Código	HTTP	Descrição	Resolução
CARD_DECLINED	402	Cartão recusado	Solicitar novo método
INVALID_CARD	400	Número inválido	Validar entrada
EXPIRED_CARD	400	Cartão expirado	Solicitar validade atualizada
INVALID_CVV	400	CVV inválido	Solicitar novamente
INSUFFICIENT_FUNDS	402	Fundos insuficientes	Sugerir alternativo
DUPLICATE_ORDER	409	Pedido duplicado	Verificar duplicatas
INVALID_CURRENCY	400	Moeda não suportada	Checar código
API_KEY_INVALID	401	Autenticação falhou	Revise chave de API

Gerenciamento de Clientes

Criando um Cliente

const createCustomer = async (customerData) => {
  const payload = {
    email: customerData.email,
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    phone: customerData.phone,
    company: customerData.company,
    billing_address: {
      address1: customerData.address,
      address2: customerData.address2 || '',
      city: customerData.city,
      state: customerData.state,
      zip: customerData.zip,
      country: customerData.country
    },
    shipping_address: customerData.shippingAddress || null,
    tax_exempt: false,
    language: 'pt'
  };

  const response = await fetch('https://api.2checkout.com/1/customers', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Resposta

{
  "customer_id": "CUST-2026-123456",
  "email": "[e-mail]",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z",
  "payment_methods": [],
  "subscriptions": [],
  "order_history": []
}

Recuperando, Atualizando e Excluindo Clientes

const getCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'GET',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return await response.json();
};

const updateCustomer = async (customerId, updates) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );
  return await response.json();
};

const deleteCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'DELETE',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY
      }
    }
  );
  return response.status === 204;
};

Nota: Exclua assinaturas antes de remover clientes com cobranças ativas.

Padrões de Integração Avançados

Idempotência

Evite cobranças duplicadas usando um header exclusivo:

const idempotencyKey = `order_${userId}_${Date.now()}`;
const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'Content-Type': 'application/json',
    'X-Idempotency-Key': idempotencyKey
  },
  body: JSON.stringify(payload)
});

3D Secure 2.0 (UE)

const createOrderWith3DS = async (payload) => {
  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...payload,
      three_ds: {
        enabled: true,
        challenge_required: 'preferred',
        notification_url: 'https://your-site.com/3ds-callback'
      }
    })
  });

  const result = await response.json();

  if (result.three_ds_redirect_url) {
    res.redirect(result.three_ds_redirect_url);
  }

  return result;
};

Preço em Múltiplas Moedas

const getLocalizedPrice = async (basePrice, targetCurrency) => {
  const response = await fetch(
    `https://api.2checkout.com/1/rates?from=USD&to=${targetCurrency}`,
    {
      headers: { 'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY }
    }
  );
  const rates = await response.json();
  return basePrice * rates.rate;
};

const eurPrice = await getLocalizedPrice(99.99, 'EUR');
console.log(`Preço: EUR ${eurPrice.toFixed(2)}`);

Prorrogação de Upgrade de Assinatura

const upgradeSubscription = async (subscriptionId, newPlanId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/upgrade`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        plan_id: newPlanId,
        proration: 'immediate',
        invoice_proration: true
      })
    }
  );
  return await response.json();
};

Solução de Problemas Comuns

Webhooks não chegam

Diagnóstico:

// Verifique logs de entrega de webhook no painel
// Busque respostas ≠ 200

Soluções:

1. Endpoint deve retornar 200 OK em até 5s
2. Certifique-se que o endpoint é HTTPS
3. Libere os IPs do 2Checkout no firewall
4. Revisar verificação de assinatura
5. Teste com simulador de webhook

Pagamentos de Teste não funcionam no Sandbox

1. Confirme uso de chaves sandbox
2. Use https://sandbox.2checkout.com/api/
3. Use cartões de teste corretos
4. Verifique se a conta sandbox está ativa

Renovações de Assinatura falham silenciosamente

Diagnóstico:

const history = await fetch(
  `https://api.2checkout.com/1/subscriptions/${subId}/payments`,
  { headers: { 'X-Api-Key': privateKey } }
);

Soluções:

• Revise validade do cartão
• Verifique configurações de dunning
• Confirme recebimento do webhook subscription.payment_failed
• Certifique auto_renew habilitado

Discrepâncias de Conversão de Moeda

• Mostre conversão “aproximada” com aviso
• Trave taxa na criação do carrinho (expira em 15min)
• Armazene transações na moeda local

Falhas no AVS (Endereço)

• Use preenchimento automático de endereço
• Torne CEP obrigatório
• Implemente AVS suave
• Permita atualização do endereço

Gerenciamento de Assinaturas

Criando uma Assinatura

const createSubscription = async (customerId, planId) => {
  const payload = {
    customer_id: customerId,
    plan_id: planId,
    start_date: new Date().toISOString(),
    billing_cycle: 'monthly',
    payment_method: {
      type: 'card',
      card_token: 'tok_card_tokenized'
    },
    options: {
      trial_days: 14,
      auto_renew: true
    }
  };

  const response = await fetch('https://api.2checkout.com/1/subscriptions', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Resposta

{
  "subscription_id": "SUB-2026-567890",
  "status": "active",
  "plan_id": "PLAN-PREMIUM-MONTHLY",
  "customer_id": "CUST-789456",
  "current_period_start": "2026-03-20T00:00:00Z",
  "current_period_end": "2026-04-20T00:00:00Z",
  "trial_end": "2026-04-03T00:00:00Z",
  "amount": 29.99,
  "currency": "USD"
}

Atualizando e Cancelando Assinatura

const updateSubscription = async (subscriptionId, updates) => {
  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );
  return await response.json();
};

const cancelSubscription = async (subscriptionId, reason = '') => {
  const payload = {
    cancel_at_period_end: false,
    reason: reason
  };

  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/cancel`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );
  return await response.json();
};

---

Integração de Webhook: Eventos em Tempo Real

Webhooks atualizam seu sistema sobre pagamentos, renovações, falhas e reembolsos.

Passo 1: Configure o Endpoint

No painel:

1. Integrações > Webhooks
2. Cadastre a URL HTTPS do seu endpoint
3. Selecione eventos desejados
4. Salve e anote o segredo do webhook

Passo 2: Manipulador de Webhook (Node.js)

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

app.post('/webhooks/2checkout', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;
  const isValid = verifyWebhookSignature(payload, signature, process.env.TWOCHECKOUT_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Webhook inválido');
    return res.status(401).send('Não autorizado');
  }

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

  switch (event.type) {
    case 'order.created':
      await handleOrderCreated(event.data);
      break;
    case 'order.approved':
      await handleOrderApproved(event.data);
      break;
    case 'order.declined':
      await handleOrderDeclined(event.data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(event.data);
      break;
    case 'subscription.renewed':
      await handleSubscriptionRenewed(event.data);
      break;
    case 'subscription.cancelled':
      await handleSubscriptionCancelled(event.data);
      break;
    case 'refund.processed':
      await handleRefundProcessed(event.data);
      break;
    default:
      console.log('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')
  );
}

Eventos Críticos

Evento	Gatilho	Ação
order.created	Novo pedido	Enviar e-mail de confirmação
order.approved	Pagamento aprovado	Liberar acesso/processar pedido
order.declined	Pagamento recusado	Notificar cliente/retentativa
subscription.renewed	Renovação	Estender acesso
subscription.payment_failed	Falha em renovação	Dunning/retentativa
subscription.cancelled	Assinatura cancelada	Revogar acesso
refund.processed	Reembolso	Atualizar saldo
chargeback.received	Estorno/disputa registrada	Coletar evidências

Melhores Práticas

1. Valide sempre assinaturas
2. Responda 200 OK rapidamente
3. Enfileire eventos para processamento assíncrono
4. Garanta idempotência
5. Registre todos os eventos

Testando Sua Integração

Usando o Sandbox

const BASE_URL = 'https://sandbox.2checkout.com/api/1';

const TEST_CARDS = {
  APPROVED: '4111111111111111',
  DECLINED: '4000000000000002',
  INSUFFICIENT_FUNDS: '4000000000009995',
  EXPIRED_CARD: '4000000000000069'
};

const TEST_ADDRESS = {
  country: 'US',
  zip: '90210'
};

Testando Webhooks Localmente

npm install -g ngrok

node server.js
ngrok http 3000
# Use a URL do ngrok no painel 2Checkout

Apidog para Testes de API

1. Importe a especificação OpenAPI do 2Checkout
2. Crie coleções de testes para cada endpoint
3. Simule respostas e valide webhooks
4. Compartilhe cenários com a equipe
5. Use variáveis de ambiente para alternar entre sandbox e produção

Checklist de Implantação em Produção

• [ ] Trocar chaves sandbox por produção
• [ ] Atualizar URL base para produção
• [ ] Habilitar verificação de assinatura HMAC para webhooks
• [ ] Monitorar falhas de pagamento
• [ ] Implementar lógica de retentativa em falhas transitórias
• [ ] Testar fluxos de reembolso/estorno
• [ ] Garantir uso de tokenização PCI DSS
• [ ] Habilitar 3D Secure 2.0 para UE
• [ ] Ativar logging para auditoria
• [ ] Criar runbook para incidentes

Monitoramento e Alertas

// Taxa de sucesso de pagamento
const successRate = approvedOrders / totalOrders * 100;

if (successRate < 95) {
  sendAlert('Taxa de sucesso abaixo de 95%');
}

// Breakdown de erros
const errorBreakdown = errors.reduce((acc, err) => {
  acc[err.code] = (acc[err.code] || 0) + 1;
  return acc;
}, {});

if (errorBreakdown['CARD_DECLINED'] > threshold) {
  sendAlert('Pico de recusas de cartão');
}

Casos de Uso no Mundo Real

Loja E-commerce

• Suporte automático a 100+ moedas
• Abandono de carrinho reduzido em 23%
• Conformidade fiscal automatizada (IVA UE)
• US$ 2 milhões processados no 1º ano
• Inicialmente com checkout hospedado, migrando depois para API direta

SaaS de Assinatura

• 5.000+ assinaturas ativas
• Prorrogação automática e upgrades
• Automação de cobrança para falhas
• Rotatividade reduzida em 15% com retentativas inteligentes
• Controle de acesso via webhooks: estenda/revogue ao receber eventos

Conclusão

A API do 2Checkout cobre tudo para pagamentos programáticos e assinaturas:

• Use sempre sandbox para testar
• Implemente verificação HMAC em webhooks
• Trate erros com códigos específicos
• Teste todos os fluxos de assinatura
• Monitore métricas de pagamento em produção
• Use Apidog para acelerar e padronizar os testes

Seção de Perguntas Frequentes

O que é a API do 2Checkout?

API RESTful para pagamentos, assinaturas, reembolsos e automação de e-commerce. Suporta JSON, autenticação HMAC e webhooks.

2Checkout é o mesmo que Verifone?

Sim. 2Checkout agora é Verifone Digital Commerce. Endpoints e APIs permanecem iguais.

Como obtenho minha chave de API?

No painel 2Checkout: Integrações > Chaves de API. Você terá chave privada (servidor) e pública (tokenização).

O 2Checkout tem ambiente sandbox?

Sim. Use https://sandbox.2checkout.com/api/. Crie conta sandbox e obtenha chaves de teste separadas.

Quais métodos de pagamento são suportados?

Cartões (Visa, Mastercard, Amex, Discover), PayPal, Apple Pay, Google Pay, transferências bancárias e métodos locais em 100+ países.

Como gerencio webhooks com segurança?

Verifique sempre o header X-Webhook-Signature via HMAC-SHA256. Processe eventos assíncronos e retorne 200 OK rapidamente.

O que acontece se um pagamento de assinatura falhar?

Receba webhook subscription.payment_failed. Implemente retentativas (ex: 3 em 7 dias). Em falha total, webhook subscription.cancelled.

O 2Checkout é PCI DSS?

Sim, certificado PCI DSS Nível 1. Use tokenização client-side para evitar manipular dados brutos de cartão.

Posso testar assinaturas no sandbox?

Sim. Teste todo ciclo de assinatura, upgrades/downgrades, cancelamento. Use cartão 4111111111111111 para sucesso.

Como faço reembolso via API?

POST em /refunds com ID do pedido e valor. O 2Checkout processa e envia webhook refund.processed ao concluir.