USSD Integration

Rach CaaS includes native USSD callback handlers for two major African telecom providers, enabling end-users to access their USDC wallets from any mobile phone — no internet, no smartphone required.

USSD endpoints do not require API key or JWT authentication. They are secured by telecom-signed request payloads.

Base URL: https://rach-caas-api-dx75yvdhaq-nw.a.run.app

---

Africa's Talking USSD Webhook

Decodes Africa's Talking API payloads and advances the inner wallet state machine.

POST /v1/ussd/callback/at

Content-Type: application/x-www-form-urlencoded

Form Parameters

Parameter	Type	Required	Description
sessionId	string	✅	Unique session ID from Africa's Talking
phoneNumber	string	✅	Subscriber's E.164 phone number
text	string	—	Full concatenated input separated by * (e.g. 1*2*500)

Response

Returns a plain-text response:

• CON <message> — session continues (user sees next menu)
• END <message> — session terminates

CON Welcome to Rach Wallet
1. Check Balance
2. Send Money
3. Withdraw

---

MTN Nigeria USSD Webhook

Handles the stateful session lifecycle for MTN USSD interactions. Auto-provisions counterfactual SCWs on first dial — new customers are onboarded transparently when they dial the USSD code for the first time.

POST /v1/ussd/callback/mtn

Content-Type: application/x-www-form-urlencoded

Form Parameters

Parameter	Type	Required	Description
SessionId	string	✅	Unique session identifier generated by MTN telecom switch
Mobile	string	✅	Subscriber MSISDN in E.164 format
UserData	string	—	Text payload entered by the user on their keypad

Response

Returns CON <msg> or END <msg>:

CON Rach Wallet
1. Balance
2. Send USDC
3. Cash Out (Local Fiat)
0. Exit

Error Response 400 Bad Request

Returns a plain-text error string.

---

USSD State Machine

The USSD handlers maintain session state across multiple keypad inputs. Here's how a typical balance check flow works:

User dials *384#
        │
        ▼
CON Welcome to Rach Wallet
    1. Check Balance
    2. Send Money
    3. Withdraw
        │
  User presses 1
        │
        ▼
END Your balance: 12.50 USDC
    (≈ local fiat equivalent)

And a send flow:

User selects 2. Send Money
        │
CON Enter recipient phone number:
        │
User enters +2250700000002
        │
CON Enter amount (USDC):
        │
User enters 5
        │
CON Confirm: Send 5 USDC to +225...002?
    1. Yes
    2. No
        │
User presses 1
        │
END Transfer sent! Ref: TXN-001

---

Configuration

To configure USSD integration with Africa's Talking:

1. Create an Africa's Talking account and obtain a USSD shortcode
2. Set your callback URL to: https://rach-caas-api-dx75yvdhaq-nw.a.run.app/v1/ussd/callback/at
3. Configure the same shortcode in your Rach tenant settings

For MTN Nigeria:

1. Apply for an MTN USSD shortcode
2. Set your callback URL to: https://rach-caas-api-dx75yvdhaq-nw.a.run.app/v1/ussd/callback/mtn

Contact support@rach.finance for telecom integration assistance.