Guardian Approval

What is and isn't gated

The guardrail is on value movement off the account. Spending balance on items is treated as already authorized at deposit time.

Initiate response when guardian approval is needed

When a minor initiates a transfer or send, the standard /initiate-transfer or /initiate-send endpoint returns HTTP 202 Accepted instead of 200/201. The body includes all the standard fields plus a guardian_approval block:

{
  "status": "pending_guardian_approval",
  // Human-readable. Do not match on this string.
  "message": "Transfer initiated. Approve on your enrolled device to continue, but verification is held until the guardian on file approves it by email.",
  "transaction_id": "TXN_1715000000_ABC123",
  "guardian_approval": {
    "approval_id": "1f2a8c0d-...",
    "state": "pending",
    "expires_at": "2026-05-04T22:15:00+00:00",
    "consent_channel": "email",              // "email" (link sent) | "sms" (phone on file, no verified email)
    "poll_endpoint": "/api/transactions/TXN_1715000000_ABC123/approval-status",
    "resend_endpoint": "/api/sdk/approvals/guardian/1f2a8c0d-.../resend"
  },
  "transfer_details": { /* ...standard fields... */ },
  "verification_required": { /* ...standard fields... */ }
}

consent_channel tells you how the guardian was reached: email when the signed link went to their oldest verified address, or the literal value sms when there was no verified email (or the email could not be handed over) and the guardian was reached on the phone on file instead. Use it for your waiting copy (“we emailed your parent” vs “we contacted your parent”). resend_endpoint is a legacy field, see The resend endpoint. The same fields appear on the SDK send/transfer 202 bodies and on the wallet app's.

Poll the approval status

Response while pending

{
  "status": "ok",
  "approval": {
    "approval_id": "1f2a8c0d-...",
    "transaction_id": "TXN_1715000000_ABC123",
    "state": "pending",
    "expires_at": "2026-05-04T22:15:00+00:00",
    "decided_at": null,
    "decision_source": null,
    "consent_channel": "email",
    "action_description": "send 50 IPC from GameX to GameY"
  }
}

Terminal states

The state field transitions to one of:

• approved, guardian pressed Approve on the emailed page. The player can now approve as normal, with a passkey or a QR device approval, and your side calls the approve endpoint (POST /api/sdk/transfers/{id}/approve or POST /api/sdk/send/{id}/approve); the transaction then completes.
• rejected, guardian pressed Decline. Transaction is dead; show the user a clear message.
• expired, the short-lived approval window closed without a decision. Same as rejected from the user's perspective.

When you see a terminal state, stop polling. decided_at tells you when the decision landed; decision_source is email_link for a decision on the hosted page, sms_inbound (a legacy value) for a reply from the guardian's phone, and expiry_job for time-outs. consent_channel is the channel the request went out on.

Suggested partner UI flow

What the guardian sees

When the guardian has no verified email, or the email could not be delivered, the request reaches them on the phone on file instead, and consent_channel carries the legacy literal sms. The poll, the approval window and the terminal states are the same either way.

The resend endpoint (legacy)

guardian_approval.resend_endpoint points at POST /api/sdk/approvals/guardian/<approval_id>/resend, which re-sends the request to the phone on file. It is kept for integrations that already call it; do not build new UI on it. The emailed link is the path to design around. If you already call it: the only accepted body is the literal { "channel": "sms" }, it is allowed once per approval and only from the initiating minor's SDK player token, and its error codes are 400 INVALID_INPUT, 403 NOT_INITIATOR, 404 APPROVAL_NOT_FOUND, 409 CHANNEL_WAS_SMS (the request already went to the phone at creation), 409 ALREADY_RESENT, 410 APPROVAL_GONE and the retryable 503 DELIVERY_FAILED.

The short-lived approval window is unchanged by a resend, and the emailed link keeps working. The status poll and the terminal states are the same whichever channel the guardian answers on.

The same page for phone-share and recipient-identity consents

Two other consents go to the same hosted page by email. Neither changes your integration: the status codes, bodies and retry contracts you already handle are identical; only how the consenting person is reached changed, and a consent_channel field tells you which way it went.

On the page: opening the link decides nothing; unknown, expired and used links all read as “not valid”; a request already decided says so. The decision runs through the same server-side helpers as the in-app path, so money behaviour cannot differ by channel.

Edge cases worth handling

Testing in sandbox

Sandbox supports the same flow end-to-end. To test, contact your Invo onboarding rep to flag a test wallet as a minor with a guardian. Then:

1. Initiate a transfer or send from the minor's player. Confirm you receive the 202 response.
2. Watch the guardian's inbox for the email (consent_channel: "email") and press Approve on the page.
3. Keep polling. Within about 5 seconds the state should flip to approved.
4. Approve with a passkey or QR device approval and call the approve endpoint; the transfer completes.
5. Repeat and press Decline to verify your rejected-state UI.
6. Leave it undecided until the short-lived approval window closes to verify expiry.

HTTP status code reference

Implementation Examples

The 202 detection + polling loop runs on your secure backend, alongside your existing /initiate-transfer code. The sample below shows the full pattern in Node.js; the contract is the same in any server language. Never run it in a game client: it uses your title's secret key.

// On your secure server. Call this AFTER /initiate-transfer or /initiate-send returns.
// It returns the final approval state, or null if the response was 200/201 (no gate).
async function handleInitiateResponse(initiateResponse, transactionId) {
  // 200/201 → no guardian needed. Proceed with normal verify flow.
  if (initiateResponse.status !== 202) return null;

  const body = await initiateResponse.json();
  if (body.status !== 'pending_guardian_approval') return null;

  const expiresAt = new Date(body.guardian_approval.expires_at);
  const pollUrl = `https://invo.network${body.guardian_approval.poll_endpoint}`;

  while (Date.now() < expiresAt.getTime()) {
    await new Promise(r => setTimeout(r, 7000)); // 7s cadence (within 5-10s recommended)

    const statusRes = await fetch(pollUrl, {
      headers: { 'X-Game-Secret-Key': process.env.INVO_SDK_KEY },
    });
    const statusBody = await statusRes.json();
    const state = statusBody.approval?.state;

    if (state === 'approved')  return 'approved';
    if (state === 'rejected')  return 'rejected';
    if (state === 'expired')   return 'expired';
    // state === 'pending' → keep polling
  }

  return 'expired'; // safety net
}

// Wiring it into your transfer flow:
async function startTransfer(payload) {
  const initRes = await fetch('https://invo.network/api/transfers/initiate-transfer', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Game-Secret-Key': process.env.INVO_SDK_KEY,
    },
    body: JSON.stringify(payload),
  });

  const body = await initRes.json();
  const transactionId = body.transaction_id;

  // Notify your client immediately so it can show "waiting for parent" UI.
  if (initRes.status === 202) {
    notifyClient(transactionId, { phase: 'pending_guardian', expires_at: body.guardian_approval.expires_at });

    const finalState = await handleInitiateResponse(initRes, transactionId);
    if (finalState === 'rejected' || finalState === 'expired') {
      notifyClient(transactionId, { phase: 'guardian_terminal', state: finalState });
      return;
    }
    notifyClient(transactionId, { phase: 'guardian_approved' });
  }

  // Approved (or no gate) → the player approves with a passkey or QR device approval,
  // then call POST /api/sdk/transfers/{id}/approve as normal.
}

// POST /api/sdk/transfers/{id}/approve (or /api/sdk/send/{id}/approve) can return:
//   200 → approved, transfer proceeds
//   202 + GUARDIAN_APPROVAL_PENDING → guardian has not decided; call again once approved
//   410 + GUARDIAN_APPROVAL_REJECTED | GUARDIAN_APPROVAL_EXPIRED → terminal

if (approveRes.status === 200) {
  // success: show the collect state
} else if (approveRes.status === 202) {
  // guardian still pending: keep polling /approval-status
} else if (approveRes.status === 410) {
  // terminal: user must re-initiate with a fresh client_request_id
}