Claim Sent Currency

// This function MUST be called on your secure server, NOT the client.
public IEnumerator ClaimSentCurrency(string claimCode, string receiverName, 
    string receiverEmail, string receiverPhone, 
    Action<string> onSuccess, Action<string> onError)
{
    string url = "https://invo.network/api/currency-sends/claim-currency";
    
    var requestData = new {
        claim_code = claimCode,
        receiver_player_name = receiverName,
        receiver_player_email = receiverEmail,
        receiver_player_phone = receiverPhone
    };
    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", "receiving_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::ClaimSentCurrency(const FString& ClaimCode, 
    const FString& ReceiverName, const FString& ReceiverEmail, 
    const FString& ReceiverPhone)
{
    TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject);
    RequestObj->SetStringField("claim_code", ClaimCode);
    RequestObj->SetStringField("receiver_player_name", ReceiverName);
    RequestObj->SetStringField("receiver_player_email", ReceiverEmail);
    RequestObj->SetStringField("receiver_player_phone", ReceiverPhone);

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

# This function MUST be called on your secure server.
func claim_sent_currency(claim_code: String, receiver_name: String, 
    receiver_email: String, receiver_phone: String):
    
    var url = "https://invo.network/api/currency-sends/claim-currency"
    var headers = [
        "X-Game-Secret-Key: receiving_game_secret_key_here",
        "Content-Type: application/json"
    ]
    var body = {
        "claim_code": claim_code,
        "receiver_player_name": receiver_name,
        "receiver_player_email": receiver_email,
        "receiver_player_phone": receiver_phone
    }
    
    http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body))

{
  "status": "success",
  "message": "Currency send claimed successfully.",
  "transaction_id": "txn_send123abc456",
  "send_details": {
    "amount_received": "450.00",
    "sending_game": "Adventure Quest",
    "receiving_currency": "Gold",
    "receiver_player": "PlayerTwo",
    "new_balance": "1450.00"
  },
  "completion_time": "2024-06-24T15:30:00Z",
  "order_id": "ord_send789def012"
}

{
  "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 receiver_player_id set to the chosen account, or fix the receiver_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",
  "message": "Claim code is not valid: Claim code expired."
}

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

{
  "status": "error",
  "error_code": "WRONG_CLAIM_ENDPOINT",
  "message": "This claim code is for a self-transfer. Use POST /api/transfers/claim-transfer instead.",
  "expected_endpoint": "/api/transfers/claim-transfer",
  "expected_body_fields": [
    "claim_code",
    "target_player_name",
    "target_player_email",
    "target_player_phone",
    "target_currency_id"
  ]
}

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