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.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Checkout.com Official Node.js Payment SDK

eCommerce, Marketplace & POS Systems

無料