What we do
Tools
Industries
Department
How we workLet's talk →
Home/Braintree/Braintree Sandbox
Braintree developer guide

The Braintree Sandbox: Credentials, Test Cards, and Forcing a Decline

The Braintree sandbox is a whole separate gateway, with its own login, merchant ID and API keys, where no real card is ever charged. Below is the setup from sign-up to a first transaction, the test values that make it fail on purpose, how to test webhooks, and what changes when you switch to production.

Sign-up to a first sandbox transaction

  1. 1

    Open a free sandbox account

    Sign up for a free sandbox account through Braintree's developer site. It isn't tied to a live merchant account, and you can use it right away.

    Watch for: the sandbox's business country defaults to the country you sign up from. Change it before you submit if you're testing for another market.

  2. 2

    Generate the API keys

    Gear icon API Generate New API Key

    Copy the merchant ID, public key and private key. The private key belongs in your server's environment variables, never in front-end code.

    Watch for: you need admin rights on the sandbox account to see the keys.

  3. 3

    Point the SDK at the sandbox

    Set the environment to Sandbox in the server SDK's gateway config and pass the three values. The sandbox Control Panel lives at sandbox.braintreegateway.com. Production keys won't work against the sandbox, and sandbox keys won't work in production.

  4. 4

    Run a sale without building the front end

    Use the nonce fake-valid-nonce as the payment method on a sale for an amount like 10.00. Card-specific versions exist too, such as fake-valid-visa-nonce, plus fake-venmo-account-nonce and Apple Pay or Google Pay test nonces.

  5. 5

    Then try a real card form

    In Drop-in or Hosted Fields, enter a test card: Visa 4111111111111111, Mastercard 5555555555554444, Amex 378282246310005 or Discover 6011000991300009, with any future expiry date.

    Watch for: a valid test card doesn't guarantee approval. The amount, CVV and postal code all change the result.

Test amounts and values that force each outcome

Send this Sandbox returns Use it to test
Any amount from 0.01 to 1999.99 Authorized and settled Your success path and receipt.
2000.00 to 2999.99 Processor declined, with the response code matching the amount (2001.00 gives 2001) Each decline message your customer could see, one code at a time.
3000.00 to 3000.99 Failed with processor response 3000 Processor outages: retry or queue, not a decline message.
5001.00 Gateway rejected (application incomplete) Errors that come from the gateway rather than the bank.
Card 4023898493988028 A disputed transaction Your Dispute Opened webhook handler.
Nonce fake-processor-declined-visa-nonce A declined card verification Saving a card to the vault that the bank refuses.

What a passing sandbox suite still hasn't proven

The webhook handler only knows the kinds you tested

How you'll know: Sample notifications from webhookTesting.sampleNotification() parse fine, but the handler assumes every event is a subscription.

Fix: Handle unknown kinds without throwing. Braintree warns that pointing Check URL at a production endpoint sends a test kind your code may not expect.

Sample notifications carry dummy objects

How you'll know: Code that reads fields off the webhook body works in tests and returns blanks on real events.

Fix: Use the webhook as a signal, then look up the full transaction or subscription from the gateway by ID before acting on it.

Overlapping money events never appear in test

How you'll know: No test covers a partial refund during an open dispute window, or a vaulted card expiring mid-subscription.

Fix: Write those cases down and build an explicit response for each. Run the first live ones under supervision.

Sandbox settings left behind

How you'll know: Plans, add-ons, merchant accounts or fraud rules that worked in sandbox are missing after launch.

Fix: Nothing configured in sandbox transfers to production. Recreate each setting in the production Control Panel and keep a list so none get skipped.

Braintree sandbox questions

How do I get Braintree sandbox access?

Sign up for a sandbox account on Braintree's developer site. It's free, separate from any live merchant account, and gives you a merchant ID and API keys as soon as you log in.

Do I log into the sandbox the same way as production?

No. The sandbox has its own login page at sandbox.braintreegateway.com and its own username, password, merchant ID and API keys. Nothing is shared between sandbox and production data.

What test card numbers does Braintree sandbox support?

Braintree publishes a list in its developer docs: 4111111111111111 for Visa and 5555555555554444 for Mastercard are the usual starting points, plus Amex, Discover, JCB, Maestro and UnionPay numbers. The transaction amount decides whether a test card is approved or declined.

Can I test webhooks in the Braintree sandbox?

Yes, from code or from the Control Panel. In code, gateway.webhookTesting.sampleNotification() builds a signed sample you pass to your parser. In the Control Panel, go to the gear icon, then API, then Webhooks, and click Check URL to send a test to your endpoint. Your endpoint has to be reachable from the internet, so local development needs a tunnel.

What is fake-valid-nonce?

A test payment method nonce that sandbox accepts as a valid card, so you can create a transaction from your server without rendering a card form. It only works in sandbox.

How do I move from sandbox to production?

Production is a separate merchant account with its own credentials. Swap in the production merchant ID and keys, change the SDK environment, recreate every plan and setting, and register your webhook URLs again in the production Control Panel.

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.