SDK Unity (jeux vidéo)

Le SDK Unity de SOAMTAR (version 1.0.1, espace de noms Soamtar) permet à vos joueurs de payer avec Orange Money Sierra Leone, en leones (SLE), depuis votre jeu ou votre application Unity. Il ouvre le checkout hébergé SOAMTAR dans le navigateur du système.

Fonctionnement

Le jeu ne crée jamais de paiement et ne détient jamais de clé secrète.

Unity game                     Your backend                         SOAMTAR API
    |-- 1. purchase intent ----->|                                       |
    |                            |-- 2. POST /v1/payments (sk_ key) ---->|
    |                            |<-- payment_url -----------------------|
    |<-- 3. payment_url ---------|                                       |
    |-- 4. Checkout(url): system browser, payer approves with PIN       |
    |-- 5. ask your backend for the final status                        |

1. Votre backend crée le paiement avec une clé secrète (sk_test_… / sk_live_…) grâce à un SDK serveur, puis renvoie la payment_url au jeu.
2. Le jeu appelle Checkout(paymentUrl). Dans le navigateur, le payeur saisit son numéro Orange Money (+232 suivi de 8 chiffres) et confirme la demande sur son téléphone avec son code PIN Orange Money.
3. Ne débloquez l'objet qu'une fois le paiement confirmé par votre backend (webhook payment.success ou GET/v1/payments/{id}).

Sécurité critique

Le SDK Unity n'accepte que des clés publiques (pk_test_… / pk_live_…) : le constructeur lève une ArgumentException pour toute autre valeur. N'embarquez jamais de clé secrète (sk_…) dans un jeu : elle peut être extraite de l'APK/IPA ou de la mémoire.

Installation

Copiez le dossier Assets/Soamtar du dépôt du SDK dans le dossier Assets de votre projet :

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

Prérequis : Unity 2021.3 ou plus récent.

Utilisation

using System.Collections;
using Soamtar;
using UnityEngine;
using UnityEngine.Networking;

public class PurchaseManager : MonoBehaviour
{
    private SoamtarClient soamtar;
    private string pendingOrderId;

    void Start()
    {
        soamtar = new SoamtarClient("pk_test_your_public_key");
    }

    public void OnBuyGoldPack()
    {
        StartCoroutine(CreatePayment());
    }

    IEnumerator CreatePayment()
    {
        // Your backend decides the price and creates the payment with its secret key.
        using var request = new UnityWebRequest("https://api.yourgame.example/purchases", "POST");
        request.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes("{\"item\":\"gold_pack\"}"));
        request.downloadHandler = new DownloadHandlerBuffer();
        request.SetRequestHeader("Content-Type", "application/json");

        yield return request.SendWebRequest();

        if (request.result != UnityWebRequest.Result.Success)
        {
            Debug.LogError("Could not create the payment: " + request.error);
            yield break;
        }

        var purchase = JsonUtility.FromJson<PurchaseResponse>(request.downloadHandler.text);
        pendingOrderId = purchase.orderId;

        if (!soamtar.Checkout(purchase.paymentUrl))
        {
            Debug.LogError("Refused payment URL");
        }
    }

    void OnApplicationFocus(bool hasFocus)
    {
        // The player came back from the browser: ask YOUR backend whether the order is paid.
        if (hasFocus && pendingOrderId != null)
        {
            StartCoroutine(RefreshOrder(pendingOrderId));
        }
    }

    IEnumerator RefreshOrder(string orderId) { /* call your backend */ yield break; }
}

[System.Serializable]
public class PurchaseResponse
{
    public string orderId;
    public string paymentUrl; // payment_url returned by SOAMTAR to your backend
}

Pour ramener automatiquement le joueur dans le jeu, faites passer par votre backend success_url et failed_url à la création du paiement, en pointant vers une page ou un deep link géré par votre jeu : le checkout hébergé y redirige à la fin du paiement.

API

Membre	Description
new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")	N'accepte que des clés pk_test_ / pk_live_. baseUrl (HTTPS) fixe l'hôte accepté pour les URL de checkout.
bool Checkout(string paymentUrl)	Ouvre l'URL via Application.OpenURL. Renvoie false sans rien ouvrir si l'URL n'est pas en HTTPS sur l'hôte SOAMTAR.
bool IsTestMode	true pour les clés pk_test_.
SoamtarClient.Version	"1.0.1"

Plateformes

Application.OpenURL ouvre le navigateur par défaut sur Android, iOS, Windows et macOS, et un nouvel onglet en WebGL.

Check-list sécurité

• Isolation : le paiement se déroule dans le navigateur du système ; le joueur confirme avec son code PIN Orange Money sur son téléphone. Le jeu ne voit jamais le PIN.
• Vérification côté serveur : la transaction est créée et confirmée par votre backend (webhook payment.success). Ne débloquez jamais un achat sur la seule parole du client.
• Mode test : avec des clés pk_test_ et sk_test_, les paiements sont simulés sur le même hôte (https://app.so-amtar.com) ; aucun argent réel ne circule.