Initiate Player Currency Send

Node.js (server)

// Node (server). INVO_GAME_SECRET comes from your server's environment.
const res = await fetch('https://invo.network/api/currency-sends/initiate-send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Game-Secret-Key': process.env.INVO_GAME_SECRET,
  },
  body: JSON.stringify({
    client_request_id: crypto.randomUUID(),   // reuse the same id if you retry
    sender_player_name: 'PlayerOne',
    sender_player_email: 'player1@example.com',
    sender_player_phone: '+15555550111',
    receiver_player_email: 'recipient@example.com',   // optional, recommended
    receiver_player_phone: '+15555550122',
    receiving_game_id: 123456789012,
    amount: '500.00',
  }),
});
const data = await res.json();
// 201: data.transaction_id; the sender approves next (see Peer Send, stage by stage).

Python (server)

# Python (server)
import os, uuid, requests
r = requests.post(
    "https://invo.network/api/currency-sends/initiate-send",
    headers={"X-Game-Secret-Key": os.environ["INVO_GAME_SECRET"]},
    json={
        "client_request_id": str(uuid.uuid4()),
        "sender_player_name": "PlayerOne",
        "sender_player_email": "player1@example.com",
        "sender_player_phone": "+15555550111",
        "receiver_player_email": "recipient@example.com",
        "receiver_player_phone": "+15555550122",
        "receiving_game_id": 123456789012,
        "amount": "500.00",
    },
    timeout=15,
)
data = r.json()
# 201: data['transaction_id']; the sender approves next.

Success Response (201 Created)

{
  "status": "success",
  "message": "Currency send initiated. Approve on your enrolled device to continue.",
  "transaction_id": "TXN20260904121000123456ABC123",
  "order_id": "ORD_1757000000_A1B2C3D4",
  "new_balance": "9500.00",
  "currency_name": "Gold",
  "verification_method": "in_app",
  "verification_expires_at": "2026-01-01T12:10:00Z",
  "claim_delivery_planned": "email",
  "send_details": {
    "sending_game": "Adventure Quest",
    "receiving_game": "Space Warriors",
    "receiving_game_id": "987654321098",
    "currency": "Gold",
    "currency_id": 1,
    "amount_initiated": "500.00",
    "fees_preview": {
      "total_fee": "50.00",
      "source_rate_pct": "3.5",
      "target_rate_pct": "3.5",
      "sending_game_fee": "17.50",
      "receiving_game_fee": "17.50",
      "platform_fee": "15.00",
      "net_amount": "450.00"
    },
    "receiver_phone": "+1987654321",
    "send_type": "cross_game",
    "transfer_policy": {
      "source_universal_transfers": "yes",
      "policy_applied": "universal",
      "target_in_linked_list": null
    }
  },
  "verification_required": {
    "phone_number_masked": "******7890",
    "pin_expires_in_minutes": 10
  }
}

Top-level new_balance is the canonical post-write balance, the sender's available balance after the send amount has been reserved. Display this value rather than recomputing it client-side. fees_preview also includes source_rate_pct and target_rate_pct.

verification_method is 'in_app' | 'sms', and it tells you whether a legacy fallback message went out, not which factor you may use. 'in_app' means Invo saw an approval route for this sender and sent nothing; 'sms' is a legacy value; do not build on it. In both cases, approve with a passkey or a device approval grant and call POST /api/sdk/send/{id}/approve, both paths are live on the transaction regardless of this value. verification_expires_at is the end of the approval window. Full worked examples: Peer Send, stage by stage.

Pending Guardian Approval (202 Accepted)

{
  "status": "pending_guardian_approval",
  "transaction_id": "TXN20260904121000123456ABC123",
  "order_id": "ORD_1757000000_A1B2C3D4",
  "guardian_approval": {
    "approval_id": "1f2a8c0d-...",
    "state": "pending",
    "expires_at": "2026-05-04T22:15:00+00:00",
    "poll_endpoint": "/api/transactions/TXN20260904121000123456ABC123/approval-status"
  },
  "send_details": { /* same as 201 success */ },
  "verification_required": { /* same as 201 success */ }
}

Show a "waiting for parent approval" UI and poll poll_endpoint every 5 to 10s. See Guardian Approval for the full state machine.

Error Response - Phone-Share Approval Required (409 Conflict)

{
  "status": "error",
  "error_code": "PHONE_SHARE_APPROVAL_REQUIRED",
  "message": "This phone number is already linked to another Invo account. The existing phone owner must approve via SMS before this email can also use this phone.",
  "phone": "+15551234567",
  "requesting_email": "bob@example.com",
  "existing_account_hints": ["al***@example.com"],
  "next_endpoint": "/api/wallet/phone-share/initiate",
  "approval_id": "1f2a8c0d-...",
  "expires_at": "2026-05-04T22:25:00+00:00",
  "code_sent": true,
  "already_approved": false
}

Fires when the supplied phone is already on file with a different email. Same contract for developer SDK integrations and platform-tier partners. INVO delivers a one-time code to the existing phone owner before returning the 409. Have the owner enter it in your UI, then call POST /api/wallet/phone-share/approve with the approval_id from the body and the 6-digit OTP, then retry the original call. Only call /phone-share/initiate manually if code_sent: false. Match on error_code, not message text.

Initiate-time gate (since 2026-05-07): the gate now fires at /initiate-send as well as /claim-currency. Previously the conflict was only detected at claim time, after the sender had reserved funds and started approval. Now the 409 fires at initiate, before any Transaction, TransferPin, or OrderBook row is created. Net effect: zero side effects until the existing phone owner has approved.

If already_approved: true: auto-retry the original action immediately, do not show the OTP entry UI. The flag means a concurrent approval landed between gate-check and response, the pair is approved on the backend; the gate fired in a brief race window. The retry will succeed. One retry, no loops.

Anti-abuse fields (optional, present only when triggered): cooldown_seconds appears when a fresh OTP for the same (phone, email) was minted less than 30s ago, no new code is sent, the previous code on the user's phone is still valid, and the included approval_id is the same row. Show the OTP entry panel as normal; do not show "code not sent" copy and do not auto-call /phone-share/initiate until the cooldown elapses. rate_limited: true + retry_after_seconds appear when this phone has hit the platform-wide 40-OTP-per-hour cap, no code sent, no approval_id returned, surface "please wait before requesting another code."

Two response paths the existing phone owner can choose between:

• Approve via UI: type the 6-digit code into your UI → call POST /api/wallet/phone-share/approve with { approval_id, otp }.
• Reject (new, 2026-05-14): either call POST /api/wallet/phone-share/reject with { approval_id, otp } from your UI. Rejected rows are terminal, the requesting email must re-trigger a fresh request to retry. A subsequent /phone-share/initiate for the same pair creates a new approval row.

While your approval panel is open, poll GET /api/wallet/phone-share/status?phone=...&email=... every 3 to 5s. Auto-retry the original action when approved: true; surface a clear rejection message and offer a "try again" affordance on rejection (the status endpoint returns approved: false for both pending and rejected states, distinguishable only by the existence of a newer pending row after a fresh initiate).

Error Response - Policy Violation (403 Forbidden)

{
  "status": "error",
  "message": "Currency send not allowed: Receiving game 'Space Warriors' (ID: 987654321098) is not in the linked games list for sending game 'Adventure Quest'. Linked games: [123456789012, 456789012345]",
  "error_code": "CURRENCY_SEND_POLICY_VIOLATION"
}

Error Response - Title in Testing (403 Forbidden)

{
  "status": "error",
  "error_code": "TARGET_GAME_NOT_LIVE",
  "game_status": "testing",
  "message": "Currency sends require BOTH games to be live. The receiving game 'Test Game' is currently in testing and cannot receive currency until its owner switches it to Live in their developer console (Game Settings > Status)."
}

A sending title in Testing answers the same way with error_code: "SOURCE_GAME_NOT_LIVE". Match on error_code.

Error Response - Into a Platform Store Title from Outside It (409 Conflict)

{
  "status": "error",
  "error_code": "NON_STEAM_VALUE_INTO_STEAM_BLOCKED",
  "message": "This title only accepts currency from other Steam titles."
}

Fires when sending from a title outside a platform store into a title distributed through that store (a per-title setting INVO manages): currency from outside cannot enter. Currency bought through a platform store is subject to that store's rules: moving it to a title outside the store answers 409 STEAM_VALUE_NON_TRANSFERABLE, which you must handle too. Destination lists already leave out titles this would block, and most integrations never see it. Match on error_code, not message text.

Error Response - Rate Limited (429 Too Many Requests)

{
  "error": "velocity_limit_exceeded",
  "message": "Hourly currency send limit of 25 sends exceeded. Please try again later."
}

This 429 is a business limit (sends per player per hour, 25 by default), so its body carries error, not error_code: match on error: "velocity_limit_exceeded". A request rate limit answers a different 429 with error_code: "RATE_LIMITED". Honour Retry-After when it is present.