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

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": "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 send = await invoSdk.initiateSend({
  clientRequestId: randomUUID(),
  senderPlayerName: "Ada", senderPlayerEmail: "ada@example.com", senderPlayerPhone: "+15555550100",
  receiverPlayerPhone: "+15555550111", receiverPlayerEmail: "bo@example.com",
  receivingGameId: 155963559928,
  amount: "50.00",
});
// send.transactionId · send.verificationExpiresAt
// send.guardianApproval is present on the 202 branch — see Stage 3c

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=155963559928,
    amount="50.00",
)
# send.transaction_id · send.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: senderToken } = await invoSdk.mintPlayerToken({ playerEmail: "ada@example.com" });

sender_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\":\"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 }

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

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

const client = new InvoClient({ token: senderToken, baseUrl });

// runs the challenge, the passkey ceremony AND the approve call in one step
const approved = await client.approveSend(transactionId);
// approved.status === "approved", approved.next === "pending_claim"

// 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" | "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.

// 1. transaction-bound challenge
const optsRes = await fetch(`${BASE}/api/sdk/send/${txn}/approve/webauthn/begin`, {
  method: "POST", headers: { Authorization: `Bearer ${senderToken}` },
});
const options = await optsRes.json();

// 2. the ceremony (decode the base64url fields per the WebAuthn spec first)
const credential = await navigator.credentials.get({ publicKey: decodeOptions(options) });

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

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

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

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

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

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

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

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

curl -sS -X POST "$BASE/api/sdk/send/$TXN/resend-claim" -H "Authorization: Bearer $PLAYER_TOKEN"

const { status, json } = await invo("POST", `/api/sdk/send/${txn}/resend-claim`, asPlayer(senderToken));
if (status === 429) waitThen(json.retry_after);

status, body = invo("POST", f"/api/sdk/send/{txn}/resend-claim", as_player(sender_token))
if status == 429:
    wait_then(body["retry_after"])