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

TL;DR

A API do 2Checkout (agora Verifone) permite que desenvolvedores processem pagamentos, gerenciem assinaturas e lidem com transações de e-commerce de forma programática. Ela suporta endpoints RESTful para pedidos, clientes, produtos e webhooks com autenticação baseada em JSON usando chaves de API. Este guia abrange desde a configuração inicial até o gerenciamento avançado de webhooks.

Introdução

O processamento de pagamentos é a espinha dorsal de qualquer negócio online. Erre, e você perde receita. Acerte, e você desbloqueia mercados globais. A API do 2Checkout (recentemente renomeada para Verifone) gerencia pagamentos para mais de 45.000 comerciantes em todo o mundo, processando bilhões em transações anualmente.

Aqui está a realidade: 67% dos compradores abandonam carrinhos devido à fricção no pagamento. Uma integração robusta da API de pagamento impacta diretamente seu resultado final.

Este guia detalha o processo completo de integração da API do 2Checkout. Você aprenderá sobre autenticação, processamento de pagamentos, gerenciamento de assinaturas, tratamento de webhooks e solução de problemas de erros. Ao final, você terá uma integração de pagamento pronta para produção.

O Que É a API do 2Checkout?

2Checkout (agora operando como Verifone Digital Commerce) oferece uma API RESTful para processamento de pagamentos e gerenciamento de assinaturas. A API gerencia:

• Pagamentos únicos e recorrentes
• Gerenciamento de clientes e produtos
• Rastreamento do ciclo de vida do pedido
• Gerenciamento de reembolsos e disputas
• Automação de impostos e conformidade
• Suporte a múltiplas moedas (mais de 100 moedas)

Principais Recursos

Visão Geral da Arquitetura da API

O 2Checkout usa uma estrutura de API REST versionada:

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

A Versão 2 é a versão recomendada atualmente, com gerenciamento de assinaturas e tratamento de webhooks aprimorados.

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

Passo 1: Crie Sua Conta 2Checkout

Antes de acessar a API, você precisa de uma conta de comerciante:

1. Visite a página de cadastro do 2Checkout (Verifone)
2. Conclua a verificação comercial (requer documentos da empresa)
3. Aguarde a aprovação (normalmente 24-48 horas)
4. Acesse seu Painel de Controle para obter as credenciais da API

Passo 2: Obtenha as Chaves da API

Navegue até Integrações > Chaves da API no seu Painel de Controle:

• Chave de API Privada: Usada para autenticação no lado do servidor (mantenha-a secreta)
• Chave de API Pública: Usada para tokenização no lado do cliente (segura para expor)
• Segredo do Webhook: Usado para verificar assinaturas de webhook

Nota de segurança: Nunca faça commit de chaves de API para controle de versão. Use variáveis de ambiente:

# .env file
TWOCHECKOUT_PRIVATE_KEY="sua_chave_privada_aqui"
TWOCHECKOUT_PUBLIC_KEY="sua_chave_publica_aqui"
TWOCHECKOUT_WEBHOOK_SECRET="seu_segredo_webhook_aqui"

Passo 3: Sandbox vs Produção

O 2Checkout oferece ambientes separados:

Use credenciais sandbox durante o desenvolvimento. Mude para chaves de produção apenas quando estiver pronto para processar pagamentos reais.

Passo 4: Métodos de Autenticação

O 2Checkout suporta duas abordagens de autenticação:

Método 1: Autenticação por Chave de API (Recomendado)

Inclua sua chave privada no cabeçalho da 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: Autenticação por Assinatura HMAC

Para segurança aprimorada, assine as requisições com HMAC-SHA256:

const crypto = require('crypto');

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

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

Processe um único pagamento com o endpoint /orders:

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 // Da tokenização no lado do cliente
    }
  };

  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 implemente um tratamento de erros adequado:

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

  if (result.error) {
    // Tratar códigos de erro específicos
    switch (result.error.code) {
      case 'CARD_DECLINED':
        // Solicitar outro cartão ao cliente
        break;
      case 'INSUFFICIENT_FUNDS':
        // Mostrar mensagem apropriada
        break;
      case 'INVALID_CVV':
        // Solicitar nova entrada do CVV
        break;
      default:
        // Registrar e mostrar erro genérico
        console.error('Pagamento falhou:', result.error);
    }
  }
} catch (error) {
  // Erro de rede ou servidor
  console.error('Falha na requisição da API:', error);
}

Códigos de Erro Comuns

Gerenciamento de Clientes

Gerenciar dados de clientes é essencial para negócios de assinatura e compras repetidas. O 2Checkout oferece uma API completa para 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' // Alterado para Português
  };

  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 do Cliente

{
  "customer_id": "CUST-2026-123456",
  "email": "john.doe@example.com",
  "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 Detalhes do Cliente

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

Atualizando Informações do Cliente

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

Excluindo um Cliente

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; // Sem conteúdo em caso de sucesso
};

Nota: A exclusão de um cliente com assinaturas ativas ou saldos pendentes falhará. Cancele as assinaturas primeiro.

Padrões de Integração Avançados

Idempotência para Retentativas Seguras

APIs de pagamento devem suportar requisições idempotentes para evitar cobranças duplicadas:

const createIdempotentOrder = async (payload, idempotencyKey) => {
  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 // Única por pedido
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

// Gerar chave única por pedido (armazene no seu banco de dados)
const idempotencyKey = `order_${userId}_${Date.now()}`;

Se a requisição expirar, mas o 2Checkout a processou, tentar novamente com a mesma chave retorna o resultado original em vez de cobrar duas vezes.

Gerenciando 3D Secure 2.0 (Conformidade UE)

Para clientes europeus, a autenticação 3D Secure 2.0 é obrigatória sob PSD2:

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', // ou 'mandatory' para a UE
        notification_url: 'https://your-site.com/3ds-callback'
      }
    })
  });

  const result = await response.json();

  // Gerenciar redirecionamento 3DS
  if (result.three_ds_redirect_url) {
    // Redirecionar o cliente para o seu banco para autenticação
    res.redirect(result.three_ds_redirect_url);
  }

  return result;
};

Preços em Múltiplas Moedas

Exiba os preços em moedas locais enquanto liquida na sua moeda base:

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

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

Prorrogação para Upgrades de Assinatura

Quando os clientes fazem upgrade no meio do ciclo, calcule as cobranças prorrogadas:

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', // Cobrar a diferença agora
        invoice_proration: true  // Mostrar item na fatura
      })
    }
  );

  return await response.json();
};

Solução de Problemas Comuns

Problema: Webhooks Não Chegam

Sintomas: Pedidos são processados, mas seu sistema não é atualizado.

Diagnóstico:

// Verificar logs de entrega de webhook no painel do 2Checkout
// Procurar por tentativas de entrega falhas ou respostas que não sejam 200

Soluções:

1. Verifique se o endpoint retorna 200 OK em até 5 segundos
2. Verifique a validade do certificado SSL (deve ser HTTPS)
3. Coloque os intervalos de IP do 2Checkout na lista branca do seu firewall
4. Revise a lógica de verificação de assinatura do webhook
5. Teste com o simulador de webhook antes da produção

Problema: Pagamentos de Teste Falham no Sandbox

Sintomas: Todos os cartões de teste são recusados no ambiente sandbox.

Soluções:

1. Confirme o uso de chaves de API sandbox (não de produção)
2. Verifique a URL base do sandbox: https://sandbox.2checkout.com/api/
3. Use os números de cartão de teste corretos (consulte a seção Testes)
4. Verifique o status da conta sandbox (pode expirar após inatividade)

Problema: Renovações de Assinatura Falham Silenciosamente

Sintomas: Assinaturas aparecem ativas, mas as renovações não são processadas.

Diagnóstico:

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

Soluções:

1. Verifique a expiração do método de pagamento do cliente
2. Revise as configurações de dunning no Painel de Controle
3. Verifique a entrega do webhook para subscription.payment_failed
4. Confirme se a flag auto_renew está habilitada

Problema: Discrepâncias na Conversão de Moeda

Sintomas: O valor cobrado difere da conversão esperada.

Causa: O 2Checkout usa taxas de câmbio diárias, que flutuam.

Solução:

• Exiba conversão “aproximada” com aviso
• Bloqueie as taxas na criação do carrinho com validade de 15 minutos
• Armazene as transações na moeda local do cliente

Problema: Falhas no AVS (Verificação de Endereço)

Sintomas: Cartões legítimos são recusados devido a divergência de endereço.

Soluções:

1. Use o preenchimento automático de endereço (Google Places, Lob)
2. Torne o CEP/código postal obrigatório no checkout
3. Implemente AVS suave (avise em vez de recusar)
4. Permita que o cliente atualize o endereço de cobrança

Gerenciamento de Assinaturas

O 2Checkout se destaca em faturamento recorrente. Veja como gerenciar 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', // ou 'anual', 'semanal'
    payment_method: {
      type: 'card',
      card_token: 'tok_card_tokenized'
    },
    options: {
      trial_days: 14, // Período de teste gratuito opcional
      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 da Assinatura

{
  "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 uma Assinatura

Mude planos, atualize métodos de pagamento ou modifique quantidades:

const updateSubscription = async (subscriptionId, updates) => {
  const payload = {
    ...updates
    // Exemplos:
    // plan_id: 'PLAN-ENTERPRISE-MONTHLY',
    // quantity: 5,
    // payment_method: { card_token: 'new_token' }
  };

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

  return await response.json();
};

Cancelando uma Assinatura

const cancelSubscription = async (subscriptionId, reason = '') => {
  const payload = {
    cancel_at_period_end: false, // true = cancelar após o período atual, false = imediato
    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: Manuseio de Eventos em Tempo Real

Webhooks notificam seu sistema sobre eventos de pagamento sem a necessidade de polling. Isso é crucial para renovações de assinatura, pagamentos falhos e reembolsos.

Passo 1: Configure o Endpoint do Webhook

No seu Painel de Controle 2Checkout:

1. Navegue até Integrações > Webhooks
2. Adicione a URL do seu endpoint (deve usar HTTPS)
3. Selecione os eventos para assinar
4. Salve e anote seu Segredo do Webhook

Passo 2: Crie o Manipulador de Webhook

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;

  // Verificar assinatura do webhook
  const isValid = verifyWebhookSignature(payload, signature, process.env.TWOCHECKOUT_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 '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('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')
  );
}

Eventos Críticos de Webhook

Melhores Práticas para Webhooks

1. Sempre verifique as assinaturas - Impede webhooks falsificados
2. Retorne 200 OK rapidamente - O 2Checkout tenta novamente em respostas que não sejam 200
3. Processe assincronamente - Enfileire eventos para processamento em segundo plano
4. Implemente idempotência - Gerencie entregas duplicadas de webhook
5. Registre tudo - Depure disputas de pagamento com logs carimbados por tempo

Testando Sua Integração

Usando o Ambiente Sandbox

O sandbox do 2Checkout permite que você teste sem cobranças reais:

// Usar URL base do sandbox
const BASE_URL = 'https://sandbox.2checkout.com/api/1';

// Números de cartão de teste
const TEST_CARDS = {
  APPROVED: '4111111111111111',
  DECLINED: '4000000000000002',
  INSUFFICIENT_FUNDS: '4000000000009995',
  EXPIRED_CARD: '4000000000000069'
};

// Endereços de teste
const TEST_ADDRESS = {
  country: 'US',
  zip: '90210' // Aciona verificações AVS
};

Testando Webhooks Localmente

Use o ngrok para expor seu servidor local:

# Instalar ngrok
npm install -g ngrok

# Iniciar seu servidor na porta 3000
node server.js

# Expor à internet
ngrok http 3000

# Copiar a URL do ngrok para as configurações de webhook do 2Checkout

Apidog para Testes de API

O Apidog simplifica o teste da API do 2Checkout:

1. Importar Especificação OpenAPI - Carregue a definição da API do 2Checkout
2. Crie Cenários de Teste - Construa coleções para cada endpoint
3. Simule Respostas - Teste sem atingir a API
4. Valide Webhooks - Inspecione estruturas de payload
5. Compartilhe com a Equipe - Colabore nos testes de integração

Crie variáveis de ambiente para chaves de sandbox vs produção e, em seguida, alterne os contextos com um clique.

Lista de Verificação para Implantação em Produção

Antes de entrar em produção:

• [ ] Mudar de chaves de API sandbox para produção
• [ ] Atualizar a URL base para https://api.2checkout.com/
• [ ] Habilitar verificação de assinatura de webhook
• [ ] Configurar monitoramento para pagamentos falhos
• [ ] Configurar lógica de retentativa para falhas transitórias
• [ ] Testar fluxos de reembolso e estorno
• [ ] Verificar conformidade com PCI DSS (usar tokenização)
• [ ] Habilitar 3D Secure 2.0 para clientes da UE
• [ ] Configurar logging para trilhas de auditoria
• [ ] Criar runbook para problemas de pagamento

Monitoramento e Alerta

Acompanhe estas métricas:

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

if (successRate < 95) {
  // Alertar equipe de pagamentos
  sendAlert('Taxa de sucesso de pagamento caiu abaixo de 95%');
}

// Rastrear códigos de erro específicos
const errorBreakdown = errors.reduce((acc, err) => {
  acc[err.code] = (acc[err.code] || 0) + 1;
  return acc;
}, {});

// Alertar sobre pico em erros específicos
if (errorBreakdown['CARD_DECLINED'] > threshold) {
  sendAlert('Pico de recusas de cartão detectado');
}

Casos de Uso no Mundo Real

Integração de Loja E-commerce

Um varejista de moda integrou o 2Checkout para gerenciar pagamentos globais. Resultados:

• Suportou automaticamente mais de 100 moedas
• Reduziu o abandono de carrinho em 23%
• Gerenciou automaticamente a conformidade com o IVA da UE
• Processou mais de US$ 2 milhões no primeiro ano

A implementação levou 3 semanas, usando inicialmente as páginas de checkout hospedadas do 2Checkout, e depois migrou para a integração direta da API para uma UX personalizada.

Negócio de Assinatura SaaS

Um SaaS de gerenciamento de projetos utilizou as assinaturas do 2Checkout:

• Gerenciou mais de 5.000 assinaturas ativas
• Gerenciou a prorrogação para upgrades de plano
• Automatizou a cobrança (dunning) para renovações falhas
• Reduziu a rotatividade em 15% com retentativas inteligentes

Recurso chave: Controle de acesso baseado em webhook. Quando subscription.renewed chega, estenda instantaneamente o acesso do usuário. Quando subscription.cancelled, agende a revogação do acesso.

Conclusão

A API do 2Checkout oferece tudo o que é necessário para processamento de pagamentos e gerenciamento de assinaturas. Principais pontos:

• Use o ambiente sandbox para todo o desenvolvimento e testes
• Implemente a verificação de assinatura HMAC para webhooks
• Trate erros de forma elegante com tratamento de códigos de erro específicos
• Teste os fluxos de assinatura completamente (período de teste, renovação, cancelamento)
• Monitore as métricas de pagamento em produção
• Use o Apidog para simplificar o teste de API e a colaboração em equipe

Seção de Perguntas Frequentes

O que é a API do 2Checkout?

A API do 2Checkout (agora Verifone) é uma interface RESTful para processamento de pagamentos, gerenciamento de assinaturas, tratamento de reembolsos e automação de transações de e-commerce. Ela suporta payloads JSON, autenticação HMAC e webhooks em tempo real.

2Checkout é o mesmo que Verifone?

Sim. O 2Checkout foi adquirido pela Verifone em 2020 e renomeado para Verifone Digital Commerce. Os endpoints da API e a funcionalidade permanecem os mesmos, embora alguma documentação faça referência à Verifone.

Como obtenho minha chave de API do 2Checkout?

Faça login no seu Painel de Controle do 2Checkout, navegue até Integrações > Chaves de API, e gere uma nova chave. Você receberá uma chave privada (lado do servidor) e uma chave pública (tokenização do lado do cliente).

O 2Checkout tem um ambiente sandbox?

Sim. Use https://sandbox.2checkout.com/api/ para testes. Crie uma conta sandbox separada para obter chaves de API de teste e processar transações de teste sem cobranças reais.

Quais métodos de pagamento o 2Checkout suporta?

O 2Checkout suporta cartões de crédito (Visa, Mastercard, Amex, Discover), PayPal, Apple Pay, Google Pay, transferências bancárias e métodos de pagamento locais em mais de 100 países.

Como gerencio webhooks de forma segura?

Sempre verifique o cabeçalho X-Webhook-Signature usando HMAC-SHA256 com o seu segredo de webhook. Processe eventos assincronamente e retorne 200 OK imediatamente para evitar retentativas.

O que acontece quando um pagamento de assinatura falha?

O 2Checkout envia um webhook subscription.payment_failed. Implemente uma lógica de retentativa (geralmente 3 tentativas ao longo de 7 dias) e envie um webhook subscription.cancelled se todas as retentativas falharem.

O 2Checkout está em conformidade com PCI DSS?

Sim, o 2Checkout é certificado PCI DSS Nível 1. Use a tokenização do lado do cliente para evitar o manuseio de dados brutos de cartão, o que reduz o seu escopo de conformidade com PCI.

Posso testar assinaturas no sandbox?

Sim. O Sandbox suporta o teste completo do ciclo de vida da assinatura, incluindo períodos de teste, renovações, upgrades, downgrades e cancelamentos. Use o cartão de teste 4111111111111111 para pagamentos bem-sucedidos.

Como gerencio reembolsos via API?

Envie uma requisição POST para /refunds com o ID do pedido e o valor do reembolso. O 2Checkout processa reembolsos parciais ou totais e envia um webhook refund.processed após a conclusão.