Getting started

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.

Sandbox

When you first log into Apto, you will land in our sandbox environment. Sandbox is a simulated environment, meant to be a replica of our production environment, where you can interact with our full suite of developer tools, regardless of your PCI status. The intent is to allow you to explore what’s possible. For example, 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.

To get the most out of sandbox, you should simulate your intended use cases. For example, 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.

Creating keys

To generate sandbox keys, select Developers in the navigation menu and select Create sandbox key. We will display your API key and API secret, which you should store in a safe place. Please note that Apto does not store your keys or secrets. If you lose the credentials, you will have to create new keys.

Sandbox API URL: https://api.sbx.aptopayments.com

Creating test cardholders

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.

To trial the demonstration app, select Developers in the navigation menu, then SDKs, and then select Get the link under the overview section in the top right. You will be asked to enter a U.S. mobile phone number that you would like your download links delivered to. Each text message will include a link to download an iOS version from TestFlight and another to download an Android version from the Google Play Developer Console.

Alternatively, you can use our API to quickly create cardholders in Sandbox via a POST request to the /cardholders endpoint, or by actually mimicking your integration and implementing our SDKs.

When you create a cardholder via the API in sandbox, the Apto platform does the following:

  • onboards a fictional cardholder with an “Approved” KYC status
  • creates a fictional cardholder bank account as the “funding source”
  • creates a debit card associated with the cardholder’s bank account

As it is a Sandbox environment, none of the cardholder information you provide has to be accurate. However, if you are using the demonstration app, you will have to enter a valid phone number in order to receive the OTP.

Funding a cardholder’s account

When you land in Sandbox, your program balance will be credited with an initial $20,000.00 dummy balance.

To move funds from your program balance to a cardholder’s Apto card account using the Dashboard:

  1. Select Cardholders in the navigation menu.
  2. Search for and select the desired cardholder, and click the table to open their details.
  3. Select Load Account and follow the prompts to enter an amount to load.

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 cardholder_id, the card_id, and the transaction details (billing_amount, type, and processing_type).

The transaction type is used to signify the nature of the transaction created, and affects whether this creates a debit or credit of funds. Possible type values are:

  • purchase
  • withdrawal
  • return

The processing_type associated with a transaction is one of:

  • authorization_request
  • financial_request
  • financial_advice

authorization_request processing types create a temporary hold on a card. The amount adjusts the cardholder's balance, but does not affect settlement. It is just securing the funds on the balance in case the merchant later sends a settlement message. An authorization request can be declined by the cardholder's balance. In production, this is a synchronous API call that is time sensitive. Authorization requests are usually automatically released within three working days, and they should never exist beyond one month.

financial_request processing types are similar to authorization_request actions, but do not need to adjust the amount or need to create a temporary hold. This means that the card networks will be claiming these funds during the following day’s settlement.

financial_advice processing types, otherwise known as force posts, create a transaction without a previous hold having been made on the account. These are rare scenarios, and are not time-sensitive transactions. If they induce a negative balance situation, they are usually resolved with the cardholder or by disputing the transaction with the networks. Please note that Apto cannot decline these messages.

Updating test transactions

In sandbox, transactions can be updated with a PUT request to the /cards/{card_id}/transactions/{transaction_id endpoint that passes the cardholder_id, card_id, transaction_id, and transaction details.

The permitted processing_type is either authorization_request or financial_advice.

In this scenario, the 'authorization_request' processing type changes the temporary hold that had been applied to a card. With the difference of the billing amount then adjusted on the cardholder's balance. Authorization requests used to update a transaction do not affect settlement. They are just securing the funds on the balance in case the merchant sends a settlement message. Any authorization requests that increase the billing amount can be declined by the cardholder's balance, whereas authorization requests that decrease the billing amount cannot be declined. In production, authorization requests are usually automatically released within 3 working days, and they should never exist beyond 1 month.

The 'financial_advice' processing type, when following an authorization request captures from the previous amount that was held. In production, the networks will be claiming these funds on the next settlement day. The transaction billing amount can be above or below any previous authorization requests. These advices cannot be declined based on the cardholder's balance.

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, open the Apto developer dashboard, navigate to Developers, open the Webhooks tab, and select Add endpoint. Enter your endpoint URL, select events for Apto to send, and select Create.

For more detail on how webhooks work, including a list of events you can subscribe to, see Webhooks. 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 Program Balance will be credited with an initial $20,000.00 dummy balance. Create a cardholder, transfer funds from your program balance to their bank account, and create a test transaction to simultaneously see the cardholder’s balance debited, your settlement and revenue accounts credited, and your billing account debited.

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 API key that you created and include the environment: .sandbox parameter.

Please see SDKs, to learn more.