The card road, end to end

# 1. your server: mint the link
curl -sS -X POST "$BASE/api/checkout/card-setup-sessions" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "player_email": "member@example.com",
    "success_url": "https://yourtitle.com/membership/saved",
    "cancel_url":  "https://yourtitle.com/membership",
    "metadata": {"member_id": "7"}
  }'
# 201 {"session_id": "...", "card_setup_url": "https://invo.network/card-setup?session=...",
#      "expires_at": "2026-09-12T00:29:08+00:00"}

# 2. send the member to card_setup_url; they come back to success_url

# 3. your server: read the saved card
curl -sS "$BASE/api/currency-purchases/player-cards?player_email=member%40example.com" \
  -H "X-Game-Secret-Key: $GAME_SECRET"
# 200 {"cards": [{"id": 42, "last_four": "4242", "brand": "visa", "exp_month": 12, "exp_year": 2030, ...}]}

// 1. mint the link
const session = await invo.cards.createSetupSession({
  playerEmail: "member@example.com",
  successUrl: "https://yourtitle.com/membership/saved",   // optional
  cancelUrl: "https://yourtitle.com/membership",          // optional; carried, not used by the page today
  metadata: { member_id: "7" },                           // optional; stored, never returned: correlate via successUrl
});
// session.sessionId, session.cardSetupUrl, session.expiresAt (10 minutes out); metadata is not returned anywhere

// 2. send the member there (redirect or top-level window; never an iframe)
redirectMember(session.cardSetupUrl);

// 3. when they land on successUrl, read the card
const { cards } = await invo.cards.list("member@example.com");
const card = cards[0];            // newest first: { id: 42, lastFour: "4242", brand: "visa", ... }

// 1. mint the link
const { status, json } = await invo("POST", "/api/checkout/card-setup-sessions", {
  player_email: "member@example.com",
  success_url: "https://yourtitle.com/membership/saved",
  cancel_url: "https://yourtitle.com/membership",
  metadata: { member_id: "7" },
});
if (status === 201) {
  redirectMember(json.card_setup_url);           // use it as given; expires at json.expires_at
} else if (status === 404 && json.error_code === "PLAYER_NOT_FOUND") {
  // the member does not exist in this title yet: create them first
}

// 3. on their return, read the card
const cards = (await invo("GET",
  "/api/currency-purchases/player-cards?player_email=" + encodeURIComponent("member@example.com"))).json.cards;
const card = cards[0];                           // undefined when nothing was saved

# 1. mint the link
session = invo.cards.create_setup_session(
    player_email="member@example.com",
    success_url="https://yourtitle.com/membership/saved",   # optional
    cancel_url="https://yourtitle.com/membership",          # optional; carried, not used by the page today
    metadata={"member_id": "7"},                            # optional; stored, never returned: correlate via success_url
)
# session.session_id, session.card_setup_url, session.expires_at (10 minutes out); metadata is not returned anywhere

# 2. send the member there (redirect or top-level window; never an iframe)
redirect_member(session.card_setup_url)

# 3. when they land on success_url, read the card
cards = invo.cards.list("member@example.com").cards
card = cards[0] if cards else None               # newest first

# 1. mint the link
status, body = invo("POST", "/api/checkout/card-setup-sessions", {
    "player_email": "member@example.com",
    "success_url": "https://yourtitle.com/membership/saved",
    "cancel_url": "https://yourtitle.com/membership",
    "metadata": {"member_id": "7"},
})
if status == 201:
    redirect_member(body["card_setup_url"])      # use it as given; expires at body["expires_at"]
elif status == 404 and body.get("error_code") == "PLAYER_NOT_FOUND":
    pass   # the member does not exist in this title yet: create them first

# 3. on their return, read the card
_, cards_body = invo("GET", "/api/currency-purchases/player-cards",
                     params={"player_email": "member@example.com"})
card = cards_body["cards"][0] if cards_body["cards"] else None

# server-side: the card was already tokenised on the client by your card form
curl -sS -X POST "$BASE/api/currency-purchases/setup-intent" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "player_email": "member@example.com",
    "setup_reference": "card-setup-member-7-2026-09",
    "payment_method_id": "<token from your card form>"
  }'

# if the response was requires_action / requires_confirmation, the client confirms
# with the card element using client_secret, then your server calls:
curl -sS -X POST "$BASE/api/currency-purchases/setup-intent/confirm" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"setup_intent_id": "<opaque setup reference>"}'

// 1. begin: returns the setup reference and the client secret for your card form
const setup = await invo.cards.beginSetup({
  playerEmail: "member@example.com",
  setupReference: "card-setup-member-7-2026-09",   // your idempotency anchor
  // paymentMethodId: "<token from your card form>",  // optional: saves immediately
});
// setup.clientSecret   -> hand to the client; confirm with your card element
// setup.setupIntentId  -> what step 2 needs
// setup.status         -> "succeeded" when the card is already saved; otherwise
//                         "requires_action" | "requires_confirmation" | "requires_payment_method"

// 2. confirm: only when step 1 did not already save the card, after the
//    client finished with the card element
const saved = await invo.cards.confirmSetup({
  setupIntentId: setup.setupIntentId,
});
console.log(saved.card.id, saved.alreadySaved);   // 42, false

const { status, json } = await invo("POST", "/api/currency-purchases/setup-intent", {
  player_email: "member@example.com",
  setup_reference: "card-setup-member-7-2026-09",
  payment_method_id: "<token from your card form>",   // omit to get a client_secret instead
});

if (status === 200 && json.status === "succeeded") {
  cardId = json.card.id;                       // 42
} else if (status === 200) {
  // requires_action | requires_confirmation | requires_payment_method:
  // send json.client_secret to the client, confirm with the card element, then:
  const done = await invo("POST", "/api/currency-purchases/setup-intent/confirm", {
    setup_intent_id: json.setup_intent_id,
  });
  if (done.status === 400 && done.json.status === "still_requires_action") {
    // the client has not finished yet; try again after it has
  } else if (done.status === 200) {
    cardId = done.json.card.id;
  }
} else {
  switch (json.error_code) {
    case "PLAYER_NOT_FOUND":        /* create the player first */ break;
    case "SETUP_REFERENCE_REUSED":  /* new reference for a new setup */ break;
    case "CARD_DECLINED":
    case "SETUP_FAILED":
    case "INVALID_PAYMENT_METHOD":  /* ask for another card */ break;
    case "CARD_PERSIST_FAILED":     /* retry /setup-intent/confirm with the same id */ break;
  }
}

# 1. begin
setup = invo.cards.begin_setup(
    player_email="member@example.com",
    setup_reference="card-setup-member-7-2026-09",   # your idempotency anchor
    # payment_method_id="<token from your card form>",  # optional: saves immediately
)
# setup.client_secret   -> hand to the client; confirm with your card element
# setup.setup_intent_id -> what step 2 needs
# setup.status          -> "succeeded" when the card is already saved; otherwise
#                          "requires_action" | "requires_confirmation" | "requires_payment_method"

# 2. confirm: only when step 1 did not already save the card
saved = invo.cards.confirm_setup(setup_intent_id=setup.setup_intent_id)
print(saved.card.id, saved.already_saved)   # 42 False

status, body = invo("POST", "/api/currency-purchases/setup-intent", {
    "player_email": "member@example.com",
    "setup_reference": "card-setup-member-7-2026-09",
    "payment_method_id": "<token from your card form>",   # omit to get a client_secret instead
})

if status == 200 and body["status"] == "succeeded":
    card_id = body["card"]["id"]                    # 42
elif status == 200:
    # requires_action | requires_confirmation | requires_payment_method:
    # send body["client_secret"] to the client, confirm with the card element, then:
    s2, done = invo("POST", "/api/currency-purchases/setup-intent/confirm",
                    {"setup_intent_id": body["setup_intent_id"]})
    if s2 == 400 and done.get("status") == "still_requires_action":
        pass   # the client has not finished yet
    elif s2 == 200:
        card_id = done["card"]["id"]
else:
    code = body.get("error_code")
    # PLAYER_NOT_FOUND, SETUP_REFERENCE_REUSED, CARD_DECLINED, SETUP_FAILED,
    # INVALID_PAYMENT_METHOD, RAW_CARD_NOT_SUPPORTED, CARD_PERSIST_FAILED

curl -sS "$BASE/api/currency-purchases/player-cards?player_email=member%40example.com" \
  -H "X-Game-Secret-Key: $GAME_SECRET"

const { cards } = await invo.cards.list("member@example.com");
const newest = cards[0];        // { id: 42, lastFour: "4242", brand: "visa", expMonth: 12, expYear: 2030 }

const { json } = await invo("GET",
  "/api/currency-purchases/player-cards?player_email=" + encodeURIComponent("member@example.com"));
const newest = json.cards[0];   // undefined when the member has no unexpired card

cards = invo.cards.list("member@example.com").cards
newest = cards[0] if cards else None

_, body = invo("GET", "/api/currency-purchases/player-cards",
               params={"player_email": "member@example.com"})
newest = body["cards"][0] if body["cards"] else None

curl -sS -X POST "$BASE/api/subscriptions/subscribe" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "guild-42-member-7",
    "player_email": "member@example.com",
    "player_name": "Member Seven",
    "item_id": "guild-42-membership",
    "item_name": "Guild 42 membership",
    "amount_usd": "9.99",
    "interval": "month",
    "interval_count": 1,
    "player_card_id": 42,
    "metadata": {"guild_id": "42"},
    "consent": {
      "consent_at": "2026-09-06T14:01:50+00:00",
      "consent_ip": "203.0.113.7",
      "consent_user_agent": "Mozilla/5.0 ...",
      "disclosed_amount_usd": "9.99",
      "disclosed_interval": "month",
      "terms_version": "2026-09"
    }
  }'

const result = await invo.subscriptions.create({
  clientRequestId: "guild-42-member-7",      // generated once, persisted, replayed on retry
  playerEmail: "member@example.com",
  playerName: "Member Seven",
  itemId: "guild-42-membership",
  itemName: "Guild 42 membership",
  amountUsd: "9.99",
  interval: "month",
  intervalCount: 1,
  playerCardId: 42,                          // omit to let Invo pick the newest saved card
  metadata: { guild_id: "42" },
  consent: {
    consentAt: "2026-09-06T14:01:50+00:00",
    consentIp: memberIp,                     // the MEMBER's IP, as your server saw it
    consentUserAgent: memberUserAgent,
    disclosedAmountUsd: "9.99",
    disclosedInterval: "month",
    termsVersion: "2026-09",
  },
});

// result.idempotentReplay   false on the 201, true on a replayed 200
// result.subscription       the subscription object (see /docs/subscriptions-manage)
// result.card               the card backing it, or null
// result.firstCharge        branch on .status (next section)

const body = {
  client_request_id: "guild-42-member-7",
  player_email: "member@example.com",
  player_name: "Member Seven",
  item_id: "guild-42-membership",
  item_name: "Guild 42 membership",
  amount_usd: "9.99",
  interval: "month",
  interval_count: 1,
  player_card_id: 42,
  metadata: { guild_id: "42" },
  consent: {
    consent_at: "2026-09-06T14:01:50+00:00",
    consent_ip: memberIp,
    consent_user_agent: memberUserAgent,
    disclosed_amount_usd: "9.99",
    disclosed_interval: "month",
    terms_version: "2026-09",
  },
};

let { status, json } = await invo("POST", "/api/subscriptions/subscribe", body);
if (status >= 500 || status === 0) {
  // timeout or 5xx: REPLAY the same body before anything else
  ({ status, json } = await invo("POST", "/api/subscriptions/subscribe", body));
}

if (status === 201 || (status === 200 && json.idempotent_replay)) {
  handleFirstCharge(json.subscription, json.first_charge);   // next section
} else if (status === 409 && json.error_code === "ACTIVE_SUBSCRIPTION_EXISTS") {
  // the member already has a live subscription to this item: use it
  const existing = json.subscription_id;
} else if (status === 409 && json.error_code === "IDEMPOTENT_REPLAY_MISMATCH") {
  // same key, different terms: json.mismatched_fields says which
} else if (status === 403 && json.error_code === "GAME_NOT_LIVE") {
  // make the game live in the console
} else if (status === 503 && json.error === "flow_paused") {
  // retry later with the SAME client_request_id
}

result = invo.subscriptions.create(
    client_request_id="guild-42-member-7",     # generated once, persisted, replayed on retry
    player_email="member@example.com",
    player_name="Member Seven",
    item_id="guild-42-membership",
    item_name="Guild 42 membership",
    amount_usd="9.99",
    interval="month",
    interval_count=1,
    player_card_id=42,                         # omit to let Invo pick the newest saved card
    metadata={"guild_id": "42"},
    consent={
        "consent_at": "2026-09-06T14:01:50+00:00",
        "consent_ip": member_ip,               # the MEMBER's IP, as your server saw it
        "consent_user_agent": member_user_agent,
        "disclosed_amount_usd": "9.99",
        "disclosed_interval": "month",
        "terms_version": "2026-09",
    },
)

# result.idempotent_replay   False on the 201, True on a replayed 200
# result.subscription        the subscription object
# result.card                the card backing it, or None
# result.first_charge        branch on .status (next section)

body = {
    "client_request_id": "guild-42-member-7",
    "player_email": "member@example.com",
    "player_name": "Member Seven",
    "item_id": "guild-42-membership",
    "item_name": "Guild 42 membership",
    "amount_usd": "9.99",
    "interval": "month",
    "interval_count": 1,
    "player_card_id": 42,
    "metadata": {"guild_id": "42"},
    "consent": {
        "consent_at": "2026-09-06T14:01:50+00:00",
        "consent_ip": member_ip,
        "consent_user_agent": member_user_agent,
        "disclosed_amount_usd": "9.99",
        "disclosed_interval": "month",
        "terms_version": "2026-09",
    },
}

try:
    status, res = invo("POST", "/api/subscriptions/subscribe", body)
    if status >= 500:
        status, res = invo("POST", "/api/subscriptions/subscribe", body)   # replay, same key
except requests.RequestException:
    status, res = invo("POST", "/api/subscriptions/subscribe", body)       # replay, same key

if status == 201 or (status == 200 and res.get("idempotent_replay")):
    handle_first_charge(res["subscription"], res["first_charge"])   # next section
elif status == 409 and res.get("error_code") == "ACTIVE_SUBSCRIPTION_EXISTS":
    existing = res["subscription_id"]      # the member's live subscription to this item
elif status == 409 and res.get("error_code") == "IDEMPOTENT_REPLAY_MISMATCH":
    mismatched = res["mismatched_fields"]
elif status == 503 and res.get("error") == "flow_paused":
    pass   # retry later with the SAME client_request_id

function handleFirstCharge(sub, fc) {
  switch (fc.status) {
    case "paid":
      // key the entitlement on the PAID period (fc.paid_period_seq === 1), not on
      // sub.period_seq, which already points at the next window (2)
      grantAccess(sub.subscription_id, fc.paid_period_seq, fc.paid_through);
      break;
    case "requires_action":
      // nothing charged; paid_through is null
      sendToMember(sub.player_id, "Confirm your payment: " + fc.confirmation_url, fc.expires_at);
      break;
    case "skipped_trial":
      grantTrialAccess(sub.subscription_id, sub.trial_end);
      break;
    case "failed":
      tellMemberToFixCard(sub.player_id, fc.failure_code, fc.next_retry_at);
      break;
    case "pending":
      // wait for subscription.renewed or subscription.payment_failed (about 30 minutes at most)
      break;
  }
}

def handle_first_charge(sub, fc):
    st = fc["status"]
    if st == "paid":
        # key the entitlement on the PAID period (fc["paid_period_seq"] == 1), not on
        # sub["period_seq"], which already points at the next window (2)
        grant_access(sub["subscription_id"], fc["paid_period_seq"], fc["paid_through"])
    elif st == "requires_action":
        # nothing charged; paid_through is None
        send_to_member(sub["player_id"], "Confirm your payment: " + fc["confirmation_url"],
                       expires_at=fc["expires_at"])
    elif st == "skipped_trial":
        grant_trial_access(sub["subscription_id"], sub["trial_end"])
    elif st == "failed":
        tell_member_to_fix_card(sub["player_id"], fc["failure_code"], fc["next_retry_at"])
    elif st == "pending":
        pass   # wait for subscription.renewed or subscription.payment_failed

curl -sS -X POST "$BASE/api/subscriptions/subscribe" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "guild-42-member-8",
    "player_email": "eight@example.com",
    "player_name": "Member Eight",
    "item_id": "guild-42-membership",
    "amount_usd": "9.99",
    "trial_days": 7
  }'
# 201, subscription.status "trialing", first_charge.status "skipped_trial", paid_through null

const trial = await invo.subscriptions.create({
  clientRequestId: "guild-42-member-8",
  playerEmail: "eight@example.com",
  playerName: "Member Eight",
  itemId: "guild-42-membership",
  amountUsd: "9.99",
  trialDays: 7,                 // or trialEnd: "2026-09-13T00:00:00+00:00"
});
// trial.firstCharge.status === "skipped_trial"; grant trial access until trial.subscription.trialEnd

trial = invo.subscriptions.create(
    client_request_id="guild-42-member-8",
    player_email="eight@example.com",
    player_name="Member Eight",
    item_id="guild-42-membership",
    amount_usd="9.99",
    trial_days=7,                 # or trial_end="2026-09-13T00:00:00+00:00"
)
# trial.first_charge.status == "skipped_trial"; grant trial access until trial.subscription.trial_end

curl -sS -X POST "$BASE/api/subscriptions/subscribe" \
  -H "X-Game-Secret-Key: $GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "guild-42-member-9",
    "player_email": "nine@example.com",
    "player_name": "Member Nine",
    "item_id": "guild-42-membership",
    "amount_usd": "9.99",
    "wallet_only": true
  }'
# do NOT send player_card_id with wallet_only: true (409 WALLET_ONLY_SUBSCRIPTION)

const walletOnly = await invo.subscriptions.create({
  clientRequestId: "guild-42-member-9",
  playerEmail: "nine@example.com",
  playerName: "Member Nine",
  itemId: "guild-42-membership",
  amountUsd: "9.99",
  walletOnly: true,
});

wallet_only = invo.subscriptions.create(
    client_request_id="guild-42-member-9",
    player_email="nine@example.com",
    player_name="Member Nine",
    item_id="guild-42-membership",
    amount_usd="9.99",
    wallet_only=True,
)