braintree

Braintree Payment Gateway API Skill

Overview

Braintree (by PayPal) provides enterprise payment processing accepting Credit Cards, PayPal, Venmo, Apple Pay, and Google Pay with PCI-compliant Hosted Fields and Drop-in UI.

Installation

npm install braintree

Server Initialization

import braintree, { Environment } from 'braintree';

const gateway = new braintree.BraintreeGateway({
  environment:
    process.env.NODE_ENV === 'production'
      ? Environment.Production
      : Environment.Sandbox,
  merchantId: process.env.BRAINTREE_MERCHANT_ID!,
  publicKey: process.env.BRAINTREE_PUBLIC_KEY!,
  privateKey: process.env.BRAINTREE_PRIVATE_KEY!,
});

Standard Payment Flow

Step 1: Generate Client Token for Frontend

export async function getClientToken(customerId?: string) {
  const response = await gateway.clientToken.generate({
    customerId: customerId,
  });
  return response.clientToken;
}

Step 2: Charge the Payment Method Nonce

export async function createSaleTransaction(nonce: string, amount: string) {
  const result = await gateway.transaction.sale({
    amount,
    paymentMethodNonce: nonce,
    options: {
      submitForSettlement: true, // Auto-submit for settlement
    },
  });

  if (result.success) {
    return { success: true, transactionId: result.transaction.id };
  } else {
    throw new Error(result.message);
  }
}

AI Pitfalls & Anti-Hallucination Guidelines

• Never Handle PAN Data: Never write code that receives raw card numbers on the backend. The frontend must tokenize the card via Braintree Drop-in/Hosted Fields and send only a paymentMethodNonce.
• Settlement Flag: Forgetting submitForSettlement: true leaves transactions in an authorized-only state requiring manual capture.

Production Verification Checklist

• Client token generated per checkout session
• 3D Secure 2.0 verification enabled for PSD2 SCA compliance
• Webhook listeners configured for disbursement and dispute notifications