Collecting, Stage by Stage

const BASE = process.env.INVO_BASE_URL;                    // https://invo.network  |  https://sandbox.invo.network/sandbox
const GAME_SECRET = process.env.INVO_RECEIVING_GAME_SECRET; // YOUR game — the receiving one. 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, requests

BASE = os.environ["INVO_BASE_URL"]                        # https://invo.network  |  https://sandbox.invo.network/sandbox
GAME_SECRET = os.environ["INVO_RECEIVING_GAME_SECRET"]    # YOUR game — the receiving one. 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 -G "$BASE/api/transfers/inbound-pending" \
  --data-urlencode "player_phone=+15555550111" \
  -H "X-Game-Secret-Key: $GAME_SECRET" | jq '.inbound_pending'

const q = new URLSearchParams({ player_phone: "+15555550111" });
const { json } = await invo("GET", `/api/transfers/inbound-pending?${q}`, asGame);
for (const row of json.inbound_pending) {
  // row.flow decides the endpoint later; row.claim_code_expires_at drives the countdown you show
  surfaceCollectPrompt(row);
}

from urllib.parse import urlencode

q = urlencode({"player_phone": "+15555550111"})
_, body = invo("GET", f"/api/transfers/inbound-pending?{q}", as_game)
for row in body["inbound_pending"]:
    # row["flow"] decides the endpoint later; row["claim_code_expires_at"] drives the countdown
    surface_collect_prompt(row)

# 1. your server mints the RECIPIENT's token, with YOUR game secret
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":"bo@example.com"}' | jq -r .token)

# 2. what is waiting for her
curl -sS "$BASE/api/sdk/transfers/pending" -H "Authorization: Bearer $PLAYER_TOKEN" \
  | jq '[.pending[] | select(.kind=="receiving_confirm")]'

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

const toCollect = json.pending.filter((i) => i.kind === "receiving_confirm");

for (const item of toCollect) {
  // THE ONE BRANCH THAT MATTERS. Do not assume the rail.
  const path = item.flow === "transfer"
    ? `/api/sdk/transfers/${item.transfer_id}/confirm-receipt`
    : `/api/sdk/send/${item.transfer_id}/confirm-receipt`;

  render({
    title: `${item.amount} ${item.currency} from ${item.counterparty_game}`,
    expiresAt: item.expires_at,
    disabled: item.held,
    disabledReason: item.hold_reason,
    onCollect: () => collect(path, item),      // Stage 3 + 4
  });
}

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

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

const { pending } = await client.getPendingCollect();
// Same list as GET /api/sdk/transfers/pending, camelCased:
//   item.transferId  (the backend key is transfer_id)
//   item.kind        "receiving_confirm" | "identity_gate"
//   item.flow        "send" | "transfer"      <- THE BRANCH
//   item.amount, item.currency, item.counterpartyGame
//   item.expiresAt, item.stepUpRequired, item.held, item.holdReason

for (const item of pending.filter((i) => i.kind === "receiving_confirm")) {
  // Branch on flow. kind does NOT tell you the rail.
  await (item.flow === "transfer"
    ? client.confirmReceiptTransfer(item.transferId)
    : client.confirmReceiptSend(item.transferId));
}

_, tok = invo("POST", "/api/sdk/player-token", as_game, {"player_email": "bo@example.com"})
_, body = invo("GET", "/api/sdk/transfers/pending", as_player(tok["token"]))

to_collect = [i for i in body["pending"] if i["kind"] == "receiving_confirm"]

for item in to_collect:
    # THE ONE BRANCH THAT MATTERS. Do not assume the rail.
    if item["flow"] == "transfer":
        path = f"/api/sdk/transfers/{item['transfer_id']}/confirm-receipt"
    else:
        path = f"/api/sdk/send/{item['transfer_id']}/confirm-receipt"

    render(
        title=f"{item['amount']} {item['currency']} from {item['counterparty_game']}",
        expires_at=item["expires_at"],
        disabled=item["held"],
        disabled_reason=item["hold_reason"],
        on_collect=lambda p=path, it=item: collect(p, it),   # Stage 3 + 4
    )

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

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

// challenge + passkey ceremony + confirm-receipt, in one call
await (item.flow === "transfer"
  ? client.confirmReceiptTransfer(item.transfer_id)
  : client.confirmReceiptSend(item.transfer_id));

// FROM A CLICK HANDLER. The popup must open synchronously.
const result = await client.approveHosted({
  transactionId: txn,
  flow: "send_receipt",
  // 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 rail = item.flow === "transfer" ? "transfers" : "send";

// 1. transaction-bound challenge
const optsRes = await fetch(`${BASE}/api/sdk/${rail}/${item.transfer_id}/confirm-receipt/webauthn/begin`, {
  method: "POST", headers: { Authorization: `Bearer ${recipientToken}` },
});
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 CREDITS
const res = await fetch(`${BASE}/api/sdk/${rail}/${item.transfer_id}/confirm-receipt`, {
  method: "POST",
  headers: { Authorization: `Bearer ${recipientToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ webauthn_assertion: encodeCredential(credential) }),
});
const done = await res.json();   // { status: "completed", amount_received: "45.00" }

// 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,
    },
  };
}

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_receipt\",\"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

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

# THE CALL THAT CREDITS. Do not stop at "approved" above.
curl -sS -X POST "$BASE/api/sdk/send/$TXN/confirm-receipt" \
  -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: recipientToken,
  transactionId: item.transferId,
  flow: "send_receipt",
  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(item.transferId, grant.deviceCode);

const outcome = await invoSdk.completeDeviceApproval({
  playerToken: recipientToken,
  transactionId: item.transferId,
  flow: "send_receipt",
  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 "completed" + settlement.amountReceived on success.
// settlement.status "not_pending": already collected, or the claim window closed.
//   settlement.alreadySettled true means it is already collected. false covers "not
//   there yet" too (the SENDER may not have approved), so read settlement.currentStatus.
// settlement.holdReason: a 202 hold (RECIPIENT_IDENTITY_PENDING, ...).

// 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: recipientToken, 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: recipientToken, 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: recipientToken, transactionId: item.transferId, flow: "send_receipt", deviceCode,
  });
}

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

const rail      = item.flow === "transfer" ? "transfers" : "send";
const grantFlow = item.flow === "transfer" ? "transfer_receipt" : "send_receipt";

const { json: grant } = await invo("POST", "/api/sdk/approvals/device/begin", asPlayer(recipientToken), {
  transaction_id: item.transfer_id, flow: grantFlow, 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(recipientToken), {
    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(recipientToken), {
        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}`);
}

// THE CALL THAT CREDITS
const { status, json: done } = await invo("POST",
  `/api/sdk/${rail}/${item.transfer_id}/confirm-receipt`,
  asPlayer(recipientToken), { device_code: grant.device_code });
// 200 -> { status: "completed", amount_received: "45.00" }

import os
from invonetwork import InvoServer

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

grant_flow = "transfer_receipt" if item["flow"] == "transfer" else "send_receipt"

# 1. BEGIN is always yours: your game draws the QR between begin and the first poll.
grant = invo_sdk.begin_device_approval(
    player_token=recipient_token,
    transaction_id=item["transfer_id"],
    flow=grant_flow,
    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, 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 the status endpoint is the only way to learn whether
#        the credit landed.
record_attempt(item["transfer_id"], 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=recipient_token,
    transaction_id=item["transfer_id"],
    flow=grant_flow,
    device_code=grant.device_code,
    interval=grant.interval,
    on_enrollment=on_enrollment,
)

if outcome.status != "approved":
    return handle_decline_or_expiry(outcome)

settlement = outcome.settlement   # the money step has already run
# settlement.status "completed" + settlement.amount_received on success.
# settlement.status "not_pending": already collected, or the claim window closed.
#   already_settled True means it is already collected. False ALSO covers "not there
#   yet" (the SENDER may not have approved), so read settlement.current_status.
# settlement.hold_reason: a 202 hold (RECIPIENT_IDENTITY_PENDING, ...).

rail       = "transfers" if item["flow"] == "transfer" else "send"
grant_flow = "transfer_receipt" if item["flow"] == "transfer" else "send_receipt"

_, grant = invo("POST", "/api/sdk/approvals/device/begin", as_player(recipient_token),
                {"transaction_id": item["transfer_id"], "flow": grant_flow, "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(recipient_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(recipient_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}")

# THE CALL THAT CREDITS
status, done = invo("POST", f"/api/sdk/{rail}/{item['transfer_id']}/confirm-receipt",
                    as_player(recipient_token), {"device_code": grant["device_code"]})
# 200 -> {"status": "completed", "amount_received": "45.00"}

async function collect(item, recipientToken, factorBody) {
  const rail = item.flow === "transfer" ? "transfers" : "send";
  const { status, json } = await invo("POST",
    `/api/sdk/${rail}/${item.transfer_id}/confirm-receipt`,
    asPlayer(recipientToken), factorBody);

  if (status === 200) return credited(json.amount_received);

  // Some refusals carry "code", others carry "error_code", a few only "error".
  // Check all three or you will fall through to default on the ones that matter.
  switch (json.code ?? json.error_code ?? json.error) {
    case "TRANSACTION_NOT_PENDING":
      // NOT an error. Already collected, or the window closed.
      return reconcile(item.transfer_id, json.current_status);
    case "receiver_not_enrolled_use_claim_code":
      // RAIL-SPECIFIC. The hosted claim page serves peer sends only.
      return item.flow === "transfer"
        ? offerClaimTransfer(item)              // claim-transfer, game secret
        : offerHostedClaimOrClaimCurrency(item); // hosted /claim page, or claim-currency
    case "PHONE_SHARE_APPROVAL_REQUIRED":
      return startConsentFlow(json);              // retry after consent
    case "RECIPIENT_IDENTITY_PENDING":
      return tellPlayerToConfirmThenRetry();
    case "CONFIRM_RECEIPT_FAILED":
      return logForSupport({ txn: item.transfer_id, errorRef: json.error_ref });  // never retry
    default:
      return handleRefusal(status, json);
  }
}

def collect(item, recipient_token, factor_body):
    rail = "transfers" if item["flow"] == "transfer" else "send"
    status, body = invo("POST", f"/api/sdk/{rail}/{item['transfer_id']}/confirm-receipt",
                        as_player(recipient_token), factor_body)

    if status == 200:
        return credited(body["amount_received"])

    # Some refusals carry "code", others "error_code", a few only "error".
    # Check all three or you will fall through on the ones that matter.
    code = body.get("code") or body.get("error_code") or body.get("error")
    if code == "TRANSACTION_NOT_PENDING":
        return reconcile(item["transfer_id"], body["current_status"])   # not an error
    if code == "receiver_not_enrolled_use_claim_code":
        # RAIL-SPECIFIC. The hosted claim page serves peer sends only.
        if item["flow"] == "transfer":
            return offer_claim_transfer(item)            # claim-transfer, game secret
        return offer_hosted_claim_or_claim_currency(item)  # hosted /claim page, or claim-currency
    if code == "PHONE_SHARE_APPROVAL_REQUIRED":
        return start_consent_flow(body)                                 # retry after consent
    if code == "RECIPIENT_IDENTITY_PENDING":
        return tell_player_to_confirm_then_retry()
    if code == "CONFIRM_RECEIPT_FAILED":
        return log_for_support(txn=item["transfer_id"], error_ref=body.get("error_ref"))  # never retry
    return handle_refusal(status, body)

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

const rail = item.flow === "transfer" ? "transfers" : "currency-sends";
const { json: s } = await invo("GET", `/api/${rail}/${item.transfer_id}/status`, asGame);
// s.transaction_status === "completed"

rail = "transfers" if item["flow"] == "transfer" else "currency-sends"
_, s = invo("GET", f"/api/{rail}/{item['transfer_id']}/status", as_game)
# s["transaction_status"] == "completed"