Peer Send, 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 senderToken = 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
sender_token = tok.token

curl -sS -X POST "$BASE/api/currency-sends/initiate-send" \
  -H "X-Game-Secret-Key: $GAME_SECRET" -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "send-'"$(uuidgen)"'",
    "sender_player_name": "Ada",
    "sender_player_email": "ada@example.com",
    "sender_player_phone": "+15555550100",
    "receiver_player_phone": "+15555550111",
    "receiver_player_email": "bo@example.com",
    "receiving_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 send = await invoSdk.initiateSend({
  clientRequestId: randomUUID(),
  senderPlayerName: "Ada", senderPlayerEmail: "ada@example.com", senderPlayerPhone: "+15555550100",
  receiverPlayerPhone: "+15555550111", receiverPlayerEmail: "bo@example.com",
  receivingGameId: 123456789012,
  amount: "50.00",
});
// send.transactionId · send.verificationExpiresAt
// send.guardianApproval is present on the 202 branch, see Stage 3c
if (send.identityRekeyed && send.playerToken) senderToken = send.playerToken;   // see the box above
// send.claimDeliveryPlanned: how the claim link or code will reach the recipient

import os, uuid
from invonetwork import InvoServer

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

send = invo_sdk.initiate_send(
    client_request_id=str(uuid.uuid4()),
    sender_player_name="Ada", sender_player_email="ada@example.com", sender_player_phone="+15555550100",
    receiver_player_phone="+15555550111", receiver_player_email="bo@example.com",
    receiving_game_id=123456789012,
    amount="50.00",
)
# send.transaction_id · send.verification_expires_at
if send.identity_rekeyed and send.player_token:
    sender_token = send.player_token   # see the box above
# send.claim_delivery_planned: how the claim link or code will reach the recipient

# 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\":\"send\",\"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. Do not stop at "approved" above.
curl -sS -X POST "$BASE/api/sdk/send/$TXN/approve" \
  -H "Authorization: Bearer $PLAYER_TOKEN" -H "Content-Type: application/json" \
  -d "{\"device_code\":\"$DEVICE_CODE\"}"

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: senderToken,
  transactionId: txn,
  flow: "send",
  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 getSendStatus is the only way to
//        learn whether the money moved.
await recordAttempt(txn, grant.deviceCode);

const outcome = await invoSdk.completeDeviceApproval({
  playerToken: senderToken,
  transactionId: txn,
  flow: "send",
  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.
// settlement.status "not_pending": the backend answered TRANSACTION_NOT_PENDING.
//   settlement.alreadySettled true  -> an earlier attempt already landed. Safe.
//   settlement.alreadySettled false -> DOES NOT mean "start again". Read
//   settlement.currentStatus, or fetch the transaction, before telling the player anything.
// settlement.holdReason: a 202 hold (GUARDIAN_APPROVAL_PENDING, RISK_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: senderToken, 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: senderToken, 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: senderToken, transactionId: txn, flow: "send", deviceCode,
  });
}

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

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

// poll
let interval = grant.interval;
for (;;) {
  const { json: p } = await invo("POST", "/api/sdk/approvals/device/poll", asPlayer(senderToken), {
    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(senderToken), {
        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}`);   // expired_token | access_denied | invalid_grant
}

// APPROVE, the poll proved WHO. This is what moves the money.
const { status, json: approved } = await invo("POST", `/api/sdk/send/${txn}/approve`,
  asPlayer(senderToken), { device_code: grant.device_code });
// 200 -> { status: "approved", next: "pending_claim", transaction_id, claim_delivery }

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=sender_token,
    transaction_id=txn,
    flow="send",
    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_send_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=sender_token,
    transaction_id=txn,
    flow="send",
    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.
# settlement.status "not_pending": the backend answered TRANSACTION_NOT_PENDING.
#   settlement.already_settled true  -> an earlier attempt already landed. Safe.
#   settlement.already_settled false -> DOES NOT mean "start again". Read
#   settlement.current_status, or fetch the transaction, before telling the player anything.
# settlement.hold_reason: a 202 hold (GUARDIAN_APPROVAL_PENDING, RISK_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=sender_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=sender_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=sender_token, transaction_id=txn, flow="send",
        device_code=device_code,
    )

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

# poll
interval = grant["interval"]
while True:
    _, p = invo("POST", "/api/sdk/approvals/device/poll", as_player(sender_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(sender_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}")   # expired_token | access_denied | invalid_grant

# APPROVE, the poll proved WHO. This is what moves the money.
status, approved = invo("POST", f"/api/sdk/send/{txn}/approve", as_player(sender_token),
                        {"device_code": grant["device_code"]})
# 200 -> {"status": "approved", "next": "pending_claim", "transaction_id": ..., "claim_delivery": ...}

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: "send",
  // 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.status "approved", next "pending_claim".
// "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: "send" });
} 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/send/${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/send/{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/send/${txn}/approve`,
  asPlayer(senderToken), { 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) {
  markApproved(txn);                       // json.next === "pending_claim"
} else if (code === "TRANSACTION_NOT_PENDING") {
  // NOT an error. Someone (probably you) already approved it.
  reconcile(txn, json.current_status);     // e.g. "pending_claim" or "completed"
} else if (code === "SEND_APPROVE_FAILED") {
  // AMBIGUOUS: the money may already have moved. Never retry, never refund,
  // never re-initiate. Read the status first, then raise the error_ref.
  reconcileThenReport(txn, json.error_ref);
} else {
  handleRefusal(status, json);
}

status, body = invo("POST", f"/api/sdk/send/{txn}/approve",
                    as_player(sender_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:
    mark_approved(txn)                          # body["next"] == "pending_claim"
elif code == "TRANSACTION_NOT_PENDING":
    # NOT an error. Already approved: read the status and move on.
    reconcile(txn, body["current_status"])
elif code == "SEND_APPROVE_FAILED":
    # AMBIGUOUS: the money may already have moved. Never retry, never refund,
    # never re-initiate. Read the status first, then raise the error_ref.
    reconcile_then_report(txn, error_ref=body.get("error_ref"))
else:
    handle_refusal(status, body)

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

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

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

# the RECEIVING game mints the RECIPIENT's token
RECIPIENT_TOKEN=$(curl -sS -X POST "$BASE/api/sdk/player-token" \
  -H "X-Game-Secret-Key: $RECEIVING_GAME_SECRET" -H "Content-Type: application/json" \
  -d '{"player_email":"bo@example.com","player_phone":"+15555550111","player_name":"Bo"}' | jq -r .token)

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

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

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

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

const tok = await receivingSdk.mintPlayerToken({
  playerEmail: "bo@example.com", playerPhone: "+15555550111", playerName: "Bo",
});

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

const { status, json } = await invo("POST", `/api/sdk/send/${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 -> hosted claim page (6c), or the claim-code fallback

receiving_sdk = InvoServer(game_secret=os.environ["RECEIVING_GAME_SECRET"], base_url=BASE)

tok = receiving_sdk.mint_player_token(player_email="bo@example.com", player_phone="+15555550111", player_name="Bo")

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

status, body = invo("POST", f"/api/sdk/send/{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 -> hosted claim page (6c), or the claim-code fallback

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