Manual USSD Payments & Auto-Reconciliation

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

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)	`1264{merchant_code}{amount}#`	`12646700000005000#`
Orange Money (Cameroon)	`#15041{merchant_code}{amount}#`	`#150411234565000#`
MTN MoMo (Côte d’Ivoire)	`1331{merchant_code}{amount}#`	`133101020304055000#`
Orange Money (Côte d’Ivoire)	`#14421{merchant_code}{amount}#`	`#1442107080910115000#`

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

POST https://api.viarosandbox.com/v1/ussd-sms/inbound
Authorization: Bearer sk_test_...
Content-Type: application/json

Request Body

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

Response

{
  "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

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

Request Body

{
  "client_secret": "pi_1234567890_secret_abc123xyz",
  "transaction_hash": "MP260908.1402.A98765",
  "customer_phone": "+237671234567"
}

Response

{
  "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:
{ "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.

Operator	Dial Code Format	Example (Amount: 5,000 XAF)
MTN MoMo (Cameroon)	`1264{merchant_code}{amount}#`	`12646700000005000#`
Orange Money (Cameroon)	`#15041{merchant_code}{amount}#`	`#150411234565000#`
MTN MoMo (Côte d’Ivoire)	`1331{merchant_code}{amount}#`	`133101020304055000#`
Orange Money (Côte d’Ivoire)	`#14421{merchant_code}{amount}#`	`#1442107080910115000#`

Getting Started

Payment Acceptance

Recurring & Subscriptions

Enterprise & Reliability

Manual USSD Payments & Auto-Reconciliation

How It Works

1. Dial Codes & Operator Formatting

2. Inbound SMS Auto-Reconciliation API

Endpoint

Request Body

Response

3. Customer Self-Verification API

Endpoint

Request Body

Response

4. Double-Spend & Fraud Prevention

​How It Works

​1. Dial Codes & Operator Formatting

​2. Inbound SMS Auto-Reconciliation API

​Endpoint

​Request Body

​Response

​3. Customer Self-Verification API

​Endpoint

​Request Body

​Response

​4. Double-Spend & Fraud Prevention

How It Works

1. Dial Codes & Operator Formatting

2. Inbound SMS Auto-Reconciliation API

Endpoint

Request Body

Response

3. Customer Self-Verification API

Endpoint

Request Body

Response

4. Double-Spend & Fraud Prevention