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

# Payment Request - OneTap

> API reference for managing payment requests

## Create Payment Request

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

<ParamField body="payer" type="string" required>
  Customer's PayTag (e.g., `@johndoe`)
</ParamField>

<ParamField body="amount" type="number" required>
  Payment amount in the specified currency (maximum: 999,999,999)
</ParamField>

<ParamField body="reference" type="string">
  Unique reference for this transaction (max 100 characters). Auto-generated if not provided.
</ParamField>

<ParamField body="comment" type="string">
  Description or note for the payment request (max 250 characters)
</ParamField>

<ParamField body="currency" type="string" default="NGN">
  Currency code: `NGN` (Nigerian Naira) or `FP` (FLEX Points)
</ParamField>

<ParamField body="duration" type="integer" default="30">
  Expiration duration in minutes (minimum: 2)
</ParamField>

<ParamField body="pin" type="string">
  Customer's PIN for additional verification (optional, 6 digits)
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom data to store with the payment request
</ParamField>

### Request Example

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

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

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

### Response

<ResponseField name="ID" type="integer">
  Unique payment request identifier
</ResponseField>

<ResponseField name="Reference" type="string">
  Transaction reference
</ResponseField>

<ResponseField name="Amount" type="number">
  Payment amount
</ResponseField>

<ResponseField name="Status" type="string">
  Current status: `Pending`, `Accepted`, `Declined`, `Cancelled`, or `Expired`
</ResponseField>

<ResponseField name="Description" type="string">
  Payment description/comment
</ResponseField>

<ResponseField name="PayTag" type="object">
  Merchant information

  <Expandable title="properties">
    <ResponseField name="ID" type="integer">
      PayTag ID
    </ResponseField>

    <ResponseField name="Tag" type="string">
      PayTag handle
    </ResponseField>

    <ResponseField name="Name" type="string">
      Display name
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="Payer" type="object">
  Customer information (same structure as PayTag)
</ResponseField>

<ResponseField name="Type" type="string">
  Transaction type (always `C2M` for customer-to-merchant)
</ResponseField>

<ResponseField name="ExpiresAt" type="string">
  ISO 8601 datetime when the payment request expires
</ResponseField>

<ResponseField name="CreatedAt" type="string">
  ISO 8601 datetime when the payment request was created
</ResponseField>

<ResponseField name="UpdatedAt" type="string">
  ISO 8601 datetime of last update
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## List Payment Requests

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

<ParamField query="limit" type="integer" default="20">
  Number of results per page (max: 100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `Pending`, `Accepted`, `Declined`, `Cancelled`, or `Expired`
</ParamField>

### Request Example

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

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

### Response

<ResponseField name="items" type="array">
  Array of payment request objects
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of payment requests matching the query
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of results per page
</ResponseField>

<ResponseField name="offset" type="integer">
  Current pagination offset
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```
</ResponseExample>

***

## Get Payment Request

Retrieve details of a specific payment request by reference.

<ParamField path="reference" type="string" required>
  Unique payment request reference
</ParamField>

### Request Example

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

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

### Response

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

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## Cancel Payment Request

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

<ParamField path="reference" type="string" required>
  Unique payment request reference to cancel
</ParamField>

### Request Example

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

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

### Response

Returns the cancelled payment request with updated status.

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## Resolve PayTag

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

<Info>
  This endpoint does **not** require the `x-location` header.
</Info>

<ParamField query="tag" type="string" required>
  Customer PayTag to verify (e.g., `@johndoe`)
</ParamField>

### Request Example

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

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

### Response

<ResponseField name="Name" type="string">
  Customer's display name
</ResponseField>

<ResponseField name="Tag" type="string">
  Customer's PayTag handle
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "Name": "John Doe",
    "Tag": "@johndoe"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 404 - PayTag Not Found theme={null}
  {
    "statusCode": 404,
    "message": "PayTag not found"
  }
  ```
</ResponseExample>

***

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

<AccordionGroup>
  <Accordion title="400 - Bad Request">
    ```json theme={null}
    {
      "statusCode": 400,
      "message": "Validation failed",
      "errors": [
        "amount must be a positive number",
        "payer must be a valid PayTag"
      ]
    }
    ```
  </Accordion>

  <Accordion title="401 - Unauthorized">
    ```json theme={null}
    {
      "statusCode": 401,
      "message": "Unauthorized"
    }
    ```
  </Accordion>

  <Accordion title="404 - Not Found">
    ```json theme={null}
    {
      "statusCode": 404,
      "message": "Payment request not found"
    }
    ```
  </Accordion>
</AccordionGroup>