canonical: https://jentic.com/apis/braintreepayments.com/braintreepayments

# Braintreepayments Braintree GraphQL API

The Braintree GraphQL API is PayPal's payment processing platform exposed as a single GraphQL endpoint, supporting credit cards, PayPal, Venmo, Apple Pay, Google Pay, Samsung Pay, US bank accounts, and local payment methods. All operations are submitted as POST requests to /graphql with a JSON body containing a GraphQL query or mutation plus variables. The API covers tokenizing payment instruments, charging and authorizing transactions, capturing and refunding, managing customers and payment methods, and running searches across the merchant's transaction history. It is designed for online merchants and platforms that need a unified payments backend across cards and alternative payment methods.

## For AI agents

Tokenize payment methods and charge cards, PayPal, Venmo, and digital wallets through Braintree's GraphQL endpoint, with refunds, captures, and customer management in one mutation surface.

## Scope

Does not handle accounting, tax filing, payroll, or invoicing - use for processing card, wallet, and bank payments only.

## Capabilities

- Charge a card or PayPal account by sending a chargePaymentMethod mutation to POST /graphql
- Authorize a payment and capture it later via authorizePaymentMethod and captureTransaction mutations
- Refund a settled transaction in full or partially with the refundTransaction mutation
- Tokenize raw card details into a single-use payment method via tokenizeCreditCard before charging
- Vault customers and their payment methods so subsequent charges run against a stored token
- Search transactions, customers, and disputes by id, status, or date range using GraphQL queries
- Issue a client token for the Drop-in or hosted fields UI via createClientToken

## Use cases

### E-commerce checkout with cards and wallets

Accept payments on a storefront across credit cards, PayPal, Venmo, Apple Pay, and Google Pay through one Braintree GraphQL endpoint. The frontend collects a payment method via Drop-in or hosted fields, the backend exchanges it for a single-use token, and a chargePaymentMethod mutation posts the charge in one round trip. Settlement, fraud screening, and 3D Secure are handled by Braintree behind the scenes.

Example prompt: Send a chargePaymentMethod mutation to POST /graphql with a single-use token and amount '49.99' USD, then read transaction.status from the response to confirm SUBMITTED_FOR_SETTLEMENT.

### Authorize-then-capture for shippable goods

Hold funds on a buyer's card at checkout and only capture them when the order ships. The merchant sends authorizePaymentMethod for the order amount, then captureTransaction once the warehouse confirms dispatch. This avoids charging customers for items that turn out to be out of stock and limits exposure to refund fees on cancellations.

Example prompt: Call authorizePaymentMethod for amount '120.00', store the returned transaction.id, then on shipment call captureTransaction with that id and amount '120.00'.

### Refunds and dispute resolution

When a customer requests a refund, send refundTransaction with the original transaction id and the amount to return. For partial refunds, pass a smaller amount; the API handles the linkage to the parent transaction and returns the refund's settlement status. Disputes can be looked up via the dispute search query to inspect status and evidence requirements.

Example prompt: Send refundTransaction with transactionId={original_id} and amount '25.00' to POST /graphql and confirm refund.status is SUBMITTED_FOR_SETTLEMENT in the response.

### Vaulted customer with stored payment methods

Create a Braintree customer record, attach one or more payment methods, and charge that vaulted method on subsequent orders without re-collecting card data. This is the foundation for one-click checkout, subscriptions, and account-on-file billing, and keeps card data inside Braintree's PCI scope rather than the merchant's.

Example prompt: Run createCustomer with email and name, then chargePaymentMethod against the returned customer's vaulted paymentMethod.id for amount '14.99'.

### AI agent integration via Jentic

An agent that needs to take a payment can discover Braintree through Jentic search, load the GraphQL operation schema, and execute the chargePaymentMethod mutation without ever holding the merchant's API keys in its context. Jentic injects credentials at runtime so the agent only sees inputs and outputs.

Example prompt: Through Jentic, search for 'process a credit card payment', load the chargePaymentMethod operation, and execute it with paymentMethodId and amount supplied by the caller.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /graphql | Single GraphQL endpoint for all queries and mutations (charge, refund, vault, search) |

## Key resources

- **GraphQL endpoint** — All Braintree operations are POST requests to /graphql with a query or mutation in the body - transactions, customers, payment methods, refunds, and disputes are all reached through this single URL.

## Why Jentic

- **Setup:** Wiring Braintree by hand means choosing basic auth with your public and private key or a bearer token, picking the production or sandbox host, and learning its GraphQL schema before you can charge a card. Through Jentic you install once, import the Braintree GraphQL API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Braintree exposes a single /graphql endpoint where the operation lives in the request body, so scope the agent to the operations it needs, such as charging a payment method, and leave out ones like refunding a transaction unless the agent requires them. Every operation you allow is one you have explicitly chosen.
- **Credential handling:** Your Braintree public and private key pair and any OAuth bearer token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'process a credit card payment' or 'refund a transaction', and Jentic returns the matching Braintree GraphQL operation with its input variables typed so the agent calls the right operation without learning the GraphQL schema.

## Related APIs

- **Braze API** — Trigger Braze customer messages when a Braintree transaction succeeds, fails, or is refunded
- **Breadcrumbs API** — Score lead and customer fit based on Braintree purchase activity captured by Breadcrumbs
- **Breeze API** — Sync Braintree customer and order data into Breeze CRM contact records

## FAQ

### What authentication does the Braintree GraphQL API use?

The API supports HTTP bearer tokens (OAuth access tokens or client tokens) and HTTP basic auth using base64-encoded public_key:private_key. Through Jentic, those keys live in the encrypted vault and are attached to the Authorization header on POST /graphql at execution time, so they never appear in agent prompts.

### Can I refund a transaction with the Braintree GraphQL API?

Yes. Send a refundTransaction mutation to POST /graphql with the original transaction id and an optional amount for partial refunds. The response returns refund.id and refund.status, which moves to SUBMITTED_FOR_SETTLEMENT once Braintree queues it.

### What payment methods does the Braintree GraphQL API support?

Credit and debit cards, PayPal, Venmo, Apple Pay, Google Pay, Samsung Pay, US bank accounts (ACH), and local payment methods. They are all charged through the same chargePaymentMethod mutation by passing the appropriate single-use token or vaulted payment method id.

### What are the rate limits for the Braintree GraphQL API?

Braintree does not publish a public per-endpoint rate limit - quotas are tied to merchant account configuration. For high-volume processing, contact Braintree support to confirm thresholds and enable burst handling on /graphql.

### How do I charge a card with the Braintree GraphQL API through Jentic?

Install the SDK with pip install jentic, then await client.search('process a credit card payment'), await client.load on the chargePaymentMethod operation, and await client.execute with paymentMethodId and amount. Jentic posts the GraphQL mutation to /graphql with vaulted credentials.

### Does the Braintree GraphQL API support sandbox testing?

Yes. Point requests at https://sandbox.braintreegateway.com instead of the production base URL and use sandbox merchant credentials. The schema and mutations are identical, so the same chargePaymentMethod and refundTransaction calls work end-to-end.

### Can I limit what my agent is allowed to do with the Braintree GraphQL API?

Yes. Braintree exposes a single /graphql endpoint where the actual operation lives in the request body, and because Jentic One is self-hosted, your own rules decide which of those operations the agent may call. You can allow only what a task needs, such as chargePaymentMethod for taking a payment, while leaving out operations like refundTransaction unless the agent genuinely requires them. Your Braintree public and private key pair and any OAuth bearer token stay stored and encrypted on your own instance and are attached to the request only at execution time, so the agent never sees them.