> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pay4power.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pay4power.com/_mcp/server.

# Integration Flow

> The recommended sequence for integrating Pay4Power bill payment APIs.

Use this flow for electricity, airtime, data, TV, and transaction-status integrations.

## 1. Authenticate

Call the token endpoint and keep the returned bearer token available for server-side API calls.

## 2. Discover services

Call `GET /services` to retrieve available service categories such as electricity, airtime, data, and TV.

## 3. Discover providers

Call `GET /providers` to retrieve providers for the service you want to vend. Provider codes are required by the transaction endpoints.

## 4. Validate customer details

For products that require validation, call the relevant verification or initiation endpoint before vending. Electricity and TV flows usually need customer or package validation before payment.

## 5. Vend the transaction

Submit the vend request with the provider code, customer identifier, amount, and transaction reference required by the product flow.

## 6. Confirm final status

Use `GET /requery` to confirm final state, especially for pending or asynchronous responses.

## Recommended transaction handling

| Concern           | Recommendation                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| References        | Generate a unique client-side reference for each transaction attempt.                                                              |
| Pending responses | Treat pending states as unresolved until requery returns a final result.                                                           |
| Retries           | Retry status checks, not duplicate vend requests, unless your backend has confirmed the original request failed before processing. |
| Reconciliation    | Persist Pay4Power references, correlation IDs, request payloads, and final statuses.                                               |