DEV Community

Cover image for Como Usar APIs Braintree? Guia Completo
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Usar APIs Braintree? Guia Completo

Em resumo

As APIs do Braintree permitem processar pagamentos com cartões de crédito, PayPal, Venmo e carteiras digitais. A integração ocorre via SDKs server-side (Node, Python, Ruby, etc.), onde você gera tokens de cliente para segurança no frontend e gerencia transações, reembolsos e assinaturas. Para testar, use o Apidog para validar cargas de webhook e experimentar a integração com dados de sandbox antes de ir para produção.

Experimente o Apidog hoje

Introdução

O Braintree processa bilhões em pagamentos anualmente e é utilizado por empresas como Uber, Airbnb e GitHub. Ele suporta pagamentos por cartão de crédito, PayPal, Venmo, Apple Pay, Google Pay e transferências ACH.

APIs de pagamento exigem precisão. Um erro pode causar prejuízo financeiro e perda de confiança do cliente. Implementação e testes rigorosos são essenciais.

O Braintree oferece dois tipos de integração: UI Drop-in (formulário pronto) e UI Personalizada (controle total). Ambas usam as APIs server-side para processar pagamentos. Aqui, focamos nos fluxos server-side após o clique em "Pagar".

💡 Dica: Se você desenvolve integrações de pagamento, o Apidog auxilia a testar manipuladores de webhook e validar respostas. Simule webhooks do Braintree localmente para garantir que seu código trate sucesso, falha e casos de borda antes de processar transações reais.

Teste webhooks do Braintree com Apidog - grátis

Configurando o Braintree

Criar uma conta Braintree

Acesse braintreepayments.com e crie uma conta sandbox. Você receberá:

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

Armazene essas credenciais com segurança. Nunca compartilhe ou comite a chave privada no Git.

Credenciais do Braintree

Instalar o SDK

O Braintree oferece SDKs para várias linguagens.

Node.js:

npm install braintree
Enter fullscreen mode Exit fullscreen mode

Python:

pip install braintree
Enter fullscreen mode Exit fullscreen mode

Ruby:

gem install braintree
Enter fullscreen mode Exit fullscreen mode

Inicialização do 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
})
Enter fullscreen mode Exit fullscreen mode

Gerar um token de cliente

Antes de exibir o formulário de pagamento, gere um token de cliente para autorizar o frontend:

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

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

Processando pagamentos

O fluxo de pagamento

  1. O frontend envia o nonce do método de pagamento para o backend.
  2. O servidor cria uma transação usando o nonce.
  3. O Braintree processa o pagamento.
  4. O backend recebe resposta de sucesso/falha.
  5. O pedido é finalizado ou um erro é exibido.

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
    })
  }
})
Enter fullscreen mode Exit fullscreen mode

Cobrar com método de pagamento salvo

Após a primeira transação, salve o método de pagamento para cobranças futuras:

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

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

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

Transações PayPal

O fluxo é semelhante: o frontend obtém um nonce do PayPal e o backend processa:

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

Reembolsos e anulações

Reembolso total 

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

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

Reembolso parcial 

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

if (result.success) {
  console.log('Reembolso parcial processado')
}
Enter fullscreen mode Exit fullscreen mode

Anular uma transação

Use para cancelar autorizações não liquidadas:

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

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

Fluxo de status da transação 

authorized → submitted_for_settlement → settled
                    ↓
                  voided

settled → refunded
Enter fullscreen mode Exit fullscreen mode

Assinaturas e cobrança recorrente

O Braintree suporta pagamentos recorrentes.

Criar um plano

No painel do Braintree ou via API:

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

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)
}
Enter fullscreen mode Exit fullscreen mode

Cancelar uma assinatura 

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

if (result.success) {
  console.log('Assinatura cancelada')
}
Enter fullscreen mode Exit fullscreen mode

Atualizar assinatura 

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

Webhooks para eventos de pagamento

Webhooks notificam seu sistema sobre eventos críticos, como cobranças recorrentes 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

  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')
    }
  )
})
Enter fullscreen mode Exit fullscreen mode

Registrar webhook no Braintree

No painel Braintree, acesse Configurações → Webhooks e adicione a URL do endpoint. Em desenvolvimento, use ngrok ou similar para receber webhooks localmente.

Testando com Apidog

APIs de pagamento exigem testes detalhados. Não use dados de produção. O Apidog permite simular e validar todos os fluxos sem riscos.

Testando Webhooks com Apidog

1. Simular cargas de webhook

Monte cargas simuladas e envie para seu endpoint:

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}
Enter fullscreen mode Exit fullscreen mode

2. Separação de ambientes

Configure variáveis de ambiente por ambiente:

# 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
Enter fullscreen mode Exit fullscreen mode

3. Validar respostas de webhook

No seu runner de testes:

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', () => {
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})
Enter fullscreen mode Exit fullscreen mode

Teste webhooks do Braintree com Apidog - grátis

Erros comuns e correções

Processador Recusou

Causa: O banco do cliente recusou a transação.

Correção: Exiba erro genérico e sugira outro cartão. Registre o processorResponseCode para depuração.

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

Gateway Rejeitou

Causa: Filtros de fraude do Braintree bloquearam.

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') {
  // Bloqueio por fraude
}
Enter fullscreen mode Exit fullscreen mode

Falhas na liquidação

Causa: Transação não foi liquidada após autorização.

Correção: Monitore webhooks transaction_settlement_declined. Causas comuns: cartão expirado, bloqueio do emissor, fundos insuficientes.

Transações duplicadas

Causa: Cliente clicou duas vezes em "Pagar" ou o código fez retry.

Correção: Use o parâmetro orderId para evitar duplicidades:

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123',
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

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 cartão e PayPal, a integração costuma ser mais simples do que Stripe + PayPal separadamente.

Casos de uso reais

Plataforma SaaS: Ferramenta de gerenciamento de projetos usa Braintree para assinaturas mensais. Webhooks tratam pagamentos falhos e notificam usuários por e-mail. Usuários atualizam métodos de pagamento autônomos.

Marketplace: Plataforma de freelancers divide pagamentos entre taxa da plataforma e freelancers, usando sub-comerciantes do Braintree.

E-commerce com PayPal: Loja online oferece cartões e PayPal via integração unificada, usando o mesmo objeto cliente para ambos.

Conclusão

Resumo prático:

  • SDKs do Braintree processam pagamentos server-side.
  • Tokens de cliente autorizam o frontend.
  • Transações cobram cartões e PayPal.
  • Assinaturas automatizam cobrança recorrente.
  • Webhooks notificam sobre eventos de pagamento.
  • Teste tudo com Apidog antes de ir para produção.

Perguntas Frequentes

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

Nonce é um token de uso único que representa o método de pagamento. O frontend gera esse token após o usuário inserir os dados do cartão. O backend usa o nonce para cobrar. Nonces expiram em 3 horas.

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

Autorização reserva fundos. Liquidação efetiva a cobrança. Por padrão, o Braintree liquida automaticamente. Para pré-vendas, autorize e liquide depois:

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

// Liquidar posteriormente
await gateway.transaction.submitForSettlement('transaction_id')
Enter fullscreen mode Exit fullscreen mode

Como lido com moedas?

Cada conta de comerciante tem uma moeda padrão. Para multi-moeda, são necessárias contas separadas. Consulte o suporte Braintree para configuração.

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

  • 4111111111111111 – Visa (sucesso)
  • 4000111111111115 – Visa (recusa)
  • 5555555555554444 – Mastercard (sucesso)
  • 378282246310005 – Amex (sucesso)

Como lido com disputas/chargebacks?

Monitore webhooks dispute_opened, dispute_won e dispute_lost. Envie evidências pelo painel do Braintree. Documente todas as interações e entregas.

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

Não. Armazene apenas tokens de método de pagamento. O Braintree cuida da conformidade PCI.

O que é 3D Secure?

3D Secure adiciona verificação extra para transações online. Habilite no painel e trate respostas authentication_required:

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

Quanto tempo levam os reembolsos?

Normalmente, 3 a 5 dias úteis, dependendo do banco do cliente. O webhook transaction_refunded sinaliza a conclusão.

Top comments (0)