SDK Unity (jogos)

O SDK Unity da SOAMTAR (versão 1.0.1, namespace Soamtar) permite que os jogadores paguem com Orange Money Sierra Leone, em leones (SLE), a partir do seu jogo ou app Unity. Abre o checkout alojado da SOAMTAR no navegador do sistema.

Como funciona

O jogo nunca cria um pagamento nem guarda uma chave 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. O seu backend cria o pagamento com uma chave secreta (sk_test_… / sk_live_…) através de um SDK de servidor e devolve o payment_url ao jogo.
2. O jogo chama Checkout(paymentUrl). No navegador, o pagador introduz o seu número Orange Money (+232 seguido de 8 dígitos) e confirma o pedido no telefone com o seu PIN Orange Money.
3. Desbloqueie o item apenas depois de o seu backend confirmar o pagamento (webhook payment.success ou GET/v1/payments/{id}).

Segurança crítica

O SDK Unity só aceita chaves públicas (pk_test_… / pk_live_…): o construtor lança uma ArgumentException para qualquer outro valor. Nunca inclua uma chave secreta (sk_…) num jogo: pode ser extraída do APK/IPA ou da memória.

Instalação

Copie a pasta Assets/Soamtar do repositório do SDK para a pasta Assets do seu projeto:

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

Requisitos: Unity 2021.3 ou posterior.

Utilização

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 trazer o jogador de volta automaticamente, faça com que o seu backend envie success_url e failed_url ao criar o pagamento, apontando para uma página ou deep link tratado pelo seu jogo: o checkout alojado redireciona para lá quando o pagamento termina.

API

Membro	Descrição
new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")	Só aceita chaves pk_test_ / pk_live_. baseUrl (HTTPS) define o host aceite para os URL de checkout.
bool Checkout(string paymentUrl)	Abre o URL com Application.OpenURL. Devolve false e não abre nada se o URL não for HTTPS no host SOAMTAR.
bool IsTestMode	true para chaves pk_test_.
SoamtarClient.Version	"1.0.1"

Plataformas

Application.OpenURL abre o navegador predefinido em Android, iOS, Windows e macOS, e um novo separador em WebGL.

Lista de segurança

• Isolamento: o pagamento decorre no navegador do sistema; o jogador confirma com o PIN Orange Money no telefone. O jogo nunca vê o PIN.
• Verificação no servidor: o seu backend cria e confirma a transação (webhook payment.success). Nunca desbloqueie uma compra apenas com base no que o cliente diz.
• Modo de teste: com chaves pk_test_ e sk_test_, os pagamentos são simulados no mesmo host (https://app.so-amtar.com); não há movimento de dinheiro real.