Payment Request - OneTap

Create Payment Request

Create a new payment request for a customer. The customer will receive a notification and can approve or decline the request.

string

required

Customer’s PayTag (e.g., @johndoe)

number

required

Payment amount in the specified currency (maximum: 999,999,999)

string

Unique reference for this transaction (max 100 characters). Auto-generated if not provided.

string

Description or note for the payment request (max 250 characters)

string

default:"NGN"

Currency code: NGN (Nigerian Naira) or FP (FLEX Points)

integer

default:"30"

Expiration duration in minutes (minimum: 2)

string

Customer’s PIN for additional verification (optional, 6 digits)

object

Additional custom data to store with the payment request

Request Example

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/merchant/payment-request \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-location: your_location_id' \
  --data '{
    "payer": "@johndoe",
    "amount": 5000,
    "reference": "INV-12345",
    "comment": "Payment for Invoice #12345",
    "currency": "NGN",
    "duration": 60,
    "metadata": {
      "invoice_id": "12345",
      "customer_email": "john@example.com"
    }
  }'

const response = await fetch('https://staging-api.yourflexpay.com/v2/merchant/payment-request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-client-id': 'your_client_id',
    'x-api-key': 'your_api_key',
    'x-location': 'your_location_id'
  },
  body: JSON.stringify({
    payer: '@johndoe',
    amount: 5000,
    reference: 'INV-12345',
    comment: 'Payment for Invoice #12345',
    currency: 'NGN',
    duration: 60,
    metadata: {
      invoice_id: '12345',
      customer_email: 'john@example.com'
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://staging-api.yourflexpay.com/v2/merchant/payment-request',
    headers={
        'Content-Type': 'application/json',
        'x-client-id': 'your_client_id',
        'x-api-key': 'your_api_key',
        'x-location': 'your_location_id'
    },
    json={
        'payer': '@johndoe',
        'amount': 5000,
        'reference': 'INV-12345',
        'comment': 'Payment for Invoice #12345',
        'currency': 'NGN',
        'duration': 60,
        'metadata': {
            'invoice_id': '12345',
            'customer_email': 'john@example.com'
        }
    }
)

data = response.json()

Response

integer

Unique payment request identifier

string

Transaction reference

number

Payment amount

string

Current status: Pending, Accepted, Declined, Cancelled, or Expired

string

Payment description/comment

object

Merchant information

Show properties

integer

PayTag ID

string

PayTag handle

string

Display name

object

Customer information (same structure as PayTag)

string

Transaction type (always C2M for customer-to-merchant)

string

ISO 8601 datetime when the payment request expires

string

ISO 8601 datetime when the payment request was created

string

ISO 8601 datetime of last update

{
  "ID": 12345,
  "Reference": "INV-12345",
  "Amount": 5000,
  "Status": "Pending",
  "Description": "Payment for Invoice #12345",
  "PayTag": {
    "ID": 1,
    "Tag": "@yourbusiness",
    "Name": "Your Business Name"
  },
  "Payer": {
    "ID": 2,
    "Tag": "@johndoe",
    "Name": "John Doe"
  },
  "Type": "C2M",
  "ExpiresAt": "2026-07-30T15:30:00Z",
  "CreatedAt": "2026-07-30T14:30:00Z",
  "UpdatedAt": "2026-07-30T14:30:00Z"
}

List Payment Requests

Retrieve a paginated list of payment requests for your merchant location.

integer

default:"20"

Number of results per page (max: 100)

integer

default:"0"

Number of results to skip for pagination

string

Filter by status: Pending, Accepted, Declined, Cancelled, or Expired

Request Example

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/merchant/payment-request?limit=10&status=Pending' \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-location: your_location_id'

const params = new URLSearchParams({
  limit: '10',
  status: 'Pending'
});

const response = await fetch(
  `https://staging-api.yourflexpay.com/v2/merchant/payment-request?${params}`,
  {
    headers: {
      'x-client-id': 'your_client_id',
      'x-api-key': 'your_api_key',
      'x-location': 'your_location_id'
    }
  }
);

const data = await response.json();

Response

array

Array of payment request objects

integer

Total number of payment requests matching the query

integer

Number of results per page

integer

Current pagination offset

{
  "items": [
    {
      "ID": 12345,
      "Reference": "INV-12345",
      "Amount": 5000,
      "Status": "Pending",
      "Description": "Payment for Invoice #12345",
      "PayTag": {
        "ID": 1,
        "Tag": "@yourbusiness",
        "Name": "Your Business Name"
      },
      "Payer": {
        "ID": 2,
        "Tag": "@johndoe",
        "Name": "John Doe"
      },
      "Type": "C2M",
      "ExpiresAt": "2026-07-30T15:30:00Z",
      "CreatedAt": "2026-07-30T14:30:00Z",
      "UpdatedAt": "2026-07-30T14:30:00Z"
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}

Get Payment Request

Retrieve details of a specific payment request by reference.

string

required

Unique payment request reference

Request Example

curl --request GET \
  --url https://staging-api.yourflexpay.com/v2/merchant/payment-request/INV-12345 \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-location: your_location_id'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/merchant/payment-request/INV-12345',
  {
    headers: {
      'x-client-id': 'your_client_id',
      'x-api-key': 'your_api_key',
      'x-location': 'your_location_id'
    }
  }
);

const data = await response.json();

Response

Returns a single payment request object (same structure as create endpoint).

{
  "ID": 12345,
  "Reference": "INV-12345",
  "Amount": 5000,
  "Status": "Accepted",
  "Description": "Payment for Invoice #12345",
  "PayTag": {
    "ID": 1,
    "Tag": "@yourbusiness",
    "Name": "Your Business Name"
  },
  "Payer": {
    "ID": 2,
    "Tag": "@johndoe",
    "Name": "John Doe"
  },
  "Type": "C2M",
  "ExpiresAt": "2026-07-30T15:30:00Z",
  "CreatedAt": "2026-07-30T14:30:00Z",
  "UpdatedAt": "2026-07-30T14:35:00Z"
}

Cancel Payment Request

Cancel a pending payment request. Only requests with Pending status can be cancelled.

string

required

Unique payment request reference to cancel

Request Example

curl --request POST \
  --url https://staging-api.yourflexpay.com/v2/merchant/payment-request/INV-12345/cancel \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key' \
  --header 'x-location: your_location_id'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/merchant/payment-request/INV-12345/cancel',
  {
    method: 'POST',
    headers: {
      'x-client-id': 'your_client_id',
      'x-api-key': 'your_api_key',
      'x-location': 'your_location_id'
    }
  }
);

const data = await response.json();

Response

Returns the cancelled payment request with updated status.

{
  "ID": 12345,
  "Reference": "INV-12345",
  "Amount": 5000,
  "Status": "Cancelled",
  "Description": "Payment for Invoice #12345",
  "PayTag": {
    "ID": 1,
    "Tag": "@yourbusiness",
    "Name": "Your Business Name"
  },
  "Payer": {
    "ID": 2,
    "Tag": "@johndoe",
    "Name": "John Doe"
  },
  "Type": "C2M",
  "ExpiresAt": "2026-07-30T15:30:00Z",
  "CreatedAt": "2026-07-30T14:30:00Z",
  "UpdatedAt": "2026-07-30T14:45:00Z"
}

Resolve PayTag

Verify that a customer PayTag exists and retrieve basic information before creating a payment request.

This endpoint does not require the x-location header.

string

required

Customer PayTag to verify (e.g., @johndoe)

Request Example

curl --request GET \
  --url 'https://staging-api.yourflexpay.com/v2/merchant/payment-request/resolve-paytag?tag=@johndoe' \
  --header 'x-client-id: your_client_id' \
  --header 'x-api-key: your_api_key'

const response = await fetch(
  'https://staging-api.yourflexpay.com/v2/merchant/payment-request/resolve-paytag?tag=@johndoe',
  {
    headers: {
      'x-client-id': 'your_client_id',
      'x-api-key': 'your_api_key'
    }
  }
);

const data = await response.json();

Response

string

Customer’s display name

string

Customer’s PayTag handle

{
  "Name": "John Doe",
  "Tag": "@johndoe"
}

{
  "statusCode": 404,
  "message": "PayTag not found"
}

Payment Request Statuses

Status	Description
`Pending`	Awaiting customer action
`Accepted`	Customer approved and payment completed
`Declined`	Customer rejected the payment request
`Cancelled`	Merchant cancelled the request
`Expired`	Request expired before customer action

Error Responses

400 - Bad Request

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "amount must be a positive number",
    "payer must be a valid PayTag"
  ]
}

401 - Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

404 - Not Found

{
  "statusCode": 404,
  "message": "Payment request not found"
}

Wallet SSO

Merchant

Partner

IDAAS

Payment Request - OneTap

Create Payment Request

Request Example

Response

List Payment Requests

Request Example

Response

Get Payment Request

Request Example

Response

Cancel Payment Request

Request Example

Response

Resolve PayTag

Request Example

Response

Payment Request Statuses

Error Responses

​Create Payment Request

​Request Example

​Response

​List Payment Requests

​Request Example

​Response

​Get Payment Request

​Request Example

​Response

​Cancel Payment Request

​Request Example

​Response

​Resolve PayTag

​Request Example

​Response

​Payment Request Statuses

​Error Responses

Create Payment Request

Request Example

Response

List Payment Requests

Request Example

Response

Get Payment Request

Request Example

Response

Cancel Payment Request

Request Example

Response

Resolve PayTag

Request Example

Response

Payment Request Statuses

Error Responses