Leggere le conferme mobile money in tempo reale

L'esigenza

Vende online in un paese dove si paga con mobile money. L'operatore conferma ogni pagamento con un SMS al numero dell'esercente, immediatamente. Un'API, quando esiste, richiede settimane di pratiche, una società registrata, un volume minimo e spesso una quota di ogni transazione.

Nel frattempo la conferma di cui ha bisogno sta già arrivando, su un telefono, sotto forma di messaggio.

Come funziona

La SIM che riceve le conferme dell'operatore è una delle schede SIM associate al suo gateway. Da lì:

1. Il messaggio arriva sul telefono e il gateway lo registra, sulla sua macchina. Un operatore scrive da un codice breve o da un nome, non da un numero: lo aggiunga ai Mittenti da registrare in Impostazioni > Ricezione, altrimenti sarà rifiutato come ogni servizio sconosciuto. Il Registro attività ne mostra la grafia esatta dal primo messaggio.
2. Un webhook chiama la sua applicazione appena arriva l'SMS: lo iscriva a message.received nella pagina Webhook. La chiamata è firmata in HMAC-SHA256, perché lei possa provare che viene dal suo gateway, e porta gli identificativi del messaggio, mai il suo testo.
3. Il suo codice legge il messaggio tramite l'API del gateway, con una chiave limitata all'ambito Lettura: GET /api/v1/messages/{id} restituisce il mittente e il testo.
4. Il suo codice verifica il mittente, legge l'importo e il riferimento, e segna l'ordine come pagato.

Nulla viene interrogato in ciclo e nulla attende: il webhook parte quando l'SMS arriva.

Cosa sapere prima di costruirci sopra

• Il formato del messaggio appartiene all'operatore. Può cambiarne la formulazione senza avvisarla, e un parser scritto sulla vecchia smette allora di riconoscerlo. Registri ciò che non è riuscito ad analizzare, e tenga d'occhio quel registro.
• Un SMS non è una prova di pagamento. Dice ciò che l'operatore ha inviato a quel numero. Per un importo che conta, confermi sull'estratto o sull'API dell'operatore prima di consegnare qualcosa di irreversibile.
• Riservi la SIM ricevente a questo uso, su un telefono che resta sotto carica. Una conferma che arriva a telefono spento viene letta al ritorno, non è persa, ma è letta in ritardo.
• Verifichi le condizioni del suo operatore: ciò che ha il diritto di automatizzare su un conto mobile money dipende dalla sua regola, non dalla nostra.

Cosa serve

Un telefono associato, la SIM che riceve le conferme, il mittente dell'operatore registrato in Impostazioni > Ricezione, un webhook su message.received, una chiave API con ambito Lettura e un endpoint nella sua applicazione. Il gateway conserva i messaggi; la decisione di accettare un pagamento resta nel suo codice.