Get Pending Authorization Transactions

Overview

GetPendingAuthorizationTransactionsQuery returns the non-expired transactions awaiting authorisation by the currently authenticated customer profile.

The query is safe to call after login, when the authorisation screen opens, or after the user taps a transaction_authorisation notification. The backend derives the tenant and customer profile from the access token; the caller cannot select another user or tenant.

Endpoint

POST /api/bpm/selfservice/cmd

Authentication

Customer authentication is required:

Authorization: Bearer <customer-access-token>
Content-Type: application/json

Mobile applications should also send their normal device and application headers:

X-App-Channel: Mobile
X-Device-Id: <stable-app-installation-id>
X-Client-Platform: Android
X-App-Version: <application-version>

Command name

GetPendingAuthorizationTransactionsQuery

Request parameters

This command has no request parameters. Do not send userId, tenantId, or values copied from an FCM payload.

Request example

The standard /cmd envelope uses a JSON-encoded data string:

{
  "cmd": "GetPendingAuthorizationTransactionsQuery",
  "data": "{}"
}

Example:

const response = await fetch(
  `${apiBaseUrl}/api/bpm/selfservice/cmd`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'X-App-Channel': 'Mobile',
      'X-Device-Id': installationId,
      'X-Client-Platform': platform,
      'X-App-Version': appVersion,
    },
    body: JSON.stringify({
      cmd: 'GetPendingAuthorizationTransactionsQuery',
      data: '{}',
    }),
  },
);

const result = await response.json();

Successful response

{
  "ok": true,
  "message": "Executed successfully",
  "outData": {
    "isSuccessful": true,
    "statusCode": "00",
    "message": "1 transaction(s) awaiting authorisation.",
    "data": [
      {
        "id": 123,
        "requestId": 456,
        "transactionType": "TRANSFERS_INTER_BANK",
        "transactionAmount": 25000.00,
        "currencyCode": "NGN",
        "sourceAccountNumber": "<masked-or-display-account>",
        "destinationAccountNumber": "<masked-or-display-account>",
        "destinationAccountName": "Transaction beneficiary",
        "narration": "Transaction narration",
        "authorizationStatus": "Prepared – Awaiting Signature",
        "authorizationMethod": "PIN",
        "expiresAt": "2026-08-24T15:30:00Z",
        "createdAt": "2026-08-24T15:15:00Z",
        "secondsRemaining": 900
      }
    ]
  },
  "logs": []
}

An empty result is successful:

{
  "ok": true,
  "message": "Executed successfully",
  "outData": {
    "isSuccessful": true,
    "statusCode": "00",
    "message": "0 transaction(s) awaiting authorisation.",
    "data": []
  }
}

Response fields

Field	Type	Description
id	integer	Server transaction identifier used by AuthorizeTransactionCommand
requestId	integer	Correlation identifier for the originating request
transactionType	string	Transaction module/type
transactionAmount	decimal	Transaction amount
currencyCode	string	ISO-style currency code stored for the transaction
sourceAccountNumber	string	Source account recorded for the transaction
destinationAccountNumber	string	Destination account, where applicable
destinationAccountName	string	Destination account name, where available
narration	string	Transaction narration
authorizationStatus	string	Prepared – Awaiting Signature or Awaiting Authorisation
authorizationMethod	string	Method the frontend must collect: PIN, OTP_EMAIL, OTP_MOBILE, AUTHENTICATOR_APP, or PUSH_APPROVE
expiresAt	datetime	UTC expiry time
createdAt	datetime	UTC creation time
secondsRemaining	integer	Approximate seconds remaining at query execution time

Filtering and ordering

The backend returns only transactions that:

• belong to the authenticated tenant and customer profile;
• have Prepared or AwaitingAuthorisation authorisation status;
• have an expiry time later than the current server time.

Results are ordered by expiresAt, earliest first. The frontend should still treat secondsRemaining as advisory and expect the authorisation command to reject a transaction that expires before submission.

Frontend handling

When opened from FCM:

1. Authenticate the user if necessary.
2. Execute this query.
3. Find the server-returned item whose id matches the notification's transactionId.
4. If no match exists, show that the request is expired, completed, or no longer available.
5. Render the confirmation UI from the server-returned item.
6. Submit approval using Authorize Transaction.

Do not display sensitive transaction details directly from the notification data map.

Error handling

Missing or invalid authentication is rejected by the self-service endpoint with HTTP 401.

A handled command failure is returned inside the normal command envelope:

{
  "ok": true,
  "message": "Executed successfully",
  "outData": {
    "isSuccessful": false,
    "statusCode": "400",
    "message": "Error fetching pending transactions: <reason>",
    "data": null
  }
}

Clients must check both the HTTP result and outData.isSuccessful.

Security requirements

• Never add a user or tenant selector to the request.
• Never treat a transaction identifier received through FCM as proof of ownership.
• Never cache the returned list beyond its expiry window.
• Mask account identifiers according to the application's display policy.
• Re-query after login, profile switch, app resume, or an authorisation failure caused by stale state.

Related APIs

• Authorize Transaction
• FCM Frontend Integration