¿Cómo Utilizar las APIs de Braintree?

TL;DR

Las APIs de Braintree procesan pagos de tarjetas de crédito, PayPal, Venmo y monederos digitales. Se integra a través de SDKs del lado del servidor (Node, Python, Ruby, etc.), crea tokens de cliente para la seguridad del frontend y gestiona transacciones, reembolsos y suscripciones. Para las pruebas, utilice Apidog para validar las cargas útiles de los webhooks y probar su integración con datos de sandbox antes de salir a producción.

Introducción

Braintree procesa miles de millones en pagos anualmente. Es el procesador de pagos detrás de empresas como Uber, Airbnb y GitHub. La plataforma maneja tarjetas de crédito, PayPal, Venmo, Apple Pay, Google Pay y transferencias ACH.

Las APIs de pago son diferentes de otras APIs. Un error con un catálogo de productos es molesto. Un error con los pagos cuesta dinero real y rompe la confianza del cliente. Necesita hacerlo bien.

Braintree ofrece dos rutas de integración: Interfaz de usuario "Drop-in" (formulario de pago preconstruido) e Interfaz de usuario personalizada (control total). Ambas utilizan las mismas APIs del lado del servidor para el procesamiento real de pagos. Esta guía cubre el trabajo del lado del servidor que ocurre después de que un cliente hace clic en "Pagar".

Pruebe los webhooks de Braintree con Apidog - gratis

Configuración de Braintree

Crear una cuenta de Braintree

Vaya a braintreepayments.com (Braintree ahora es PayPal Enterprise Payments) y cree una cuenta de sandbox. Obtendrá:

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

Guárdelos de forma segura. La clave privada es como una contraseña; nunca la suba a Git.

Instalar el SDK

Braintree proporciona SDKs del lado del servidor para la mayoría de los lenguajes:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

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

Generar un token de cliente

Antes de mostrar el formulario de pago, genere un token de cliente. Esto 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 })
})

El frontend utiliza 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 su servidor
2. El servidor crea una transacción usando el nonce
3. Braintree procesa el pago
4. El servidor recibe la respuesta de éxito/fallo
5. Usted cumple el pedido o muestra un error

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

Cargar con un método de pago guardado

Después de la primera transacción, puede guardar el método de pago para uso futuro:

// 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
  }
})

Transacciones de PayPal

Braintree maneja PayPal de la misma manera que las tarjetas. El frontend obtiene un nonce de PayPal, usted lo carga:

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

Reembolsos y anulaciones

Reembolso completo

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 procesado')
}

Anular una transacción

Anular detiene una transacción antes de que se liquide. Utilícelo para pagos autorizados pero no capturados:

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

if (result.success) {
  console.log('Transacción anulada')
}

Flujo de estado de la transacción

autorizada → enviada_para_liquidación → liquidada
                    ↓
                  anulada
                    
liquidada → reembolsada

Suscripciones y facturación recurrente

Braintree gestiona suscripciones para pagos recurrentes.

Crear un plan

Primero, cree un plan en el panel de control de Braintree o a través de la API:

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

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

Cancelar una suscripción

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

if (result.success) {
  console.log('Suscripción cancelada')
}

Actualizar suscripción

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

Webhooks para eventos de pago

Los webhooks notifican a su servidor sobre eventos de transacciones. Esto es crítico para 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')
    }
  )
})

Registrar webhook en Braintree

En el panel de control de Braintree, vaya a Configuración → Webhooks y agregue la URL de su endpoint. En desarrollo, use un servicio de tunneling como ngrok para recibir webhooks localmente.

Pruebas con Apidog

Las APIs de pago necesitan pruebas exhaustivas. No puede depender de los datos de producción. Apidog le ayuda a probar sin riesgo.

1. Simular cargas útiles de webhook

En lugar de esperar a que Braintree envíe webhooks, cree cargas útiles simuladas:

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

Envíe esto a su endpoint de webhook y verifique que su código los maneje correctamente.

2. Separación de entornos

Cree entornos separados:

# 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

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', () => {
  // Verifique sus logs o base de datos
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Pruebe los webhooks de Braintree con Apidog - gratis

Errores comunes y soluciones

Procesador Rechazado

Causa: El banco rechazó la transacción.

Solución: Esto a menudo se debe a fondos insuficientes o filtros de fraude. Muestre un error genérico al cliente y sugiera intentar con una tarjeta diferente. Registre el 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.'
    })
  }
}

Gateway Rechazado

Causa: Los filtros de fraude de Braintree bloquearon la transacción.

Solución: Verifique el 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
}

Fallos de liquidación

Causa: La transacción no pudo liquidarse después de la autorización.

Solución: Monitoree los webhooks de transaction_settlement_declined. Causas comunes:

• El método de pago caducó entre la autorización y la liquidación
• El emisor bloqueó la transacción
• Se detectaron fondos insuficientes

Transacciones duplicadas

Causa: El cliente hizo clic en "Pagar" dos veces o su código reintentó.

Solución: Use el parámetro orderId. Braintree rechazará duplicados dentro de un período de tiempo:

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

Alternativas y comparaciones

La principal ventaja de Braintree es el soporte nativo para PayPal y Venmo. Si necesita tanto el procesamiento de tarjetas como PayPal, a menudo es más sencillo que Stripe + PayPal por separado.

Casos de uso en el mundo real

Plataforma de suscripción SaaS. Una herramienta de gestión de proyectos utiliza Braintree para suscripciones mensuales. Los webhooks manejan los pagos fallidos (tarjeta caducada, fondos insuficientes) enviando notificaciones por correo electrónico. Los usuarios actualizan los métodos de pago sin contactar con el soporte.

Pagos de marketplaces. Una plataforma de autónomos divide los pagos entre la tarifa de la plataforma y el autónomo. La configuración de cuentas de comerciante y sub-comerciantes de Braintree gestiona la complejidad.

Comercio electrónico con PayPal. Una tienda online ofrece tarjetas de crédito y PayPal. La API unificada de Braintree significa que una sola integración maneja ambos. El mismo objeto de cliente funciona en todos los métodos de pago.

Conclusión

Esto es lo que ha aprendido:

• Los SDK de Braintree gestionan el procesamiento de pagos del lado del servidor
• Los tokens de cliente autorizan la comunicación del frontend
• Las ventas de transacciones cargan tarjetas de crédito y PayPal
• Las suscripciones gestionan la facturación recurrente
• Los webhooks le notifican sobre eventos de pago
• Pruebe a fondo con Apidog antes de salir a producción

Preguntas Frecuentes

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

Un nonce es un token de un solo uso que representa un método de pago. El frontend lo genera después de que un cliente introduce los detalles de la tarjeta. Su servidor utiliza el nonce para cargar la tarjeta. Los nonces caducan después de 3 horas.

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

La autorización reserva fondos en la tarjeta. La liquidación realmente carga la tarjeta. Por defecto, Braintree auto-liquida. Para pre-pedidos, autorice primero, luego liquide 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')

¿Cómo manejo la moneda?

Cada cuenta de comerciante de Braintree tiene una moneda predeterminada. La multimoneda requiere múltiples cuentas de comerciante. Consulte con el soporte de Braintree para la configuración multimoneda.

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

Braintree proporciona tarjetas de prueba en el sandbox:

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

¿Cómo manejo las disputas/contracargos?

Escuche los webhooks dispute_opened, dispute_won y dispute_lost. Proporcione pruebas a través del panel de control de Braintree. Documente todo: comunicaciones con el cliente, confirmaciones de entrega, 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 sin procesar. En su lugar, almacene tokens de método de pago. Braintree gestiona el alcance de PCI.

¿Qué es 3D Secure?

3D Secure añade un paso de verificación adicional para transacciones sin tarjeta presente. Braintree lo soporta. Habilítelo en el panel de control y maneje las respuestas authentication_required:

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

¿Cuánto tardan los reembolsos?

Los reembolsos suelen procesarse en 3-5 días hábiles. El tiempo depende del banco del cliente. Recibirá un webhook transaction_refunded cuando se complete.