External auth

In some debit-based funding models, a card’s funding source is not under Apto’s direct control, as discussed in the debit cards section. In these cases, although we still conduct standard authorization checks, Apto also involves you in the process so that you can execute your own authorization logic. However, you may also wish to participate in the authorization process under other funding models. For example, you might want to limit cardholder spending to certain categories, merchants, or times of day. Whatever controls you want to implement, they’re possible with a process called “external auth” and our External Auth API. External auth puts you in the authorization flow, allowing you to make real-time decisions on every transaction in your card program.

To implement external auth, you must provide an authorization API so the Apto platform can delegate the auth decision to you.

Your API must have two functions:

  • Read balances - Used to present the available funding sources to the user.
  • Authorize - Apto will use this function to obtain a decision (authorized or declined) from your platform.

Authorizations are real-time requests to your API endpoint. We pass transaction, cardholder, merchant information using a username and password for authentication, and request you set the ‘Approved’ field to ‘False’ or ‘True’ based on your auth logic. These requests are time sensitive and require immediate response. In case of timeouts, we have the option to stand-in and authorize based on configurations you set.

If you are implementing external auth as part of a debit model in which you control the source of funds, we recommend you also capture funds from the user’s account when authorizing a transaction.

You are responsible for all of the transactions you authorize throughout the day. Throughout the day, the movement of funds from your user’s accounts replenishes your program wallet, ensuring that your transactions continue processing. During settlement, the card networks will calculate the net-settlement amount that needs to be transferred between the issuing and acquiring banks, and, during their nightly sweep, will collect everything that is owed. In advance of this, At the end of the day, Apto will send you a settlement file instructing the amount that should be deposited into the Settlement Account to cover the day’s transactions. If you do not control your user’s accounts and are using ACH to collect funds back from them, you should maintain a float in your program wallet to account for delays.

We will send you updates to an authorization via transaction_update webhooks. You can use these webhooks to trigger movements between your program wallet and the cardholder’s account to ensure they are debited correctly. For more detail, see the Webhooks article and the Event Webhooks API reference documentation.