Cross-Game Transfer, Stage by Stage

const BASE = process.env.INVO_BASE_URL;            // https://invo.network  |  https://sandbox.invo.network/sandbox
const GAME_SECRET = process.env.INVO_GAME_SECRET;  // server-side only

async function invo(method, path, headers, body) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: { "Content-Type": "application/json", ...headers },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  return { status: res.status, json };
}
const asGame   = { "X-Game-Secret-Key": GAME_SECRET };
const asPlayer = (token) => ({ Authorization: `Bearer ${token}` });

import os, time, uuid, requests

BASE = os.environ["INVO_BASE_URL"]            # https://invo.network  |  https://sandbox.invo.network/sandbox
GAME_SECRET = os.environ["INVO_GAME_SECRET"]  # server-side only

def invo(method, path, headers=None, body=None):
    r = requests.request(method, BASE + path,
                         headers={"Content-Type": "application/json", **(headers or {})},
                         json=body, timeout=15)
    try:
        return r.status_code, r.json()
    except ValueError:
        return r.status_code, {}

as_game = {"X-Game-Secret-Key": GAME_SECRET}
def as_player(token): return {"Authorization": f"Bearer {token}"}

PLAYER_TOKEN=$(curl -sS -X POST "$BASE/api/sdk/player-token" \
  -H "X-Game-Secret-Key: $GAME_SECRET" -H "Content-Type: application/json" \
  -d '{"player_email":"ada@example.com","player_phone":"+15555550100","player_name":"Ada"}' | jq -r .token)

import { InvoServer } from "@invonetwork/web-sdk/server";
const invoSdk = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET!, baseUrl: process.env.INVO_BASE_URL! });

const tok = await invoSdk.mintPlayerToken({
  playerEmail: "ada@example.com",
  playerPhone: "+15555550100",
  playerName: "Ada",
});
if (tok.phoneMismatch) await updatePhoneThenRemint();   // see Player Identity
let playerToken = tok.token;

from invonetwork import InvoServer
invo_sdk = InvoServer(game_secret=os.environ["INVO_GAME_SECRET"], base_url=os.environ["INVO_BASE_URL"])

tok = invo_sdk.mint_player_token(
    player_email="ada@example.com",
    player_phone="+15555550100",
    player_name="Ada",
)
if tok.phone_mismatch:
    update_phone_then_remint()   # see Player Identity
player_token = tok.token

curl -sS -X POST "$BASE/api/transfers/initiate-transfer" \
  -H "X-Game-Secret-Key: $GAME_SECRET" -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "tfr-'"$(uuidgen)"'",
    "source_player_name": "Ada",
    "source_player_email": "ada@example.com",
    "source_player_phone": "+15555550100",
    "target_player_phone": "+15555550100",
    "target_player_email": "ada@example.com",
    "target_game_id": "123456789012",
    "amount": "50.00"
  }'

import { InvoServer } from "@invonetwork/web-sdk/server";
import { randomUUID } from "node:crypto";

const invoSdk = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET!, baseUrl: process.env.INVO_BASE_URL! });

const t = await invoSdk.initiateTransfer({
  clientRequestId: randomUUID(),
  sourcePlayerName: "Ada", sourcePlayerEmail: "ada@example.com", sourcePlayerPhone: "+15555550100",
  targetPlayerPhone: "+15555550100", targetPlayerEmail: "ada@example.com",
  targetGameId: 123456789012,
  amount: "50.00",
});
// t.transactionId · t.verificationExpiresAt
if (t.identityRekeyed && t.playerToken) playerToken = t.playerToken;   // see the box above

import os, uuid
from invonetwork import InvoServer

invo_sdk = InvoServer(game_secret=os.environ["INVO_GAME_SECRET"], base_url=os.environ["INVO_BASE_URL"])

t = invo_sdk.initiate_transfer(
    client_request_id=str(uuid.uuid4()),
    source_player_name="Ada", source_player_email="ada@example.com", source_player_phone="+15555550100",
    target_player_phone="+15555550100", target_player_email="ada@example.com",
    target_game_id=123456789012,
    amount="50.00",
)
# t.transaction_id · t.verification_expires_at
if t.identity_rekeyed and t.player_token:
    player_token = t.player_token   # see the box above

# begin
BEGIN=$(curl -sS -X POST "$BASE/api/sdk/approvals/device/begin" \
  -H "Authorization: Bearer $PLAYER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"transaction_id\":\"$TXN\",\"flow\":\"transfer\",\"channel\":\"qr\"}")
DEVICE_CODE=$(echo "$BEGIN" | jq -r .device_code)
INTERVAL=$(echo "$BEGIN" | jq -r .interval)
echo "$BEGIN" | jq -r '.verification_uri_complete, .user_code'   # render the first as a QR

# poll
while :; do
  P=$(curl -sS -X POST "$BASE/api/sdk/approvals/device/poll" \
    -H "Authorization: Bearer $PLAYER_TOKEN" -H "Content-Type: application/json" \
    -d "{\"device_code\":\"$DEVICE_CODE\"}")
  case "$(echo "$P" | jq -r '.status // .error')" in
    approved)              break ;;
    authorization_pending) sleep "$INTERVAL" ;;
    slow_down)             INTERVAL=$((INTERVAL + 5)); sleep "$INTERVAL" ;;
    *)                     echo "stopped: $P"; exit 1 ;;
  esac
done

# APPROVE, the step that moves money and issues the claim code.
curl -sS -X POST "$BASE/api/sdk/transfers/$TXN/approve" \
  -H "Authorization: Bearer $PLAYER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"device_code\":\"$DEVICE_CODE\"}" | jq '{status, next, claim_code, claim_code_expires_at}'

import { InvoServer } from "@invonetwork/web-sdk/server";

const invoSdk = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET!, baseUrl: process.env.INVO_BASE_URL! });

// 1. BEGIN is always yours: your game draws the QR between begin and the first poll.
const grant = await invoSdk.beginDeviceApproval({
  playerToken: playerToken,
  transactionId: txn,
  flow: "transfer",
  channel: "qr",
});
showQr(grant.verificationUriComplete, grant.userCode);

// 2 + 3. completeDeviceApproval polls AND calls approveWithDeviceCode when the poll
//        says approved. One call, so stopping at the poll is not possible. It blocks
//        for as long as the player takes: run it from a worker or a job, not from a
//        request handler with a short timeout.
//        RECORD THE ATTEMPT FIRST. If the process dies between the settle call and its
//        response, that record plus getTransferStatus is the only way to
//        learn whether the money moved.
await recordAttempt(txn, grant.deviceCode);

const outcome = await invoSdk.completeDeviceApproval({
  playerToken: playerToken,
  transactionId: txn,
  flow: "transfer",
  deviceCode: grant.deviceCode,
  interval: grant.interval,
  onEnrollment: (enrollment, respond) => {
    if (enrollment?.state === "awaiting_screen") {
      showPrompt(
        "Set up Invo on " + enrollment.deviceLabel + "? Code " + enrollment.matchCode,
        (ok) => respond(ok ? "approve" : "deny"),
      );
    } else {
      hidePrompt();
    }
  },
});

// outcome.status: "approved" | "denied" | "expired" | "aborted"
if (outcome.status !== "approved") return handleDeclineOrExpiry(outcome);

const settlement = outcome.settlement!;   // the money step has already run
// settlement.status "approved" + settlement.next "pending_claim" on success, and
//   settlement.claimCode / settlement.claimCodeExpiresAt: STORE BOTH.
// settlement.status "not_pending": the backend answered TRANSACTION_NOT_PENDING, and no
//   claim code is re-issued. settlement.alreadySettled true means an earlier attempt
//   landed; false does NOT mean "start again": read settlement.currentStatus first.
// settlement.holdReason: a 202 hold. The money is held, not refused.

// Use the three calls directly when your server cannot block. Keep deviceCode in your
// own store and poll from a scheduler.
const poll = await invoSdk.pollDeviceApproval({ playerToken: playerToken, deviceCode });
// poll.status: "approved" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied"
//   invalid_grant is THROWN as an InvoError, not returned.

if (poll.status === "authorization_pending" && poll.enrollment?.state === "awaiting_screen") {
  const ok = await askOnScreen(
    "Set up Invo on " + poll.enrollment.deviceLabel + "? Code " + poll.enrollment.matchCode);
  await invoSdk.confirmDeviceEnrollment({
    playerToken: playerToken, deviceCode, decision: ok ? "approve" : "deny",
  });
}

if (poll.status === "approved") {
  // THE MONEY STEP. Polling to "approved" and stopping here moves nothing.
  const settlement = await invoSdk.approveWithDeviceCode({
    playerToken: playerToken, transactionId: txn, flow: "transfer", deviceCode,
  });
}

const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));

const { json: grant } = await invo("POST", "/api/sdk/approvals/device/begin", asPlayer(playerToken), {
  transaction_id: txn, flow: "transfer", channel: "qr",
});
showQr(grant.verification_uri_complete, grant.user_code);

let interval = grant.interval;
for (;;) {
  const { json: p } = await invo("POST", "/api/sdk/approvals/device/poll", asPlayer(playerToken), {
    device_code: grant.device_code,
  });
  if (p.status === "approved") break;
  if (p.error === "authorization_pending") {
    if (p.enrollment?.state === "awaiting_screen") {
      const ok = await askOnScreen(`Set up Invo on ${p.enrollment.device_label}? Code ${p.enrollment.match_code}`);
      await invo("POST", "/api/sdk/approvals/device/confirm-enrollment", asPlayer(playerToken), {
        device_code: grant.device_code, decision: ok ? "approve" : "deny",
      });
    }
    await sleep(interval);
    continue;
  }
  if (p.error === "slow_down") { interval += 5; await sleep(interval); continue; }
  throw new Error(`device approval stopped: ${p.error}`);
}

// APPROVE, the poll proved WHO. This moves the money and returns the claim code.
const { status, json: approved } = await invo("POST", `/api/sdk/transfers/${txn}/approve`,
  asPlayer(playerToken), { device_code: grant.device_code });
// 200 -> { status: "approved", next: "pending_claim", claim_code, claim_code_expires_at }

import os
from invonetwork import InvoServer

invo_sdk = InvoServer(game_secret=os.environ["INVO_GAME_SECRET"], base_url=os.environ["INVO_BASE_URL"])

# 1. BEGIN is always yours: your game draws the QR between begin and the first poll.
grant = invo_sdk.begin_device_approval(
    player_token=player_token,
    transaction_id=txn,
    flow="transfer",
    channel="qr",
)
show_qr(grant.verification_uri_complete, grant.user_code)

# 2 + 3. complete_device_approval polls AND calls approve_with_device_code when the poll
#        says approved. One call, so stopping at the poll is not possible. It blocks for
#        as long as the player takes: run it from a worker, not a request handler.
#        RECORD THE ATTEMPT FIRST. If the process dies between the settle call and its
#        response, that record plus get_transfer_status is the only way to learn
#        whether the money moved.
record_attempt(txn, grant.device_code)

def on_enrollment(enrollment, respond):
    if enrollment and enrollment.state == "awaiting_screen":
        ok = ask_on_screen(
            f"Set up Invo on {enrollment.device_label}? Code {enrollment.match_code}")
        respond("approve" if ok else "deny")

outcome = invo_sdk.complete_device_approval(
    player_token=player_token,
    transaction_id=txn,
    flow="transfer",
    device_code=grant.device_code,
    interval=grant.interval,
    on_enrollment=on_enrollment,
)

# outcome.status: "approved" | "denied" | "expired" | "aborted"
if outcome.status != "approved":
    return handle_decline_or_expiry(outcome)

settlement = outcome.settlement   # the money step has already run
# settlement.status "approved" + settlement.next "pending_claim" on success, and
#   settlement.claim_code / settlement.claim_code_expires_at: STORE BOTH.
# settlement.status "not_pending": the backend answered TRANSACTION_NOT_PENDING, and no
#   claim code is re-issued. settlement.already_settled true means an earlier attempt
#   landed; false does NOT mean "start again": read settlement.current_status first.
# settlement.hold_reason: a 202 hold. The money is held, not refused.

# Use the three calls directly when your server cannot block.
poll = invo_sdk.poll_device_approval(player_token=player_token, device_code=device_code)
# poll.status: "approved" | "authorization_pending" | "slow_down" | "expired_token" | "access_denied"
#   invalid_grant is RAISED as an InvoError, not returned.

if poll.status == "authorization_pending" and poll.enrollment and poll.enrollment.state == "awaiting_screen":
    ok = ask_on_screen(
        f"Set up Invo on {poll.enrollment.device_label}? Code {poll.enrollment.match_code}")
    invo_sdk.confirm_device_enrollment(
        player_token=player_token, device_code=device_code,
        decision="approve" if ok else "deny",
    )

if poll.status == "approved":
    # THE MONEY STEP. Polling to "approved" and stopping here moves nothing.
    settlement = invo_sdk.approve_with_device_code(
        player_token=player_token, transaction_id=txn, flow="transfer",
        device_code=device_code,
    )

_, grant = invo("POST", "/api/sdk/approvals/device/begin", as_player(player_token),
                {"transaction_id": txn, "flow": "transfer", "channel": "qr"})
show_qr(grant["verification_uri_complete"], grant["user_code"])

interval = grant["interval"]
while True:
    _, p = invo("POST", "/api/sdk/approvals/device/poll", as_player(player_token),
                {"device_code": grant["device_code"]})
    if p.get("status") == "approved":
        break
    err = p.get("error")
    if err == "authorization_pending":
        enrol = p.get("enrollment")
        if enrol and enrol.get("state") == "awaiting_screen":
            ok = ask_on_screen(f"Set up Invo on {enrol['device_label']}? Code {enrol['match_code']}")
            invo("POST", "/api/sdk/approvals/device/confirm-enrollment", as_player(player_token),
                 {"device_code": grant["device_code"], "decision": "approve" if ok else "deny"})
        time.sleep(interval)
        continue
    if err == "slow_down":
        interval += 5
        time.sleep(interval)
        continue
    raise RuntimeError(f"device approval stopped: {err}")

# APPROVE, the poll proved WHO. This moves the money and returns the claim code.
status, approved = invo("POST", f"/api/sdk/transfers/{txn}/approve", as_player(player_token),
                        {"device_code": grant["device_code"]})
# 200 -> {"status": "approved", "next": "pending_claim", "claim_code": ..., "claim_code_expires_at": ...}

import { InvoClient } from "@invonetwork/web-sdk";

const client = new InvoClient({
  token: freshTokenFromYourServer,          // minted right before this click
  baseUrl,
  refreshToken: () => fetchNewTokenFromYourServer(),   // used once on SDK_TOKEN_EXPIRED
});

// FROM A CLICK HANDLER. The popup must open synchronously.
const result = await client.approveHosted({
  transactionId: txn,
  flow: "transfer",
  // renderPrompt: false + onEnrollment if you want to draw the match-code prompt yourself
  // popupBlocked: "resolve" (default) resolves "blocked" so you can retry from a button;
  //   "redirect" navigates THIS tab instead, and your page unloads.
});

// result.status: "approved" | "denied" | "expired" | "closed" | "blocked" | "redirected"
// "approved":   result.approval is the approve response. The money call already ran.
//               result.approval carries the claim code: store it.
// "closed":     the player closed the popup. Nothing moved; they can try again.
// "redirected": your page is gone; the device_approval.approved webhook and the status read are your signal.

try {
  await client.approveHosted({ transactionId: txn, flow: "transfer" });
} catch (err) {
  if (err.code === "PLAYER_TOKEN_STALE") {
    // The player's phone was added after this token was minted. Get a new token
    // from your server, build a new InvoClient with it, and let the player click again.
    showRetryButton(await fetchNewTokenFromYourServer());
  } else {
    throw err;
  }
}

async function approveWithFreshToken(txn, deviceCode, mint) {
  let token = await mint();                         // POST /api/sdk/player-token, phone included
  for (let attempt = 0; attempt < 2; attempt++) {
    const { status, json } = await invo("POST", `/api/sdk/transfers/${txn}/approve`,
      asPlayer(token), { device_code: deviceCode });
    const code = json.code ?? json.error_code ?? json.error;
    if (attempt === 0 && (code === "PLAYER_TOKEN_STALE" || code === "SDK_TOKEN_EXPIRED")) {
      token = await mint();                         // nothing moved; mint and retry once
      continue;
    }
    return { status, json };
  }
}

def approve_with_fresh_token(txn, device_code, mint):
    token = mint()                                  # POST /api/sdk/player-token, phone included
    for attempt in range(2):
        status, body = invo("POST", f"/api/sdk/transfers/{txn}/approve",
                            as_player(token), {"device_code": device_code})
        code = body.get("code") or body.get("error_code") or body.get("error")
        if attempt == 0 and code in ("PLAYER_TOKEN_STALE", "SDK_TOKEN_EXPIRED"):
            token = mint()                          # nothing moved; mint and retry once
            continue
        return status, body

const { status, json } = await invo("POST", `/api/sdk/transfers/${txn}/approve`,
  asPlayer(playerToken), { device_code: deviceCode });

// Some refusals carry "code", others "error_code", a few only "error".
// Read all three or you fall through on every guardian, risk and phone-share hold.
const code = json.code ?? json.error_code ?? json.error;

if (status === 200) {
  store(txn, json.claim_code, json.claim_code_expires_at);   // json.next === "pending_claim"
} else if (code === "TRANSACTION_NOT_PENDING") {
  // NOT an error. Already approved, read the status and reconcile.
  reconcile(txn, json.current_status);
} else if (code === "TRANSFER_APPROVE_FAILED") {
  // AMBIGUOUS: the money may already have moved. Never retry, never refund.
  reconcileThenReport(txn, json.error_ref);
} else {
  handleRefusal(status, json);
}

status, body = invo("POST", f"/api/sdk/transfers/{txn}/approve",
                    as_player(player_token), {"device_code": device_code})

# Some refusals carry "code", others "error_code", a few only "error".
# Read all three or you fall through on every guardian, risk and phone-share hold.
code = body.get("code") or body.get("error_code") or body.get("error")

if status == 200:
    store(txn, body["claim_code"], body["claim_code_expires_at"])
elif code == "TRANSACTION_NOT_PENDING":
    reconcile(txn, body["current_status"])          # already approved; not an error
elif code == "TRANSFER_APPROVE_FAILED":
    # AMBIGUOUS: the money may already have moved. Never retry, never refund.
    reconcile_then_report(txn, error_ref=body.get("error_ref"))
else:
    handle_refusal(status, body)

curl -sS "$BASE/api/transfers/$TXN/status" \
  -H "X-Game-Secret-Key: $GAME_SECRET" | jq '{transaction_status, verification_state, claim_code_expires_at}'

const { json: s } = await invo("GET", `/api/transfers/${txn}/status`, asGame);
// s.verification_state: "awaiting" | "approved" | "completed" | "expired" | "failed" | "unknown"

_, s = invo("GET", f"/api/transfers/{txn}/status", as_game)
# s["verification_state"]: "awaiting" | "approved" | "completed" | "expired" | "failed" | "unknown"

# the DESTINATION game mints the same player's token, over there
DEST_TOKEN=$(curl -sS -X POST "$BASE/api/sdk/player-token" \
  -H "X-Game-Secret-Key: $DEST_GAME_SECRET" -H "Content-Type: application/json" \
  -d '{"player_email":"ada@example.com","player_phone":"+15555550100","player_name":"Ada"}' | jq -r .token)

# begin a grant on the RECEIPT flow
curl -sS -X POST "$BASE/api/sdk/approvals/device/begin" \
  -H "Authorization: Bearer $DEST_TOKEN" -H "Content-Type: application/json" \
  -d "{\"transaction_id\":\"$TXN\",\"flow\":\"transfer_receipt\"}"

# ... show the QR, poll to "approved" exactly as in Stage 3a ...

# THE CALL THAT COLLECTS
curl -sS -X POST "$BASE/api/sdk/transfers/$TXN/confirm-receipt" \
  -H "Authorization: Bearer $DEST_TOKEN" -H "Content-Type: application/json" \
  -d "{\"device_code\":\"$DEVICE_CODE\"}"

const destSdk = new InvoServer({ gameSecret: process.env.DEST_GAME_SECRET!, baseUrl });

const tok = await destSdk.mintPlayerToken({
  playerEmail: "ada@example.com", playerPhone: "+15555550100", playerName: "Ada",
});

const { json: grant } = await invo("POST", "/api/sdk/approvals/device/begin", asPlayer(tok.token), {
  transaction_id: txn, flow: "transfer_receipt",       // note the flow
});
// ... show QR, poll to approved (identical loop to Stage 3a) ...

const { status, json } = await invo("POST", `/api/sdk/transfers/${txn}/confirm-receipt`,
  asPlayer(tok.token), { device_code: grant.device_code });
// 200 -> { status: "completed", amount_received: "45.00" }
// 409 receiver_not_enrolled_use_claim_code -> claim-transfer (the fallback below). The hosted
//     claim page does NOT serve transfers.

dest_sdk = InvoServer(game_secret=os.environ["DEST_GAME_SECRET"], base_url=BASE)

tok = dest_sdk.mint_player_token(player_email="ada@example.com", player_phone="+15555550100", player_name="Ada")

_, grant = invo("POST", "/api/sdk/approvals/device/begin", as_player(tok.token),
                {"transaction_id": txn, "flow": "transfer_receipt"})   # note the flow
# ... show QR, poll to approved (identical loop to Stage 3a) ...

status, body = invo("POST", f"/api/sdk/transfers/{txn}/confirm-receipt",
                    as_player(tok.token), {"device_code": grant["device_code"]})
# 200 -> {"status": "completed", "amount_received": "45.00"}
# 409 receiver_not_enrolled_use_claim_code -> claim-transfer (the fallback below). The hosted
#     claim page does NOT serve transfers.

const client = new InvoClient({ token: destinationToken, baseUrl });
await client.confirmReceiptTransfer(transactionId);   // challenge + passkey + confirm-receipt in one