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

# Architecture & Best Practices

> Critical integration patterns that prevent financial loss. Read this before writing your first purchase call.

> [!WARNING]
>
> These are not optional suggestions. Not following these patterns — especially Two-Step Verification — can result in funds sent to the wrong account with no possibility of reversal.

## Transaction Lifecycle

Every purchase is **asynchronous**. Your server submits the request, we queue it to the upstream carrier, and the final status arrives via webhook (or `/requery`). This diagram shows the complete flow:

```mermaid theme={null}
sequenceDiagram
    participant C as Your Server
    participant R as RapidTopup API
    participant P as Upstream Provider
    participant W as Your Webhook

    C->>R: POST /purchase (with idempotency_key)
    R-->>C: 200 OK (data.status = "pending")
    R->>P: Forward to carrier (MTN / DSTV / DISCO)
    P-->>R: Provider confirms outcome

    alt Transaction Succeeded
        R->>W: POST webhook (status = "success", signed HMAC-SHA512)
        W-->>R: 200 OK
    else Transaction Failed
        R->>W: POST webhook (status = "failed", wallet auto-refunded)
        W-->>R: 200 OK
    end

    Note over C,R: Webhook missed or timed out?
    C->>R: POST /requery (reference)
    R-->>C: Final status + full transaction object
```

> [!NOTE]
>
> If your webhook endpoint is unreachable, we retry up to 5 times with exponential backoff. Implement `POST /requery` as a fallback for any transaction that stays `pending` beyond your expected SLA.

***

## 1. Two-Step Verification *(Mandatory for Cable & Electricity)*

**Never blind-recharge a Cable TV or Electricity account.**

You must call `GET /services/verify` first, display the resolved customer name to your user, and only call `POST /purchase` **after** the user confirms the name is correct.

**1. User enters account number**

Your UI collects the meter or smartcard number from the user.

**2. Call GET /services/verify**

Send the account number and service ID to our verification endpoint.

**3. Display the customer name**

Show `customer_name` prominently. E.g. *"You are recharging: JOHN DOE"*

**4. User confirms**

The user confirms the name matches their account.

**5. Call POST /purchase**

Only now proceed with the purchase.

**Why?** Electricity and Cable TV transactions are processed instantly and are **irreversible**. Verifying the account name is the only way to protect your users from paying for someone else's account.

***

## 2. Strict Idempotency

**Never blindly retry a `/purchase` request on network timeout.**

```text ✅ Correct Flow theme={null}
POST /purchase  →  Network timeout / no response
    ↓
Wait 30 seconds
    ↓
POST /requery with the transaction reference
    ↓
If status = "success" → done
If status = "pending" → wait and requery again
If status = "failed"  → wallet already refunded, safe to retry
```

```text ❌ Wrong Flow theme={null}
POST /purchase  →  Network timeout
    ↓
Retry POST /purchase immediately
    ↓
DOUBLE CHARGE — customer billed twice
```

Always include a unique `idempotency_key` in every purchase. If the same key is sent twice, the API returns the **original transaction** instead of charging again.

***

## 3. Timezone Awareness

All API timestamps are returned in **UTC**. Convert to **West Africa Time (WAT / GMT+1)** before displaying to Nigerian users.

```
2026-10-03T08:00:00Z  →  09:00:00 WAT (Nigeria)
```

***

## 4. Secure Key Storage

> [card] ✅ Do this
>
> Store your API key in environment variables (`.env` file). Never commit it to source control.

> [card] ❌ Never do this
>
> Hardcode the key in your source code, client-side JavaScript, or mobile app bundles.

If a key is ever exposed, revoke it immediately from the Developer Dashboard and generate a new one.


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