Como Usar APIs Braintree? Guia Completo

Em resumo

As APIs do Braintree processam pagamentos de cartões de crédito, PayPal, Venmo e carteiras digitais. Você integra via SDKs server-side (Node, Python, Ruby, etc.), cria tokens de cliente para segurança frontend e gerencia transações, reembolsos e assinaturas. Para testes, use o Apidog para validar cargas de webhook e testar sua integração com dados de sandbox antes de entrar em produção.

Introdução

O Braintree processa bilhões em pagamentos anualmente. É o processador de pagamentos por trás de empresas como Uber, Airbnb e GitHub. A plataforma lida com cartões de crédito, PayPal, Venmo, Apple Pay, Google Pay e transferências ACH.

APIs de pagamento são diferentes de outras APIs. Um erro em um catálogo de produtos é irritante. Um erro com pagamentos custa dinheiro real e quebra a confiança do cliente. Você precisa fazer isso direito.

O Braintree oferece dois caminhos de integração: UI Drop-in (formulário de pagamento pré-construído) e UI Personalizada (controle total). Ambos usam as mesmas APIs server-side para o processamento real do pagamento. Este guia cobre o trabalho server-side que acontece depois que um cliente clica em "Pagar".

💡

Se você está construindo integrações de pagamento, o Apidog te ajuda a testar manipuladores de webhook e validar respostas de pagamento. Você pode simular os webhooks do Braintree localmente, garantindo que seu código lide com sucesso, falha e casos de borda antes de processar transações reais.

botão

Teste webhooks do Braintree com Apidog - grátis

Configurando o Braintree

Criar uma conta Braintree

Acesse braintreepayments.com (Braintree agora é PayPal Enterprise Payments) e crie uma conta sandbox. Você receberá:

Merchant ID: abc123xyz
Public Key: def456...
Private Key: ghi789...

Armazene-os de forma segura. A chave privada é como uma senha - nunca a comite no Git.

Instalar o SDK

O Braintree oferece SDKs server-side para a maioria das linguagens:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

Inicializar o gateway:

const braintree = require('braintree')

const gateway = new braintree.BraintreeGateway({
  environment: braintree.Environment.Sandbox,
  merchantId: process.env.BRAINTREE_MERCHANT_ID,
  publicKey: process.env.BRAINTREE_PUBLIC_KEY,
  privateKey: process.env.BRAINTREE_PRIVATE_KEY
})

Gerar um token de cliente

Antes de exibir o formulário de pagamento, gere um token de cliente. Isso autoriza o frontend a se comunicar com o Braintree.

app.get('/checkout/token', async (req, res) => {
  const clientToken = await gateway.clientToken.generate()
  res.json({ clientToken: clientToken.clientToken })
})

O frontend usa este token para inicializar a UI Drop-in ou uma integração personalizada.

Processando pagamentos

O fluxo de pagamento

O frontend envia o nonce do método de pagamento para o seu servidor
O servidor cria uma transação usando o nonce
O Braintree processa o pagamento
O servidor recebe a resposta de sucesso/falha
Você conclui o pedido ou exibe um erro

Cobrar um cartão de crédito

app.post('/checkout', async (req, res) => {
  const { paymentMethodNonce, amount, orderId } = req.body

  const result = await gateway.transaction.sale({
    amount: amount,
    paymentMethodNonce: paymentMethodNonce,
    orderId: orderId,
    options: {
      submitForSettlement: true
    }
  })

  if (result.success) {
    res.json({
      success: true,
      transactionId: result.transaction.id
    })
  } else {
    res.status(400).json({
      success: false,
      message: result.message
    })
  }
})

Cobrar com método de pagamento salvo

Após a primeira transação, você pode salvar o método de pagamento para uso futuro:

// Criar cliente com método de pagamento
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// O método de pagamento é salvo
const paymentMethodToken = result.customer.paymentMethods[0].token

// Cobrar método de pagamento salvo mais tarde
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

Transações PayPal

O Braintree lida com o PayPal da mesma forma que com os cartões. O frontend obtém um nonce do PayPal, você o cobra:

const result = await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: paypalNonce,
  orderId: 'ORDER-123',
  options: {
    submitForSettlement: true
  }
})

Reembolsos e anulações

Reembolso total

const result = await gateway.transaction.refund('transaction_id')

if (result.success) {
  console.log('Reembolsado:', result.transaction.id)
}

Reembolso parcial

const result = await gateway.transaction.refund('transaction_id', '50.00')

if (result.success) {
  console.log('Reembolso parcial processado')
}

Anular uma transação

Anular uma transação a interrompe antes que ela seja liquidada. Use isso para pagamentos autorizados, mas não capturados:

const result = await gateway.transaction.void('transaction_id')

if (result.success) {
  console.log('Transação anulada')
}

Fluxo de status da transação

authorized → submitted_for_settlement → settled
                    ↓
                  voided
                    
settled → refunded

Assinaturas e cobrança recorrente

O Braintree lida com assinaturas para pagamentos recorrentes.

Criar um plano

Primeiro, crie um plano no painel de controle do Braintree ou via API:

const result = await gateway.plan.create({
  id: 'monthly-premium',
  name: 'Monthly Premium',
  billingFrequency: 1,
  currencyIsoCode: 'USD',
  price: '29.99'
})

Criar uma assinatura

const result = await gateway.subscription.create({
  paymentMethodToken: paymentMethodToken,
  planId: 'monthly-premium',
  firstBillingDate: new Date()
})

if (result.success) {
  console.log('Assinatura criada:', result.subscription.id)
}

Cancelar uma assinatura

const result = await gateway.subscription.cancel('subscription_id')

if (result.success) {
  console.log('Assinatura cancelada')
}

Atualizar assinatura

const result = await gateway.subscription.update('subscription_id', {
  planId: 'annual-premium',
  price: '299.99'
})

Webhooks para eventos de pagamento

Webhooks notificam seu servidor sobre eventos de transação. Isso é crítico para assinaturas e disputas.

Criar um endpoint de webhook

app.post('/webhooks/braintree', (req, res) => {
  const signature = req.body.bt_signature
  const payload = req.body.bt_payload

  // Verificar e analisar o webhook
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('Webhook inválido')
      }

      switch (webhookNotification.kind) {
        case 'subscription_charged_successfully':
          handleSuccessfulCharge(webhookNotification.subscription)
          break
        case 'subscription_charged_unsuccessfully':
          handleFailedCharge(webhookNotification.subscription)
          break
        case 'dispute_opened':
          handleDispute(webhookNotification.dispute)
          break
        case 'transaction_settled':
          handleSettledTransaction(webhookNotification.transaction)
          break
      }

      res.status(200).send('OK')
    }
  )
})

Registrar webhook no Braintree

No painel de controle do Braintree, vá para Configurações → Webhooks e adicione a URL do seu endpoint. Em desenvolvimento, use um serviço de tunelamento como o ngrok para receber webhooks localmente.

Testando com Apidog

APIs de pagamento precisam de testes rigorosos. Você não pode depender de dados de produção. O Apidog te ajuda a testar sem riscos.

1. Simular cargas de webhook

Em vez de esperar que o Braintree envie webhooks, crie cargas simuladas:

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}

Envie-os para o seu endpoint de webhook e verifique se o seu código os manipula corretamente.

2. Separação de ambientes

Crie ambientes separados:

# Sandbox
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# Production
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production

3. Validar respostas de webhook

pm.test('Webhook processado com sucesso', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('ID da transação logado', () => {
  // Verifique seus logs ou banco de dados
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Teste webhooks do Braintree com Apidog - grátis

Erros comuns e correções

Processador Recusou

Causa: O banco rejeitou a transação.

Correção: Isso geralmente ocorre devido a fundos insuficientes ou filtros de fraude. Exiba um erro genérico ao cliente e sugira tentar um cartão diferente. Registre o processorResponseCode para depuração.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // Banco recusou
    return res.status(400).json({
      error: 'Seu banco recusou esta transação. Por favor, tente um cartão diferente.'
    })
  }
}

Gateway Rejeitou

Causa: Os filtros de fraude do Braintree bloquearam a transação.

Correção: Verifique o gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // Divergência de CVV
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Verificação de endereço falhou
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Ferramentas avançadas de fraude bloquearam
}

Falhas na liquidação

Causa: A transação não pôde ser liquidada após a autorização.

Correção: Monitore os webhooks `transaction_settlement_declined`. Causas comuns:

O método de pagamento expirou entre a autorização e a liquidação
O emissor bloqueou a transação
Fundos insuficientes se tornaram aparentes

Transações duplicadas

Causa: O cliente clicou em "Pagar" duas vezes ou seu código tentou novamente.

Correção: Use o parâmetro `orderId`. O Braintree rejeitará duplicatas dentro de uma janela de tempo:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // Evita duplicatas
  options: {
    submitForSettlement: true
  }
})

Alternativas e comparações

Característica	Braintree	Stripe	PayPal
Preços	2.9% + 30¢	2.9% + 30¢	2.9% + 30¢
Suporte PayPal	Nativo	Adicional	Nativo
Assinaturas	Sim	Sim	Limitado
Internacional	46 países	46 países	Mais de 200 países
Ferramentas de fraude	Incorporado	Incorporado	Básico
Qualidade do SDK	Excelente	Excelente	Bom
Pagamentos	Sim	Sim	Sim

A principal vantagem do Braintree é o suporte nativo ao PayPal e Venmo. Se você precisa de processamento de cartão e PayPal, muitas vezes é mais simples do que Stripe + PayPal separadamente.

Casos de uso reais

Plataforma de assinatura SaaS. Uma ferramenta de gerenciamento de projetos usa o Braintree para assinaturas mensais. Webhooks lidam com pagamentos falhos (cartão expirado, fundos insuficientes) enviando notificações por e-mail. Os usuários atualizam os métodos de pagamento sem contatar o suporte.

Pagamentos em marketplace. Uma plataforma de freelancers divide pagamentos entre a taxa da plataforma e o freelancer. As contas de comerciante do Braintree e a configuração de sub-comerciante lidam com a complexidade.

E-commerce com PayPal. Uma loja online oferece cartões de crédito e PayPal. A API unificada do Braintree significa que uma única integração lida com ambos. O mesmo objeto de cliente funciona em todos os métodos de pagamento.

Conclusão

Aqui está o que você aprendeu:

SDKs do Braintree lidam com o processamento de pagamentos server-side
Tokens de cliente autorizam a comunicação frontend
Vendas de transações cobram cartões de crédito e PayPal
Assinaturas lidam com a cobrança recorrente
Webhooks notificam você sobre eventos de pagamento
Teste minuciosamente com Apidog antes de entrar em produção

botão

Perguntas Frequentes

O que é um nonce de método de pagamento?

Um nonce é um token de uso único que representa um método de pagamento. O frontend o gera depois que um cliente insere os detalhes do cartão. Seu servidor usa o nonce para cobrar o cartão. Nonces expiram após 3 horas.

Qual a diferença entre autorização e liquidação?

Autorização reserva fundos no cartão. Liquidação de fato cobra o cartão. Por padrão, o Braintree liquida automaticamente. Para pré-vendas, autorize primeiro e depois liquide no momento do envio:

// Autorizar apenas
await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: nonce,
  options: {
    submitForSettlement: false // Autorizar apenas
  }
})

// Liquidar mais tarde
await gateway.transaction.submitForSettlement('transaction_id')

Como eu lido com moedas?

Cada conta de comerciante do Braintree tem uma moeda padrão. Multi-moeda requer várias contas de comerciante. Verifique com o suporte do Braintree para configurar multi-moeda.

Que números de cartão de teste devo usar?

O Braintree fornece cartões de teste no sandbox:

4111111111111111 - Visa (sucesso)
4000111111111115 - Visa (recusa)
5555555555554444 - Mastercard (sucesso)
378282246310005 - Amex (sucesso)

Como lido com disputas/chargebacks?

Monitore os webhooks `dispute_opened`, `dispute_won` e `dispute_lost`. Forneça evidências através do painel de controle do Braintree. Documente tudo - comunicações com o cliente, confirmações de entrega, termos de serviço.

Posso armazenar números de cartão de crédito?

Não. A conformidade com PCI proíbe o armazenamento de números de cartão brutos. Armazene tokens de método de pagamento em vez disso. O Braintree lida com o escopo do PCI.

O que é 3D Secure?

O 3D Secure adiciona uma etapa extra de verificação para transações sem cartão presente. O Braintree o suporta. Habilite no painel de controle e lide com as respostas `authentication_required`:

const result = await gateway.transaction.sale({
  amount: '100.00',
  paymentMethodNonce: nonce,
  threeDSecure: {
    required: true
  }
})

Quanto tempo levam os reembolsos?

Os reembolsos geralmente são processados em 3-5 dias úteis. O tempo depende do banco do cliente. Você receberá um webhook `transaction_refunded` quando concluído.