When a cardholder uses his or her Apto Card to purchase goods or services, Apto must quickly confirm that the cardholder has sufficient funds prior to authorizing the transaction. A cardholder's spendable balance can be exposed from a custodian's API -or- mainly reside within Apto.

Custodian API provides spendable balance acting as the infallible balance authority. In this case, Apto will request the user's current spendable balance from the custodian's API (your software). Apto will perform basic performance testing of your API prior to launch. Please reach out to Apto Support to discuss integration specifics.

-OR-

Apto stores a spendable balance for each cardholder at card level. Your service simply updates each card balance as it changes within your business logic by consuming Apto's Card Balances.

The Apto API is architected around REST, using standard HTTP verbs to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Apto API is served over HTTPS to ensure data privacy; HTTP is not supported. Every request must include your secret API key. Request data must be included in the body.

Apto has a fully supported, production replica sandbox environment https://api.sbx.aptopayments.com. Please reach out for API access.

Apto uses conventional HTTP status codes to communicate success or failure of a request. HTTP codes in the 200-299 indicate successful requests. HTTP codes in the 400-499 range generally are caused by an unsupported or invalid request. HTTP 500 errors are usually caused by an issue or misconfiguration on our backend. Please reach out and we will resolve the issue.

All POST and PUT requests support idempotency as a parameter within the request. Idempotency enables safely retrying requests without duplicating functionality. Idempotency keys need to be uniquely generated by the client for every individual request. We recommend saving off used idempotency keys or using an algorithm with enough entropy to ensure no collisions. Idempotency is useful in operations like ordering a new card, to ensure only one card is ordered when transmission errors occur. Idempotent requests are the equivalent to Apto saving off the original response, including 500 errors caused by Apto, and 400 invalid requests.

Some resources can be paginated. Apto uses a simple cursor based pagination that orders objects based on time of occurance. The cursor is identified by one of 2 parameters, starting_after or ending_before. Both of these parameters take an existing object ID value. If starting_after is provided, Apto returns the next objects that occurred after the starting_after ID. Providing the ending_before parameter returns the parameters that occurred just before. A limit parameter can also be provided, if not provided the default value will be set to 25. The maximum number of returned elements is limited to 50 independently of the value set in this parameter.

When Apto needs to make backwards incompatible changes to our api, Apto versions all current clients to the current version. These previous versions will be supported, so no changes will be made under your feet. We will let you know that you can upgrade to the latest version for that resource, and you will be able to activate the new version via header when you are ready.

The Apto API uses API keys to authenticate requests. API keys will be provided to you through PGP under request. Authentication occurs through HTTP basic auth. Basic auth is a simple and secure authentication method, and requires a username and password to authenticate all your requests. Your API keys are powerful! Keep them safe and secure. Be careful to not share them within tools such as github or other third parties. Be careful to not embed them within client-side code. API keys should be stored server-side only.

Use the /cardholders endpoint to create and manage Apto cardholders. Cardholder objects allow you to track application status and confirm basic customer info. You can retrieve individual cardholders as well as a list of all your cardholders.

Know Your Customer: Each cardholder object includes a kyc_status. This represents the current state of a user's 'Know Your Customer' identity verification process. More context around a cardholder's kyc_status is provided with specific (and separate) reason groups.

KYC reasons will all have a null value when kyc_status is PASSED