v1.0.5Changelog
Home›API Reference›Accounts

Account Management

Two endpoints for account lookup (resolving a card PAN to account IDs) and balance inquiry.

Account Lookup

POST /api/ssb/accountservices/{version}/accounts

Retrieves the list of accounts associated with the presented card PAN and institution. Returns account IDs, types, and transaction capabilities for use in subsequent balance inquiry and transaction calls.

Operation ID: AccountLookup

💡
Always Call First

Account Lookup is typically the first authenticated call in a session. The returned accounts[].id values are required as paymentInstrument.account.id in all subsequent financial transaction requests.

head.acquirerId string No
Acquirer institution ID.
head.description string Yes
Transaction description. Example: "ATM Account Lookup"
transaction.rrn string Yes
12-digit retrieval reference number.
transaction.date string Yes
Transaction date. Format: YYYYMMDD.
transaction.type string Yes
Must be: ACCOUNTLOOKUP
deviceInfo.terminalId string Yes
ATM terminal ID.
deviceInfo.terminalLoc string Yes
Terminal location.
deviceInfo.acceptorId string Yes
Acceptor ID.
institution.id string Yes
Financial institution ID.
card.pan string Context
Cardholder PAN. Required for card-present channel lookup.
json
{
  "head": {
    "acquirerId":  "10001",
    "description": "ATM Account Lookup"
  },
  "transaction": {
    "rrn":  "250603001001",
    "date": "20260603",
    "type": "ACCOUNTLOOKUP"
  },
  "deviceInfo": {
    "terminalId":  "ATM00001",
    "terminalLoc": "100 Main St, New York NY 10001",
    "acceptorId":  "ACCEPTOR000001"
  },
  "institution": { "id": "000100" },
  "card": { "pan": "543100XXXXXXXXX0781" }
}
accounts[].id string
Account identifier. Use as paymentInstrument.account.id in all transaction requests.
accounts[].accountType string
Account type: DDA · SDA · LOAN · etc.
accounts[].txnCapability string
Transaction capability code.
accounts[].description string
Human-readable account label.
json — 200 OK
{
  "head": {
    "acquirerId":  "10001",
    "description": "ATM Account Lookup"
  },
  "transaction": {
    "rrn":  "250603001001",
    "date": "20260603",
    "type": "ACCOUNTLOOKUP"
  },
  "institution": { "id": "000100" },
  "accounts": [
    {
      "id":          "DDA1234567890",
      "accountType": "DDA",
      "txnCapability": "DW",
      "description": "Checking Account"
    },
    {
      "id":          "SAV9876543210",
      "accountType": "SDA",
      "txnCapability": "DW",
      "description": "Savings Account"
    }
  ]
}

Balance Inquiry

POST /api/ssb/accountservices/{version}/accounts/balance

Returns current balance(s) for the specified account. The balances array may contain multiple entries (Available, Balance/Ledger, PaymentDue) depending on account type.

Operation ID: BalanceInquiry

head.description string Yes
Transaction description.
transaction.rrn string Yes
12-digit RRN.
transaction.type string Yes
Must be: BALANCEINQUIRY
deviceInfo.terminalId string Yes
ATM terminal ID.
deviceInfo.terminalLoc string Yes
Terminal location.
deviceInfo.acceptorId string Yes
Acceptor ID.
paymentInstrument.account.id string Yes
Account ID from Account Lookup response.
paymentInstrument.card.pan string No
Card PAN. Optional.
institution.id string Yes
Institution ID.
json
{
  "head": {
    "acquirerId":  "10001",
    "description": "ATM Balance Inquiry"
  },
  "transaction": {
    "rrn":  "250603001010",
    "date": "20260603",
    "type": "BALANCEINQUIRY"
  },
  "deviceInfo": {
    "terminalId":  "ATM00001",
    "terminalLoc": "100 Main St, New York NY 10001",
    "acceptorId":  "ACCEPTOR000001"
  },
  "paymentInstrument": {
    "account": { "id": "DDA1234567890" },
    "card":    { "pan": "543100XXXXXXXXX0781" }
  },
  "institution": { "id": "000100" }
}
balances[].type string
Available · Balance · PaymentDue
balances[].amount number
Balance amount.
balances[].currencyCode string
ISO 4217 currency code.
balances[].dueDate string
Due date for PaymentDue balance type on loan accounts.
status.authId string
Authorization ID (DE-38).
status.responseCode string
"000" = approved.
branch.id / name / address string
Branch details of the posting branch.
json — 200 OK
{
  "transaction": {
    "rrn":  "250603001010",
    "date": "20260603",
    "type": "BALANCEINQUIRY"
  },
  "paymentInstrument": {
    "account": { "id": "DDA1234567890" }
  },
  "institution": { "id": "000100" },
  "branch": {
    "id":      "BR-001",
    "name":    "Main Street Branch",
    "address": "100 Main Street, New York, NY 10001"
  },
  "balances": [
    { "type": "Available", "amount": 4821.50, "currencyCode": "USD" },
    { "type": "Balance",   "amount": 4821.50, "currencyCode": "USD" }
  ],
  "status": { "authId": "AUTH01", "responseCode": "000" }
}