TealfabricLibrary

Braintree Payment Connector Guide

The Braintree connector helps Tealfabric workflows create and track payment transactions through Braintree. It is suited for checkout orchestration, payment status verification, and post-payment automation such as fulfillment or fraud review workflows.

Document information
FieldValue
Canonical URL/docs/04_connecting-systems/connectors/b/braintree
Version (published date)2026-05-08
Tagsconnectors, reference, braintree
Connector IDbraintree-1.0.0

Braintree connector flow showing credential-authenticated transaction creation, payment status retrieval, and workflow-driven post-payment automation.

Configure merchant credentials

Set merchant_id, public_key, and private_key from your Braintree control panel, then set environment to sandbox for testing or production for live payments. Keep production and sandbox credentials isolated so test traffic never reaches live payment flows.

Set timeout_seconds according to your network conditions and expected request latency. Run test before launching new workflows to confirm credentials and API reachability.

Create transactions with send

Use send when your workflow needs to submit charges, authorize amounts, or complete captures in a payment path. The connector serializes data to Braintree XML and POSTs to transactions by default. Override endpoint when calling another merchant API path.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function createTransaction(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "send",
      endpoint: "transactions",
      data: {
        amount: "49.99",
        payment_method_nonce: "fake-valid-nonce",
        order_id: "ORD-100045",
        options: {
          submit_for_settlement: true
        }
      }
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}
curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "endpoint": "transactions",
    "data": {
      "amount": "49.99",
      "payment_method_nonce": "fake-valid-nonce",
      "order_id": "ORD-100045",
      "options": {
        "submit_for_settlement": true
      }
    }
  }'

{
  "success": true,
  "data": {
    "message": "Braintree transaction processed successfully",
    "result": {
      "transaction": {
        "id": "abc123",
        "status": "submitted_for_settlement",
        "amount": "49.99"
      }
    }
  }
}

Retrieve payment state with receive

Use receive to fetch transaction details by transaction_id (alias id) or by explicit endpoint path relative to /merchants/{merchant_id}/.

{
  "operation": "receive",
  "transaction_id": "abc123"
}

{
  "success": true,
  "data": {
    "message": "Braintree data retrieved successfully",
    "result": {
      "transaction": {
        "id": "abc123",
        "status": "settled",
        "amount": "49.99"
      }
    }
  }
}

Test connectivity with test

test validates credentials by calling GET merchant_accounts and returns the resolved API base URL, merchant ID, and environment.

{
  "success": true,
  "data": {
    "message": "Braintree connection test successful",
    "details": {
      "api_base_url": "https://api.sandbox.braintreegateway.com",
      "merchant_id": "<MERCHANT_ID>",
      "environment": "sandbox"
    }
  }
}

Reliability and compliance guidance

Common failures include credential mismatches, invalid payment method nonces, and environment mix-ups between sandbox and production. Validate credential sets first, then verify you are sending nonce and transaction fields accepted by your account configuration.

For stable payment automation, retry only transient network failures, log transaction IDs for traceability, and keep sensitive card data out of workflow payloads. This approach supports operational reliability and security expectations.

Additional resources