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

# Purchase Bill / Vend Token

> Execute bill payment, token purchase, or data bundle topup with automatic account debit and margin-guarded failover.

Executes an end-to-end bill payment or utility token purchase.

### Transaction Lifecycle

1. **Mandate Check & Direct Debit**: Handle checks the user's active bank account mandate and initiates direct settlement via OnePipe.
2. **Provider Dispatch**: Once debit succeeds, the request is sent to the primary provider (Remita / Kuda).
3. **Resilient Failover**: If the primary provider fails, Handle automatically shifts fulfillment to a secondary provider without double-debiting the user.
4. **Token Delivery**: The generated 20-digit token (for prepaid power), PIN (for exams), or confirmation receipt is returned immediately.

### Sample Success Response

```json theme={null}
{
  "success": true,
  "transactionId": "HDL-BILL-1790800000-482",
  "provider": "kuda",
  "token": "4819-2049-1829-9401-2910",
  "units": "45.2 kWh",
  "amount": 5000,
  "status": "COMPLETED",
  "message": "Transaction fulfilled successfully."
}
```


## OpenAPI

````yaml openapi.json POST /bill-payment/purchase
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/purchase:
    post:
      tags:
        - VAS & Bill Payments
      summary: Purchase Bill / Vend Token
      description: >-
        Execute instant bill payment or token vend with margin-guarded failover
        routing and linked account debit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category
                - billerCode
                - recipientId
                - amount
              properties:
                category:
                  type: string
                  enum:
                    - GOVERNMENT
                    - ELECTRICITY
                    - AIRTIME
                    - DATA
                    - INTERNET
                    - CABLE_TV
                    - UTILITIES
                    - EDUCATION
                    - FLIGHTS
                    - BETTING
                    - GAMING
                    - SOLAR
                    - TRANSPORT
                    - ESIM
                    - TAXES
                    - HOSPITALS
                    - INSURANCE
                    - RELIGIOUS
                    - ASSOCIATIONS
                    - FINANCIAL_SERVICES
                    - CREDIT_LOANS
                    - MICRO_PENSIONS
                    - INVOICE
                    - GIFT_CARDS
                    - SHOPPING
                    - FOOD_DINING
                    - LIFESTYLE_BEAUTY
                    - HOME_LIVING
                  default: ELECTRICITY
                  example: ELECTRICITY
                canonicalKey:
                  type: string
                  default: electricity:aedc:prepaid
                  example: electricity:aedc:prepaid
                billerCode:
                  type: string
                  default: AEDC
                  example: AEDC
                recipientId:
                  type: string
                  default: '0219927013063'
                  example: '0219927013063'
                amount:
                  type: number
                  default: 1000
                  example: 1000
                metadata:
                  type: object
                  properties:
                    meterType:
                      type: string
                      enum:
                        - prepaid
                        - postpaid
                    billPaymentProductId:
                      type: string
                      example: NOTICE_OF_OFFENCE
      responses:
        '200':
          description: Vend receipt, token, and transaction reference
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    example: COMPLETED
                  reference:
                    type: string
                    example: HDL-BILL-1727788412991-842
                  providerCode:
                    type: string
                    example: KUDA
                  providerReference:
                    type: string
                    example: KD-TX-9847120938
                  token:
                    type: string
                    example: 4819-2049-1829-4019-3382
                  units:
                    type: string
                    example: 34.5 kWh
                  message:
                    type: string
                    example: Transaction Successful
                  amount:
                    type: number
                    example: 1000
                  recipientId:
                    type: string
                    example: '0219927013063'
              example:
                success: true
                status: COMPLETED
                reference: HDL-BILL-1727788412991-842
                providerCode: KUDA
                providerReference: KD-TX-9847120938
                token: 4819-2049-1829-4019-3382
                units: 34.5 kWh
                message: Transaction Successful
                amount: 1000
                recipientId: '0219927013063'
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.