Traiter nextAction

Quand vous créez un payin (POST /v1/payins), la réponse contient un objet nextAction. Il vous dit quoi faire ensuite. Votre travail : lire nextAction.type et réagir.

{
  "transactionId": "txn_payin_...",
  "status": "PENDING",
  "nextAction": { "type": "NONE", "url": null }
}

Il existe cinq types. Voici le tableau de décision.

`nextAction.type`	Ce que vous faites
`NONE`	Rien. Attendez le webhook ou interrogez le statut.
`REDIRECT`	Envoyez le payeur vers `nextAction.url`.
`OTP_REQUIRED`	Demandez l'OTP au payeur, puis appelez `execute`.
`USSD_REQUIRED`	Affichez la consigne USSD. Puis attendez.
`LOCAL_CONFIRMATION`	Demandez au payeur de confirmer sur son téléphone. Puis attendez.

NONE

Il n'y a rien à faire. Le paiement suit son cours.

Attendez le webhook payment.payin.succeeded ou payment.payin.failed. Vous pouvez aussi lire le statut avec GET /v1/transactions/{transactionId}.

REDIRECT

Le payeur doit ouvrir une page pour finir le paiement. L'URL est dans nextAction.url.

Redirigez le payeur vers nextAction.url.
Le payeur termine le paiement sur cette page.
Attendez le webhook ou lisez le statut.

nextAction.url est une page hébergée par FreeGate. Ce n'est jamais un lien direct vers l'opérateur.

OTP_REQUIRED

Le payeur reçoit un code par SMS (l'OTP). Vous devez récupérer ce code et l'envoyer à FreeGate.

Le code part dans le corps de la requête de POST /v1/payins/{transactionId}/execute. Le champ s'appelle otpCode.

curl -X POST "$BASE_URL/v1/payins/$TRANSACTION_ID/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "otpCode": "123456"
  }'

La réponse renvoie un nouveau status et un nouveau nextAction. Répétez tant que nextAction.type n'est pas NONE et que le status n'est pas terminal (SUCCESS ou FAILED).

En sandbox, utilisez un numéro qui se termine par 005 avec l'OTP 123456 pour un succès, ou 006 pour un échec d'OTP.

USSD_REQUIRED

Le payeur confirme le paiement avec un code USSD sur son téléphone.

Affichez la consigne (par exemple : « Composez le code reçu pour confirmer »).
Le payeur confirme sur son téléphone.
Attendez le webhook ou lisez le statut.

LOCAL_CONFIRMATION

Le payeur confirme dans l'application mobile de son opérateur.

Affichez la consigne (par exemple : « Ouvrez votre application et confirmez »).
Le payeur confirme.
Attendez le webhook ou lisez le statut.

Le flux, en une image

POST /v1/payins  ──►  lire nextAction.type
                         │
   ┌─────────────┬───────┼───────────┬──────────────────┐
 NONE        REDIRECT  OTP_REQUIRED  USSD_REQUIRED   LOCAL_CONFIRMATION
   │             │          │            │                  │
 attendre    rediriger   execute      afficher           afficher
             vers url    (otpCode)    la consigne        la consigne
                            │            │                  │
                            └────────────┴──────────────────┘
                                      │
                             attendre le webhook
                              ou lire le statut

Gérez tous les types que vos opérateurs peuvent renvoyer. Un opérateur peut utiliser OTP_REQUIRED, un autre REDIRECT : le type dépend de l'opérateur, pas du montant.