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

# Vend electricity via parent account (v2)

> You can use this endpoint to vend electricity via parent account.

<Warning>
  Always requery the transaction using [Fetch a single transaction on the parent account](/nomba-api-reference/requery/fetch-a-single-transaction-on-the-parent-account) to confirm its final status before issuing a refund.
</Warning>

<Note>
  The `code` field in the response reflects the HTTP status code of the response. For example, `200` means the request completed successfully, and `201` means it was accepted and is still being processed.
</Note>


## OpenAPI

````yaml post /v2/bill/electricity
openapi: 3.0.1
info:
  description: ''
  title: Vendor API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.nomba.com
  - description: Sandbox
    url: https://sandbox.nomba.com
security: []
tags:
  - name: Authenticate
  - name: Accounts
  - name: Virtual Accounts
  - name: Online Checkout
  - name: Charge
  - name: Transfers
  - name: Direct Debits
  - name: Terminals
  - name: Transactions
  - name: Airtime and Data Vending
  - name: Electricity Vending
  - name: CableTV Subscription
  - name: Betting Vending
paths:
  /v2/bill/electricity:
    post:
      tags:
        - Electricity Vending
      summary: Vend electricity via parent account
      description: You can use this endpoint to vend electricity via parent account.
      operationId: Vend electricity via parent account v2
      parameters:
        - description: The parent accountId of the business.
          in: header
          name: accountId
          schema:
            type: string
            format: uuid
            example: 890022ce-bae0-45c1-9b9d-ee7872e6ca27
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElectricityVendingRequest'
        description: The request payload required to vend electricity
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      Response code. This reflects the HTTP status code of the
                      response, e.g. `200` when the request completed
                      successfully and `201` when it was accepted and is still
                      being processed.
                    example: '200'
                    enum:
                      - '200'
                      - '201'
                      - '400'
                      - '401'
                      - '403'
                      - '429'
                      - '500'
                  description:
                    type: string
                    example: SUCCESS
                    description: Response description
                  message:
                    type: string
                    description: Response message
                    example: Transaction completed Successfully
                  status:
                    type: boolean
                    description: Whether the request was successful
                    example: true
                  data:
                    $ref: '#/components/schemas/ElectricityVendingV2Response'
                required:
                  - code
                  - description
                  - data
              example:
                code: '200'
                description: SUCCESS
                message: Transaction completed Successfully
                status: true
                data:
                  id: API-PHCN-28958-37da63af-8daa-4cb7-9070-e32920e38c12
                  status: SUCCESS
                  type: phcn
                  amount: 1000
                  source: api
                  sourceUserId: null
                  customerBillerId: '12345678902'
                  productId: benin
                  meta:
                    payment_type: prepaid
                    api_rrn: null
                    biller_account_name: John Doe
                    rrn: null
                    api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
                    api_client_id: 05cc8ef7-3aa6-408a-9cde-1a91fd20f592
                    user_id: 0167288-d989-460a-bbde-9842f2b4320f
                    merchantTxRef: 310120260017AM
                    allowDuplicate: true
                    sender_name: Josh Doe
                    idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
                    pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
                    userName: John Doe
                    isCorporate: 'true'
                    currency: NGN
                    hooksEligible: 'true'
                    isSubscribedToSavingsService: false
                    isSubscribedToLoanService: false
                    txnAlertEligible: false
                    banking_entity_id: 189585760
                    banking_entity_user_id: 188595905
                    banking_entity_type: CORPORATE
                    transactionCategory: Bills & Utility
                    meterNumber: '12345678901'
                    amount_charged: '1000.0'
                    paymentVendor: wallet
                    wallet_balance: '3055.85'
                    wallet_currency: NGN
                    paymentVendorReference: 6ab8d20521deef068755e6a2
                    gatewayMessage: 'Token: 43557934939308375700'
                    billingServiceResponse: 'Token: 43557934939308375700'
                    phcnToken: '43557934939308375700'
                    phcnCustomerName: Mr Johnson
                    phcnCustomerAddress: '29 Okabiri Street '
                    phcnCustomerPhone: '09012345678'
                    phcnVendToken: '14557934939308375701'
                    phcnVendUnits: '16.4'
                    meterDebt: unknown
                    units: '16.4'
                    income: '21.0'
                    paymentFee: 0
                    tx_revenue: '21.0'
                  userId: null
                  timeCreated: '2026-09-27T08:21:25.582+00:00'
          description: OK - your request was successful.
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: string
                example: '40'
            X-Rate-Limit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: string
                example: '39'
            X-Rate-Limit-Window:
              description: The specified rate limit window
              schema:
                type: string
                example: 1s
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: >-
                      Response code. This reflects the HTTP status code of the
                      response, e.g. `200` when the request completed
                      successfully and `201` when it was accepted and is still
                      being processed.
                    example: '201'
                    enum:
                      - '200'
                      - '201'
                      - '400'
                      - '401'
                      - '403'
                      - '429'
                      - '500'
                  description:
                    type: string
                    description: Response description
                    example: PROCESSING
                  message:
                    type: string
                    description: Response message
                    example: Success
                  status:
                    type: boolean
                    description: Whether the request was successful
                    example: true
                  data:
                    $ref: '#/components/schemas/ElectricityVendingV2Response'
                required:
                  - code
                  - description
                  - data
              example:
                code: '201'
                description: PROCESSING
                message: Success
                status: true
                data:
                  id: API-PHCN-28958-37da63af-8daa-4cb7-9070-e32920e38c12
                  status: PENDING_BILLING
                  type: phcn
                  amount: 1000
                  source: api
                  sourceUserId: null
                  customerBillerId: '12345678902'
                  productId: benin
                  meta:
                    payment_type: prepaid
                    api_rrn: null
                    biller_account_name: John Doe
                    rrn: null
                    api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
                    api_client_id: 05cc8ef7-3aa6-408a-9cde-1a91fd20f592
                    user_id: 0167288-d989-460a-bbde-9842f2b4320f
                    merchantTxRef: 310120260017AM
                    allowDuplicate: true
                    sender_name: Josh Doe
                    idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
                    pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
                    userName: John Doe
                    isCorporate: 'true'
                    currency: NGN
                    hooksEligible: 'true'
                    isSubscribedToSavingsService: false
                    isSubscribedToLoanService: false
                    txnAlertEligible: false
                    banking_entity_id: 189585760
                    banking_entity_user_id: 188595905
                    banking_entity_type: CORPORATE
                    transactionCategory: Bills & Utility
                    meterNumber: '12345678901'
                    amount_charged: '1000.0'
                    paymentVendor: wallet
                    wallet_balance: '3055.85'
                    wallet_currency: NGN
                  userId: null
                  timeCreated: '2026-09-27T08:21:25.582+00:00'
          description: >-
            Created - your request was accepted and is being processed.
            `data.status` is `PENDING_BILLING`; listen for webhook notifications
            or requery the transaction for the final status.
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: string
                example: '40'
            X-Rate-Limit-Remaining:
              description: The number of remaining requests in the current period
              schema:
                type: string
                example: '39'
            X-Rate-Limit-Window:
              description: The specified rate limit window
              schema:
                type: string
                example: 1s
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: The request body sent by merchant did not pass the validation checks
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: >-
            The access_token provided to access the resource is missing or
            invalid.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationError'
          description: The client does not have the permissions to access this resource
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordNotFoundError'
          description: The record that the client is trying to access does not exist.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: >-
            The client has maxed out the number of calls within a time period on
            this resource.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Downstream system error.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Resource not available
      security:
        - BearerAuth: []
components:
  schemas:
    ElectricityVendingRequest:
      type: object
      properties:
        disco:
          type: string
          example: jed
        merchantTxRef:
          type: string
          description: This is an idempotency key and must be unique per transaction.
          example: '12345'
        payerName:
          type: string
          example: John Doe
        amount:
          type: integer
          example: 1000
        customerId:
          type: string
          example: customer123
        meterType:
          type: string
          example: prepaid
    ElectricityVendingV2Response:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the electricity transaction
          example: API-PHCN-28958-37da63af-8daa-4cb7-9070-e32920e38c12
        status:
          type: string
          description: >-
            Status of the transaction. `SUCCESS` (HTTP 200) means the purchase
            completed; `PENDING_BILLING` (HTTP 201) means it is still being
            processed
          example: SUCCESS
        type:
          type: string
          description: Transaction type
          example: phcn
        amount:
          type: number
          format: double
          description: Amount paid for electricity
          example: 1000
        source:
          type: string
          description: Channel through which the transaction was initiated
          example: api
        sourceUserId:
          type: string
          description: Identifier of the source user, if any
          nullable: true
        customerBillerId:
          type: string
          description: Meter number credited with the payment
          example: '12345678902'
        productId:
          type: string
          description: The electricity distribution company (disco)
          example: benin
        meta:
          type: object
          description: >-
            Additional transaction metadata, including the electricity token
            (`phcnToken`) and units purchased
          additionalProperties: true
          example:
            payment_type: prepaid
            api_rrn: null
            biller_account_name: John Doe
            rrn: null
            api_account_id: 0167288-d989-460a-bbde-9842f2b4320f
            api_client_id: 05cc8ef7-3aa6-408a-9cde-1a91fd20f592
            user_id: 0167288-d989-460a-bbde-9842f2b4320f
            merchantTxRef: 310120260017AM
            allowDuplicate: true
            sender_name: Josh Doe
            idempotentKey: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
            pos_withdrawal_id: 0167288-d989-460a-bbde-9842f2b4320f_310120260017AM
            userName: John Doe
            isCorporate: 'true'
            currency: NGN
            hooksEligible: 'true'
            isSubscribedToSavingsService: false
            isSubscribedToLoanService: false
            txnAlertEligible: false
            banking_entity_id: 189585760
            banking_entity_user_id: 188595905
            banking_entity_type: CORPORATE
            transactionCategory: Bills & Utility
            meterNumber: '12345678901'
            amount_charged: '1000.0'
            paymentVendor: wallet
            wallet_balance: '3055.85'
            wallet_currency: NGN
            paymentVendorReference: 6ab8d20521deef068755e6a2
            gatewayMessage: 'Token: 43557934939308375700'
            billingServiceResponse: 'Token: 43557934939308375700'
            phcnToken: '43557934939308375700'
            phcnCustomerName: Mr Johnson
            phcnCustomerAddress: '29 Okabiri Street '
            phcnCustomerPhone: '09012345678'
            phcnVendToken: '14557934939308375701'
            phcnVendUnits: '16.4'
            meterDebt: unknown
            units: '16.4'
            income: '21.0'
            paymentFee: 0
            tx_revenue: '21.0'
        userId:
          type: string
          description: Identifier of the user, if any
          nullable: true
        timeCreated:
          type: string
          description: Time the transaction was created
          format: date-time
          example: '2026-09-27T08:21:25.582+00:00'
      required:
        - id
        - status
        - type
        - amount
        - timeCreated
    RequestError:
      type: object
      description: Request Error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '400'
        description:
          type: string
          description: Additional details about the error.
          example: Request failed.
    AuthenticationError:
      type: object
      description: Authentication Error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '401'
        description:
          type: string
          description: Additional details about the error.
          example: Unauthorized
    AuthorizationError:
      type: object
      description: Permissions error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '403'
        description:
          type: string
          description: Additional details about the error.
          example: Forbidden
    RecordNotFoundError:
      type: object
      description: Record-Not-Found error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '404'
        description:
          type: string
          description: Additional details about the error.
          example: Record not found
    RateLimitError:
      type: object
      description: Rate-limit error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '429'
        description:
          type: string
          description: Additional details about the error.
          example: Too many requests
    ServerError:
      type: object
      description: Server error response.
      properties:
        code:
          type: string
          description: API error code.
          example: '500'
        description:
          type: string
          description: Additional details about the error.
          example: Server error
  securitySchemes:
    BearerAuth:
      description: >-
        Nomba authenticates API calls with [OAuth2 HTTP bearer
        tokens](http://tools.ietf.org/html/rfc6750). There are two methods of
        authentication; [Client-Credentials
        method](https://www.rfc-editor.org/rfc/rfc6749) and [PKCE (Proof Key for
        Code Exchange)](https://www.rfc-editor.org/rfc/rfc7636) method. In each
        of the methods, You will get an `ACCESS_TOKEN`. You need to use an
        `"Authorization"` HTTP header to provide your `ACCESS_TOKEN`. For
        example: `Authorization: {ACCESS_TOKEN}`.
      scheme: bearer
      type: http
      bearerFormat: JWT

````