Initiate Player Currency Send

// This function MUST be called on your secure server, NOT the client.
public IEnumerator InitiateCurrencySend(string clientRequestId, string senderName,
    string senderEmail, string senderPhone, string receiverEmail, string receiverPhone,
    int receivingGameId, string amount, Action<string> onSuccess, Action<string> onError)
{
    string url = "https://invo.network/api/currency-sends/initiate-send";

    var requestData = new {
        client_request_id = clientRequestId,
        sender_player_name = senderName,
        sender_player_email = senderEmail,
        sender_player_phone = senderPhone,
        receiver_player_email = receiverEmail, // REQUIRED 2026-05-07: gates phone-share check at initiate
        receiver_player_phone = receiverPhone,
        receiving_game_id = receivingGameId, // Same as your game ID for peer-to-peer
        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::InitiateCurrencySend(const FString& ClientRequestId,
    const FString& SenderName, const FString& SenderEmail,
    const FString& SenderPhone, const FString& ReceiverEmail,
    const FString& ReceiverPhone, int32 ReceivingGameId, const FString& Amount)
{
    TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject);
    RequestObj->SetStringField("client_request_id", ClientRequestId);
    RequestObj->SetStringField("sender_player_name", SenderName);
    RequestObj->SetStringField("sender_player_email", SenderEmail);
    RequestObj->SetStringField("sender_player_phone", SenderPhone);
    RequestObj->SetStringField("receiver_player_email", ReceiverEmail); // REQUIRED 2026-05-07: gates phone-share check at initiate
    RequestObj->SetStringField("receiver_player_phone", ReceiverPhone);
    RequestObj->SetNumberField("receiving_game_id", ReceivingGameId);
    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/currency-sends/initiate-send");
    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::OnSendInitiated);
    Request->ProcessRequest();
}

# This function MUST be called on your secure server.
func initiate_currency_send(client_request_id: String, sender_name: String,
    sender_email: String, sender_phone: String,
    receiver_email: String, receiver_phone: String,
    receiving_game_id: int, amount: String):

    var url = "https://invo.network/api/currency-sends/initiate-send"
    var headers = [
        "X-Game-Secret-Key: your_game_secret_key_here",
        "Content-Type: application/json"
    ]
    var body = {
        "client_request_id": client_request_id,
        "sender_player_name": sender_name,
        "sender_player_email": sender_email,
        "sender_player_phone": sender_phone,
        "receiver_player_email": receiver_email, # REQUIRED 2026-05-07: gates phone-share check at initiate
        "receiver_player_phone": receiver_phone,
        "receiving_game_id": receiving_game_id, # Same as your game ID for peer-to-peer
        "amount": amount
    }
    
    http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body))

{
  "status": "success",
  "message": "Currency send initiated. Please verify with the SMS PIN sent to your phone.",
  "transaction_id": "txn_send123abc456",
  "order_id": "ord_send789def012",
  "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",
      "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
  }
}

{
  "status": "pending_guardian_approval",
  "message": "Currency send initiated. SMS PIN sent to your phone, but verification is held until the guardian on file approves via SMS.",
  "transaction_id": "txn_send123abc456",
  "order_id": "ord_send789def012",
  "guardian_approval": {
    "approval_id": "1f2a8c0d-...",
    "state": "pending",
    "expires_at": "2026-05-04T22:15:00+00:00",
    "poll_endpoint": "/api/transactions/txn_send123abc456/approval-status"
  },
  "send_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": "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"
}

{
  "status": "error",
  "message": "Currency sends are not allowed to games in testing status. Receiving game 'Test Game' must be live to receive currency sends."
}

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