Unity SDK（游戏）

SOAMTAR Unity SDK（版本 1.0.1，命名空间 Soamtar）让玩家在您的 Unity 游戏或应用中使用 Orange Money Sierra Leone 以利昂（SLE）付款。它会在系统浏览器中打开 SOAMTAR 托管收银台。

工作原理

游戏从不创建支付，也从不持有私钥。

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. 您的后端使用 服务器 SDK 和私钥（sk_test_… / sk_live_…）创建支付，然后将 payment_url 返回给游戏。
2. 游戏调用 Checkout(paymentUrl)。付款人在浏览器中输入其 Orange Money 号码（+232 加 8 位数字），并在手机上用 Orange Money PIN 确认请求。
3. 只有在您的后端确认支付成功后（payment.success webhook 或 GET/v1/payments/{id}）才解锁物品。

关键安全要求

Unity SDK 只接受公钥（pk_test_… / pk_live_…）：传入其他值时构造函数会抛出 ArgumentException。切勿在游戏中打包私钥（sk_…）：它可能从 APK/IPA 或内存中被提取。

安装

将 SDK 仓库中的 Assets/Soamtar 文件夹复制到项目的 Assets 目录：

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

要求：Unity 2021.3 或更高版本。

使用

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
}

如需自动将玩家带回游戏，请让您的后端在创建支付时传入 success_url 和 failed_url，指向由游戏处理的页面或深层链接：支付结束时托管收银台会重定向到该地址。

API

成员	说明
new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")	仅接受 pk_test_ / pk_live_ 密钥。baseUrl（HTTPS）决定收银台 URL 允许的主机。
bool Checkout(string paymentUrl)	通过 Application.OpenURL 打开 URL。如果 URL 不是 SOAMTAR 主机上的 HTTPS 地址，返回 false 且不打开任何内容。
bool IsTestMode	使用 pk_test_ 密钥时为 true。
SoamtarClient.Version	"1.0.1"

平台支持

Application.OpenURL 在 Android、iOS、Windows 和 macOS 上打开默认浏览器，在 WebGL 上打开新标签页。

安全清单

• 隔离：支付在系统浏览器中完成；玩家在手机上用 Orange Money PIN 确认。游戏永远看不到 PIN。
• 服务器端验证：交易由您的后端创建并确认（payment.success webhook）。切勿仅凭客户端的说法解锁购买内容。
• 测试模式：使用 pk_test_ 和 sk_test_ 密钥时，支付在同一主机（https://app.so-amtar.com）上模拟处理，不会产生真实资金流动。