v1.0.5Changelog
Home›API Reference›Preferences

Customer Preferences

Three endpoints to retrieve, upsert, and delete cardholder ATM preference profiles. Lookup key is Institution ID + Card PAN.

Retrieve Preferences

POST /api/ssb/accountservices/{version}/preferences/retrieve

Retrieves the stored cardholder ATM preference profile. Lookup key is Institution ID + Card PAN. Terminal ID is not part of the lookup key.

Operation ID: GetPreferences

institution.id string Yes
Financial institution ID. Example: "000100"
card.pan string Yes
Cardholder PAN. Example: "543100XXXXXXXXX0781"
json
{
  "institution": { "id": "000100" },
  "card":        { "pan": "543100XXXXXXXXX0781" }
}
profileStatus string
0=Not set · 1=Active · 2=NeverAsk · 3=Deleted
profileData.language string
Language preference. ENG=English · SPA=Spanish
profileData.fastCashAmount string
Fast cash amount code. Example: "020" = $20.00
profileData.fastCashReceipt string
Receipt preference. 1=Print · 2=No print · 3=Ask
profileData.withdrawalReceipt string
Withdrawal receipt preference.
profileData.otherReceipt string
Other transaction receipt preference.
profileData.receiptBalance string
Print balance on receipt. 1=Yes · 0=No
profileData.account string
Default account. CHK=Checking · SAV=Savings
status.responseCode string
"000" = success
json — 200 OK
{
  "status": { "responseCode": "000" },
  "profileStatus": "1",
  "profileData": {
    "language":          "ENG",
    "fastCashAmount":    "020",
    "fastCashReceipt":   "2",
    "withdrawalReceipt": "2",
    "otherReceipt":      "1",
    "receiptBalance":    "1",
    "account":           "CHK"
  }
}

Add / Update Preferences

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

Creates or updates a cardholder ATM preference profile. Supports two modes: full profile update (provide all profileData fields) or neverAsk mode (profileData.neverAsk: true suppresses all ATM prompts).

Operation ID: AddPreferences

🚨
Mutually Exclusive Modes

profileData must contain either full profile fields or neverAsk: true — not both. Sending both returns 400 Bad Request.

institution.id string Yes
Financial institution ID.
card.pan string Yes
Cardholder PAN.
deviceInfo.terminalId string Yes
ATM terminal ID.
deviceInfo.terminalLoc string Yes
Terminal location.
deviceInfo.acceptorId string Yes
Acceptor ID.
profileData.language string Context
Language code. Required for full profile mode.
profileData.fastCashAmount string Context
3-character fast cash amount code. Example: "020"
profileData.fastCashReceipt string Context
Receipt code: 1=Print · 2=No print · 3=Ask
profileData.withdrawalReceipt string Context
Withdrawal receipt code.
profileData.otherReceipt string Context
Other receipt code.
profileData.receiptBalance string Context
Print balance flag. 1=Yes · 0=No
profileData.account string Context
Default account. CHK · SAV
profileData.neverAsk boolean Context
true = suppress all ATM prompts. Mutually exclusive with other fields.
json — Full Profile
{
  "institution": { "id": "000100" },
  "card":        { "pan": "543100XXXXXXXXX0781" },
  "deviceInfo": {
    "terminalId":  "00000162",
    "terminalLoc": "100 Main St",
    "acceptorId":  "ACCEPTOR000001"
  },
  "profileData": {
    "language":          "ENG",
    "fastCashAmount":    "020",
    "fastCashReceipt":   "2",
    "withdrawalReceipt": "2",
    "otherReceipt":      "1",
    "receiptBalance":    "1",
    "account":           "CHK"
  }
}
status.responseCode string
"000" = profile saved.
success boolean
true if profile was created or updated.
message string
Confirmation message. Example: "PREFERENCE ADD"
json — 200 OK
{
  "status":  { "responseCode": "000" },
  "success": true,
  "message": "PREFERENCE ADD"
}

neverAsk Mode Example

json
{
  "institution": { "id": "000100" },
  "card":        { "pan": "543100XXXXXXXXX0781" },
  "deviceInfo": {
    "terminalId":  "00000162",
    "terminalLoc": "100 Main St",
    "acceptorId":  "ACCEPTOR000001"
  },
  "profileData": { "neverAsk": true }
}

Delete Preferences

POST /api/ssb/accountservices/{version}/preferences/delete

Deletes the stored cardholder preference profile. Operation is idempotent — no error is returned if the profile does not exist.

Operation ID: DeletePreferences

institution.id string Yes
Financial institution ID.
card.pan string Yes
Cardholder PAN. Identifies the profile to delete.
deviceInfo.terminalId string Yes
ATM terminal ID.
deviceInfo.terminalLoc string Yes
Terminal location.
deviceInfo.acceptorId string Yes
Acceptor ID.
json
{
  "institution": { "id": "000100" },
  "card":        { "pan": "543100XXXXXXXXX0781" },
  "deviceInfo": {
    "terminalId":  "00000162",
    "terminalLoc": "100 Main St",
    "acceptorId":  "ACCEPTOR000001"
  }
}
status.responseCode string
"000" = success.
success boolean
true even if no profile existed (idempotent).
message string
Confirmation message. Example: "PREFERENCE DELETE"
json — 200 OK
{
  "status":  { "responseCode": "000" },
  "success": true,
  "message": "PREFERENCE DELETE"
}
ℹ
Idempotent Operation

Calling this endpoint on a card with no preference profile returns success: true without error. Safe to call multiple times.