feat(tools): add Mastercard Payment Integration Tool

[Samir-atra]

Resolves #4653

Summary

This PR adds a new Mastercard Payment Gateway Services (MPGS) integration tool to the Hive tools library. The tool enables Hive agents to securely handle payment orchestration, tokenization, and transaction management directly via the Mastercard Payment Gateway API.

Changes

New Files

• tools/src/aden_tools/tools/mastercard_tool/mastercard_tool.py - Main tool implementation with 8 MCP tools
• tools/src/aden_tools/tools/mastercard_tool/__init__.py - Module exports
• tools/src/aden_tools/tools/mastercard_tool/README.md - Comprehensive documentation
• tools/tests/test_mastercard_tool.py - Unit tests (22 tests, all passing)

Modified Files

• tools/src/aden_tools/tools/__init__.py - Added mastercard_tool registration
• tools/README.md - Added mastercard_* to available tools list

Available Tools

This integration provides 8 MCP tools for comprehensive payment operations:

Tool	Description
mastercard_create_token	Securely store card details and return a non-sensitive token
mastercard_authorize	Verify funds on a customer's card and place a hold on the amount
mastercard_pay	Execute a direct payment or capture a previously authorized transaction
mastercard_capture	Capture funds from a previously authorized transaction
mastercard_refund	Process full or partial refunds against a specific transaction
mastercard_retrieve_transaction	Fetch the current status and details of a payment or order
mastercard_verify_service	Validate cardholder authentication (3DS) eligibility
mastercard_void	Cancel a previously authorized transaction

Configuration

Environment variables required:

export MASTERCARD_MERCHANT_ID="your_merchant_id"
export MASTERCARD_API_PASSWORD="your_api_password"
export MASTERCARD_BASE_URL="https://test-gateway.mastercard.com"  # Optional

Testing

All 22 unit tests pass:

tests/test_mastercard_tool.py::TestMastercardClient::test_init PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_auth_tuple PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_api_url PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_create_token_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_authorize_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_pay_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_capture_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_refund_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_retrieve_transaction_order_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_retrieve_transaction_specific_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_verify_service_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_void_success PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_handle_response_401 PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_handle_response_404 PASSED
tests/test_mastercard_tool.py::TestMastercardClient::test_handle_response_429 PASSED
tests/test_mastercard_tool.py::TestMastercardToolRegistration::test_register_tools PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_no_credentials_error PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_create_token_validation PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_authorize_validation PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_refund_validation PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_timeout_handling PASSED
tests/test_mastercard_tool.py::TestMastercardToolValidation::test_network_error_handling PASSED

============================== 22 passed in 0.31s ==============================

Use Case

This enables agents to handle end-to-end e-commerce workflows, such as:

# 1. Create token for customer's card
token_result = mastercard_create_token(
    card_number="5123456789012346",
    card_expiry_month="12",
    card_expiry_year="2027"
)

# 2. Authorize payment for flight booking
auth_result = mastercard_authorize(
    order_id="flight-booking-001",
    amount="50000",
    currency="USD",
    token=token_result["token"],
    description="Flight to Paris"
)

# 3. Capture the payment
capture_result = mastercard_capture(
    order_id="flight-booking-001",
    transaction_id="2"
)

Reference Documentation

• Mastercard Integration Guidelines

[github-actions]

PR Closed - Requirements Not Met

This PR has been automatically closed because it doesn't meet the requirements.

PR Author: @Samir-atra
Found issues: #4653 (assignees: none)
Problem: The PR author must be assigned to the linked issue.

To fix:

1. Assign yourself (@Samir-atra) to one of the linked issues
2. Re-open this PR

Exception: To bypass this requirement, you can:

• Add the micro-fix label or include micro-fix in your PR title for trivial fixes
• Add the documentation label or include doc/docs in your PR title for documentation changes

Micro-fix requirements (must meet ALL):

Qualifies	Disqualifies
< 20 lines changed	Any functional bug fix
Typos & Documentation & Linting	Refactoring for "clean code"
No logic/API/DB changes	New features (even tiny ones)

Why is this required? See #472 for details.