FuturePayNG Logo
FuturePayNGv1.0.0
FuturePayNG Invoice Payment API v1.0.0

Invoice Payment API Reference

Complete RESTful endpoints for invoice lifecycles: generate dynamic QR codes, poll status, cancel abandoned checkouts, refund payments, and query transaction ledgers.

api1. Endpoints Overview

Available REST Endpoints

All endpoints accept and return JSON. Authenticate every call using the X-FuturePay-Api-Key header.

MethodEndpoint PathPurposeStatus
POST/api/v1/checkout/invoicesCreates an invoice & generates dynamic QR code base64201 Created
GET/api/v1/checkout/invoices/{invoiceReference}Retrieves real-time payment status (pending, paid, cancelled)200 OK
POST/api/v1/checkout/invoices/{invoiceReference}/cancelCancels an unpaid or abandoned pending checkout invoice200 OK
POST/api/v1/checkout/invoices/{invoiceReference}/refundIssues a full refund of a paid invoice back to the customer200 OK
GET/api/v1/checkout/invoicesQueries merchant invoices filtered by status and date200 OK
Interactive Live Console

Live API Request & Response Playground

Send real HTTP requests against the FuturePayNG Staging API with instant responses.

https://stage-futurepay.yellow.team
POSThttps://stage-futurepay.yellow.team/api/v1/checkout/invoices
Response Payload
Click "Send Request" to execute this call live against FuturePayNG Staging API
POST/api/v1/checkout/invoices
Create Invoice

Call this endpoint when the customer clicks "Pay with FuturePayNG" on your web storefront. It generates a unique invoice reference, checkout payment URL, and base64 PNG QR code for display.

Request Body Parameters:

FieldTypeRequiredDescription
orderReferenceStringRequiredYour unique internal order/cart ID (e.g. ORDER-89421).
amountNumberRequiredTotal payable amount in NGN (Minimum: 100).
currencyStringOptionalISO currency code. Defaults to NGN.
webhookUrlStringOptionalYour HTTPS endpoint for asynchronous payment notifications.
metadataObjectOptionalArbitrary key-value pairs stored and returned with webhooks.
Sample 201 Created ResponseJSON
{
  "invoiceReference": "FP-M3PSY-77TUY",
  "orderReference": "ORDER-NG-89421",
  "amount": 25000,
  "currency": "NGN",
  "status": "pending",
  "createdAt": "2026-11-07T10:05:51.481Z",
  "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAANQAAADUCAYAAADk3g0Y...",
  "qrHash": "9e3b77a70e034bd4a535a75775960aa31152e40c2c82907f03a1cd96df7ce942",
  "merchant": {
    "businessName": "Your Registered Business",
    "businessOwnerName": "Business Director"
  },
  "metadata": {
    "email": "customer@example.com"
  },
  "expiresAt": "2026-11-07T20:05:51.417Z"
}
GET/api/v1/checkout/invoices/{invoiceReference}
Poll Status

Use this endpoint if your server does not receive webhooks or if your frontend needs to poll payment confirmation every 3 seconds while the customer modal is open.

Sample 200 OK ResponseJSON
{
  "invoiceReference": "FP-S5HAG-KY8AT",
  "orderReference": "ORDER-NG-89421",
  "amount": 25000,
  "currency": "NGN",
  "status": "paid",
  "createdAt": "2026-11-05T10:26:25.707Z",
  "merchant": {
    "businessName": "Your Registered Business",
    "businessOwnerName": "Business Director"
  },
  "customer": {
    "fullName": "Customer Name",
    "phoneNumber": "+2348122211137"
  },
  "paymentMethod": "Card",
  "metadata": {
    "email": "customer@example.com"
  },
  "paidAt": "2026-11-05T10:27:56.000Z",
  "expiresAt": "2026-11-05T20:26:26.000Z"
}
POST/api/v1/checkout/invoices/{invoiceReference}/cancel
Cancel Invoice

Cancels an unpaid invoice if the customer abandons checkout or closes the modal. Only invoices in pending status can be cancelled.

Sample 200 OK Cancelled ResponseJSON
{
  "invoiceReference": "FP-M3PSY-77TUY",
  "orderReference": "ORDER-NG-89421",
  "amount": 25000,
  "currency": "NGN",
  "status": "cancelled",
  "createdAt": "2026-11-07T10:05:51.481Z",
  "merchant": {
    "businessName": "Your Registered Business",
    "businessOwnerName": "Business Director"
  },
  "metadata": {
    "email": "customer@example.com"
  },
  "cancelledAt": "2026-11-07T10:05:53.478Z",
  "expiresAt": "2026-11-07T20:05:51.000Z"
}
POST/api/v1/checkout/invoices/{invoiceReference}/refund
Full Refund

Refunds an already paid invoice in full directly back to the customer's FuturePayNG wallet. Only invoices in paid status can be refunded.

Sample 200 OK Refunded ResponseJSON
{
  "invoiceReference": "FP-S5HAG-KY8AT",
  "orderReference": "ORDER-NG-89421",
  "amount": 25000,
  "currency": "NGN",
  "status": "refunded_full",
  "createdAt": "2026-11-05T10:26:25.707Z",
  "merchant": {
    "businessName": "Your Registered Business",
    "businessOwnerName": "Business Director"
  },
  "customer": {
    "fullName": "Customer Name",
    "phoneNumber": "+2348122211137"
  },
  "paymentMethod": "Card",
  "metadata": {
    "email": "customer@example.com"
  },
  "paidAt": "2026-11-05T10:27:56.000Z",
  "refundedAt": "2026-11-07T10:07:07.981Z",
  "expiresAt": "2026-11-05T20:26:26.000Z"
}
GET/api/v1/checkout/invoices
Query Ledger

Fetches a paginated list of your merchant invoices. Supports filtering query parameters:

statusFilter by pending, paid, cancelled, or refunded_full.
page & limitStandard pagination. Default limit=20, maximum 100.
fromDate / toDateFilter by ISO-8601 creation dates.
Sample 200 OK Paginated List ResponseJSON
{
  "invoices": [
    {
      "invoiceReference": "FP-S5HAG-KY8AT",
      "orderReference": "ORDER-NG-89421",
      "amount": 25000,
      "currency": "NGN",
      "status": "paid",
      "createdAt": "2026-11-05T10:26:25.707Z",
      "merchant": {
        "businessName": "Your Registered Business",
        "businessOwnerName": "Business Director"
      },
      "customer": {
        "fullName": "Customer Name",
        "phoneNumber": "+2348122211137"
      },
      "paymentMethod": "Card",
      "metadata": {
        "email": "customer@example.com"
      },
      "paidAt": "2026-11-05T10:27:56.000Z",
      "expiresAt": "2026-11-05T20:26:26.000Z"
    }
  ],
  "total": 167,
  "page": 1,
  "limit": 10
}