What we do
Tools
Industries
Department
How we workLet's talk →
Home/Braintree/Which Braintree API to Call
Braintree developers

How a Braintree API Charge Actually Happens, Token to Settlement

The card form gets the attention, but every Braintree charge is decided on your server. It hands the browser or app a client token, gets back a single-use nonce, and charges that nonce through one of two interfaces: a server SDK, or the GraphQL API. The choice changes how you authenticate and what your code looks like. It barely changes what you can do with the money.

Which Braintree interface fits what you are building

You are building Reach for Watch for
A backend in Java, .NET, Node.js, PHP, Python or Ruby That language's server SDK, configured with the environment, merchant ID, public key and private key. The private key stays in server config. Keep the SDK version current, since that's how you get API changes.
A backend in another language, or a team that already works in GraphQL The GraphQL API: one POST endpoint, payments.braintree-api.com/graphql, with payments.sandbox.braintree-api.com/graphql for testing. Auth is Basic with public:private Base64-encoded, and every request needs a Braintree-Version header holding a date like 2019-01-01.
A card form on the web The JavaScript SDK components, such as Hosted Fields, which keep card inputs in iframes Braintree hosts. Drop-in is deprecated. Our Braintree hub covers what moving off it involves.
A native iOS or Android app Braintree's mobile SDKs, which take the same client token your server already generates. The app still sends the nonce to your server. Charging never happens from the device.
Server SDK code moving to GraphQL A gradual move, one operation at a time. IDs aren't interchangeable. Braintree's migration guide has a section on legacy versus GraphQL IDs, so plan for stored transaction IDs.

Client token to a settled Braintree charge

  1. 1

    Your server generates a client token

    The front end asks your server for one, and the server SDK creates it. Pass a customer ID when you want that customer's saved payment methods on offer.

  2. 2

    The client SDK turns card details into a nonce

    The customer types into Braintree-hosted fields, the client SDK sends the details to Braintree, and your page gets back a payment method nonce to post to your server.

    Watch for: a nonce works once and expires three hours after it's created. It isn't a saved card.

  3. 3

    Your server charges the nonce

    With a server SDK, that's a transaction sale, with the option to submit for settlement straight away. On GraphQL, chargePaymentMethod captures immediately, while authorizePaymentMethod places a hold you capture later with captureTransaction.

  4. 4

    Vault it if you will charge again

    For renewals, top-ups or a stored card on file, save the nonce to the vault and keep the payment method token it returns. Future charges use that token, not a nonce.

  5. 5

    Follow the status through to settled

    A sale moves from Authorized to Submitted for settlement, then Settling, then Settled. PayPal, Venmo and ACH transactions can sit in Settlement pending for a while, which is normal.

    Watch for: an authorization that's never submitted expires. For Visa that's 8 days by default, for a Mastercard final authorization 7 days.

Past the charge: capture, postings and stored cards

The API tells you a transaction was authorized or settled. It doesn't know that a held order just shipped, that a refund belongs to a particular invoice, or that a support rep is looking at an out-of-date card on a CRM record. For things that happen later, like a dispute opening or a subscription charging, Braintree posts a signed webhook that your code parses with the server SDK before acting on it.

n-frames builds the parts around a working Braintree integration: a capture job driven by your fulfillment system, settled transactions posted to your accounting system with each refund tied to its sale, and vaulted payment method changes carried to the CRM record that refers to them. The test plan for all of it runs in the sandbox first.

Braintree API mistakes that show up a week after launch

Holds placed, never captured

How you'll know: Transactions pile up as Authorized, then flip to Authorization expired, and the money never arrives.

Fix: Submit for settlement at charge time, or run a job that captures when the order ships, well inside the card's expiry window.

Voiding a sale that is already settling

How you'll know: A cancel request fails for an order you're trying to call back.

Fix: Voids only work before Settling. After that, refund the transaction instead, and have your code check the status first.

Storing the nonce as if it were the card

How you'll know: The first charge works and the next month's renewal fails.

Fix: Nonces are single use. Vault the payment method and store the token it gives you.

GraphQL calls with no version header

How you'll know: Requests that look right are rejected before they do anything.

Fix: Add Braintree-Version with a fixed date to every request. Braintree suggests the date you started integrating.

Braintree API questions from developers

Does Braintree have a sandbox for testing the API?

Yes. It's a separate gateway with its own merchant ID and keys: set your server SDK's environment to Sandbox, or call the GraphQL sandbox endpoint. The test card numbers and the amounts that trigger each decline are on our Braintree sandbox page.

What's the difference between Drop-in UI and Hosted Fields?

Drop-in was a ready-made payment form with cards and wallets in one box. Hosted Fields gives you individual card fields you lay out and style yourself, each sitting in a Braintree iframe so card numbers never touch your code. Braintree has deprecated Drop-in, so new builds should use Hosted Fields or the other JavaScript SDK components.

Does Braintree have a GraphQL API?

Yes, alongside the server SDKs. It's a single endpoint you POST to, authenticated with your Base64-encoded public and private keys, and every request carries a Braintree-Version date header.

Is there a Braintree SDK for mobile apps?

Braintree has mobile SDKs for both iOS and Android. They collect payment details in the app and return a nonce, which your server then charges with a server SDK or GraphQL.

Where do I find Braintree's API docs?

On PayPal's developer site: the SDK guides and reference sit under developer.paypal.com/braintree/docs, and the GraphQL guides and schema under developer.paypal.com/braintree/graphql. Older braintreepayments.com links redirect there.

How long does a Braintree payment method nonce last?

Three hours, and it can be used only once. To charge the same card again later, vault it and keep the payment method token.

Who can build on the Braintree API for our business?

That's work n-frames takes on for businesses already processing through Braintree: capture tied to shipping, settled transactions posted to accounting, and stored card changes reflected in your CRM, all tested in the sandbox before it touches live charges.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.