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

# Manual USSD Payments & Auto-Reconciliation

> Accept manual USSD mobile money transfers with automated SMS reconciliation and instant settlement.

In many African markets (such as Cameroon, Côte d'Ivoire, and Senegal), automated STK push / USSD prompt delivery from telecom operators can occasionally experience network congestion or operator downtime.

To guarantee 100% checkout completion, Pursar provides a **Manual USSD Payment & Auto-Reconciliation Engine**. Customers can dial the standard telecom merchant USSD code directly from their phone, and Pursar will automatically reconcile the transaction using incoming confirmation SMS messages.

***

## How It Works

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Customer as Customer
    participant Checkout as Pursar Hosted Checkout
    participant Telco as MTN / Orange Network
    participant Daemon as SMS Daemon Listener
    participant Pursar as Pursar Payment Engine
    participant Merchant as Merchant Webhook

    Customer->>Checkout: Selects "Manual USSD"
    Checkout-->>Customer: Displays USSD code (*126*4*...#) & Merchant Code
    Customer->>Telco: Dials USSD code & authorizes PIN
    Telco-->>Customer: SMS with Transaction ID (e.g. MP260908.1234.A12345)
    Telco-->>Daemon: Inbound SMS delivered to merchant listener phone
    Daemon->>Pursar: POST /v1/ussd-sms/inbound (raw SMS + HMAC)
    Pursar->>Pursar: Regex parse + match against pending orders
    alt Customer submits TxID on checkout
        Customer->>Checkout: Enters TxID on screen
        Checkout->>Pursar: POST /public/payment_intents/{id}/reconcile-manual
        Pursar-->>Checkout: Payment Succeeded!
    else Daemon ingests SMS first
        Pursar->>Pursar: Matches & marks Succeeded
        Checkout->>Pursar: Polling receives "succeeded"
    end
    Pursar->>Merchant: Dispatches payment.succeeded webhook
```

***

## 1. Dial Codes & Operator Formatting

When a customer selects **Manual USSD** on your checkout, Pursar generates a dynamic USSD code formatted with your merchant code and transaction amount:

| Operator | Dial Code Format | Example (Amount: 5,000 XAF) |
| :- | :- | :- |
| **MTN MoMo (Cameroon)** | `*126*4*{merchant_code}*{amount}#` | `*126*4*670000000*5000#` |
| **Orange Money (Cameroon)** | `#150*4*1*{merchant_code}*{amount}#` | `#150*4*1*123456*5000#` |
| **MTN MoMo (Côte d'Ivoire)** | `*133*1*{merchant_code}*{amount}#` | `*133*1*0102030405*5000#` |
| **Orange Money (Côte d'Ivoire)** | `#144*2*1*{merchant_code}*{amount}#` | `#144*2*1*0708091011*5000#` |

Customers on mobile browsers can tap the **"Tap to dial"** button on the checkout screen to open their phone dialer pre-filled with the USSD code.

***

## 2. Inbound SMS Auto-Reconciliation API

If your organization deploys dedicated Android devices (running Android 4.4+ or specialized background daemon apps with SMS permissions), incoming SMS notifications from MTN or Orange can be forwarded automatically to Pursar for real-time order matching.

### Endpoint

```http theme={null}
POST https://api.viarosandbox.com/v1/ussd-sms/inbound
Authorization: Bearer sk_test_...
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "raw_sms": "Paiement de 5000 FCFA a PURSAR MERCHANT reussi. Ref: MP260908.1402.A98765. Nouveau solde: 142000 FCFA.",
  "network": "MTN",
  "sender_phone": "+237671234567"
}
```

### Response

```json theme={null}
{
  "success": true,
  "message": "USSD transaction automatically reconciled",
  "data": {
    "reconciled": true,
    "payment_ref": "PUR_TXN_987654",
    "transaction_hash": "MP260908.1402.A98765",
    "amount": 5000
  }
}
```

If no matching pending transaction is found immediately (e.g. if the SMS arrives before the customer finishes entering their details), the receipt is buffered in `UssdReceipt` with status `unmatched`. When the customer or merchant claims it later, it is instantly settled without delay.

***

## 3. Customer Self-Verification API

If the customer is completing checkout on the web, they can submit their Transaction ID directly:

### Endpoint

```http theme={null}
POST https://api.viarosandbox.com/v1/public/payment_intents/{id}/reconcile-manual
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "client_secret": "pi_1234567890_secret_abc123xyz",
  "transaction_hash": "MP260908.1402.A98765",
  "customer_phone": "+237671234567"
}
```

### Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": "tx_658dc9182374b",
    "status": "succeeded",
    "amount": 5000,
    "currency": "XAF",
    "payment_ref": "PUR_TXN_987654",
    "metadata": {
      "reconciled_via": "ussd_sms_buffer",
      "reconciliation_hash": "MP260908.1402.A98765"
    }
  }
}
```

***

## 4. Double-Spend & Fraud Prevention

Pursar guarantees bank-grade security for manual USSD payments:

* **Strict Uniqueness**: Every transaction reference code / hash is stored and checked. If an already-claimed code is reused, Pursar immediately responds with `409 Conflict`:
  ```json theme={null}
  {
    "status_code": 409,
    "message": "This transaction hash reference has already been claimed or reconciled"
  }
  ```
* **Amount Tolerances**: When matching buffered receipts against pending charges, the amount must match exactly (tolerance (\le 0.01)).
* **Time Limits**: Receipts expire after 2 hours if left unclaimed to prevent historical reuse.


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