> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincode.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# List Awaiting Payments

> Retrieve all pending/awaiting payment records for a customer based on filters such as date range, currency, and reference search.

## 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

<Note>
  Use this endpoint to display or filter all awaiting/pending payments for your customers.
</Note>

## Authentication

<ParamField header="X-Auth-Token" type="string" required>
  Authentication token obtained after login.
</ParamField>

<ParamField header="uuid" type="string" required>
  Device UUID used for request tracking.
</ParamField>

<ParamField header="platform" type="string" required>
  Platform identifier (e.g., "WEB", "ANDROID", "IOS").
</ParamField>

## Query Parameters

<ParamField query="page" type="number">
  Pagination page number (default: `1`)
</ParamField>

<ParamField query="size" type="number">
  Number of records per page (default: `20`)
</ParamField>

## Request Body

<ParamField body="selectedCurrency" type="string" required>
  Currency code used for filtering (e.g., `"USD"`, `"NGN"`, `"GBP"`).
</ParamField>

<ParamField body="fromDate" type="string" required>
  Start date in format `dd/MM/yyyy` (e.g., `"01/01/2024"`).
</ParamField>

<ParamField body="toDate" type="string" required>
  End date in format `dd/MM/yyyy` (e.g., `"31/01/2024"`).
</ParamField>

<ParamField body="searchablePaymentReference" type="string">
  Optional payment reference or identifier used for fuzzy search.
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.example.com/awaiting-payments?page=1&size=20',
    {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'X-Auth-Token': authToken,
        'uuid': deviceUuid,
        'platform': 'WEB'
      },
      body: JSON.stringify({
        selectedCurrency: 'USD',
        fromDate: '01/01/2024',
        toDate: '31/01/2024',
        searchablePaymentReference: 'TRX'
      })
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

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

  response = requests.get(url, json=payload, headers=headers)
  data = response.json()
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json 200 OK theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "status": "FAILED",
    "message": "Invalid device info.",
    "responseCode": 401
  }
  ```

  ```json 500 Error theme={null}
  {
    "status": "FAILED",
    "message": "Please send currency !",
    "responseCode": 500
  }
  ```
</CodeGroup>

## Use Cases

### 1. Display Awaiting Payments in a Dashboard

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

### 2. Filter Payments by Date Range

```javascript theme={null}
await getAwaitingPayments({
  selectedCurrency: "GBP",
  fromDate: "01/02/2024",
  toDate: "10/02/2024"
});
```

### 3. Identify Items Requiring Follow-Up

```javascript theme={null}
const items = res.data.awaitingPayments.filter(
  p => p.bankTransferFollowupActionType === 'MARK_AS_PENDING_TRANSACTION'
);
```

## Error Handling

<ResponseExample>
  ```javascript theme={null}
  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);
  }
  ```
</ResponseExample>

## Important Notes

<Warning>
  * Authentication is mandatory
  * `selectedCurrency`, `fromDate`, and `toDate` are required
  * Users with role `CASHIER` are not allowed
</Warning>

<Info>
  * Date format must be `dd/MM/yyyy`
  * The lifecycle status helps identify pending, received, or completed items
  * Reference search improves lookup of specific payments
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Awaiting Payment Actions" href="/api/deposit-engine/awaiting-payment-actions">
    Take follow-up actions (mark pending, confirm, etc.)
  </Card>

  <Card title="Bank I Will Pay Later" href="/api/deposit-engine/bank-iwillpaylater">
    Mark a payment as 'I will pay later'
  </Card>

  <Card title="Payment Method Charges" href="/api/deposit-engine/payment-methods-charges">
    Retrieve applicable charges for payments
  </Card>

  <Card title="Supported Payment Methods" href="/api/deposit-engine/supported-payment-methods">
    View available payment methods
  </Card>
</CardGroup>

```
```


## OpenAPI

````yaml GET /paymentmanagement/awaiting-payments
openapi: 3.0.0
info:
  title: FinCode API
  version: v6
servers:
  - url: https://{tenant}.fincode.software/api/v6/services
    description: API v6
    variables:
      tenant:
        default: remitjunction
        description: Enter your tenant subdomain
  - url: https://{tenant}.fincode.software/api/v1/services
    description: API v1
    variables:
      tenant:
        default: finlend
        description: Enter your tenant subdomain
  - url: https://api.stag.songhaiexchange.io
    description: Songhai Exchange API
security: []
paths:
  /paymentmanagement/awaiting-payments:
    get:
      summary: List Awaiting Payments
      description: Retrieve all pending payments
      operationId: listAwaitingPayments
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - $ref: '#/components/parameters/uuidHeader'
        - in: header
          name: X-Auth-Token
          schema:
            type: string
          required: true
        - in: query
          name: page
          schema:
            type: number
            default: 1
        - in: query
          name: size
          schema:
            type: number
            default: 20
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                selectedCurrency:
                  type: string
                fromDate:
                  type: string
                toDate:
                  type: string
                searchablePaymentReference:
                  type: string
              required:
                - selectedCurrency
                - fromDate
                - toDate
      responses:
        '200':
          description: List of awaiting payments
components:
  parameters:
    platformHeader:
      in: header
      name: platform
      schema:
        type: string
        default: fincode
      required: true
    uuidHeader:
      in: header
      name: uuid
      schema:
        type: string
        default: '200'
      required: true

````