DEV Community

Cover image for ¿Cómo Utilizar las APIs de Braintree?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Cómo Utilizar las APIs de Braintree?

TL;DR

Las APIs de Braintree procesan pagos con tarjetas de crédito, PayPal, Venmo y monederos digitales. Se integran usando SDKs del lado del servidor (Node, Python, Ruby, etc.), generan tokens de cliente para el frontend y gestionan transacciones, reembolsos y suscripciones. Para pruebas, utiliza Apidog para validar cargas útiles de webhooks y probar tu integración con datos de sandbox antes de pasar a producción.

Prueba Apidog hoy

Introducción

Braintree procesa miles de millones en pagos cada año y es el motor de pagos detrás de empresas como Uber, Airbnb y GitHub. Soporta tarjetas de crédito, PayPal, Venmo, Apple Pay, Google Pay y transferencias ACH.

A diferencia de otras APIs, las APIs de pago requieren máxima precisión. Un fallo puede significar pérdida de dinero y confianza del cliente.

Braintree permite dos tipos de integración: una interfaz "Drop-in" (formulario preconstruido) y una interfaz personalizada (control total). Ambas usan las mismas APIs del backend para procesar pagos. Esta guía se centra en la implementación backend después de que el cliente hace clic en "Pagar".

💡 Si estás construyendo integraciones de pago, Apidog te ayuda a probar manejadores de webhooks y validar respuestas de pago. Puedes simular webhooks de Braintree localmente, asegurando que tu código maneje correctamente éxitos, fallos y casos extremos antes de trabajar con transacciones reales.

Prueba los webhooks de Braintree con Apidog - gratis

Configuración de Braintree

Crear una cuenta de Braintree

Accede a braintreepayments.com y crea una cuenta de sandbox. Obtendrás:

  • ID de Comerciante: abc123xyz
  • Clave Pública: def456...
  • Clave Privada: ghi789...

Guarda estos datos en un lugar seguro. Nunca subas la clave privada a Git.

Captura de pantalla de la configuración de Braintree para obtener las claves de API

Instalar el SDK

Braintree ofrece SDKs backend para varios lenguajes.

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

Inicializar el 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

Generar un token de cliente

Antes de mostrar el formulario de pago, genera un token de cliente. Este token autoriza al frontend a comunicarse con Braintree.

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

El frontend usará este token para inicializar la UI "Drop-in" o la integración personalizada.

Procesamiento de pagos

El flujo de pago

  1. El frontend envía el nonce del método de pago a tu servidor.
  2. El backend crea una transacción usando el nonce.
  3. Braintree procesa el pago.
  4. El backend recibe la respuesta de éxito o fallo.
  5. Cumples el pedido o muestras un error al usuario.

Cargar una tarjeta 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

Cargar con un método de pago guardado

Después de la primera transacción, puedes guardar el método de pago para futuros cargos:

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

// El método de pago está guardado
const paymentMethodToken = result.customer.paymentMethods[0].token

// Cargar método de pago guardado más tarde
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Transacciones de PayPal

Braintree maneja PayPal igual que las tarjetas. El frontend obtiene un nonce de PayPal y tú lo cargas:

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

Reembolsos y anulaciones

Reembolso completo 

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

Anular una transacción

Anula una transacción antes de que se liquide:

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

if (result.success) {
  console.log('Transacción anulada')
}
Enter fullscreen mode Exit fullscreen mode

Flujo de estado de la transacción 

autorizada → enviada_para_liquidación → liquidada
                    ↓
                  anulada

liquidada → reembolsada
Enter fullscreen mode Exit fullscreen mode

Suscripciones y facturación recurrente

Braintree permite gestionar pagos recurrentes fácilmente.

Crear un plan

Crea un plan en el panel de control o vía 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

Crear una suscripción 

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

if (result.success) {
  console.log('Suscripción creada:', result.subscription.id)
}
Enter fullscreen mode Exit fullscreen mode

Cancelar una suscripción 

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

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

Actualizar suscripción 

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

Webhooks para eventos de pago

Los webhooks notifican a tu servidor sobre eventos críticos de transacciones, suscripciones y disputas.

Crear un endpoint de webhook 

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

  // Verificar y parsear el 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')
    }
  )
})
Enter fullscreen mode Exit fullscreen mode

Registrar webhook en Braintree

En el panel de Braintree, ve a Configuración → Webhooks y agrega la URL de tu endpoint. Para desarrollo, usa ngrok u otro túnel para recibir webhooks localmente.

Pruebas con Apidog

Las APIs de pago requieren pruebas exhaustivas. Apidog te permite probar sin afectar datos reales.

Captura de pantalla de la interfaz de Apidog mostrando la prueba de webhook.

1. Simular cargas útiles de webhook

Crea cargas simuladas para probar tu endpoint:

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

Envía esto a tu endpoint y verifica que tu código maneje correctamente el webhook.

2. Separación de entornos

Define variables de entorno distintas para sandbox y producción:

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

# Producción
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 respuestas de webhook 

pm.test('Webhook procesado exitosamente', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('ID de transacción registrado', () => {
  // Verifica tus logs o base de datos
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})
Enter fullscreen mode Exit fullscreen mode

Prueba los webhooks de Braintree con Apidog - gratis

Errores comunes y soluciones

Procesador Rechazado

Causa: El banco rechazó la transacción.

Solución: Suele ser por fondos insuficientes o filtros de fraude. Muestra un error genérico y sugiere otra tarjeta. Registra processorResponseCode para depuración.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // Banco rechazado
    return res.status(400).json({
      error: 'Su banco rechazó esta transacción. Por favor, intente con una tarjeta diferente.'
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Gateway Rechazado

Causa: Filtros de fraude de Braintree.

Solución: Verifica gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // Desajuste de CVV
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Fallo en la verificación de dirección
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Herramientas avanzadas de fraude lo bloquearon
}
Enter fullscreen mode Exit fullscreen mode

Fallos de liquidación

Causa: La transacción no se pudo liquidar después de autorizar.

Solución: Monitorea el webhook transaction_settlement_declined. Causas comunes:

  • Método de pago caducado entre autorización y liquidación
  • El emisor bloqueó la transacción
  • Fondos insuficientes

Transacciones duplicadas

Causa: Doble clic en "Pagar" o reintentos en código.

Solución: Usa el parámetro orderId. Braintree rechaza duplicados en un período corto.

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 y comparaciones

Característica Braintree Stripe PayPal
Precios 2.9% + 30¢ 2.9% + 30¢ 2.9% + 30¢
Soporte de PayPal Nativo Complemento Nativo
Suscripciones Sí Sí Limitado
Internacional 46 países 46 países 200+ países
Herramientas de fraude Integrado Integrado Básico
Calidad del SDK Excelente Excelente Buena
Pagos Sí Sí Sí

La ventaja principal de Braintree es el soporte nativo para PayPal y Venmo. Si necesitas ambos, tarjetas y PayPal, suele ser más sencillo que integrar Stripe y PayPal por separado.

Casos de uso en el mundo real

Plataforma SaaS: Una herramienta de gestión de proyectos utiliza Braintree para suscripciones mensuales. Webhooks gestionan pagos fallidos (tarjeta caducada, fondos insuficientes) enviando emails automáticos. Los usuarios actualizan métodos de pago sin soporte manual.

Marketplaces: Una plataforma de freelancers divide pagos entre la comisión de la plataforma y el freelancer, usando cuentas de comerciante y sub-comerciantes de Braintree.

E-commerce con PayPal: Una tienda online acepta tarjetas y PayPal. La API unificada de Braintree gestiona ambos con un solo flujo e igual objeto de cliente.

Conclusión

Resumen de pasos clave:

  • Los SDK de Braintree gestionan pagos backend.
  • Tokens de cliente autorizan el frontend.
  • Transacciones cargan tarjetas y PayPal.
  • Suscripciones manejan facturación recurrente.
  • Webhooks notifican sobre eventos críticos.
  • Prueba exhaustivamente con Apidog antes de producción.

Preguntas Frecuentes

¿Qué es un nonce de método de pago?

Un nonce es un token de un solo uso generado por el frontend tras ingresar los datos de la tarjeta. El backend usa el nonce para procesar el cargo. Caduca en 3 horas.

¿Cuál es la diferencia entre autorización y liquidación?

La autorización reserva fondos en la tarjeta. La liquidación ejecuta el cobro. Por defecto, Braintree auto-liquida. Para pre-pedidos, autoriza primero y liquida al enviar:

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

// Liquidar más tarde
await gateway.transaction.submitForSettlement('transaction_id')
Enter fullscreen mode Exit fullscreen mode

¿Cómo manejo la moneda?

Cada cuenta de comerciante en Braintree tiene una moneda predeterminada. Para multimoneda, necesitas múltiples cuentas. Contacta al soporte de Braintree para configurarlo.

¿Qué números de tarjeta de prueba debo usar?

En el sandbox de Braintree:

  • 4111111111111111 — Visa (éxito)
  • 4000111111111115 — Visa (rechazo)
  • 5555555555554444 — Mastercard (éxito)
  • 378282246310005 — Amex (éxito)

¿Cómo manejo las disputas/contracargos?

Escucha los webhooks dispute_opened, dispute_won, dispute_lost. Sube pruebas por el panel de Braintree. Documenta todo: emails, entregas, términos de servicio.

¿Puedo almacenar números de tarjeta de crédito?

No. El cumplimiento de PCI prohíbe almacenar números de tarjeta. Solo almacena tokens de método de pago. Braintree gestiona la seguridad PCI.

¿Qué es 3D Secure?

3D Secure añade una verificación adicional para pagos sin tarjeta física. Braintree lo soporta. Actívalo en el panel y maneja respuestas con authentication_required:

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

¿Cuánto tardan los reembolsos?

Los reembolsos suelen tomar 3-5 días hábiles, dependiendo del banco. Recibirás un webhook transaction_refunded al completarse.

Top comments (0)