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

# Generate Remita RRR

> Dynamically generate a new 12-digit RRR invoice for Universities, Polytechnics, Federal MDAs, and State Governments.

Generate an official Remita Retrieval Reference (RRR) on the fly for institutional payments like school fees, acceptance fees, court fees, or taxes.

### Custom Fields

Universities and government agencies often require custom fields (e.g. `matric_no`, `department`, `session`, `tax_id`). You can supply these inside the `customFields` array.

### Sample Request

```bash theme={null}
curl --request POST \
  --url 'https://api-local.handle.ng/api/v1/bill-payment/rrr/generate' \
  --header 'Authorization: Bearer sk_test_handle_master_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "billerId": "SPECSELECTRICITY",
    "billPaymentProductId": "9676615755",
    "amount": 1000,
    "payerName": "Ayodeji Peters",
    "payerEmail": "ayodeji@example.com",
    "payerPhone": "08012345678",
    "customFields": [
      { "variable_name": "account_number", "value": "0219927013063" }
    ]
  }'
```


## OpenAPI

````yaml openapi.json POST /bill-payment/rrr/generate
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/rrr/generate:
    post:
      tags:
        - VAS & Bill Payments
      summary: Generate Remita RRR Invoice
      description: >-
        Dynamically generate a new 12-digit Remita Retrieval Reference (RRR)
        invoice for universities, polytechnics, Federal MDAs, and state
        government institutions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - billerId
                - amount
                - payerName
                - payerEmail
                - payerPhone
              properties:
                billerId:
                  type: string
                  description: >-
                    Biller or institution identifier (e.g. SPECSELECTRICITY,
                    S0000573002)
                  default: SPECSELECTRICITY
                  example: SPECSELECTRICITY
                billPaymentProductId:
                  type: string
                  description: Specific service type ID (e.g. 9676615755)
                  default: '9676615755'
                  example: '9676615755'
                amount:
                  type: number
                  description: Payment amount in NGN
                  default: 1000
                  example: 1000
                payerName:
                  type: string
                  default: Ayodeji Peters
                  example: Ayodeji Peters
                payerEmail:
                  type: string
                  default: ayodeji@example.com
                  example: ayodeji@example.com
                payerPhone:
                  type: string
                  default: '08012345678'
                  example: '08012345678'
                customFields:
                  type: array
                  description: >-
                    Custom institutional fields (e.g. Account Number, Matric No,
                    Session)
                  items:
                    type: object
                    properties:
                      variable_name:
                        type: string
                        default: account_number
                        example: account_number
                      value:
                        type: string
                        default: '0219927013063'
                        example: '0219927013063'
      responses:
        '200':
          description: >-
            Generated RRR code, payment identifier, and institutional invoice
            summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: RRR generated successfully
                  data:
                    type: object
                    properties:
                      rrr:
                        type: string
                        example: '280799679353'
                      paymentIdentifier:
                        type: string
                        example: init_hdl_1727788412991
                      amount:
                        type: number
                        example: 1000
                      billerName:
                        type: string
                        example: ABUJA ELECTRICITY DISTRIBUTION COMPANY
                      serviceTypeName:
                        type: string
                        example: AEDC Prepaid
                      customFields:
                        type: array
                        items:
                          type: object
                          properties:
                            variable_name:
                              type: string
                              example: account_number
                            value:
                              type: string
                              example: '0219927013063'
              example:
                success: true
                message: Approved or completed successfully
                data:
                  rrr: '280799679353'
                  paymentIdentifier: init_hdl_1727788412991
                  amount: 1000
                  billerName: ABUJA ELECTRICITY DISTRIBUTION COMPANY
                  serviceTypeName: AEDC Prepaid
                  customFields:
                    - variable_name: account_number
                      value: '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.