Sandbox User Guide on

Sandbox User Guide

The Sandbox allows Publishers to test and validate their Button integration without impacting live data, a live partnership, or incurring a commission.

In this guide, we'll review the following:

Key Concepts

The Button Sandbox environment enables a Publisher to test a Button integration end-to-end. It also validates that orders placed via Button’s test Merchant on mWeb attribute properly. Within Sandbox, you'll be able to make test purchases & orders for free without incurring commissions or impacting the live environment. All testing data will be separate from live data and visible only in Sandbox mode via the dashboard.

This can be done by completing the following steps:

  • Configuring a Webhook Endpoint
  • Creating a test transaction
  • Verifying the order in your Sandbox Dashboard

Before starting in the Sandbox environment, please ensure the following:

  1. You have a Live Button account that has been configured with the help of our Partner Engineering team.
  2. You have integrated the Button SDK

If you haven’t completed these steps please reach out to your Button Partner Engineering contact.

Where to Find It

Sandbox can be accessed after logging into the Button Dashboard. It can be enabled via a toggle in the upper right hand corner of the page.

Note: Sandbox is currently available for new Publishers only. Please reach out to your Partner Success Manager to enable the feature if the toggle is not visible.

Sandbox User Guide

When you’re in Sandbox Mode, you will only see data affiliated with the test orders and the Button Test Merchant. This environment mirrors your Live Dashboard, so you can find all your information and data in the same places.

Configuring a Webhook Endpoint

  • Login to your dashboard and toggle Sandbox on
  • Go to the Webhooks page in your Sandbox Dashboard and click 'Add a Webhook'
  • Enter in your webhook endpoint URL, and select the three Transaction event types (validating, pending, declined).

Sandbox User Guide

Webhooks allow you to get real-time updates when a user completes an order. Once you configure the destination of the webhook, Button will send you an HTTP POST request for every occurrence of the selected event types. For more information on webhooks, see this guide.

You must use a different Sandbox Webhook endpoint from your Production Webhooks to avoid critical errors in your production environment.

Note: If you currently validate the HMAC signature of webhooks, you'll need to update the HMAC key you validate against as well.

Create Test Transactions

Sandbox App ID

You automatically have a separate Sandbox App ID to start testing in staging. This App ID can be used any time you want to run a new test in Sandbox and is only associated with Button’s Test Merchant.

Note: In your live environment, you will need to utilize your Button apps for iOS, Android and/or mWeb. Your Apps will be associated to your partner Brands once partnerships are approved.

To retrieve your Sandbox App ID, go to the Apps tab in your Sandbox Dashboard and select which App you’d like to use for your sandbox test. You will have different App IDs for iOS, Android, and mobile web.

Once you have the appropriate Sandbox App ID, add it to your iOS, Android, or web application.

Sandbox User Guide

Sandbox User Guide

Setup Button Test Merchant

After integrating the Button SDK, create a Button Purchase Path by passing the URL for the Button Test Merchant to the SDK:

let url = URL(string: "")!
let request = PurchasePathRequest(url: url)
Button.purchasePath.fetch(request: request) { purchasePath, error in
NSURL *url = [NSURL URLWithString:@""];
BTNPurchasePathRequest *request = [BTNPurchasePathRequest requestWithURL:url];
[Button.purchasePath fetchWithRequest:request purchasePathHandler:
^(BTNPurchasePath *purchasePath, NSError *error) {
    [purchasePath start];

Run your Test Application with your Button Sandbox App ID

Once you run your App, you’ll see a Button Test Merchant Button render and you can proceed through a checkout flow.

You will be able to:

  • Tap the Button and make a purchase
  • Test in-app checkout
    • Message your Partner Engineering contact to finalize any test Button Test Merchant transactions; be sure to include the source token (srctok-xxx) for each transaction you want to finalize

Commission rates for the Button Test Merchant can be found on the Partners page of your Button Test Dashboard.

You won't be able to:

  • Use any Brand except the Test Merchant
  • Cancel or return purchases
  • Test app-to-app deeplinking (Note: the process for order reporting does not change with an app-to-app deeplink so this test will validate that flow)

Verify Transaction

Once you’ve completed checkout, check the following:

Simulate Adjusted, Cancelled, and Finalized Transaction Events

Transactions can be updated in three ways:

  1. Adjusted: the transaction can be changed in some way (e.g. partial return)
  2. Cancelled: the transaction can be cancelled/returned
  3. Finalized: the transaction can finalize and no longer be changed

As such, your webhook ingestion service will need to support these flows. To simulate these transactions in Sandbox, please send your Partner Engineering representative Transaction IDs (tx-xxx) for transactions you've generated in Sandbox, as well as what you would like to be done to the transaction (e.g. cancel, adjust, finalize). Your PE rep will update the sandbox transaction accordingly, which will trigger the corresponding webhook to your endpoint.