How to test PayPal and Braintree sandbox payments

PayPal and Braintree are often integrated side by side: PayPal Checkout for wallet payments and card fields, Braintree for merchants who want a full card gateway with vaulting and fraud tools. Both are PayPal services and both document their testing on developer.paypal.com, yet their sandboxes work differently. A test plan written for one won’t carry over to the other unchanged, so this guide treats them separately and then combines them into one test matrix.

Two sandboxes, two sets of credentials

The PayPal sandbox is, in PayPal’s words, a self-contained virtual testing environment that simulates the live production environment. You create an app in the developer dashboard, use its sandbox client ID and secret, and call the sandbox API endpoints (api-m.sandbox.paypal.com). Activity there creates mock transactions only.

The Braintree sandbox is a separate account with its own login, merchant ID and API keys. Braintree’s documentation is explicit that the sandbox is an entirely separate environment from production and that nothing created there — processing options, recurring billing settings — transfers to production. Plan to configure both environments independently and to keep their credentials in separate configuration entries.

Set up the PayPal sandbox and test buyers

You create and manage sandbox accounts from the sandbox Accounts page in the developer dashboard. Create at least one business account (the merchant receiving funds) and one personal account (the buyer). To pay with the PayPal wallet in your test checkout, log in to the PayPal pop-up with the personal account’s sandbox credentials. To see the result from the merchant side, log in to the sandbox site at sandbox.paypal.com with the business account and review the mock transactions.

Useful wallet scenarios to cover:

• The buyer approves the payment and your server captures the order.
• The buyer closes the pop-up or cancels — your page must leave the cart intact and allow a retry.
• The capture fails after approval — use negative testing (below) to force it and check that you don’t mark the order as paid.

Test card payments in PayPal Expanded Checkout

Expanded Checkout (also called advanced card payments) renders card fields on your page. In the sandbox, use PayPal’s static test cards with any future expiry date and a three-digit CVV (four digits for American Express). PayPal also offers a credit card generator on its developer site that produces more sandbox cards, which you can add to a sandbox account or use directly.

PayPal lists its 3636… test cards under JCB, although numbers starting with 36 normally belong to Diners Club. If your own brand detection labels them differently, that is expected rather than a bug. More cards are on our PayPal test cards page.

Rejection triggers: forcing card declines

PayPal doesn’t use special card numbers for declines. Instead, enter a rejection trigger in the First Name or Name on Card field. PayPal suggests a Visa such as 4012 8888 8888 1881 with a future expiry and any CVV for these tests. The values are case-sensitive.

The important behavior to test: the order is still created, but the card payment comes back with the status DECLINED. Code that checks only for an HTTP error will treat these as successes. Read the capture status, and for codes such as SUSPECTED_FRAUD, INVALID_OR_RESTRICTED_CARD and LOST_OR_STOLEN — which PayPal marks “try using another card, do not retry the same card” — ask the buyer for a different payment method rather than offering a retry.

Negative testing with the mock-response header

For API-level errors that a card trigger can’t produce, PayPal’s negative testing lets you add a PayPal-Mock-Response header to a sandbox request. The header configures the sandbox to return the error code you name:

PayPal-Mock-Response: {"mock_application_codes": "DUPLICATE_INVOICE_ID"}

PayPal’s own Expanded Checkout sample code includes commented-out mock headers for capture errors such as INSTRUMENT_DECLINED and TRANSACTION_REFUSED. Wire the header behind a test-only flag so it can never be sent from production code.

Test 3D Secure in PayPal

PayPal supports 3D Secure for card fields in countries with a PSD2 compliance mandate. Pass SCA_ALWAYS to trigger authentication on every transaction or SCA_WHEN_REQUIRED to authenticate only when a regional mandate such as PSD2 requires it. The approval callback returns a liability-shift value that your page uses to decide whether to capture.

PayPal’s US purchase-flow test cases include, for Visa:

These cards work only for purchase flows, not for saving a payment method, and PayPal publishes separate cards for other issuing countries. Pick cards from the country you sell in.

Test Braintree transactions with amounts

Braintree’s sandbox works on a simple rule worth memorizing: transaction success is determined by the test amount; verification success is determined by the test card number. So 4111 1111 1111 1111 succeeds at 10.00 and is declined at 2001.00. Only documented test numbers are accepted — a random Luhn-valid number from a generator is not a Braintree test card.

Because the response code equals the amount, a handful of amounts covers the declines most checkouts need to distinguish:

import braintree, os

gateway = braintree.BraintreeGateway(braintree.Configuration(
    braintree.Environment.Sandbox,
    merchant_id=os.environ['BT_MERCHANT_ID'],
    public_key=os.environ['BT_PUBLIC_KEY'],
    private_key=os.environ['BT_PRIVATE_KEY'],
))

for amount in ('10.00', '2000.00', '2001.00', '2004.00', '3000.00'):
    result = gateway.transaction.sale({
        'amount': amount,
        'payment_method_nonce': 'fake-valid-nonce',   # documented test nonce: a valid card
        'options': {'submit_for_settlement': True},
    })
    tx = result.transaction
    print(amount, result.is_success, tx.processor_response_code if tx else result.message)

Failed verifications, card types and fraud tools

When you vault a card with verification enabled, the card number decides the outcome. Braintree documents cards that make verification fail, such as 4000 1111 1111 1115 (Visa, processor declined) and 3566 0020 2036 0505 (JCB, failed with 3000). These numbers don’t change transaction outcomes, which still follow the amount.

Other test cards return specific card-type indicators, which is useful if your logic treats prepaid, debit or commercial cards differently:

• 4012 0043 3850 8385 — prepaid “Yes” and debit “Yes”
• 4009 0400 0000 0009 — commercial “Yes”
• 4012 0000 3333 0125 — debit “Yes”

For Braintree’s fraud tools, 4000 1111 1111 1511 is gateway-rejected with the reason fraud, and 4111 1300 0000 0003 is rejected with risk_threshold. Braintree notes you can’t tweak sandbox settings to reject transactions; you use these specific values instead.

CVV and AVS rules in the Braintree sandbox

Security code and postal code values produce specific response codes, but they only trigger a rejection if you have AVS and CVV rules enabled in your sandbox. If a CVV test “does nothing”, check the rules before debugging your code.

Any other CVV or postal code returns M (matches). For background on what these codes check, see our guide to CVV, CVC and CID security codes.

Test 3D Secure 2 in Braintree

Braintree’s 3D Secure test cards have one strict requirement: the expiry month must be 01 and the year must be the current year + 3. Other dates won’t produce the documented results. Braintree also recommends disabling ad blockers during these tests, because they can block the device data collection 3D Secure relies on.

To test what happens when you skip authentication, create a sandbox transaction for 2099.00: it simulates the 2099 “Cardholder Authentication Required” soft decline that issuers send when 3D Secure wasn’t performed. The full list of 3DS cards is on our Braintree test cards page, and our 3-D Secure testing guide compares outcomes across gateways.

A combined test matrix

If your checkout offers both PayPal and Braintree, run the same business scenarios through each, using the mechanism each sandbox provides:

For every row, check the same three things: what the buyer sees, what your order record says, and what your logs contain. Logs should show the transaction ID and response code — never the full card number. Our guide to test data and PCI DSS explains how to keep real card data out of test systems entirely.