Initiate Cross-Game Transfer

// This function MUST be called on your secure server, NOT the client.
public IEnumerator InitiateTransfer(string clientRequestId, string playerName,
    string playerEmail, string playerPhone, string targetPlayerEmail, string targetPlayerPhone,
    int targetGameId, string amount,
    Action<string> onSuccess, Action<string> onError)
{
    string url = "https://invo.network/api/transfers/initiate-transfer";

    var requestData = new {
        client_request_id = clientRequestId,
        source_player_name = playerName,
        source_player_email = playerEmail,
        source_player_phone = playerPhone,
        target_player_email = targetPlayerEmail, // REQUIRED 2026-05-07: gates phone-share check at initiate
        target_player_phone = targetPlayerPhone, // SECURITY: Claim code can only be used by this phone
        target_game_id = targetGameId, // Must be different from your game ID
        amount = amount
    };
    string jsonBody = JsonUtility.ToJson(requestData);

    using (UnityWebRequest request = new UnityWebRequest(url, "POST"))
    {
        byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody);
        request.uploadHandler = new UploadHandlerRaw(bodyRaw);
        request.downloadHandler = new DownloadHandlerBuffer();
        
        request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here");
        request.SetRequestHeader("Content-Type", "application/json");

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)
        {
            onSuccess?.Invoke(request.downloadHandler.text);
        }
        else
        {
            onError?.Invoke(request.error + ": " + request.downloadHandler.text);
        }
    }
}

// This function MUST be called on your secure server.
void AYourGameMode::InitiateTransfer(const FString& ClientRequestId,
    const FString& PlayerName, const FString& PlayerEmail,
    const FString& PlayerPhone, const FString& TargetPlayerEmail,
    const FString& TargetPlayerPhone, int32 TargetGameId, const FString& Amount)
{
    TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject);
    RequestObj->SetStringField("client_request_id", ClientRequestId);
    RequestObj->SetStringField("source_player_name", PlayerName);
    RequestObj->SetStringField("source_player_email", PlayerEmail);
    RequestObj->SetStringField("source_player_phone", PlayerPhone);
    RequestObj->SetStringField("target_player_email", TargetPlayerEmail); // REQUIRED 2026-05-07: gates phone-share check at initiate
    RequestObj->SetStringField("target_player_phone", TargetPlayerPhone); // SECURITY: Claim code can only be used by this phone
    RequestObj->SetNumberField("target_game_id", TargetGameId);
    RequestObj->SetStringField("amount", Amount);

    FString RequestBody;
    TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody);
    FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer);

    TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest();
    Request->SetURL("https://invo.network/api/transfers/initiate-transfer");
    Request->SetVerb("POST");
    Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here");
    Request->SetHeader("Content-Type", "application/json");
    Request->SetContentAsString(RequestBody);

    Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnTransferInitiated);
    Request->ProcessRequest();
}

# This function MUST be called on your secure server.
func initiate_transfer(client_request_id: String, player_name: String,
    player_email: String, player_phone: String,
    target_player_email: String, target_player_phone: String,
    target_game_id: int, amount: String):

    var url = "https://invo.network/api/transfers/initiate-transfer"
    var headers = [
        "X-Game-Secret-Key: your_game_secret_key_here",
        "Content-Type: application/json"
    ]
    var body = {
        "client_request_id": client_request_id,
        "source_player_name": player_name,
        "source_player_email": player_email,
        "source_player_phone": player_phone,
        "target_player_email": target_player_email, # REQUIRED 2026-05-07: gates phone-share check at initiate
        "target_player_phone": target_player_phone, # SECURITY: Claim code can only be used by this phone
        "target_game_id": target_game_id, # Must be different from your game ID
        "amount": amount
    }

    http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body))

{
  "status": "success",
  "message": "Transfer initiated. Please verify with the SMS PIN sent to your phone.",
  "transaction_id": "txn_abc123def456",
  "order_id": "TFRO_1719235200_A1B2C3D4",
  "transfer_details": {
    "source_game": "Adventure Quest",
    "target_game": "Space Warriors",
    "target_game_id": "987654321098",
    "currency": "Gold",
    "currency_id": 1,
    "amount_initiated": "500.00",
    "fees_preview": {
      "total_fee": "50.00",
      "source_game_fee": "17.50",
      "target_game_fee": "17.50",
      "invo_fee": "15.00",
      "net_amount": "450.00"
    },
    "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
  }
}

{
  "status": "pending_guardian_approval",
  "message": "Transfer initiated. SMS PIN sent to your phone, but verification is held until the guardian on file approves via SMS.",
  "transaction_id": "txn_abc123def456",
  "order_id": "TFRO_1719235200_A1B2C3D4",
  "guardian_approval": {
    "approval_id": "1f2a8c0d-...",
    "state": "pending",
    "expires_at": "2026-05-04T22:15:00+00:00",
    "poll_endpoint": "/api/transactions/txn_abc123def456/approval-status"
  },
  "transfer_details": { /* same as 201 success */ },
  "verification_required": { /* same as 201 success */ }
}

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

{
  "status": "error",
  "message": "Self-transfers (same game) are not allowed through this endpoint. Use currency sends for peer-to-peer transactions within your game."
}

{
  "status": "error",
  "message": "Transfer not allowed: Target game 'Space Warriors' (ID: 987654321098) is not in the linked games list for source game 'Adventure Quest'. Linked games: [123456789012, 456789012345]",
  "error_code": "TRANSFER_POLICY_VIOLATION"
}

{
  "error": "velocity_limit_exceeded",
  "message": "Hourly transfer limit of 10 transfers exceeded. Please try again later."
}