Unity SDK (video games)

The SOAMTAR Unity SDK (version 1.0.1, namespace Soamtar) lets players pay with Orange Money Sierra Leone, in leones (SLE), from your Unity game or app. It opens the SOAMTAR hosted checkout in the system browser.

How it works

The game never creates a payment and never holds a secret key.

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. Your backend creates the payment with a secret key (sk_test_… / sk_live_…) using a server SDK, then returns payment_url to the game.
2. The game calls Checkout(paymentUrl). In the browser, the payer enters their Orange Money number (+232 followed by 8 digits) and confirms the request on their phone with their Orange Money PIN.
3. Unlock the item only once your backend has confirmed the payment (payment.success webhook or GET /v1/payments/{id}).

Critical security

The Unity SDK only accepts public keys (pk_test_… / pk_live_…): the constructor throws an ArgumentException for anything else. Never ship a secret key (sk_…) in a game: it can be extracted from the APK/IPA or from memory.

Installation

Copy the Assets/Soamtar folder of the SDK repository into your project's Assets directory:

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

Requirements: Unity 2021.3 or later.

Usage

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
}

To bring the player back automatically, have your backend pass success_url and failed_url when it creates the payment, pointing to a page or deep link handled by your game: the hosted checkout redirects there when the payment ends.

API

Member	Description
new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")	Accepts pk_test_ / pk_live_ keys only. baseUrl (HTTPS) sets the host accepted for checkout URLs.
bool Checkout(string paymentUrl)	Opens the URL with Application.OpenURL. Returns false and opens nothing if the URL is not HTTPS on the SOAMTAR host.
bool IsTestMode	true for pk_test_ keys.
SoamtarClient.Version	"1.0.1"

Platform support

Application.OpenURL opens the default browser on Android, iOS, Windows and macOS, and a new tab on WebGL.

Security checklist

• Isolation: the payment happens in the system browser; the player confirms with their Orange Money PIN on their phone. The game never sees the PIN.
• Server-side verification: the transaction is created and confirmed by your backend (payment.success webhook). Never unlock a purchase on the client's word alone.
• Test mode: with pk_test_ and sk_test_ keys, payments are simulated on the same host (https://app.so-amtar.com); no real money moves.