Create a sandbox account

If you haven't already, sign up for a free Braintree sandbox account:

Sign Up for a Braintree Sandbox Account

Log in to obtain your sandbox API credentials. You'll need your:

  • Sandbox Merchant ID
  • Public Key
  • Private Key

Use these credentials for your development and testing.

When you go live, you will need to replace your sandbox API credentials with production API credentials.

Install and configure

Add the braintree gem to your project's Gemfile:

Ruby
gem "braintree"

Supports ruby 1.8 (>= 1.8.6), 1.9, and 2.0

And run bundle install to install it.

See also

In your code, configure the environment and API credentials:

Ruby
Braintree::Configuration.environment = :sandbox
Braintree::Configuration.merchant_id = "use_your_merchant_id"
Braintree::Configuration.public_key = "use_your_public_key"
Braintree::Configuration.private_key = "use_your_private_key"

Generate a client token

Your server is responsible for generating a client token, which contains all authorization and configuration information your client needs to initialize the client SDK to communicate with Braintree. Including a customerId when generating the client token lets returning customers select from previously used payment method options, improving user experience over multiple checkouts. Set Up Your Client covers the client side of the exchange.

If you are creating SEPA transactions, you will need to create a customer and include a customer_id in your request.

Send a client token to your client

Here is an example of how your server would generate and expose a client token:

Ruby
get "/client_token" do
  Braintree::ClientToken.generate
end

How the token is used by the client may vary. In JavaScript integrations the client token is often included in the generated HTML/JS, while in mobile apps the client token must be requested. These methods are discussed in the client token setup section.

Receive a payment method nonce from your client

Once your client successfully obtains a customer payment method, it receives a payment_method_nonce representing customer payment authorization, which it then sends to your server.

Your server implementation is then responsible for receiving the payment_method_nonce and using it appropriately.

Ruby
post "/checkout" do
  nonce = params[:payment_method_nonce]
  # Use payment method nonce here...
end

Create a transaction

You can create a transaction using a payment_method_nonce and an amount:

Ruby
result = Braintree::Transaction.sale(
  :amount => "100.00",
  :payment_method_nonce => nonce_from_the_client
)

The sale call returns a Transaction Result Object which contains the transaction and information about the request.

See below for test values for nonce_from_the_client to use against your sandbox account. To verify your integration, you can check in the sandbox Control Panel, where transactions will immediately appear on success.

Testing in sandbox

Develop and test your code against your sandbox account before processing live transactions against a production account.

Braintree's sandbox environment provides test values (card numbers, amounts, CVVs, and postal codes) for you to simulate transactions with validated cards.

Test values

In order to simplify testing your server side code, the Braintree library provides static payment_method_nonce values for you to use in the Braintree sandbox.

Valid nonces

Nonce Description
fake-valid-nonce A valid nonce that can be used to create a transaction
fake-valid-visa-nonce A nonce representing a valid Visa card request
fake-valid-amex-nonce A nonce representing a valid American Express card request
fake-valid-mastercard-nonce A nonce representing a valid Mastercard request
fake-valid-discover-nonce A nonce representing a valid Discover card request
fake-valid-jcb-nonce A nonce representing a valid JCB card request
fake-valid-maestro-nonce A nonce representing a valid Maestro card request
fake-valid-dinersclub-nonce A nonce representing a valid Diners Club card request
fake-valid-prepaid-nonce A nonce representing a valid prepaid card request
fake-valid-commercial-nonce A nonce representing a valid commercial card request
fake-valid-durbin-regulated-nonce A nonce representing a valid Durbin regulated card request
fake-valid-healthcare-nonce A nonce representing a valid healthcare card request
fake-valid-debit-nonce A nonce representing a valid debit card request
fake-valid-payroll-nonce A nonce representing a valid payroll card request

Valid nonces with card info

Nonce Description
fake-valid-no-indicators-nonce A nonce representing a request for a valid card with no indicators
fake-valid-unknown-indicators-nonce A nonce representing a request for a valid card with unknown indicators
fake-valid-country-of-issuance-usa-nonce A nonce representing a request for a valid card issued in the USA
fake-valid-country-of-issuance-cad-nonce A nonce representing a request for a valid card issued in Canada
fake-valid-issuing-bank-network-only-nonce A nonce representing a request for a valid card with the message 'Network Only' from the issuing bank

Alternate payment method nonces

Nonce Description
fake-android-pay-nonce A nonce representing an Android Pay request
fake-android-pay-visa-nonce A nonce representing an Android Pay Visa request
fake-android-pay-mastercard-nonce A nonce representing an Android Pay Mastercard request
fake-android-pay-amex-nonce A nonce representing an Android Pay American Express request
fake-android-pay-discover-nonce A nonce representing an Android Pay Discover request
fake-apple-pay-amex-nonce A nonce representing an Apple Pay request for an American Express card number
fake-apple-pay-visa-nonce A nonce representing an Apple Pay request for an Visa card number
fake-apple-pay-mastercard-nonce A nonce representing an Apple Pay request for an MasterCard card number
fake-coinbase-nonce A nonce representing a Coinbase account
fake-paypal-one-time-nonce A nonce representing an unvaulted PayPal account that a user has authorized for the one time payment flow. You can use any email address and password you like when testing PayPal in Sandbox, but there are some restrictions to consider if doing end-to-end testing.
fake-paypal-future-nonce A nonce representing an unvaulted PayPal account that a user has authorized for the future payment flow. You can use any email address and password you like when testing PayPal in Sandbox, but there are some restrictions to consider if doing end-to-end testing.

Invalid nonces

The following payment method nonces will simulate an unsuccessful verification response. Verifying a payment method is different than creating a transaction. To trigger an unsuccessful transaction, adjust the amount of the transaction.

Processor rejected nonces

Nonce Description
fake-processor-declined-visa-nonce A nonce representing a request for a Visa card that was declined by the processor
fake-processor-declined-mastercard-nonce A nonce representing a request for a Mastercard that was declined by the processor
fake-processor-declined-amex-nonce A nonce representing a request for a American Express card that was declined by the processor
fake-processor-declined-discover-nonce A nonce representing a request for a Discover card that was declined by the processor
fake-processor-failure-jcb-nonce A nonce representing a request for a JCB card that was declined by the processor

Gateway rejected nonces

Nonce Description
fake-luhn-invalid-nonce A nonce representing a Luhn-invalid card
fake-consumed-nonce A nonce that has already been consumed
fake-gateway-rejected-fraud-nonce A fraudulent nonce

When writing integrations tests against the Braintree sandbox environment, you may also use these nonce objects in place of the nonce that would normally be returned from the client side integration.

Ruby
Braintree::Test::Nonce::Transactable
Braintree::Test::Nonce::Consumed
Braintree::Test::Nonce::PayPalOneTimePayment
Braintree::Test::Nonce::PayPalFuturePayment

Conclusion

At this point, you should be able to accept a payment method nonce and create a transaction in our sandbox. When you're ready to start charging real money, transition over to our production environment. We'll explain that process next.

Next: Go Live →

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or email our Support team.