Skip to main content

​
Step 1: Request API Access

To get started, follow these steps:
  1. Contact Us: Email [email protected] with your use case to request access.
  2. Receive Credentials: We’ll provide you with both Production and Sandbox Secret Keys, along with your merchant ID.
  3. Authenticate Requests: Include your API key in the header of all requests:
In the sandbox environment, we return static data. Make sure to switch to the production environment before going live.
Your app must initiate a consent request that allows users to connect their bank account(s). This will return a URL where users can authenticate securely via their bank. Endpoint
Example Request
Example Response
Key Considerations
  • accountAuthId is essential for tracking user consent and is used in subsequent requests.
  • callbackParams are passed transparently to your redirect URL along with additional provided parameters.
  • bankAccountIds returned in the callback represent the unique identifiers for user bank accounts. These remain consistent throughout the user’s lifecycle.
Once the user completes consent, they’ll be redirected to your redirectUrl:
Important Notes
  • Users may authorize multiple bank accounts; each bank account id will be appended in the callback as comma-separted value bankAccountIds.
  • If the user unchecks the consent renewal checkbox, consent will not auto-renew after 90 days and must be reinitiated.
  • Consent can also be manually revoked by the user via their banking app at any time.

​
Step 3: Retrieve Transactions

Use the bankAccountId from the callback to fetch transaction data. Endpoint
Example Response
Results are cursor-paginated — follow links.next in the response to fetch subsequent pages. See Cursor-based pagination on the Transaction API reference for the full contract, field descriptions, and worked examples.

​
Step 4: Retrieve Bank Account Metadata

Use this API to fetch account-level metadata such as account number and sort code for the authorized account. Endpoint
Example Response
Why This Matters
  • Useful for matching and linking bank accounts to internal user profiles.
  • Ensures clarity when a user has multiple accounts with similar names.
  • Always validate this information securely before displaying it to users.
Refer to the Get Bank account API to know more about the response data and error handling. If you wish to terminate access programmatically, you can revoke access the following way: Revoke a Specific Account
Deletes consent for the specific bank account from Atoa’s records. If this is the last bank account associated with that consent, it will also revoke consent at the user’s bank. Revoke All Accounts
Use this to fully revoke the consent. This deletes all bank accounts consent from the user’s bank and from Atoa.
  • All consents are valid for 90 days.
  • If auto-renew is enabled, we will attempt background renewal before expiry.
  • Once expired, any call to transactions or account endpoints will return: 404 Consent not found
Below is a screenshot showing the bank selection screen and the auto-renewal checkbox for reference. Atoa Bank Feed 'Authorise your bank' screen: pick your bank to grant account access, with a 90-day auto-renewing consent option. 🧠 Recommendation: Prompt users to re-authenticate as consent expiration nears (e.g., 7 days before expiry).