Open Banking API — v1

Build on BankerTransact

The BankerTransact Open Banking API gives third-party applications authenticated, scoped access to banking data — accounts, customers, loans, transactions, and payments. All resources are tenant-scoped; your API key can only access data for the bank that issued it.

ℹ️

All endpoints return JSON. Dates are ISO 8601 strings. Monetary amounts are decimal numbers.

Authentication

Every request must include a valid API key or OAuth 2.0 Bearer token.

API Key

Pass your API key in the Authorization header or X-API-Key header.

curl

# Authorization header (recommended)
curl -H "Authorization: Bearer bt_abc123..." \
     https://www.bankertransact.com/api/v1/accounts

# X-API-Key header
curl -H "X-API-Key: bt_abc123..." \
     https://www.bankertransact.com/api/v1/accounts

OAuth 2.0 Bearer Token

For customer-consented access, use an OAuth access token:

curl

curl -H "Authorization: Bearer eyJhbGci..." \
     https://www.bankertransact.com/api/v1/accounts

Scopes

API keys and OAuth tokens are granted specific scopes that control which endpoints they can call.

accounts.read View account details, balances, and transaction history

accounts.write Update account information

transactions.read View transaction records

customers.read View customer profiles

loans.read View loan details, payments, and amortization schedules

payments.create Initiate internal transfers, ACH payments, and wire transfers

payments.read Check payment and transfer status

Error Handling

Errors return a JSON object with error and message fields.

JSON

{
  "error": "insufficient_scope",
  "message": "This endpoint requires the 'accounts.read' scope"
}

HTTP Code	Error	Description
400	validation_error	Missing or invalid request parameters
401	authentication_required	No valid API key or token provided
401	invalid_api_key	Key is invalid, expired, or revoked
403	insufficient_scope	Token lacks the required scope
404	not_found	Resource does not exist or belongs to another tenant
422	insufficient_funds	Account has insufficient balance
429	rate_limit_exceeded	Too many requests; check X-RateLimit-* headers
500	server_error	Internal error; retry with exponential backoff

Rate Limits

Each API key has an hourly rate limit (default: 1,000 req/hour). Rate limit info is returned in response headers:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842

When the limit is exceeded, you receive a 429 response. Use exponential backoff and retry after the rate limit window resets.

Accounts

GET /accounts List all accounts

Returns all deposit accounts for the tenant.

Query Parameters

Parameter	Type	Description
account_type	string	Filter by type: checking, savings, etc.
status	string	Filter by status: active, closed
page	integer	Page number (default: 1)
limit	integer	Per page, max 100 (default: 50)

curl

curl -H "Authorization: Bearer bt_..." \
     "https://www.bankertransact.com/api/v1/accounts?page=1&limit=20"

GET /accounts/:id Get account by ID

Returns a single deposit account.

curl

curl -H "Authorization: Bearer bt_..." \
     https://www.bankertransact.com/api/v1/accounts/42

GET /accounts/:id/balance Get real-time balance

Response

{
  "data": {
    "id": 42,
    "account_number": "1000000042",
    "current_balance": 12500.00,
    "available_balance": 12250.00,
    "currency": "USD",
    "updated_at": "2026-05-05T18:00:00Z"
  }
}

GET /accounts/:id/transactions Get account transactions

Query Parameters

Parameter	Type	Description
from_date	string	Start date YYYY-MM-DD
to_date	string	End date YYYY-MM-DD
page, limit	integer	Pagination (max limit: 200)

Customers

GET /customers List customers

Query Parameters

Parameter	Type	Description
search	string	Search by name or email
page, limit	integer	Pagination (max limit: 100)

GET /customers/:id Get customer by ID

Returns customer profile. SSN is returned as last 4 digits only.

GET /customers/:id/accounts List accounts for a customer

Returns all deposit accounts belonging to the customer.

Loans

GET /loans List loans

Query Parameters

Parameter	Type	Description
status	string	active, delinquent, paid_off
loan_type	string	Filter by loan type
page, limit	integer	Pagination

GET /loans/:id Get loan details

Returns full loan details including payment terms and current balance.

GET /loans/:id/payments Payment history

Paginated history of payments recorded against the loan.

GET /loans/:id/schedule Amortization schedule

Returns up to 36 upcoming payment periods with principal/interest breakdown.

Response

{
  "data": {
    "loan_id": 12,
    "loan_number": "LN-2024-0012",
    "schedule": [
      {
        "payment_number": 1,
        "due_date": "2026-06-01",
        "payment_amount": 843.86,
        "principal": 593.86,
        "interest": 250.00,
        "balance_after": 59406.14
      }
    ]
  }
}

Payments

POST /transactions Initiate internal transfer

⚠️

Requires payments.create scope. Transfers are immediate and posted in real-time.

Request Body

Field	Type	Description
from_account_idrequired	integer	Source account ID
to_account_idrequired	integer	Destination account ID
amountrequired	number	Transfer amount in USD
description	string	Optional memo
reference_number	string	Your idempotency key

curl

curl -X POST https://www.bankertransact.com/api/v1/transactions \
  -H "Authorization: Bearer bt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_id": 42,
    "to_account_id": 43,
    "amount": 500.00,
    "description": "Savings transfer"
  }'

POST /payments/ach Initiate ACH payment

Request Body

Field	Type	Description
account_idrequired	integer	Debit account ID
amountrequired	number	Payment amount in USD
routing_numberrequired	string	9-digit ABA routing number
account_numberrequired	string	Beneficiary account number
account_type	string	checking or savings (default: checking)
company_name	string	Company name for ACH batch

POST /payments/wire Initiate wire transfer

Request Body

Field	Type	Description
account_idrequired	integer	Debit account ID
amountrequired	number	Wire amount in USD
beneficiary_namerequired	string	Name of the receiving party
beneficiary_accountrequired	string	Receiving account number
beneficiary_bank_routingrequired	string	ABA routing number
memo	string	Wire memo/OBI

GET /payments/:id/status Get payment status

Returns the current status of a wire transfer or ACH payment by ID.

OAuth 2.0

Use OAuth 2.0 when your app needs access on behalf of a specific customer (e.g. a personal finance app reading their balance).

Authorization Code Flow

Step 1 — Redirect user to authorize

GET /api/oauth/authorize
  ?client_id=ob_abc123
  &redirect_uri=https://yourapp.com/callback
  &scope=accounts.read+transactions.read
  &state=random_state_value
  &response_type=code

Step 2 — Exchange code for token

curl -X POST https://www.bankertransact.com/api/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=ob_abc123" \
  -d "client_secret=YOUR_SECRET"

Refresh access token

curl -X POST https://www.bankertransact.com/api/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=ob_abc123" \
  -d "client_secret=YOUR_SECRET"

Webhooks

Configure webhook endpoints in the admin portal to receive real-time events.

Event Types

transaction.createdA new transaction was posted to an account

payment.completedAn ACH or wire payment settled

account.updatedAccount balance or status changed

loan.payment.receivedA loan payment was recorded

Payload Structure

JSON

{
  "event": "transaction.created",
  "tenant_id": 1,
  "timestamp": "2026-05-05T18:00:00Z",
  "data": { ... }
}

Signature Verification

Every request includes an X-BT-Signature header. Verify it using your webhook signing secret:

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expected = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}