Skip to main content
GET
/
paymentmanagement
/
awaiting-payments
List Awaiting Payments
curl --request GET \
  --url https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <x-auth-token>' \
  --header 'platform: <platform>' \
  --header 'uuid: <uuid>' \
  --data '
{
  "selectedCurrency": "<string>",
  "fromDate": "<string>",
  "toDate": "<string>",
  "searchablePaymentReference": "<string>"
}
'
try {
  const res = await fetch('/awaiting-payments?page=1&size=20', { ...config });

  const data = await res.json();

  if (data.status === 'FAILED') {
    console.error("Error:", data.message);
  }
} catch (err) {
  console.error("Network/server error:", err);
}

​
Overview

This endpoint retrieves all awaiting payments for the authenticated customer or organization within a specified date range and currency. It is typically used by dashboards, finance teams, or customer apps to list:
  • Pending bank transfers
  • Confirmations awaiting customer or MTO verification
  • Payments requiring follow-up actions
  • Items awaiting funding or payout
Use this endpoint to display or filter all awaiting/pending payments for your customers.

​
Authentication

​
X-Auth-Token
string
required
Authentication token obtained after login.
​
uuid
string
required
Device UUID used for request tracking.
​
platform
string
required
Platform identifier (e.g., “WEB”, “ANDROID”, “IOS”).

​
Query Parameters

​
page
number
Pagination page number (default: 1)
​
size
number
Number of records per page (default: 20)

​
Request Body

​
selectedCurrency
string
required
Currency code used for filtering (e.g., "USD", "NGN", "GBP").
​
fromDate
string
required
Start date in format dd/MM/yyyy (e.g., "01/01/2024").
​
toDate
string
required
End date in format dd/MM/yyyy (e.g., "31/01/2024").
​
searchablePaymentReference
string
Optional payment reference or identifier used for fuzzy search.

​
Request Example

curl --request GET \
  --url "https://api.example.com/awaiting-payments?page=1&size=20" \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: your_auth_token' \
  --header 'uuid: your_device_uuid' \
  --header 'platform: WEB' \
  --data '{
    "selectedCurrency": "USD",
    "fromDate": "01/01/2024",
    "toDate": "31/01/2024",
    "searchablePaymentReference": "TRX"
  }'

​
Response Example

{
  "status": "SUCCESS",
  "responseCode": 200,
  "data": {
    "awaitingPayments": [
      {
        "id": "AP12345",
        "payableType": "TRANSACTION",
        "bankTransferFollowupActionType": "AUTO_CONFIRM_TRANSACTION",
        "bankTransferLifeCycle": "AWAITING_BANK_TRANSFER_PAYMENT",
        "mtoPaymentConfirmtionType": "NOT_CONFIRMED",
        "customerConfirmedPaymentDate": null,
        "creationDate": "2024-01-10T12:30:00",
        "currency": "USD",
        "requestedBankTransferAmount": 150,
        "searchablePaymentReference": "TRX-90832",
        "payerBankTransferReference": "BTREF123"
      }
    ]
  }
}

​
Use Cases

​
1. Display Awaiting Payments in a Dashboard

const res = await getAwaitingPayments(filters);
res.data.awaitingPayments.forEach(entry => {
  console.log(entry.searchablePaymentReference, entry.requestedBankTransferAmount);
});

​
2. Filter Payments by Date Range

await getAwaitingPayments({
  selectedCurrency: "GBP",
  fromDate: "01/02/2024",
  toDate: "10/02/2024"
});

​
3. Identify Items Requiring Follow-Up

const items = res.data.awaitingPayments.filter(
  p => p.bankTransferFollowupActionType === 'MARK_AS_PENDING_TRANSACTION'
);

​
Error Handling

try {
  const res = await fetch('/awaiting-payments?page=1&size=20', { ...config });

  const data = await res.json();

  if (data.status === 'FAILED') {
    console.error("Error:", data.message);
  }
} catch (err) {
  console.error("Network/server error:", err);
}

​
Important Notes

  • Authentication is mandatory
  • selectedCurrency, fromDate, and toDate are required
  • Users with role CASHIER are not allowed
  • Date format must be dd/MM/yyyy
  • The lifecycle status helps identify pending, received, or completed items
  • Reference search improves lookup of specific payments

​
Next Steps

Awaiting Payment Actions

Take follow-up actions (mark pending, confirm, etc.)

Bank I Will Pay Later

Mark a payment as ‘I will pay later’

Payment Method Charges

Retrieve applicable charges for payments

Supported Payment Methods

View available payment methods

Headers

​
platform
string
default:fincode
required
​
uuid
string
default:200
required
​
X-Auth-Token
string
required

Query Parameters

​
page
number
default:1
​
size
number
default:20

Body

application/json
​
selectedCurrency
string
required
​
fromDate
string
required
​
toDate
string
required
​
searchablePaymentReference
string

Response

200

List of awaiting payments