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

# Pay a bill

> Spends an enquiry and pays the biller. The debit happens immediately; delivery of the value can take longer, so the payment often comes back `submitted` or `pending` rather than `confirmed`.

## Statuses

| Status | Meaning |
| - | - |
| `submitted` | Sent to the biller. The account has already been debited. |
| `pending` | The biller has not given a final answer. A reconciler keeps asking. |
| `confirmed` | Value delivered. **This is the success state — not `completed`.** |
| `failed` | The biller could not deliver. The debit is reversed automatically. |

<Note>A failed bill payment refunds itself. Sakawave posts a reversal against the same account, so you do not need to claim the money back — but the payment stays in the list as `failed` with a `failureReason`.</Note>

## What comes from where

The enquiry decides most of the payment. `customerName` is used only when the biller returned no name of its own, and for airtime and data the recipient is the phone number from the **enquiry**, not the `phoneNumber` in this request.

`amount` may be omitted when the enquiry or the package already fixes it. Where it is required and disagrees with the fixed price, the payment is refused rather than adjusted.

## Tokens

A biller that issues a credential — a prepaid electricity token, most often — returns it in `tokenData` once the payment is `confirmed`. Its shape varies by biller. Show it to the customer and store it: it is not re-issued.

## Idempotency

`externalReference` is the key. Reusing it returns the existing payment whatever its status, so a retry after a failure returns the failure — the same contract as [transfers](/api-reference/transfers/create-a-transfer), not the re-driving one that [cards](/api-reference/cards/issue-a-card) use. A genuine retry needs a new reference **and** a new enquiry.

## Error codes

| Status | `code` | Cause |
| - | - | - |
| `400` | `validation_failed` | A field failed validation. |
| `400` | `invalid_phone_number` | The phone number is not eight to fifteen digits. |
| `409` | `bill_enquiry_expired` | The enquiry is older than ten minutes, or has already been spent. Enquire again. |
| `409` | `bill_product_unavailable` | The biller or package has been withdrawn from the catalog since the enquiry. |
| `409` | `bill_amount_required` | This product needs an explicit amount. |
| `409` | `invalid_bill_amount` | The amount is not a positive decimal with at most two places. |
| `409` | `bill_amount_mismatch` | The amount disagrees with the enquiry or the package price. |
| `409` | `amount_below_minimum` | Below the biller’s minimum vend, which the enquiry returned as `minimumAmount`. |
| `409` | `bill_enquiry_amount_unavailable` | The enquiry priced nothing to pay. |
| `409` | `bill_enquiry_pricing_unavailable` | The enquiry has no charge or commission to apply. |
| `409` | `insufficient_funds` | The account cannot cover `totalDebit`. |
| `409` | `bill_payment_account_ineligible` | The account is inactive, not debitable, a customer wallet, or not NGN. |
| `503` | `catalog_unavailable` | The bills catalog is empty and could not be refreshed from the provider. |
| `503` | `provider_unavailable` | The bills provider could not be reached. |
| `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. |
| `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. |


## OpenAPI

````yaml /openapi.json post /v1/bill-payments
openapi: 3.1.0
info:
  title: Sakawave Business API
  version: 1.0.0-draft
  summary: >-
    Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave
    businesses.
  description: >-
    Generated from the public NestJS controllers and their Zod request schemas.
    Public URLs and policy statements remain draft until the Phase 1 contract
    checklist is approved.
  contact:
    name: Sakawave API Support
    email: api-support@sakawave.example
servers:
  - url: https://sandbox-api.sakawave.example
    description: Sandbox (default)
  - url: https://api.sakawave.example
    description: Live
security:
  - bearerAuth: []
tags:
  - name: Bill payments
    description: Browse the biller catalog, validate a customer, and pay a bill.
  - name: Cards
    description: Issue, fund, and control USD virtual and disposable cards.
  - name: eSIM
    description: >-
      Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it
      once installed.
  - name: Currencies and countries
    description: >-
      Reference data: what may be held, what may be sent where, and which
      jurisdictions are served.
  - name: Customers
    description: Create and manage customers of your business.
  - name: Accounts
    description: >-
      Open business and customer accounts, and issue the destinations that fund
      them.
  - name: Transfer destinations
    description: Resolve temporary destinations and saved recipients.
  - name: FX quotes
    description: Create and retrieve time-limited cross-currency quotes.
  - name: Transfers
    description: Preview, create, and monitor transfers.
  - name: Transactions
    description: Read ledger entries for reconciliation.
paths:
  /v1/bill-payments:
    post:
      tags:
        - Bill payments
      summary: Pay a bill
      description: >-
        Spends an enquiry and pays the biller. The debit happens immediately;
        delivery of the value can take longer, so the payment often comes back
        `submitted` or `pending` rather than `confirmed`.
      operationId: createBillPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillPaymentRequest'
            example:
              enquiryId: 01K2Z3AB4W5X6Y7Z8ABCDEFGHJ
              accountId: 01K2Z3AB4D5E6F7G8H9JKMNPQR
              amount: '5000.00'
              externalReference: bill_20260814_001
              customerName: Ada Okafor
              phoneNumber: '+2348012345678'
              email: ada@example.com
      responses:
        '201':
          description: Successful response.
          headers:
            X-Request-ID:
              description: >-
                The request identifier assigned by Sakawave. Include it in
                support requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillPaymentResponse'
              example:
                id: 01K2Z3AB4X5Y6Z7A8BCDEFGHJK
                externalReference: bill_20260814_001
                paymentReference: SKWV-BIL-01K2Z3AB4X5Y6Z7A8BCDEFGHJK
                providerTransactionId: CP-88213471
                status: confirmed
                subCategory: utility
                amount: '5000.00'
                charge: '100.00'
                commission: '0.00'
                totalDebit: '5100.00'
                currency: NGN
                group:
                  name: Electricity
                  slug: DISCO
                biller:
                  name: Example Disco
                  slug: EXAMPLE_DISCO
                package:
                  name: Prepaid
                  slug: EXAMPLE_DISCO_PREPAID
                customerReferenceLast4: '7788'
                customerName: ADA OKAFOR
                customerAddress: 14 Marina Road
                vendStatus: SUCCESSFUL
                providerStatusCode: '00'
                tokenData:
                  token: 1234-5678-9012-3456-7890
                  units: '31.4'
                failureReason: null
                createdAt: '2026-08-14T09:15:00.000Z'
                updatedAt: '2026-08-14T09:15:06.000Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ProviderUnavailableError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateBillPaymentRequest:
      type: object
      additionalProperties: false
      properties:
        enquiryId:
          $ref: '#/components/schemas/Ulid'
          description: From the enquiry. Valid for ten minutes.
        accountId:
          $ref: '#/components/schemas/Ulid'
          description: The NGN account to debit.
        amount:
          $ref: '#/components/schemas/DecimalAmount'
        externalReference:
          type: string
          minLength: 1
          maxLength: 120
          description: Your idempotency key.
        customerName:
          type: string
          minLength: 2
          maxLength: 200
          description: Ignored where the biller returned a name of its own.
        phoneNumber:
          type: string
          description: >-
            Eight to fifteen digits, optionally with a leading plus. Spaces and
            hyphens are stripped.
        email:
          type: string
          format: email
          maxLength: 255
      required:
        - enquiryId
        - accountId
        - externalReference
        - customerName
        - phoneNumber
    BillPaymentResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
        externalReference:
          type: string
        paymentReference:
          type: string
          description: Sakawave’s own reference for the payment.
        providerTransactionId:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
          enum:
            - submitted
            - pending
            - confirmed
            - failed
          description: '`confirmed` is the success state, not `completed`.'
        subCategory:
          type: string
          description: >-
            What kind of bill this was: airtime, data, utility, cable_tv,
            betting, and so on.
        amount:
          $ref: '#/components/schemas/DecimalAmount'
        charge:
          $ref: '#/components/schemas/DecimalAmount'
        commission:
          $ref: '#/components/schemas/DecimalAmount'
        totalDebit:
          $ref: '#/components/schemas/DecimalAmount'
        currency:
          type: string
          enum:
            - NGN
          description: Bill payments are NGN only.
        group:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            slug:
              type: string
          required:
            - name
            - slug
        biller:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            slug:
              type: string
          required:
            - name
            - slug
        package:
          type: object
          additionalProperties: false
          properties:
            name:
              type: string
            slug:
              type: string
          required:
            - name
            - slug
        customerReferenceLast4:
          anyOf:
            - type: string
              description: >-
                The last four characters of the meter, account, or phone number
                paid.
            - type: 'null'
        customerName:
          type: string
        customerAddress:
          anyOf:
            - type: string
            - type: 'null'
        vendStatus:
          anyOf:
            - type: string
              description: The biller’s own delivery status, upper-cased.
            - type: 'null'
        providerStatusCode:
          anyOf:
            - type: string
            - type: 'null'
        tokenData:
          anyOf:
            - type: object
              additionalProperties: true
              description: >-
                The credential the biller issued, where there is one — a prepaid
                electricity token, for instance. Shape varies by biller.
            - type: 'null'
        failureReason:
          anyOf:
            - type: string
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/IsoTimestamp'
        updatedAt:
          $ref: '#/components/schemas/IsoTimestamp'
      required:
        - id
        - externalReference
        - paymentReference
        - providerTransactionId
        - status
        - subCategory
        - amount
        - charge
        - commission
        - totalDebit
        - currency
        - group
        - biller
        - package
        - customerReferenceLast4
        - customerName
        - customerAddress
        - vendStatus
        - providerStatusCode
        - tokenData
        - failureReason
        - createdAt
        - updatedAt
    Ulid:
      type: string
      minLength: 26
      maxLength: 26
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
      description: A 26-character ULID.
    DecimalAmount:
      type: string
      pattern: ^-?\d+(?:\.\d+)?$
      example: '25000.00'
      description: >-
        A decimal display amount returned by transfer APIs. Preserve it as a
        string.
    IsoTimestamp:
      type: string
      format: date-time
      example: '2026-08-14T09:00:00.000Z'
    RequestError:
      anyOf:
        - $ref: '#/components/schemas/ValidationError'
        - $ref: '#/components/schemas/Error'
      description: >-
        Either a field-level validation failure carrying an errors array, or a
        rule the request broke, identified by code.
    Error:
      type: object
      additionalProperties: true
      properties:
        statusCode:
          type: integer
        message:
          type: string
          description: >-
            A sentence suitable for a log or a support conversation, not for a
            user interface.
        code:
          type: string
          description: >-
            The stable machine-readable reason. Branch on this, never on the
            message.
      required:
        - message
        - code
      description: >-
        An error body. Individual errors may add context fields alongside these
        three.
    RateLimitError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 429
        message:
          type: string
        code:
          const: api_key_rate_limit_exceeded
        retryAfterSeconds:
          type: integer
          minimum: 1
      required:
        - statusCode
        - message
        - code
        - retryAfterSeconds
    ValidationError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 400
        message:
          type: string
          description: The single failure, or a count when more than one field failed.
        code:
          const: validation_failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationFailure'
      required:
        - statusCode
        - message
        - code
        - errors
    ValidationFailure:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        field:
          type: string
        code:
          type: string
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
      required:
        - message
        - field
        - code
        - path
  responses:
    ValidationError:
      description: >-
        The request was rejected before it was acted on. Field failures list
        every failing field.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
          example:
            statusCode: 400
            message: Must be a valid identifier.
            code: validation_failed
            errors:
              - message: Must be a valid identifier.
                field: accountId
                code: custom
                path:
                  - accountId
    AuthenticationError:
      description: >-
        The API key is missing, invalid, inactive, expired, for another
        environment, or blocked by its IP allowlist.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            code: INVALID_API_KEY
            message: Invalid or inactive API credentials.
    NotFoundError:
      description: The requested resource was not found for this business.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            code: resource_not_found
            message: Resource not found.
    ConflictError:
      description: The request conflicts with the current resource state.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 409
            code: resource_conflict
            message: The request conflicts with the current resource state.
    RateLimitError:
      description: The API key rate limit was exceeded.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            statusCode: 429
            message: Too many API requests. Try again later.
            code: api_key_rate_limit_exceeded
            retryAfterSeconds: 17
    ServerError:
      description: An unexpected server error occurred.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 500
            code: internal_server_error
            message: An unexpected error occurred.
    ProviderUnavailableError:
      description: >-
        A payment provider could not be reached. The request had no effect;
        retry shortly.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 503
            code: provider_unavailable
            message: We could not issue an account number just now. Try again shortly.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sakawave API key
      description: >-
        A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox
        or `Bearer sk_live_…` in live.

````

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