Atoa’s Account Services APIs unlock access to a user’s financial data—such as transaction history, account metadata, and balances—via Open Banking. These APIs are powered by user consent and are ideal for:

  • Account reconciliation
  • Cash flow analysis
  • Financial data enrichment
  • ERP, accounting, or dealer management system integrations

​
Step 1: Request API Access

To get started, follow these steps:

  1. Contact Us: Email hello@paywithatoa.co.uk with your use case to request access.
  2. Receive Credentials: You’ll be issued a Production API Secret Key and merchant ID.
  3. Authenticate Requests: Include your API key in the header of all requests:
Authorization: Bearer sk_live_8aa94380efb94298aa4fe932ad78b22b

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

POST api.atoa.me/api/bank/auth/initiate

Example Request

{
  "redirectUrl": "https://your-app.com",
  "callbackParams": {      //Optional: Pass any key-value pairs
    "userId": "user_123",
  }
}

Example Response

{
  "url": "https://atoa.me/link-bank?referenceId=ed016c93-68c2-4394-8e9c-1e700f8a1b15&expiresAt=2025-04-16T17:53:48.174Z&env=PRODUCTION",
  "referenceId": "ed016c93-68c2-4394-8e9c-1e700f8a1b15",
  "expiresAt": "2025-04-16T17:53:48.174Z"
}

Key Considerations

  • referenceId 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:

https://{{your-redirect-url}}?status=SUCCESS&bankAccountIds=acc_001,acc_002&userId=abc_123

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

GET api.atoa.me/api/bank/accounts/{accountId}/transactions?from=2024-01-01&before=2024-03-01&page=0&itemsPerPage=30

Example Response

{
  "data": [
    {
      "id": "txn_001",
      "date": "2024-01-14T11:45:00Z",
      "type": "DEBIT",
      "amount": 89.99,
      "currency": "GBP",
      "description": "Amazon Marketplace",
      "reference": "INV-4321-A",
      "transactionCategory": "E-commerce",
      "status": "BOOKED"
      "balance": {"amount": 2.37, "currency": "GBP"} //Optional
    }
  ],
  "totalCount": 1,
  "page": 0,
  "itemsPerPage": 30
}

For more details on pagination and field definitions, refer to the Transaction API Reference.

​
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

POST api.atoa.me/api/bank/accounts/{accountId}

Example Response

{
  "bankName": "HSBC UK",
  "accountNumber": "12345678",
  "sortCode": "112233"
}

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

POST api.atoa.me/api/bank/auth/revoke?accountId=0011223344

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

POST api.atoa.me/api/bank/auth/revoke

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.

🧠 Recommendation: Prompt users to re-authenticate as consent expiration nears (e.g., 7 days before expiry).

Magento