Testing your program in sandbox

The Apto platform was designed to help you quickly prove out a concept and/or experiment with new card products. We’re excited about what you and the community of developers will build using the turnkey Instant Issuance program!

Creating your developer account#

To create an account with Apto, we ask you to provide your name, the name of your company, and your work email address. After you verify your email address and set up two-factor authentication, you will have immediate access to our sandbox environment and can log into the developer dashboard. Learn more about using the dashboard.


When you first log into Apto, you will land in our sandbox environment. sandbox is a simulated replica of our production environment, where you can interact with our full suite of developer tools, regardless of your Payment Card Industry Data Security Standard (PCI DSS) compliance status. The intent is to allow you to explore what’s possible.

You can create cardholders, issue cards, fund cardholder accounts, and see what it is like to monitor card program activity. You can also simulate actions that would normally be carried out by cardholders themselves, like initiating transactions. When you land in sandbox, your Funding Account will be credited with an initial $20,000.00 dummy balance.

To get the most out of sandbox, you should simulate your intended use cases. Keep in mind, the Instant Issuance program uses the funds good model and includes GET-only access to the API in production, meaning you’re reliant on our SDKs to facilitate cardholder actions. So if you’re launching your card program within these parameters, your sandbox usage should reflect that.

Once your integration is tested in sandbox, the move to production is seamless and you will be able to launch your customized Instant Issuance program.


API requests originating from sandbox accounts must be made against the sandbox API: https://api.sbx.aptopayments.com

Getting sandbox keys#

Apto uses API keys to control access to our APIs. Keys consist of a public component and a private component, which act like a username and password. The Core API and Mobile API handle keys differently. Learn more about API authentication.

Apto’s Mobile API is used to communicate between an individual cardholder’s application and the Apto platform. Mobile API keys consist of your card program’s (public) Mobile API Key and the cardholder’s (private) session token. Apto generates your Mobile API key when you create your first developer account. You can only have one public Mobile API key. Learn how to find your Mobile API key. The cardholder’s session token is generated by the API when the cardholder verifies their primary credential. Learn more about session tokens.

Apto’s Core API is used to communicate between Apto and your backend. Core API keys consist of a (public) API Key and a (private) API Secret. You can have more than one set of Core API keys, and must generate them in the Apto Dashboard. Learn how to create Core API keys.

Finding your Mobile API key#

To get your sandbox Mobile API key:

  1. Open the Apto developer dashboard and navigate to Developers.
  2. Identify the key labeled Mobile API Key.

Creating Core API keys#

You can create new sandbox keys to test out the Core API.

To generate Core API keys:

  1. Open the Apto developer dashboard and navigate to Developers.
  2. From the API Keys tab, select Add.
  3. Store your API key and API secret in a safe place. The API secret will not be available again.
  4. Select Done.

In Production, the Core API is read-only for Instant Issuance programs.

The sandbox Core API URL is https://api.sbx.aptopayments.com. We'll use this URL in the following steps to add cardholders and transactions.

API permissions for Instant Issuance vs. Enterprise programs#

For the Instant Issuance program, the Core API is read-only in both the sandbox and production environments for compliance reasons. The Core API and Mobile API have largely the same functionality, but where they differ is who is performing the action: in the Core API this is the developer (using backend-to-backend communication), and in the Mobile API this is the end user (cardholder). For speed to market, Instant Issuance circumvents a lot of the due diligence required of Enterprise programs, and therefore also restricts developers from certain actions with the Core API, such as creating a cardholder. For similar desired actions in Instant Issuance, please use the Mobile API (or related SDKs), which requires the user to verify their identity and, in turn, authorize/perform the protected action.

There are still some specific actions where we allow use of the Core API in order to make things easier, such as simulating transactions (only in sandbox) or loading funds from your Funding Account onto a card. To understand which endpoints are only available to Enterprise programs, refer to the Core API documentation. Please note the sandbox Core API URL is https://api.sbx.aptopayments.com, and we'll use this URL in some of the following steps.

Creating test cardholders#

Once you have your sandbox API keys, it’s time to create test cardholders. For Instant Issuance programs, you must use the Mobile API to create test cardholders in one or more of the following ways: our demo app, through the Mobile SDKs, or through the Mobile API. For Enterprise programs, you also have the option to use the Core API to create test cardholders.

User verification process#

For the Mobile API, Apto creates a user in your program when you submit and verify your primary credential, which in US programs is a valid US phone number. Verification includes entering a valid phone number and OTP (One Time Password).The phone number serves as the Primary Credential in the user-creation flow, therefore each new user will need a unique phone number as Primary Credentials cannot be repeated. To enable you to test creating cardholders, we’ve made a few configurations specific to verifying users in sandbox:

  • You can enter any phone number as long as it fits within the parameters of a “valid” phone number i.e., format +1 (555) 555-5555. Use a different phone number for each cardholder created; you only need to use your real phone number for access to the demo app (see following section)
  • Phone numbers will not actually be sent an SMS for verification
  • The OTP (One Time Password) will always be set to six zeroes, ‘000000’

Creating cardholders in the demo app#

The fastest way to create a test cardholder in sandbox is with our demonstration app. This is a compiled version of the mobile SDK that implements a generic UI/UX and that is tied to your sandbox environment.

When in sandbox, none of the cardholder information you provide has to be accurate. However, if you are using the demonstration app, you must enter a valid phone number in order to receive the link to download the TestFlight demo app.

To trial the demonstration app:

  1. Select Developers in the navigation menu.
  2. Select the SDKs tab.
  3. Select Get link.
  4. Enter a valid U.S. mobile phone number to deliver your download links to.
    • Each text message will include a link to download an iOS version from TestFlight or to download an Android version from the Google Play Developer Console. This link is specific to your card program. If you want to invite other team members to create test cardholders, enter their phone numbers to have the link sent to them.
  5. Install and open the app, click the Get Started button, and follow the cardholder onboarding experience.

Creating cardholders through the Mobile SDKs#

If you want to mimic your integration and implement our SDKs, you can use our Mobile SDKs to create cardholders. You’ll verify user credentials to get a session token, create a new user, and then issue a card to the user. This process is explained in detail in the Mobile SDK documentation:

Creating cardholders through the Mobile API#

Although the Mobile SDKs wrap the Mobile API and are provided for your convenience, you can also create cardholders directly through the Mobile API. For more detail, see:

Funding a cardholder’s account#

When you land in sandbox, your Funding Account will be credited with an initial $20,000.00 dummy balance.

To move funds from your Funding Account to your cardholders’ cards, you will need:

  1. Your Funding Account ID, which you can find under Settings > Account
  2. The cardholder’s card_id (can be retrieved under Cards in the Developer Portal or through the API)
  3. An optional description describing the transfer
  4. An optional idempotency_id to allow for safely retrying requests

Submit a POST request to the /cards/{card_id}/load_funds endpoint, using your Funding Account ID as the source_balance_id:

"amount": {
"currency": "USD",
"amount": 500
"description": "Credit $50",
"source_balance_id": "{FUNDING_ACCOUNT_ID}"

This should return a card object including data about the new spendable_balance:

"card": {
"id": "{CARD_ID}",
"design_key": null,
"livemode": true,
"last_four": "111",
"wallets": [],
"program_id": "Sandbox_V",
"status": "ACTIVATED",
"activated_at": "2021-01-27T18:24:35Z",
"created_at": "2021-02-17T10:18:04Z",
"issued_at": null,
"shipped_at": null,
"cardholder_id": "{CARDHOLDER_ID}",
"network": "MASTERCARD",
"ledge_account_id": null,
"ordered_status": "ORDERED",
"allow_set_pin": true,
"allow_get_pin": false,
"program_profile_id": "apto_test_luke_sbx",
"cardholder_first_name": "Bob",
"cardholder_last_name": "Ross",
"dda_number": null,
"aba_routing_number": null,
"wait_list": false,
"name_on_card": "BOB ROSS",
"allow_international": true,
"balance_id": "bal_a3c577f3f705990c",
"corporation_id": null,
"metadata": null,
"spendable_today": {
"amount": 500.0,
"currency": "USD",
"native_amount": 500.0,
"native_currency": "USD"
"spendable_balance": {
"amount": 500.0,
"currency": "USD",
"native_amount": 500.0,
"native_currency": "USD"
"total_balance": {
"amount": 500.0,
"currency": "USD",
"native_amount": 500.0,
"native_currency": "USD"
"additional_fields": []

Creating test transactions#

Our sandbox environment allows you to test the transaction lifecycle by creating transactions with the API. If subscribed, you will receive webhooks updating the total billing amount of transaction, and whether the transaction is still pending or complete. If you have configured external auth, you will receive authorization requests and financial requests to your external auth endpoint, and you must respond with approval or decline.

Creating a transaction requires submitting a POST request to the /cards/{card_id}/transactions endpoint with the card_id and the transaction details (billing_amount, type, and processing_type).

For a walkthrough on how to create and update test transactions, see Simulating Transactions.

Setting up webhooks#

Webhooks provide a powerful way to stay in the loop on what’s happening in your card program. We use webhooks to notify you when events occur so that you can take appropriate actions.

When you are ready to process webhooks, see Working with webhooks. For more detail on how webhooks work, including a list of events you can subscribe to, see our Webhooks overview. Webhooks in the Apto sandbox work exactly the same as they do in production.

Viewing sandbox activity in the dashboard#

The purpose of sandbox is to build and test your integration. Once you’ve created API keys and configured your webhooks you’ll be able to view your card program in action.

To help you get started, your sandbox Funding Account will be credited with an initial $20,000.00 dummy balance. If you followed this article and the Simulating Transactions walkthrough, you've created a cardholder, transferred funds from your Funding Account to their bank account, and created a series of test transactions. These transactions debited the cardholder’s balance, credited your settlement and Revenue Accounts, and debited your Billing Account.

To review transaction activity in the dashboard, log into the dashboard and select Transactions.

The dashboard includes loads of other useful information as well. Navigate to Cards to see card balances and other card data. Navigate to Users to user details such as KYC status, user ID, date the user was added to the system, the user's contact information, and more.

See the Managing your card program section to learn more about using Dashboard.

Implementing the SDKs#

Our developer tools provide two options for launching a cardholder application in the Instant Issuance program:

  1. Build your own UI
    • Use the Mobile SDK and PCI SDK if you want to build your own UI.
    • The SDKs wrap the API and they allow your mobile application to easily communicate with the Apto Platform.
  2. Use our white label mobile flows
    • For speed-to-market, we offer complete, white label mobile flows that include everything your users could need. Take our white label flow and drop it into your existing application or you can distribute it as a standalone app.
    • The Android and iOS flows are configurable to match your branding look and feel.

To initialize and operate the SDKs, pass the public Mobile API key that you found in the dashboard, and include the appropriate sandbox environment parameter. Please see SDKs, to learn more.