Claim Cross-Game Transfer

// This function MUST be called on your secure server, NOT the client.
public IEnumerator ClaimTransfer(string claimCode, string playerName, 
    string playerEmail, string playerPhone, int targetCurrencyId,
    Action<string> onSuccess, Action<string> onError)
{
    string url = "https://invo.network/api/transfers/claim-transfer";
    
    var requestData = new {
        claim_code = claimCode,
        target_player_name = playerName,
        target_player_email = playerEmail,
        target_player_phone = playerPhone,
        target_currency_id = targetCurrencyId
    };
    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", "target_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::ClaimTransfer(const FString& ClaimCode, 
    const FString& PlayerName, const FString& PlayerEmail, 
    const FString& PlayerPhone, int32 TargetCurrencyId)
{
    TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject);
    RequestObj->SetStringField("claim_code", ClaimCode);
    RequestObj->SetStringField("target_player_name", PlayerName);
    RequestObj->SetStringField("target_player_email", PlayerEmail);
    RequestObj->SetStringField("target_player_phone", PlayerPhone);
    RequestObj->SetNumberField("target_currency_id", TargetCurrencyId);

    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/claim-transfer");
    Request->SetVerb("POST");
    Request->SetHeader("X-Game-Secret-Key", "target_game_secret_key_here");
    Request->SetHeader("Content-Type", "application/json");
    Request->SetContentAsString(RequestBody);
    
    Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnTransferClaimed);
    Request->ProcessRequest();
}

# This function MUST be called on your secure server.
func claim_transfer(claim_code: String, player_name: String, 
    player_email: String, player_phone: String, target_currency_id: int):
    
    var url = "https://invo.network/api/transfers/claim-transfer"
    var headers = [
        "X-Game-Secret-Key: target_game_secret_key_here",
        "Content-Type: application/json"
    ]
    var body = {
        "claim_code": claim_code,
        "target_player_name": player_name,
        "target_player_email": player_email,
        "target_player_phone": player_phone,
        "target_currency_id": target_currency_id
    }
    
    http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body))

{
  "status": "success",
  "message": "Transfer claimed successfully.",
  "transaction_id": "txn_abc123def456",
  "transfer_details": {
    "amount_received": "450.00",
    "source_game": "Adventure Quest",
    "target_currency": "Gold",
    "target_player": "PlayerTwo",
    "new_balance": "1450.00"
  },
  "completion_time": "2024-06-24T15:30:00Z",
  "order_id": "TFRO_1719235200_A1B2C3D4"
}

{
  "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": "needs_account_selection",
  "claim_code": "ABCDE-12345",
  "message": "Multiple accounts share this phone number on the destination game and the supplied email did not match any of them. Re-submit with target_player_id set to the chosen account, or fix the target_player_email.",
  "candidates": [
    { "player_id": 12345, "email_hint": "al***@example.com" },
    { "player_id": 67890, "email_hint": "bo***@example.com" }
  ]
}

{
  "status": "error",
  "message": "Invalid claim code.",
  "attempts_remaining": 4
}

{
  "status": "error",
  "error_code": "WRONG_CLAIM_ENDPOINT",
  "message": "This claim code is for a player-to-player currency send. Use POST /api/currency-sends/claim-currency instead.",
  "expected_endpoint": "/api/currency-sends/claim-currency",
  "expected_body_fields": [
    "claim_code",
    "receiver_player_name",
    "receiver_player_email",
    "receiver_player_phone"
  ]
}

{
  "status": "error",
  "message": "Claim code is not valid: Claim code expired."
}

{
  "status": "error",
  "message": "Invalid claim code or transfer not intended for this game."
}

{
  "status": "error",
  "message": "Phone number mismatch: This claim code can only be redeemed by the intended recipient's phone number."
}