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>"
}
'

import requests

url = "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments"

payload = {
    "selectedCurrency": "<string>",
    "fromDate": "<string>",
    "toDate": "<string>",
    "searchablePaymentReference": "<string>"
}
headers = {
    "platform": "<platform>",
    "uuid": "<uuid>",
    "X-Auth-Token": "<x-auth-token>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    platform: '<platform>',
    uuid: '<uuid>',
    'X-Auth-Token': '<x-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    selectedCurrency: '<string>',
    fromDate: '<string>',
    toDate: '<string>',
    searchablePaymentReference: '<string>'
  })
};

fetch('https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'selectedCurrency' => '<string>',
    'fromDate' => '<string>',
    'toDate' => '<string>',
    'searchablePaymentReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Auth-Token: <x-auth-token>",
    "platform: <platform>",
    "uuid: <uuid>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments"

	payload := strings.NewReader("{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("platform", "<platform>")
	req.Header.Add("uuid", "<uuid>")
	req.Header.Add("X-Auth-Token", "<x-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments")
  .header("platform", "<platform>")
  .header("uuid", "<uuid>")
  .header("X-Auth-Token", "<x-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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);
}

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>"
}
'

import requests

url = "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments"

payload = {
    "selectedCurrency": "<string>",
    "fromDate": "<string>",
    "toDate": "<string>",
    "searchablePaymentReference": "<string>"
}
headers = {
    "platform": "<platform>",
    "uuid": "<uuid>",
    "X-Auth-Token": "<x-auth-token>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    platform: '<platform>',
    uuid: '<uuid>',
    'X-Auth-Token': '<x-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    selectedCurrency: '<string>',
    fromDate: '<string>',
    toDate: '<string>',
    searchablePaymentReference: '<string>'
  })
};

fetch('https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'selectedCurrency' => '<string>',
    'fromDate' => '<string>',
    'toDate' => '<string>',
    'searchablePaymentReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Auth-Token: <x-auth-token>",
    "platform: <platform>",
    "uuid: <uuid>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments"

	payload := strings.NewReader("{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("platform", "<platform>")
	req.Header.Add("uuid", "<uuid>")
	req.Header.Add("X-Auth-Token", "<x-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments")
  .header("platform", "<platform>")
  .header("uuid", "<uuid>")
  .header("X-Auth-Token", "<x-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.fincode.software/api/v6/services/paymentmanagement/awaiting-payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selectedCurrency\": \"<string>\",\n  \"fromDate\": \"<string>\",\n  \"toDate\": \"<string>\",\n  \"searchablePaymentReference\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

Authentication token obtained after login.

string

required

Device UUID used for request tracking.

string

required

Platform identifier (e.g., “WEB”, “ANDROID”, “IOS”).

Query Parameters

number

Pagination page number (default: 1)

number

Number of records per page (default: 20)

Request Body

string

required

Currency code used for filtering (e.g., "USD", "NGN", "GBP").

string

required

Start date in format dd/MM/yyyy (e.g., "01/01/2024").

string

required

End date in format dd/MM/yyyy (e.g., "31/01/2024").

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"
  }'

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();

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()

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"
      }
    ]
  }
}

{
  "status": "FAILED",
  "message": "Invalid device info.",
  "responseCode": 401
}

{
  "status": "FAILED",
  "message": "Please send currency !",
  "responseCode": 500
}

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

Getting Started

Core Flows

API Endpoints

List Awaiting Payments

Overview

Authentication

Query Parameters

Request Body

Request Example

Response Example

Use Cases

1. Display Awaiting Payments in a Dashboard

2. Filter Payments by Date Range

3. Identify Items Requiring Follow-Up

Error Handling

Important Notes

Next Steps

Awaiting Payment Actions

Bank I Will Pay Later

Payment Method Charges

Supported Payment Methods

Headers

Query Parameters

Body

Response

​Overview

​Authentication

​Query Parameters

​Request Body

​Request Example

​Response Example

​Use Cases

​1. Display Awaiting Payments in a Dashboard

​2. Filter Payments by Date Range

​3. Identify Items Requiring Follow-Up

​Error Handling

​Important Notes

​Next Steps

Awaiting Payment Actions

Bank I Will Pay Later

Payment Method Charges

Supported Payment Methods

Headers

Query Parameters

Body

Response

Overview

Authentication

Query Parameters

Request Body

Request Example

Response Example

Use Cases

1. Display Awaiting Payments in a Dashboard

2. Filter Payments by Date Range

3. Identify Items Requiring Follow-Up

Error Handling

Important Notes

Next Steps