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

# 1-Step Generate & Pay RRR

> Atomically generate an RRR invoice and settle it immediately from the user's bank mandate without manual code copying.

The recommended atomic flow for universities and institutions. Generates the RRR code behind the scenes and immediately executes settlement against the user's linked bank account.

### Why Use 1-Step Generate & Pay?

* **Zero Copy-Paste**: The customer does not have to copy or re-enter the 12-digit RRR code.
* **Single Confirmation**: Customer confirms once, and Handle performs the generation, mandate debit, and settlement simultaneously.
* **Immediate Official Receipt**: Delivers the completed payment reference and settlement receipt in a single response.

### Sample Request

```bash theme={null}
curl --request POST \
  --url 'https://api-local.handle.ng/api/v1/bill-payment/rrr/generate-and-pay' \
  --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-and-pay
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-and-pay:
    post:
      tags:
        - VAS & Bill Payments
      summary: 1-Step Generate & Pay RRR Invoice
      description: >-
        Seamlessly generate a new 12-digit Remita Retrieval Reference (RRR) for
        universities, MDAs, or institutions and instantly settle it in a single
        atomic request without manual code copying.
      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'
                bankAccountId:
                  type: string
                  description: Optional specific bank account ID to debit
                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: Settlement confirmation, generated RRR, and institutional receipt
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Bill processed successfully
                  transactionId:
                    type: string
                    example: tx_cly982341908235
                  data:
                    type: object
                    properties:
                      rrr:
                        type: string
                        example: '280799679353'
                      amount:
                        type: number
                        example: 1000
                      paymentIdentifier:
                        type: string
                        example: RRR_PAY_172778810293_ab92df
                      transactionStatus:
                        type: string
                        example: SUCCESS
                      billerName:
                        type: string
                        example: ABUJA ELECTRICITY DISTRIBUTION COMPANY
                      payerName:
                        type: string
                        example: Ayodeji Peters
              example:
                success: true
                message: Bill processed successfully
                transactionId: tx_cly982341908235
                data:
                  rrr: '280799679353'
                  amount: 1000
                  paymentIdentifier: RRR_PAY_172778810293_ab92df
                  transactionStatus: SUCCESS
                  billerName: ABUJA ELECTRICITY DISTRIBUTION COMPANY
                  payerName: Ayodeji Peters
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.