Terminal

Overview

Terminals are managed from the Partner Portal at https://partner.yourflexpay.com. This API is meant to be integrated into a collection terminal that has already been added and configured from the portal. The Terminal API provides endpoints for terminal-specific operations including profile management, money collection, and split payment functionality.

All terminal endpoints require three headers:

x-client-id: Your partner ID
x-api-key: Your partner API key
x-terminal: Terminal serial number

The x-terminal value must match a terminal already created in the Partner Portal.

Terminal Endpoints

Get Terminal Profile

GET /terminal - Retrieve terminal information and QR code

Initiate Transaction

POST /terminal/transaction - Process a terminal payment

List Transactions

GET /terminal/transactions - Get terminal transaction history

Get Transaction

GET /terminal/transaction/{reference} - Get specific transaction details

Split Payment Endpoints

Create Split

POST /terminal/split - Create a split payment

List Splits

GET /terminal/splits - Get all splits for terminal

Get Split

GET /terminal/split/{split} - Get split details

Split QR Code

GET /terminal/split/{split}/qr - Generate QR for split payment

Get Terminal Profile

Retrieve terminal information including balance, PayTag, and a dynamic QR code for accepting customer payments into Flex Wallet. Endpoint: GET /terminal Headers:

x-client-id: Your partner ID
x-api-key: Your API key
x-terminal: Terminal serial number (e.g., TERM-12345)

Response

{
  "SerialNumber": "TERM-12345",
  "TerminalID": "POS-001",
  "Merchant": "My Business",
  "Email": "terminal@mybusiness.com",
  "PhoneNumber": "+2348012345678",
  "Status": "Active",
  "PayTag": "@mybusiness_term1",
  "Balance": 150000.00,
  "Qr": "eyJhbW91bnQ...",
  "CreatedAt": "2026-01-15T10:00:00Z",
  "Metadata": {
    "location": "Store 1",
    "store_id": "STORE-001"
  }
}

The Qr field contains a QR payload that can be encoded into a QR code image for customers to scan and make payments through this terminal.

Initiate Transaction

Create a new collection transaction for the terminal. Endpoint: POST /terminal/transaction Request Body:

Field	Type	Required	Description
amount	number	Yes	Transaction amount (minimum: 100)
reference	string	Yes	Unique reference (max 50 chars, alphanumeric)
name	string	No	Customer name (max 100 chars)
description	string	No	Transaction description (max 255 chars)
metadata	object	No	Additional custom data

Request Example

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/terminal/transaction \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-terminal: TERM-12345' \
  --data '{
    "amount": 5000,
    "reference": "TXN-12345",
    "description": "Wallet collection",
      "metadata": {
        "product_id": "PROD-123",
        "source": "front_desk"
      }
  }'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/terminal/transaction',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-client-id': 'your_partner_id',
      'x-api-key': 'your_api_key',
      'x-terminal': 'TERM-12345'
    },
    body: JSON.stringify({
      amount: 5000,
      reference: 'TXN-12345',
      description: 'Wallet collection',
      metadata: {
        product_id: 'PROD-123',
        source: 'front_desk'
      }
    })
  }
);

const transactionToken = await response.json();

Response: Transaction reference or QR payload token for customer to complete payment

List Terminal Transactions

Retrieve paginated transaction history for the terminal. Endpoint: GET /terminal/transactions Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default: 20)
offset	integer	Pagination offset
search	string	Search by reference or customer name
reference	string	Filter by specific reference
status	string	Filter by status: `Pending`, `Successful`, `Failed`, etc.
startDate	string	Start date filter (YYYYMMDD format)
endDate	string	End date filter (YYYYMMDD format)

Response Example

{
  "items": [
    {
      "Amount": 5000,
      "Fee": 50,
      "Commission": 25,
      "Net": 4925,
      "Reference": "TXN-12345",
      "Sender": "@customer1",
      "SenderDetails": {
        "Name": "John Customer",
        "Paytag": "@customer1",
        "Amount": 5000,
        "Fee": 50,
        "Currency": "NGN"
      },
      "Recipient": "@mybusiness_term1",
      "Status": "Successful",
      "Comment": "Product purchase",
      "Date": "2026-07-30T10:00:00Z",
      "CompletedAt": "2026-07-30T10:00:15Z",
      "Metadata": {
        "product_id": "PROD-123"
      }
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

Create Split Payment

Create a split payment configuration that allows multiple parties to contribute to a total amount collected through the terminal. Endpoint: POST /terminal/split Request Body:

Field	Type	Required	Description
amount	number	Yes	Total amount to be split
title	string	No	Split title (max 50 chars)
description	string	No	Split description (max 255 chars)
reference	string	No	Custom reference (auto-generated if not provided)

Request Example

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/terminal/split \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-terminal: TERM-12345' \
  --data '{
    "amount": 10000,
    "title": "Store Order",
    "description": "Shared collection for multiple customers"
  }'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/terminal/split',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-client-id': 'your_partner_id',
      'x-api-key': 'your_api_key',
      'x-terminal': 'TERM-12345'
    },
    body: JSON.stringify({
      amount: 10000,
      title: 'Store Order',
      description: 'Shared collection for multiple customers'
    })
  }
);

const split = await response.json();

Response

{
  "Amount": 10000,
  "Reference": "SPLIT-ABC123",
  "Title": "Store Order",
  "Description": "Shared collection for multiple customers",
  "TotalPaid": 0,
  "Remaining": 10000,
  "Status": "Pending"
}

Generate Split Payment QR

Generate a QR code for a customer to contribute a specific amount to a split payment. Endpoint: GET /terminal/split/{split}/qr Path Parameters:

split: Split reference

Query Parameters:

amount (required): Amount this customer will pay

Request Example

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/terminal/split/SPLIT-ABC123/qr?amount=2500' \
  --header 'x-client-id: your_partner_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-terminal: TERM-12345'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/terminal/split/SPLIT-ABC123/qr?amount=2500',
  {
    headers: {
      'x-client-id': 'your_partner_id',
      'x-api-key': 'your_api_key',
      'x-terminal': 'TERM-12345'
    }
  }
);

const qrPayload = await response.json();

Response: QR payload string to be encoded into QR code image

Split Payment Flow

Create Split

Create a split payment with the total amount (e.g., a shared order or group collection)

Generate Individual QRs

Generate separate QR codes for each contributing party with their share (e.g., equal amounts or custom splits)

Customers Scan & Pay

Each customer scans their QR code and pays their portion

Monitor Progress

Track payments using GET /terminal/split/{split} to see TotalPaid and Remaining

Complete

When TotalPaid reaches Amount, the split status changes to “Completed”

Transaction Statuses

Status	Description
`Pending`	Transaction initiated, awaiting completion
`Successful`	Transaction completed successfully
`Failed`	Transaction failed
`Cancelled`	Transaction was cancelled
`Expired`	Transaction expired before completion
`Pending Review`	Transaction under review
`Waiting on Provider`	Awaiting external provider response

Error Responses

Status	Description
400	Invalid parameters or validation failed
401	Invalid partner credentials
404	Terminal or transaction not found
500	Server error

Quick Links

Transactions API

Gateway transaction management

Overview

Partner API overview

OpenAPI Spec

Complete API specification

For complete request/response schemas, parameters, and examples, refer to the Partner OpenAPI Specification.

Wallet SSO

Merchant

Partner

IDAAS

Overview

Terminal Endpoints

Get Terminal Profile

Initiate Transaction

List Transactions

Get Transaction

Split Payment Endpoints

Create Split

List Splits

Get Split

Split QR Code

Get Terminal Profile

Response

Initiate Transaction

Request Example

List Terminal Transactions

Response Example

Create Split Payment

Request Example

Response

Generate Split Payment QR

Request Example

Split Payment Flow

Transaction Statuses

Error Responses

Quick Links

Transactions API

Overview

OpenAPI Spec

​Overview

​Terminal Endpoints

Get Terminal Profile

Initiate Transaction

List Transactions

Get Transaction

​Split Payment Endpoints

Create Split

List Splits

Get Split

Split QR Code

​Get Terminal Profile

​Response

​Initiate Transaction

​Request Example

​List Terminal Transactions

​Response Example

​Create Split Payment

​Request Example

​Response

​Generate Split Payment QR

​Request Example

​Split Payment Flow

​Transaction Statuses

​Error Responses

​Quick Links

Transactions API

Overview

OpenAPI Spec

Overview

Terminal Endpoints

Split Payment Endpoints

Get Terminal Profile

Response

Initiate Transaction

Request Example

List Terminal Transactions

Response Example

Create Split Payment

Request Example

Response

Generate Split Payment QR

Request Example

Split Payment Flow

Transaction Statuses

Error Responses

Quick Links