Common Request & Response Objects
Shared data structures that appear across multiple endpoints. Understanding these eliminates repetition when reading individual endpoint documentation.
These objects are reused verbatim across all financial transaction endpoints. Learn them once and apply them everywhere.
head (request)
The head object identifies the acquiring institution. Present in all transaction and account management requests.
| Field | Type | Required | Description |
|---|---|---|---|
| head.acquirerId | string | No | Acquirer institution identifier. Example: "10001" |
| head.description | string | Yes | Human-readable description of the transaction. Example: "ATM Cash Withdrawal" |
transaction (request)
Carries core ISO 8583 transaction identifiers. Present on all transaction-type endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
| transaction.rrn | string | Context | Retrieval Reference Number (ISO 8583 DE-37). 12-digit numeric string. Required on all transaction types. Used as an idempotency key on retries. |
| transaction.date | string | Context | Transaction date. Format: YYYYMMDD or ISO-8601. Example: "20260603" |
| transaction.type | string | Context | Transaction type string. Must match the endpoint's expected value. See each endpoint's documentation for the required value. |
Valid transaction.type values
| Value | Endpoint |
|---|---|
ACCOUNTLOOKUP | POST /accounts |
BALANCEINQUIRY | POST /accounts/balance |
CASHWITHDRAWAL | POST /transactions/debits |
CASHWITHDRAWALREVERSAL | POST /transactions/debits/reverse |
CASHDEPOSIT · CHECKDEPOSIT · CASHCHECKDEPOSIT | POST /transactions/credits |
CASHDEPOSITREVERSAL · CHECKDEPOSITREVERSAL · CASHCHECKDEPOSITREVERSAL | POST /transactions/credits/reverse |
TRANSFER | POST /transactions/transfers |
TRANSFERREVERSAL | POST /transactions/transfers/reverse |
BILLPAYMENT | POST /transactions/billpayments |
CARDLESSWITHDRAWAL | POST /transactions/cardless |
deviceInfo (request)
Required on all ATM, IVR, and teller-originated transactions. Identifies the originating device.
| Field | Type | Required | Description |
|---|---|---|---|
| deviceInfo.terminalId | string | Yes | Terminal identifier. ATM: 8-character terminal ID. Mobile: UUID device ID. Example: "ATM00001" |
| deviceInfo.terminalLoc | string | Yes | Terminal location description. Gateway field name (alias for terminalLocation). Example: "100 Main St, New York NY 10001" |
| deviceInfo.acceptorId | string | Yes | Merchant/acceptor ID (ISO 8583 DE-42). 15-character padded string. Example: "ACCEPTOR000001" |
paymentInstrument (request & response)
Identifies the source account and optionally the card used for financial transactions.
| Field | Type | Required | Description |
|---|---|---|---|
| paymentInstrument.account.id | string | Yes | Account identifier. Format: account type prefix + number. Obtained from the Account Lookup response. Example: "DDA1234567890" |
| paymentInstrument.account.accountType | string | No | Account type code. Examples: DDA (demand deposit), SDA (savings), CHK (checking) |
| paymentInstrument.card.pan | string | Context | Primary Account Number. Required for card-present and preference endpoints. Masked in logs. |
amount (request & response)
Carries the monetary value of the transaction.
| Field | Type | Required | Description |
|---|---|---|---|
| amount.amount | number | Yes | Transaction amount as a decimal. Example: 200.00 |
| amount.currencyCode | string | Yes | ISO 4217 currency code. Example: "USD" |
| amount.accessFee | number | No | Surcharge / access fee amount. Optional. Example: 2.50 |
institution (request)
Identifies the financial institution for the transaction. Required on all service endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
| institution.id | string | Yes | Financial institution identifier. Example: "000100" |
| institution.bin | string | No | Bank Identification Number. Optional on most endpoints. |
balances[ ] (response)
Array of balance objects returned after every successful financial transaction. The array may contain multiple entries depending on account type.
| Field | Type | Description |
|---|---|---|
| balances[].type | string | Balance type. Values: Available · Balance · PaymentDue |
| balances[].amount | number | Balance amount as a decimal. |
| balances[].currencyCode | string | ISO 4217 currency code. |
| balances[].dueDate | string | Payment due date. Populated for PaymentDue balance type on loan accounts. |
On the POST /transactions/transfers endpoint, balances is an object (not a flat array) with two sub-arrays: balances.paymentInstrument[] (source account) and balances.beneficiaryInstrument[] (destination account).
status (response)
Core banking authorization status returned on all financial transaction responses.
| Field | Type | Description |
|---|---|---|
| status.authId | string | Authorization ID (ISO 8583 DE-38). 6-character alphanumeric approval code. Example: "AUTH01" |
| status.responseCode | string | "000" = approved. Non-zero = declined or error. See Transaction Response Codes. |
branch (response)
Branch details of the posting branch. Returned on all successful financial transaction responses.
| Field | Type | Description |
|---|---|---|
| branch.id | string | Branch identifier. Example: "BR-001" |
| branch.name | string | Branch name. Example: "Main Street Branch" |
| branch.address | string | Full branch address string. Example: "100 Main Street, New York, NY 10001" |
reverseInfo (request — reversal endpoints)
Required on all reversal endpoints. Links the reversal to the original transaction.
| Field | Type | Required | Description |
|---|---|---|---|
| reverseInfo.authId | string | No | Authorization ID from the original transaction response. Aids in core banking matching. |
| reverseInfo.reasonCode | string | Yes | Reason for the reversal. Examples: UNABLE_TO_DISPENSE · DEPOSIT_ERROR · TRANSFER_ERROR |
| reverseInfo.amount | number | Yes | Amount being reversed. Should match the original transaction amount. |