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}"}

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": "155963559928",
    "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: 155963559928,
  amount: "50.00",
});
// t.transactionId · t.verificationExpiresAt

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=155963559928,
    amount="50.00",
)
# t.transaction_id · t.verification_expires_at

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"}' | jq -r .token)

const { token: playerToken } = await invoSdk.mintPlayerToken({ playerEmail: "ada@example.com" });

player_token = invo_sdk.mint_player_token(player_email="ada@example.com").token

# 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 the only place the claim code appears.
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: playerToken, baseUrl });

// challenge + passkey ceremony + approve, in one call
const approved = await client.approveTransfer(transactionId);
// approved.claimCode — hold on to it for Stage 6

// 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" | "blocked" | "redirected" | "aborted"
// On "approved", result carries the settle response: the money call already ran.
// On "redirected", your page is gone: the device_approval.approved webhook is your signal.

const optsRes = await fetch(`${BASE}/api/sdk/transfers/${txn}/approve/webauthn/begin`, {
  method: "POST", headers: { Authorization: `Bearer ${playerToken}` },
});
const options = await optsRes.json();
const credential = await navigator.credentials.get({ publicKey: decodeOptions(options) });

// THE CALL THAT MOVES MONEY
const res = await fetch(`${BASE}/api/sdk/transfers/${txn}/approve`, {
  method: "POST",
  headers: { Authorization: `Bearer ${playerToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ webauthn_assertion: encodeCredential(credential) }),
});
const approved = await res.json();   // approved.claim_code

// The challenge and credential ids travel as base64url strings; the WebAuthn API wants
// ArrayBuffers, and hands them back as ArrayBuffers. These two are the whole conversion.
const b64uToBuf = (s) =>
  Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)).buffer;

const bufToB64u = (b) =>
  btoa(String.fromCharCode(...new Uint8Array(b)))
    .replace(/+/g, "-").replace(///g, "_").replace(/=+$/, "");

function decodeOptions(options) {
  return {
    ...options,
    challenge: b64uToBuf(options.challenge),
    allowCredentials: (options.allowCredentials ?? []).map((c) => ({
      ...c, id: b64uToBuf(c.id),
    })),
  };
}

function encodeCredential(cred) {
  return {
    id: cred.id,
    rawId: bufToB64u(cred.rawId),
    type: cred.type,
    response: {
      clientDataJSON:    bufToB64u(cred.response.clientDataJSON),
      authenticatorData: bufToB64u(cred.response.authenticatorData),
      signature:         bufToB64u(cred.response.signature),
      userHandle: cred.response.userHandle ? bufToB64u(cred.response.userHandle) : null,
    },
  };
}

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); this one
} 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_info}'

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

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

# 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"}' | 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 dest = { "X-Game-Secret-Key": process.env.DEST_GAME_SECRET };

const { json: tok } = await invo("POST", "/api/sdk/player-token", dest, { player_email: "ada@example.com" });

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 = {"X-Game-Secret-Key": os.environ["DEST_GAME_SECRET"]}

_, tok = invo("POST", "/api/sdk/player-token", dest, {"player_email": "ada@example.com"})

_, 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