Kadryza Pay est en preview privée au Tchad. Demander un accès anticipé →
Guides d'intégrationRunbook pré-test terrain

Runbook pre-test terrain

Ce runbook sert a verifier un test terrain controle avec un seul merchant, une Gateway Android, un numero de collecte et un faible montant. Il ne remplace pas un process de production large.

⚠️

Ne lancez pas de paiement live si une verification critique ci-dessous echoue. En cas de doute, rester en cle test ou interrompre le test.

1. Configuration serveur

  • Verifier APP_URL : il doit pointer vers le dashboard/checkout accessible au testeur, pas localhost.
  • Verifier DATABASE_URL : bonne base staging ou VPS cible.
  • Verifier REDIS_URL : Redis doit etre accessible par le backend et Asynq.
  • Verifier JWT_SECRET et les secrets gateway : valeurs longues, non par defaut.
  • Verifier CORS_ORIGINS : inclure uniquement les domaines dashboard attendus.
  • Verifier que spencerai.tech, s’il est utilise, reste un domaine temporaire de staging/test.

2. Migrations

Appliquer toutes les migrations dans l’ordre lexical. Ne pas utiliser une liste manuelle partielle.

make migrate DATABASE_URL='postgres://user:pass@host:5432/kadryza?sslmode=disable'

Verifier au minimum la presence des tables :

  • gateways ;
  • collection_numbers ;
  • payment_sessions ;
  • credit_sms_events ;
  • ledger_entries ;
  • webhook_endpoints.

3. Workers et scheduler

Verifier que le backend a demarre :

  • le serveur HTTP ;
  • Redis ;
  • le serveur Asynq ;
  • le scheduler Asynq.

Les taches attendues pour Payment Sessions :

  • credit_sms:process ;
  • credit_sms:sweep ;
  • payment_session:expire ;
  • webhook:payment_session_deliver.

4. Provisioning Gateway

Provisionner la Gateway cote backend

Creer une ligne gateways active avec gateway_id, secret hashe et operators autorises (AIRTEL, MOOV ou les deux).

Configurer l’app Android

Configurer l’URL WebSocket, le gateway_id, le secret device, puis accepter les permissions SMS, telephone, notifications et service de fond.

Verifier la connexion

La Gateway doit apparaitre connectee et les operators doivent venir du backend, pas du client Android.

5. Provisioning numeros de collecte

Creer au moins un collection_numbers par environnement a tester :

  • msisdn exact du numero Kadryza ;
  • operator correct ;
  • gateway_id de la Gateway connectee ;
  • environment : test ou live ;
  • status = active ;
  • max_pending_sessions = 1 pour le premier test.

Sur Android, configurer le mapping SIM vers numero de collecte :

  • subscriptionId si disponible ;
  • fallback simSlot / slotIndex ;
  • operator ;
  • collection_msisdn ;
  • environment ;
  • enabled = true.

Si aucun mapping fiable n’existe, l’app ne doit pas envoyer CREDIT_SMS_RECEIVED.

6. Shortcodes et parsing SMS

  • Configurer les shortcodes Airtel/Moov reels dans l’app Gateway.
  • Envoyer ou recevoir un SMS operateur de reference en mode test controle.
  • Verifier que le parser extrait :
    • montant ;
    • reference operateur si presente ;
    • telephone payeur si present ;
    • operator ;
    • isCredit = true.

Ne pas s’appuyer sur un SMS terrain non encore observe pour un test live important.

7. Test sandbox

  1. Creer une cle API test.
  2. Creer une Payment Session test.
  3. Ouvrir checkout_url.
  4. Verifier que environment = test.
  5. Verifier que le numero assigne vient d’un collection_numbers.environment = test.
  6. Simuler ou executer le paiement selon le dispositif de test.
  7. Verifier credit_sms_events.
  8. Verifier payment_sessions.status.
  9. Verifier qu’aucune entree ledger reelle n’est creee pour une session test.
  10. Verifier le webhook payment_session.* avec X-Kadryza-Test: true.

8. Test live faible montant

  1. Creer une cle API live.
  2. Creer une Payment Session live avec faible montant.
  3. Ouvrir le checkout et payer exactement le montant demande.
  4. Verifier une ligne credit_sms_events pour le SMS recu.
  5. Verifier que le statut devient SUCCESS uniquement si le match est unique.
  6. Verifier ledger_entries :
    • PAYMENT positif ;
    • FEE negatif si fee_bps > 0.
  7. Verifier le solde merchant.
  8. Verifier le webhook payment_session.succeeded.
  9. Lancer ou consulter la reconciliation read-only.

9. Si le statut n’est pas SUCCESS

CasAction
UNDER_REVIEWStopper le test automatique, comparer SMS, session, montant, numero et timestamps. Ne pas corriger le ledger manuellement.
no_match impliciteVerifier mapping SIM, collection_msisdn, operator, montant et fenetre d’expiration.
ambiguous impliciteVerifier si plusieurs sessions actives partagent montant/numero/fenetre. Garder max_pending_sessions = 1 pendant les tests initiaux.
EXPIREDCreer une nouvelle session ; ne pas reutiliser une session expiree.
Webhook non recuVerifier endpoint actif, signature, logs Asynq et reponses HTTP du merchant.

10. Criteres d’arret

Arreter le test si :

  • la Gateway est deconnectee ;
  • Redis/Asynq ne traite plus les queues ;
  • le SMS est recu mais absent de credit_sms_events ;
  • un paiement live cree un ledger inattendu ;
  • une session test cree un ledger ;
  • un cas ambigu est confirme automatiquement ;
  • le webhook merchant traite un evenement non signe.

11. Donnees a collecter

  • id de Payment Session ;
  • reference merchant ;
  • montant ;
  • operator ;
  • collection number utilise ;
  • timestamps checkout / SMS / confirmation ;
  • statut final ;
  • resultat webhook ;
  • anomalies reconciliation.

Ne copiez pas de secret, token, cle API, hash ou mot de passe dans le rapport de test.

Payment SessionsVérification des webhooks