Create a Subscription

curl -X POST https://invo.network/api/subscriptions/subscribe \
  -H "X-Game-Secret-Key: your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "subscribe:4821:guild_gold:v1",
    "player_email": "member@example.com",
    "player_name": "Ada Lovelace",
    "item_id": "guild_gold",
    "item_name": "Gold Guild Membership",
    "amount_usd": "9.99",
    "interval": "month",
    "interval_count": 1,
    "player_card_id": 91,
    "metadata": { "tier": "gold", "guild": "aurora" },
    "consent": {
      "consent_at": "2026-08-13T14:01:58-04:00",
      "consent_ip": "203.0.113.44",
      "consent_user_agent": "Mozilla/5.0 (Macintosh) Safari/605.1.15",
      "disclosed_amount_usd": "9.99",
      "disclosed_interval": "month",
      "terms_version": "2026-06-01"
    }
  }'

// SERVER ONLY. The secret key must never reach a browser or game client.
const INVO_BASE = 'https://invo.network';

async function createSubscription(player, item, priceUsd, savedCardId, consent) {
  // Generate the idempotency key ONCE, outside the retry loop.
  const clientRequestId = 'subscribe:' + player.id + ':' + item.id + ':v1';

  const res = await fetch(INVO_BASE + '/api/subscriptions/subscribe', {
    method: 'POST',
    headers: {
      'X-Game-Secret-Key': process.env.INVO_GAME_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_request_id: clientRequestId,
      player_email: player.email,
      player_name: player.name,
      item_id: item.id,
      item_name: item.name,
      amount_usd: priceUsd,          // string or number, USD
      interval: 'month',
      interval_count: 1,
      player_card_id: savedCardId,   // omit for a card-less start
      metadata: { tier: item.tier },
      consent: consent               // the MEMBER's ip + user agent
    })
  });

  const body = await res.json();

  if (res.status === 201 || res.status === 200) {
    // 200 means this was a replay of a call that already succeeded.
    if (body.idempotent_replay) {
      console.log('replay — no second agreement was created');
    }
    return body.subscription;
  }

  if (res.status === 409 && body.error_code === 'ACTIVE_SUBSCRIPTION_EXISTS') {
    // Already a member. body.subscription_id is the live one.
    return { subscription_id: body.subscription_id, already_subscribed: true };
  }

  if (res.status === 409 && body.error_code === 'PHONE_SHARE_APPROVAL_REQUIRED') {
    // Run the phone-share approval, then re-issue with the SAME key.
    throw new PhoneShareRequired(body);
  }

  if (res.status === 429 || res.status === 503 || res.status >= 500) {
    // Safe to retry — with the SAME client_request_id.
    throw new RetryableInvoError(body, res.headers.get('Retry-After'));
  }

  throw new Error('subscribe failed: ' + (body.error_code || res.status));
}

// SERVER-SIDE ONLY. Shipping the secret key in a Unity build hands an attacker
// the ability to open billing agreements against your members.
public IEnumerator CreateSubscription(
    string playerEmail, string playerName, string itemId, string itemName,
    string amountUsd, int savedCardId,
    Action<string> onSuccess, Action<string> onError)
{
    string url = "https://invo.network/api/subscriptions/subscribe";

    // Stable, member-scoped, generated ONCE — reuse it verbatim on every retry.
    string clientRequestId = "subscribe:" + playerEmail + ":" + itemId + ":v1";

    string jsonBody =
        "{" +
        "\"client_request_id\":\"" + clientRequestId + "\"," +
        "\"player_email\":\"" + playerEmail + "\"," +
        "\"player_name\":\"" + playerName + "\"," +
        "\"item_id\":\"" + itemId + "\"," +
        "\"item_name\":\"" + itemName + "\"," +
        "\"amount_usd\":\"" + amountUsd + "\"," +
        "\"interval\":\"month\"," +
        "\"interval_count\":1," +
        "\"player_card_id\":" + savedCardId +
        "}";

    using (UnityWebRequest request = new UnityWebRequest(url, "POST"))
    {
        byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody);
        request.uploadHandler = new UploadHandlerRaw(bodyRaw);
        request.downloadHandler = new DownloadHandlerBuffer();

        request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here");
        request.SetRequestHeader("Content-Type", "application/json");

        yield return request.SendWebRequest();

        // 201 = created, 200 = idempotent replay. Both are success.
        if (request.responseCode == 201 || request.responseCode == 200) {
            onSuccess?.Invoke(request.downloadHandler.text);
        } else {
            // 409 ACTIVE_SUBSCRIPTION_EXISTS means they are already a member.
            onError?.Invoke(request.downloadHandler.text);
        }
    }
}