SDK de Unity (videojuegos)

El SDK de Unity de SOAMTAR (versión 1.0.1, espacio de nombres Soamtar) permite a los jugadores pagar con Orange Money Sierra Leone, en leones (SLE), desde su juego o app de Unity. Abre el checkout alojado de SOAMTAR en el navegador del sistema.

Cómo funciona

El juego nunca crea un pago ni guarda una clave secreta.

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. Su backend crea el pago con una clave secreta (sk_test_… / sk_live_…) mediante un SDK de servidor, y devuelve payment_url al juego.
2. El juego llama a Checkout(paymentUrl). En el navegador, el pagador introduce su número Orange Money (+232 seguido de 8 dígitos) y confirma la solicitud en su teléfono con su PIN de Orange Money.
3. Desbloquee el artículo solo cuando su backend haya confirmado el pago (webhook payment.success o GET/v1/payments/{id}).

Seguridad crítica

El SDK de Unity solo acepta claves públicas (pk_test_… / pk_live_…): el constructor lanza una ArgumentException con cualquier otro valor. Nunca incluya una clave secreta (sk_…) en un juego: puede extraerse del APK/IPA o de la memoria.

Instalación

Copie la carpeta Assets/Soamtar del repositorio del SDK en la carpeta Assets de su proyecto:

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

Requisitos: Unity 2021.3 o posterior.

Uso

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
}

Para devolver al jugador automáticamente, haga que su backend envíe success_url y failed_url al crear el pago, apuntando a una página o deep link que gestione su juego: el checkout alojado redirige allí al terminar el pago.

API

Miembro	Descripción
new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")	Solo acepta claves pk_test_ / pk_live_. baseUrl (HTTPS) fija el host aceptado para las URL de checkout.
bool Checkout(string paymentUrl)	Abre la URL con Application.OpenURL. Devuelve false y no abre nada si la URL no es HTTPS en el host de SOAMTAR.
bool IsTestMode	true para claves pk_test_.
SoamtarClient.Version	"1.0.1"

Plataformas

Application.OpenURL abre el navegador predeterminado en Android, iOS, Windows y macOS, y una pestaña nueva en WebGL.

Lista de seguridad

• Aislamiento: el pago se realiza en el navegador del sistema; el jugador confirma con su PIN de Orange Money en su teléfono. El juego nunca ve el PIN.
• Verificación en el servidor: su backend crea y confirma la transacción (webhook payment.success). Nunca desbloquee una compra solo por lo que diga el cliente.
• Modo de prueba: con claves pk_test_ y sk_test_, los pagos se simulan en el mismo host (https://app.so-amtar.com); no se mueve dinero real.