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

# Get Payment History

> Retrieve past utility purchases, electricity tokens, data recharge receipts, and transaction records with pagination and filters.

Retrieve a user's recent bill payment transaction history. This allows users to look up previously generated meter tokens, recharge references, and tax/collection receipts.

### Query Parameters

| Parameter | Type | Description |
| :- | :- | :- |
| `page` | `integer` | Page number for pagination (defaults to `1`). |
| `limit` | `integer` | Number of items per page (default `20`, max `100`). |
| `category` | `string` | Filter by category (e.g. `ELECTRICITY`, `DATA`, `AIRTIME`, `RRR`). |
| `status` | `string` | Filter by status (`SUCCESS`, `PENDING`, `FAILED`). |
| `search` | `string` | Search query across meter number, phone, or reference. |

### Sample Paginated Response

```json theme={null}
{
  "success": true,
  "data": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "transactions": [
      {
        "id": "c928419a-9e02-4fbc-b819-8192a0194812",
        "userId": "efd29d37-4624-4fa5-8f24-b18cba593c9c",
        "billerType": "ELECTRICITY",
        "providerCode": "REMITA",
        "recipientId": "0219927013063",
        "amount": 5000,
        "providerReference": "HDL_VAS_1790800000",
        "status": "SUCCESS",
        "metadata": {
          "token": "4819-2049-1829-9401-2910",
          "units": "45.2 kWh",
          "customerName": "Ayodeji Peters"
        },
        "createdAt": "2026-10-01T12:00:00.000Z"
      }
    ]
  }
}
```


## OpenAPI

````yaml openapi.json GET /bill-payment/history
openapi: 3.0.3
info:
  title: Handle Merchant Payment Gateway API
  description: >-
    Developer API specification for accepting cardless, instant
    Account-to-Account (A2A) payments via Handle.
  version: 1.0.0
  contact:
    name: Handle Developer Support
    email: support@handle.ng
    url: https://handle.ng
servers:
  - url: https://api-local.handle.ng/api/v1
    description: Local Development (SSL)
  - url: https://api.handle.ng/api/v1
    description: Production Live Gateway
security:
  - BearerAuth: []
paths:
  /bill-payment/history:
    get:
      tags:
        - VAS & Bill Payments
      summary: Get Payment History
      description: >-
        Retrieve user bill payment transaction history, receipts, and token
        records with pagination and filters.
      parameters:
        - name: page
          in: query
          required: false
          description: Page number (defaults to 1)
          schema:
            type: integer
            default: 1
          example: 1
        - name: limit
          in: query
          required: false
          description: Number of records per page (default 20, max 100)
          schema:
            type: integer
            default: 20
          example: 20
        - name: category
          in: query
          required: false
          description: Filter by VAS Category (e.g. ELECTRICITY, AIRTIME, DATA, RRR)
          schema:
            type: string
          example: ELECTRICITY
        - name: status
          in: query
          required: false
          description: Filter by status (SUCCESS, PENDING, FAILED)
          schema:
            type: string
          example: SUCCESS
        - name: search
          in: query
          required: false
          description: Search by meter number, phone, recipientId, or transaction reference
          schema:
            type: string
          example: '0219927013063'
      responses:
        '200':
          description: Paginated user transaction history
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 2
                      page:
                        type: integer
                        example: 1
                      limit:
                        type: integer
                        example: 20
                      totalPages:
                        type: integer
                        example: 1
                      transactions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              example: tx_cly982341908234
                            billerType:
                              type: string
                              example: ELECTRICITY
                            providerCode:
                              type: string
                              example: KUDA
                            recipientId:
                              type: string
                              example: '0219927013063'
                            amount:
                              type: number
                              example: 1000
                            status:
                              type: string
                              example: SUCCESS
                            providerReference:
                              type: string
                              example: KD-TX-9847120938
                            createdAt:
                              type: string
                              format: date-time
                              example: '2026-10-01T11:45:22.000Z'
              example:
                success: true
                data:
                  total: 2
                  page: 1
                  limit: 20
                  totalPages: 1
                  transactions:
                    - id: tx_cly982341908234
                      userId: usr_9012481092
                      billerType: ELECTRICITY
                      providerCode: KUDA
                      recipientId: '0219927013063'
                      amount: 1000
                      status: SUCCESS
                      providerReference: KD-TX-9847120938
                      metadata:
                        token: 4819-2049-1829-4019-3382
                        units: 34.5 kWh
                        billerName: AEDC Prepaid Electricity
                      createdAt: '2026-10-01T11:45:22.000Z'
                    - id: tx_cly982341908235
                      userId: usr_9012481092
                      billerType: RRR
                      providerCode: REMITA
                      recipientId: '220799679350'
                      amount: 1000
                      status: SUCCESS
                      providerReference: RRR_PAY_172778810293
                      metadata:
                        rrr: '220799679350'
                        billerName: ABUJA ELECTRICITY DISTRIBUTION COMPANY
                        payerName: Ayodeji Peters
                      createdAt: '2026-10-01T10:15:00.000Z'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Supply your secret API key (e.g. `sk_live_...` or `sk_test_...`) in the
        Authorization header.
      x-default: sk_test_handle_master_key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.