Required dependencies

npm install user@example.com
npm install @braintree/wrap-promise
npm install dateformat
npm install xml2js

No native modules, pod installs, or binary linking steps are required. Node >= 10 is the only runtime constraint.

Project setup

1. Copy the source/ directory into your project, e.g. src/vendor/braintree/.
2. If using TypeScript, add a path alias in tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "braintree-sdk/*": ["src/vendor/braintree/*"]
       }
     }
   }
   

3. Set the following environment variables (never commit credentials):

   BRAINTREE_ENVIRONMENT=Sandbox
   BRAINTREE_MERCHANT_ID=your_merchant_id
   BRAINTREE_PUBLIC_KEY=your_public_key
   BRAINTREE_PRIVATE_KEY=your_private_key
   

4. Instantiate the gateway once at application startup and share the instance:

   import { BraintreeGateway, Environment } from "braintree";
   export const gateway = new BraintreeGateway({
     environment: Environment[process.env.BRAINTREE_ENVIRONMENT as keyof typeof Environment],
     merchantId: process.env.BRAINTREE_MERCHANT_ID!,
     publicKey: process.env.BRAINTREE_PUBLIC_KEY!,
     privateKey: process.env.BRAINTREE_PRIVATE_KEY!,
   });
   

5. Import individual gateways from the shared instance (gateway.transaction, gateway.customer, etc.) — do not construct them directly.

Public API

BraintreeGateway

class BraintreeGateway {
  constructor(config: {
    environment: Environment;
    merchantId: string;
    publicKey: string;
    privateKey: string;
  });
  clientToken: ClientTokenGateway;
  transaction: TransactionGateway;
  customer: CustomerGateway;
  paymentMethod: PaymentMethodGateway;
  subscription: SubscriptionGateway;
  dispute: DisputeGateway;
  webhookNotification: WebhookNotificationGateway;
}

The root object. Instantiate once per process with merchant credentials. All sub-gateways are accessed as properties; never import sub-gateways directly.

Environment

const Environment: {
  Sandbox: Environment;
  Production: Environment;
  Development: Environment;
};

Selects the API endpoint. Always use Environment.Sandbox during development and Environment.Production for live traffic. Passing a plain string will cause silent connection errors.

GraphQL (graphql/index.js)

class GraphQL {
  // Internal GraphQL transport used by customer session and recommendation gateways
}

// Enums
const RecommendedPaymentOption: Record<string, string>;
const Recommendations: Record<string, string>;

// Inputs
class CreateCustomerSessionInput { /* fields for session creation */ }
class UpdateCustomerSessionInput { /* fields for session update */ }
class CustomerRecommendationsInput { /* fields for fetching recommendations */ }

Used by CustomerSessionGateway to issue typed GraphQL mutations and queries. Use RecommendedPaymentOption and Recommendations enum values when interpreting recommendation payloads rather than comparing raw strings.

Working examples

Scenario - Generate a client token for front-end initialization

The Braintree JS Drop-in UI requires a short-lived client token. Generate it server-side and send it to the client on page load.

import { BraintreeGateway, Environment } from "braintree";

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

async function getClientToken(customerId?: string): Promise<string> {
  const params = customerId ? { customerId } : {};
  const response = await gateway.clientToken.generate(params);
  return response.clientToken;
}

// Express route example
// app.get("/client_token", async (req, res) => {
//   const token = await getClientToken();
//   res.json({ clientToken: token });
// });

Scenario - Create a transaction and submit for settlement

Accept a payment method nonce from the client SDK and charge the customer immediately.

import { BraintreeGateway, Environment } from "braintree";

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

async function chargeNonce(nonce: string, amountUsd: string): Promise<string> {
  const result = await gateway.transaction.sale({
    amount: amountUsd,
    paymentMethodNonce: nonce,
    options: { submitForSettlement: true },
  });

  if (!result.success) {
    throw new Error(result.message);
  }
  return result.transaction.id;
}

chargeNonce("fake-valid-nonce", "29.99").then((id) =>
  console.log("Transaction ID:", id)
);

Scenario - Create or find a customer and vault a payment method

Store a customer record with a vaulted payment method for future charges.

import { BraintreeGateway, Environment } from "braintree";

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

async function upsertCustomer(
  email: string,
  nonce: string
): Promise<{ customerId: string; paymentMethodToken: string }> {
  const result = await gateway.customer.create({
    email,
    paymentMethodNonce: nonce,
  });

  if (!result.success) {
    throw new Error(result.message);
  }

  const customer = result.customer;
  const token = customer.paymentMethods[0].token;
  return { customerId: customer.id, paymentMethodToken: token };
}

File walkthrough

• graphql/ - Houses the GraphQL transport class, input/type/union definitions, and enum constants used exclusively by customer session and recommendation GraphQL endpoints.
• braintree_gateway.js - Root entry point; constructs and exposes all sub-gateways as named properties from a single config object.
• config.js - Validates and stores merchant credentials and the chosen Environment; consumed internally by http.js and graphql_client.js.
• environment.js - Defines Sandbox, Production, and Development environment objects with their respective API hostnames and ports.
• http.js - Low-level REST transport: builds authenticated HTTPS requests, parses XML responses via xml2js, handles retries and errors.
• graphql_client.js - Separate HTTP transport for GraphQL endpoints; handles JWT auth headers and JSON request/response bodies.
• gateway.js - Abstract base class providing shared utilities (response parsing, error wrapping) inherited by all concrete gateways.
• advanced_search.js - Provides fluent field builders (textField, rangeField, multipleValueField) used to construct search payloads.
• paginated_response.js / paginated_response_stream.js - Wraps multi-page API responses; paginated_response_stream.js returns a Node.js Readable stream for large result sets.
• error_response.js - Wraps raw API validation error trees into structured objects with .errors.deepErrors() enumeration.
• exceptions.js - Exports named exception classes (AuthenticationError, AuthorizationError, NotFoundError, etc.) for typed error handling.
• digest.js - HMAC-SHA1 utility used by the webhook gateway to verify incoming webhook signatures.
• customer_session_gateway.js - Uses graphql_client.js to create/update customer sessions and fetch payment recommendations.
• disbursement_gateway.js - Queries disbursement records associated with a transaction ID.
• document_upload_gateway.js - Multipart file upload for dispute evidence documents.
• exchange_rate_quote_gateway.js - Fetches real-time FX quotes via GraphQL for multi-currency transactions.
• oauth_gateway.js - Handles OAuth token creation, refresh, and revocation for Braintree partner integrations.

Common pitfalls and fixes

• Wrong Environment value at runtime: Passing a raw string like "Sandbox" instead of Environment.Sandbox produces connection errors; always use the Environment object constants.
• Shared gateway instance not reused: Constructing new BraintreeGateway(...) per request causes connection overhead and credential parsing on every call; create once at startup and export the singleton.
• xml2js version mismatch: xml2js >= 0.5 changed its default explicitArray behavior; pin xml2js to the version declared in the upstream package.json to avoid response parse failures.
• Search methods do not return Promises: gateway.transaction.search(...) returns a stream, not a Promise; calling .then() on it throws silently — use the stream's data/end events or collect with a helper.
• Webhook signature verification skipped: Always call gateway.webhookNotification.verify(signature, payload) before trusting webhook data; skipping this check opens the endpoint to spoofed events.
• Missing environment variables in production: BRAINTREE_PRIVATE_KEY left undefined causes AuthenticationError on the first request; validate all four env vars at application startup and fail fast.

Vibe-coding prompt template

I have copied the Braintree Node.js SDK source (braintree@3.36.0) into
`src/vendor/braintree/` in my project. The integration guide is in USAGE.md.

Please integrate this SDK into my existing project step by step:

1. Read USAGE.md and the file structure under `source/` to understand all
   available exports (BraintreeGateway, Environment, customer gateway,
   transaction gateway, GraphQL inputs/types, etc.).

2. Create a `src/lib/braintreeClient.ts` singleton that initializes
   BraintreeGateway from environment variables following the pattern in USAGE.md.

3. Add an Express route `POST /payments/checkout` that accepts
   `{ nonce, amount }` in the request body, calls `gateway.transaction.sale`,
   and returns the transaction ID or a structured error.

4. Add an Express route `GET /payments/client-token` that returns a fresh
   client token, optionally scoped to a `customerId` query param.

5. Wire up webhook signature verification on `POST /webhooks/braintree` using
   `gateway.webhookNotification.verify` and log the parsed notification kind.

6. Use only the real exports visible in USAGE.md and `source/` — do not
   invent method names. Use async/await throughout. Handle errors by checking
   `result.success` and throwing typed exceptions from `source/exceptions.js`.

License and credit

The Braintree Node.js SDK is released under the MIT License (see source/LICENSE if present in this block, or the upstream repository). Upstream package: braintree on npm — source repository: github.com/braintree/braintree_node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

Hướng dẫn cài đặt đầy đủ và prompt tích hợp sẽ mở khóa sau khi mua.

Checkout.com Official Node.js Payment SDK

eCommerce, Marketplace & POS Systems

Miễn phí