### Install GlobalPayments.Api

Source: https://github.com/globalpayments/python-sdk/blob/master/README.txt

Use this command to install the Global Payments Python SDK via pip.

```bash
python pip install GlobalPayments.Api
```

--------------------------------

### Install Global Payments Python SDK

Source: https://github.com/globalpayments/python-sdk/blob/master/README.md

Install the SDK using pip. Ensure you have Python 3.10+ and OpenSSL 1.0.1+.

```bash
pip install GlobalPayments.Api
```

--------------------------------

### Charge with Shipping and Billing Address

Source: https://context7.com/globalpayments/python-sdk/llms.txt

This example demonstrates how to attach both billing and shipping addresses to a credit card charge. Ensure the Address and CreditCardData objects are properly instantiated and populated.

```python
shipping = Address()
shipping.street_address_1 = "1 Infinite Loop"
shipping.city = "Cupertino"
shipping.state = "CA"
shipping.postal_code = "95014"
shipping.country_code = "US"       # auto-resolves to country = "United States of America"

# Attach both to a charge
card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"

response = (
    card.charge(49.99)
    .with_currency("USD")
    .with_address(billing, AddressType.Billing)
    .with_address(shipping, AddressType.Shipping)
    .execute()
)
print(f"AVS Response: {response.avs_response_code}")
print(f"AVS Message: {response.avs_response_message}")
```

--------------------------------

### Transaction Management - Capture, Void, Refund, Edit

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Manages post-transaction operations such as capture, void, refund, and editing gratuity. This example demonstrates authorizing a transaction and then performing subsequent management operations.

```APIDOC
## Transaction Management — Capture, Void, Refund, Edit

After a successful authorization, use the returned `Transaction` object's management methods to capture, void, refund, or edit tip/gratuity. The `ManagementBuilder` handles all post-transaction operations.

```python
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities import Transaction
from globalpayments.api.entities.exceptions import GatewayException

card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"
card.cvn = "131"

try:
    # Step 1: Authorize (hold funds)
    auth_txn = (
        card.authorize(100.00)
        .with_currency("USD")
        .execute()
    )
    print(f"Auth ID: {auth_txn.transaction_reference.transaction_id}")

    # Step 2: Capture (settle)
    captured = auth_txn.capture(100.00).execute()
    print(f"Captured: {captured.response_code}")

    # Edit gratuity on a captured transaction
    edited = auth_txn.edit().with_gratuity(15.00).execute()

    # Void an unsettled transaction
    voided = auth_txn.void().execute()

    # Refund from transaction reference (partial refund)
    refunded = auth_txn.refund(25.00).with_currency("USD").execute()

    # Reverse an authorization
    reversed_txn = auth_txn.reverse(100.00).execute()

    # Hold / Release (for fraud review)
    held = auth_txn.hold().with_reason_code("FRAUD").execute()
    released = auth_txn.release().execute()

except GatewayException as e:
    print(f"Management error [{e.response_code}]: {e.response_message}")
```
```

--------------------------------

### Process a Payment with Credit Card Data

Source: https://github.com/globalpayments/python-sdk/blob/master/README.md

Example of processing a payment using credit card details. Requires `CreditCardData` object and handles potential API exceptions.

```python
card = CreditCardData()
card.number = '4111111111111111'
card.exp_month = '12'
card.exp_year = '2025'
card.cvn = '123'
card.card_holder_name = 'Joe Smith'

try:
    response = card.charge(129.99)
        .with_currency("EUR")
        .execute()

    result = response.response_code  # 00 == Success
    message = response.response_message  # [ test system ] AUTHORISED

except ApiException as e:
    // handle
    errors
```

--------------------------------

### Configure Realex (Global Iris) Gateway

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configure the SDK for the Realex gateway using merchant ID, shared secret, account ID, channel, and service URL. This setup is for integrations with Global Iris.

```python
# --- Realex (Global Iris) configuration ---
realex_config = PorticoConfig()
realex_config.merchant_id = "your_merchant_id"
realex_config.shared_secret = "your_shared_secret"
realex_config.account_id = "internet"
realex_config.channel = "ECOM"
realex_config.service_url = "https://pay.sandbox.realexpayments.com/epage-remote.cgi"

ServicesContainer.configure(realex_config, "realex")
```

--------------------------------

### Manage Gift Card Lifecycle Operations

Source: https://context7.com/globalpayments/python-sdk/llms.txt

The GiftCard class handles various gift and loyalty card operations including activation, balance inquiry, reload, charge, deactivate, replacement, and alias management. This example shows a sequence of these operations.

```python
from globalpayments.api.payment_methods import GiftCard
from globalpayments.api.entities.exceptions import ApiException

# Use existing gift card by card number
gift = GiftCard()
gift.number = "5022440000000000098"

try:
    # Activate a new gift card with initial value
    activate_response = gift.activate(100.00).with_currency("USD").execute()
    print(f"Activated: {activate_response.response_code}")

    # Check balance
    balance_response = gift.balance_inquiry().execute()
    print(f"Balance: {balance_response.balance_amount}")

    # Charge (redeem value)
    charge_response = gift.charge(25.00).with_currency("USD").execute()
    print(f"Charge Response: {charge_response.response_code}")

    # Add value (reload)
    reload_response = gift.add_value(50.00).with_currency("USD").execute()

    # Reverse a gift card transaction
    reverse_response = gift.reverse(25.00).with_currency("USD").execute()

    # Create a new gift card with alias
    new_card = GiftCard.create("alias1234")
    print(f"New Card Number: {new_card.number}")

    # Replace one card with another
    replacement = GiftCard()
    replacement.number = "5022440000000000007"
    replace_response = gift.replace_with(replacement).execute()

    # Deactivate
    deactivate_response = gift.deactivate().execute()

except ApiException as e:
    print(f"Gift card error: {str(e)}")
```

--------------------------------

### GiftCard - Gift & Loyalty Card Operations

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Supports the gift card lifecycle, including activation, balance inquiry, reload, charge, deactivation, replacement, and alias management. This example shows how to perform various operations on a gift card.

```APIDOC
## GiftCard — Gift & Loyalty Card Operations

`GiftCard` supports gift card lifecycle: activation, balance inquiry, reload, charge, deactivate, replacement, and alias management.

```python
from globalpayments.api.payment_methods import GiftCard
from globalpayments.api.entities.exceptions import ApiException

# Use existing gift card by card number
gift = GiftCard()
gift.number = "5022440000000000098"

try:
    # Activate a new gift card with initial value
    activate_response = gift.activate(100.00).with_currency("USD").execute()
    print(f"Activated: {activate_response.response_code}")

    # Check balance
    balance_response = gift.balance_inquiry().execute()
    print(f"Balance: {balance_response.balance_amount}")

    # Charge (redeem value)
    charge_response = gift.charge(25.00).with_currency("USD").execute()
    print(f"Charge Response: {charge_response.response_code}")

    # Add value (reload)
    reload_response = gift.add_value(50.00).with_currency("USD").execute()

    # Reverse a gift card transaction
    reverse_response = gift.reverse(25.00).with_currency("USD").execute()

    # Create a new gift card with alias
    new_card = GiftCard.create("alias1234")
    print(f"New Card Number: {new_card.number}")

    # Replace one card with another
    replacement = GiftCard()
    replacement.number = "5022440000000000007"
    replace_response = gift.replace_with(replacement).execute()

    # Deactivate
    deactivate_response = gift.deactivate().execute()

except ApiException as e:
    print(f"Gift card error: {str(e)}")
```
```

--------------------------------

### ECheck - ACH / eCheck Payments

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Processes ACH bank account payments (checking or savings) using PPD, CCD, and WEB SEC codes. This example demonstrates how to initialize an ECheck object, set payment details, and execute a charge.

```APIDOC
## ECheck — ACH / eCheck Payments

`ECheck` processes ACH bank account payments (checking or savings), supporting PPD, CCD, and WEB SEC codes.

```python
from globalpayments.api.payment_methods import ECheck
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import AccountType, CheckType, SecCode
from globalpayments.api.entities.exceptions import ApiException

check = ECheck()
check.account_number = "24413815"
check.routing_number = "490000018"
check.account_type = AccountType.Checking
check.check_type = CheckType.Personal
check.sec_code = SecCode.PPD
check.check_holder_name = "John Doe"
check.check_number = "1234"
check.phone_number = "8003214567"
check.check_verify = True
check.ach_verify = True

billing_address = Address()
billing_address.street_address_1 = "6860 Dallas Pkwy"
billing_address.city = "Plano"
billing_address.state = "TX"
billing_address.postal_code = "75024"

try:
    response = (
        check.charge(11.00)
        .with_currency("USD")
        .with_address(billing_address)
        .with_allow_duplicates(True)
        .execute()
    )
    print(f"Response Code: {response.response_code}")  # "00"
    print(f"Transaction ID: {response.transaction_reference.transaction_id}")

except ApiException as e:
    print(f"ACH error: {str(e)}")
```
```

--------------------------------

### Process ACH/eCheck Payments with ECheck

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Use the ECheck class to process ACH bank account payments. Ensure all required fields like account and routing numbers, account type, and SEC code are provided. This example demonstrates setting up an ECheck object and executing a charge.

```python
from globalpayments.api.payment_methods import ECheck
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import AccountType, CheckType, SecCode
from globalpayments.api.entities.exceptions import ApiException

check = ECheck()
check.account_number = "24413815"
check.routing_number = "490000018"
check.account_type = AccountType.Checking
check.check_type = CheckType.Personal
check.sec_code = SecCode.PPD
check.check_holder_name = "John Doe"
check.check_number = "1234"
check.phone_number = "8003214567"
check.check_verify = True
check.ach_verify = True

billing_address = Address()
billing_address.street_address_1 = "6860 Dallas Pkwy"
billing_address.city = "Plano"
billing_address.state = "TX"
billing_address.postal_code = "75024"

try:
    response = (
        check.charge(11.00)
        .with_currency("USD")
        .with_address(billing_address)
        .with_allow_duplicates(True)
        .execute()
    )
    print(f"Response Code: {response.response_code}")  # "00"
    print(f"Transaction ID: {response.transaction_reference.transaction_id}")

except ApiException as e:
    print(f"ACH error: {str(e)}")
```

--------------------------------

### Store Payment Method and Set Up Recurring Schedule

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Demonstrates creating a customer, storing a credit card as a payment method, charging against it, and setting up a recurring schedule using RecurringPaymentMethod. Requires handling ApiException.

```python
from globalpayments.api.entities import Customer, RecurringPaymentMethod, Schedule, Address
from globalpayments.api.entities.enums import SecCode, AccountType, CheckType
from globalpayments.api.payment_methods import CreditCardData, ECheck
from globalpayments.api.entities.exceptions import ApiException

# Step 1: Create a customer
customer = Customer()
customer.id = "customer-001"
customer.first_name = "John"
customer.last_name = "Smith"
customer.email = "john.smith@example.com"
customer.address = Address()
customer.address.street_address_1 = "123 Main St"
customer.address.city = "Dallas"
customer.address.state = "TX"
customer.address.postal_code = "75001"
customer.address.country = "USA"

created_customer = customer.create()
print(f"Customer Key: {created_customer.key}")

# Step 2: Store a credit card for the customer
card = CreditCardData()
card.number = "4111111111111111"
card.exp_month = "12"
card.exp_year = "2026"
card.card_holder_name = "John Smith"

payment_method = RecurringPaymentMethod(created_customer.key, "card-001")
payment_method.payment_method = card
stored_pm = payment_method.create()
print(f"Payment Method Key: {stored_pm.key}")

# Step 3: Charge against the stored payment method
existing = RecurringPaymentMethod.find("card-001")
response = (
    existing.charge(19.99)
    .with_currency("USD")
    .with_allow_duplicates(True)
    .execute()
)
print(f"Charge Response: {response.response_code}")  # "00"

# Step 4: Create a recurring schedule
schedule = existing.add_schedule("schedule-001")
schedule.name = "Monthly Subscription"
schedule.amount = 9.99
schedule.currency = "USD"
schedule.frequency = "Monthly"
created_schedule = schedule.create()
print(f"Schedule Key: {created_schedule.key}")
```

--------------------------------

### Configure Portico Gateway with Legacy Credentials

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configure the SDK for the Portico gateway using legacy credentials including site ID, license ID, device ID, username, and password. Ensure the service URL is correctly set.

```python
# --- Portico via legacy credentials ---
legacy_config = PorticoConfig()
legacy_config.site_id = 12345
legacy_config.license_id = 12345
legacy_config.device_id = 12345
legacy_config.username = "username"
legacy_config.password = "password"
legacy_config.service_url = "https://cert.api2.heartlandportico.com"

ServicesContainer.configure(legacy_config, "legacy")
```

--------------------------------

### ServicesContainer.configure — Gateway Configuration

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Initializes the SDK with a gateway configuration. This method should be called once at application startup. It supports different configuration objects for various gateways.

```APIDOC
## ServicesContainer.configure — Gateway Configuration

`ServicesContainer.configure(config, config_name="default")` initializes the SDK with a gateway. Call this once at application startup. Supports `GpApiConfig` (GP API REST) and `PorticoConfig` (Portico/Realex XML).

```python
from globalpayments.api import ServicesContainer, GpApiConfig, PorticoConfig
from globalpayments.api.entities.enums import CardChannel, Environment

# --- GP API configuration ---
gp_config = GpApiConfig()
gp_config.app_id = "YOUR_APP_ID"
gp_config.app_key = "YOUR_APP_KEY"
gp_config.channel = CardChannel.CARD_NOT_PRESENT
gp_config.environment = Environment.TEST  # or Environment.PRODUCTION

ServicesContainer.configure(gp_config)  # stored as "default"
ServicesContainer.configure(gp_config, "gpapi")  # named config

# --- Portico (Heartland) configuration via secret API key ---
portico_config = PorticoConfig()
portico_config.secret_api_key = "skapi_cert_YOUR_KEY"
portico_config.service_url = "https://cert.api2.heartlandportico.com"

ServicesContainer.configure(portico_config, "portico")

# --- Portico via legacy credentials ---
legacy_config = PorticoConfig()
legacy_config.site_id = 12345
legacy_config.license_id = 12345
legacy_config.device_id = 12345
legacy_config.username = "username"
legacy_config.password = "password"
legacy_config.service_url = "https://cert.api2.heartlandportico.com"

ServicesContainer.configure(legacy_config, "legacy")

# --- Realex (Global Iris) configuration ---
realex_config = PorticoConfig()
realex_config.merchant_id = "your_merchant_id"
realex_config.shared_secret = "your_shared_secret"
realex_config.account_id = "internet"
realex_config.channel = "ECOM"
realex_config.service_url = "https://pay.sandbox.realexpayments.com/epage-remote.cgi"

ServicesContainer.configure(realex_config, "realex")
```
```

--------------------------------

### Handle Various Exceptions in Payment Processing

Source: https://github.com/globalpayments/python-sdk/blob/master/README.md

Demonstrates how to catch different types of exceptions that can occur during payment processing, including builder, configuration, gateway, and general API errors.

```python
try:
    response = card.charge(-5.00)
        .with_currency("USD")
        .execute()

except BuilderException as e:
# handle builder errors

except ConfigurationException as e:
# handle errors related to your services configuration

except GatewayException as e:
# handle gateway errors/exceptions

except UnsupportedTransactionException as e:
# handle errors when the configured gateway doesn't support
# desired transaction

except ApiException as e:
# handle all other errors
```

--------------------------------

### Configure GP API Gateway

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configure the SDK for the GP API (Card Not Present) using your application ID and key. Supports test and production environments.

```python
from globalpayments.api import ServicesContainer, GpApiConfig, PorticoConfig
from globalpayments.api.entities.enums import CardChannel, Environment

# --- GP API configuration ---
gp_config = GpApiConfig()
gp_config.app_id = "YOUR_APP_ID"
gp_config.app_key = "YOUR_APP_KEY"
gp_config.channel = CardChannel.CARD_NOT_PRESENT
gp_config.environment = Environment.TEST  # or Environment.PRODUCTION

ServicesContainer.configure(gp_config)  # stored as "default"
ServicesContainer.configure(gp_config, "gpapi")  # named config
```

--------------------------------

### Secure3dBuilder — 3D Secure v2 Authentication

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Orchestrates the two-step 3D Secure v2 flow: verify enrollment then initiate authentication. Works with GP API gateway.

```APIDOC
## Secure3dBuilder — 3D Secure v2 Authentication

`Secure3dBuilder` orchestrates the two-step 3D Secure v2 flow: verify enrollment then initiate authentication. Works with GP API gateway.

```python
from globalpayments.api import ServicesContainer, GpApiConfig
from globalpayments.api.builders.threeD_secure_builder import Secure3dBuilder
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import (
    CardChannel,
    ThreeDSecureVersion,
    TransactionType,
    ChallengeRequestIndicator,
    AuthenticationSource,
)
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities.exceptions import ApiException

config = GpApiConfig(
    app_id="APP_ID",
    app_key="APP_KEY",
    channel=CardChannel.CARD_NOT_PRESENT,
    challenge_notification_url="https://yourapp.com/3ds/challenge",
    method_notification_url="https://yourapp.com/3ds/method",
)
ServicesContainer.configure(config)

card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"
card.cvn = "131"

billing_address = Address()
billing_address.street_address_1 = "123 Main St"
billing_address.city = "Dallas"
billing_address.state = "TX"
billing_address.postal_code = "75024"
billing_address.country = "USA"

try:
    # Step 1: Check if card is enrolled in 3DS
    secure3d = (
        Secure3dBuilder(TransactionType.VerifyEnrolled)
        .with_payment_method(card)
        .with_amount(29.99)
        .with_currency("USD")
        .execute(version=ThreeDSecureVersion.Two)
    )

    if secure3d.enrolled == "True":
        print(f"Server Transaction ID: {secure3d.server_transaction_id}")

        # Step 2: Initiate authentication
        initiated = (
            Secure3dBuilder(TransactionType.InitiateAuthentication)
            .with_three_d_secure(secure3d)
            .with_payment_method(card)
            .with_amount(29.99)
            .with_currency("USD")
            .with_address(billing_address)
            .with_customer_email("customer@example.com")
            .with_challenge_request_indicator(ChallengeRequestIndicator.NO_PREFERENCE)
            .execute(version=ThreeDSecureVersion.Two)
        )

        # If challenge required, redirect customer to initiated.issuer_acs_url
        # After challenge completed, attach 3DS data and charge
        card.three_d_secure = initiated

        charge_response = (
            card.charge(29.99)
            .with_currency("USD")
            .execute()
        )
        print(f"3DS Charge: {charge_response.response_code}")

except ApiException as e:
    print(f"3DS error: {str(e)}")
```
```

--------------------------------

### 3D Secure v2 Authentication Flow

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Orchestrates the two-step 3D Secure v2 flow: verify enrollment then initiate authentication. Works with GP API gateway. Requires configuration of GpApiConfig.

```python
from globalpayments.api import ServicesContainer, GpApiConfig
from globalpayments.api.builders.three_d_secure_builder import Secure3dBuilder
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import (
    CardChannel, ThreeDSecureVersion, TransactionType,
    ChallengeRequestIndicator, AuthenticationSource,
)
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities.exceptions import ApiException

config = GpApiConfig(
    app_id="APP_ID",
    app_key="APP_KEY",
    channel=CardChannel.CARD_NOT_PRESENT,
    challenge_notification_url="https://yourapp.com/3ds/challenge",
    method_notification_url="https://yourapp.com/3ds/method",
)
ServicesContainer.configure(config)

card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"
card.cvn = "131"

billing_address = Address()
billing_address.street_address_1 = "123 Main St"
billing_address.city = "Dallas"
billing_address.state = "TX"
billing_address.postal_code = "75024"
billing_address.country = "USA"

try:
    # Step 1: Check if card is enrolled in 3DS
    secure3d = (
        Secure3dBuilder(TransactionType.VerifyEnrolled)
        .with_payment_method(card)
        .with_amount(29.99)
        .with_currency("USD")
        .execute(version=ThreeDSecureVersion.Two)
    )

    if secure3d.enrolled == "True":
        print(f"Server Transaction ID: {secure3d.server_transaction_id}")

        # Step 2: Initiate authentication
        initiated = (
            Secure3dBuilder(TransactionType.InitiateAuthentication)
            .with_three_d_secure(secure3d)
            .with_payment_method(card)
            .with_amount(29.99)
            .with_currency("USD")
            .with_address(billing_address)
            .with_customer_email("customer@example.com")
            .with_challenge_request_indicator(ChallengeRequestIndicator.NO_PREFERENCE)
            .execute(version=ThreeDSecureVersion.Two)
        )

        # If challenge required, redirect customer to initiated.issuer_acs_url
        # After challenge completed, attach 3DS data and charge
        card.three_d_secure = initiated

        charge_response = (
            card.charge(29.99)
            .with_currency("USD")
            .execute()
        )
        print(f"3DS Charge: {charge_response.response_code}")

except ApiException as e:
    print(f"3DS error: {str(e)}")
```

--------------------------------

### Manage Transactions: Capture, Void, Refund, Edit

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Perform post-authorization transaction management using the Transaction object and ManagementBuilder. This includes capturing funds, voiding unsettled transactions, refunding amounts, editing gratuity, and holding/releasing for fraud review. An initial authorization is required before these operations.

```python
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities import Transaction
from globalpayments.api.entities.exceptions import GatewayException

card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"
card.cvn = "131"

try:
    # Step 1: Authorize (hold funds)
    auth_txn = (
        card.authorize(100.00)
        .with_currency("USD")
        .execute()
    )
    print(f"Auth ID: {auth_txn.transaction_reference.transaction_id}")

    # Step 2: Capture (settle)
    captured = auth_txn.capture(100.00).execute()
    print(f"Captured: {captured.response_code}")

    # Edit gratuity on a captured transaction
    edited = auth_txn.edit().with_gratuity(15.00).execute()

    # Void an unsettled transaction
    voided = auth_txn.void().execute()

    # Refund from transaction reference (partial refund)
    refunded = auth_txn.refund(25.00).with_currency("USD").execute()

    # Reverse an authorization
    reversed_txn = auth_txn.reverse(100.00).execute()

    # Hold / Release (for fraud review)
    held = auth_txn.hold().with_reason_code("FRAUD").execute()
    released = auth_txn.release().execute()

except GatewayException as e:
    print(f"Management error [{e.response_code}]: {e.response_message}")
```

--------------------------------

### Configure Portico Gateway with Secret API Key

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configure the SDK for the Portico gateway using a secret API key and service URL. This is typically used for testing or specific integrations.

```python
# --- Portico (Heartland) configuration via secret API key ---
portico_config = PorticoConfig()
portico_config.secret_api_key = "skapi_cert_YOUR_KEY"
portico_config.service_url = "https://cert.api2.heartlandportico.com"

ServicesContainer.configure(portico_config, "portico")
```

--------------------------------

### Configure Hosted Payment Page (HPP)

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configures the Realex Hosted Payment Page for client-side card entry. Produces a serialized JSON payload for the HPP JavaScript/iOS/Android libraries. Requires configuration of PorticoConfig and HostedPaymentConfig.

```python
from globalpayments.api import ServicesContainer, PorticoConfig
from globalpayments.api import HostedPaymentConfig
from globalpayments.api.entities.enums import FraudFilterMode, HppVersion
from globalpayments.api.payment_methods import CreditCardData

hpp_config = HostedPaymentConfig()
hpp_config.language = "en"
hpp_config.payment_button_text = "Pay Now"
hpp_config.response_url = "https://yourapp.com/payments/response"
hpp_config.card_storage_enabled = True
hpp_config.version = HppVersion.VERSION_2
hpp_config.fraud_filter_mode = FraudFilterMode.PASSIVE

config = PorticoConfig()
config.merchant_id = "your_merchant_id"
config.shared_secret = "your_shared_secret"
config.service_url = "https://pay.sandbox.realexpayments.com/epage-remote.cgi"
config.hosted_payment_config = hpp_config
ServicesContainer.configure(config)

card = CreditCardData()

# Serialize the request for the HPP JavaScript library
hpp_json = (
    card.charge(29.99)
    .with_currency("EUR")
    .with_order_id("order-12345")
    .with_description("Online purchase")
    .serialize()
)

print(hpp_json)
# Send this JSON to your frontend HPP JavaScript library
```

--------------------------------

### ReportingService — Transaction Reports

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Provides paginated transaction queries with filtering by date, transaction ID, card brand, status, amount, and batch. Supports looking up specific transactions and generating activity reports.

```APIDOC
## ReportingService — Transaction Reports

`ReportingService` provides paginated transaction queries via a fluent `where().and_with().execute()` interface. Supports filtering by date, transaction ID, card brand, status, amount, batch, and more.

```python
from datetime import datetime, timedelta, timezone
from globalpayments.api.services import ReportingService
from globalpayments.api.entities.enums import SearchCriteria, TransactionSortProperty, SortDirection
from globalpayments.api.entities.exceptions import GatewayException

start_date = (datetime.now() - timedelta(days=30)).replace(tzinfo=timezone.utc)
end_date = datetime.now().replace(tzinfo=timezone.utc)

try:
    # Paginated transaction search with date filter
    paged_response = (
        ReportingService.find_transactions_paged(1, 10)
        .where(SearchCriteria.StartDate, start_date)
        .and_with(SearchCriteria.EndDate, end_date)
        .execute()
    )
    print(f"Total Count: {paged_response.total_record_count}")
    for txn in paged_response.result:
        print(f"  {txn.transaction_id} - {txn.amount} {txn.currency} - {txn.status}")

    # Look up a specific transaction by ID
    detail = ReportingService.transaction_detail("TXN_ID_HERE").execute()
    print(f"Detail: {detail.transaction_id}, Auth: {detail.auth_code}")

    # Activity report (all gateway activity, Portico)
    activity = ReportingService.activity().execute()

    # Filter by card brand
    visa_txns = (
        ReportingService.find_transactions_paged(1, 25)
        .where(SearchCriteria.StartDate, start_date)
        .and_with(SearchCriteria.CardBrand, "VISA")
        .execute()
    )

except GatewayException as e:
    print(f"Reporting error: {str(e)}")
```
```

--------------------------------

### RecurringPaymentMethod — Stored Payment Methods & Subscriptions

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Stores payment methods (credit card or ACH) against a customer profile for recurring billing. Supports PayPlanConnector (Portico) and RealexConnector. Allows charging against stored methods and creating recurring schedules.

```APIDOC
## RecurringPaymentMethod — Stored Payment Methods & Subscriptions

`RecurringPaymentMethod` stores a payment method (credit card or ACH) against a `Customer` profile for recurring billing. Supports `PayPlanConnector` (Portico) and `RealexConnector`.

```python
from globalpayments.api.entities import Customer, RecurringPaymentMethod, Schedule, Address
from globalpayments.api.entities.enums import SecCode, AccountType, CheckType
from globalpayments.api.payment_methods import CreditCardData, ECheck
from globalpayments.api.entities.exceptions import ApiException

# Step 1: Create a customer
customer = Customer()
customer.id = "customer-001"
customer.first_name = "John"
customer.last_name = "Smith"
customer.email = "john.smith@example.com"
customer.address = Address()
customer.address.street_address_1 = "123 Main St"
customer.address.city = "Dallas"
customer.address.state = "TX"
customer.address.postal_code = "75001"
customer.address.country = "USA"

created_customer = customer.create()
print(f"Customer Key: {created_customer.key}")

# Step 2: Store a credit card for the customer
card = CreditCardData()
card.number = "4111111111111111"
card.exp_month = "12"
card.exp_year = "2026"
card.card_holder_name = "John Smith"

payment_method = RecurringPaymentMethod(created_customer.key, "card-001")
payment_method.payment_method = card
stored_pm = payment_method.create()
print(f"Payment Method Key: {stored_pm.key}")

# Step 3: Charge against the stored payment method
existing = RecurringPaymentMethod.find("card-001")
response = (
    existing.charge(19.99)
    .with_currency("USD")
    .with_allow_duplicates(True)
    .execute()
)
print(f"Charge Response: {response.response_code}")  # "00"

# Step 4: Create a recurring schedule
schedule = existing.add_schedule("schedule-001")
schedule.name = "Monthly Subscription"
schedule.amount = 9.99
schedule.currency = "USD"
schedule.frequency = "Monthly"
created_schedule = schedule.create()
print(f"Schedule Key: {created_schedule.key}")
```
```

--------------------------------

### HostedPaymentConfig — Hosted Payment Page (HPP)

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Configures the Realex Hosted Payment Page for client-side card entry. Produces a serialized JSON payload for the HPP JavaScript/iOS/Android libraries.

```APIDOC
## HostedPaymentConfig — Hosted Payment Page (HPP)

`HostedPaymentConfig` configures the Realex Hosted Payment Page for client-side card entry. Produces a serialized JSON payload for the HPP JavaScript/iOS/Android libraries.

```python
from globalpayments.api import ServicesContainer, PorticoConfig
from globalpayments.api import HostedPaymentConfig
from globalpayments.api.entities.enums import FraudFilterMode, HppVersion
from globalpayments.api.payment_methods import CreditCardData

hpp_config = HostedPaymentConfig()
hpp_config.language = "en"
hpp_config.payment_button_text = "Pay Now"
hpp_config.response_url = "https://yourapp.com/payments/response"
hpp_config.card_storage_enabled = True
hpp_config.version = HppVersion.VERSION_2
hpp_config.fraud_filter_mode = FraudFilterMode.PASSIVE

config = PorticoConfig()
config.merchant_id = "your_merchant_id"
config.shared_secret = "your_shared_secret"
config.service_url = "https://pay.sandbox.realexpayments.com/epage-remote.cgi"
config.hosted_payment_config = hpp_config
ServicesContainer.configure(config)

card = CreditCardData()

# Serialize the request for the HPP JavaScript library
hpp_json = (
    card.charge(29.99)
    .with_currency("EUR")
    .with_order_id("order-12345")
    .with_description("Online purchase")
    .serialize()
)

print(hpp_json)
# Send this JSON to your frontend HPP JavaScript library
```
```

--------------------------------

### Tokenizing Credit Card Data

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Use CreditCardData.tokenize() to store card details securely at the gateway, reducing PCI scope. The returned token can be used for subsequent transactions. Supports tokenization with or without verification, updating token expiry, and deleting tokens.

```python
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities.exceptions import ApiException

card = CreditCardData()
card.number = "4111111111111111"
card.exp_month = "12"
card.exp_year = "2026"
card.cvn = "123"

try:
    # Tokenize and verify simultaneously (default behavior)
    response = card.tokenize().execute()
    token = response.token
    print(f"Token: {token}")  # e.g. "supt_ABCdef123..."

    # Use token for future charges
    token_card = CreditCardData()
    token_card.token = token

    charge_response = (
        token_card.charge(19.99)
        .with_currency("USD")
        .execute()
    )
    print(f"Charge with token: {charge_response.response_code}")

    # Tokenize without verification
    response2 = card.tokenize(verify=False).execute()
    token2 = response2.token

    # Update token expiry
    token_card.exp_month = "01"
    token_card.exp_year = "2028"
    token_card.update_token()

    # Delete token
    token_card.delete_token()

except ApiException as e:
    print(f"Tokenization error: {str(e)}")
```

--------------------------------

### Paginated Transaction Search with Date Filter

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Use ReportingService.find_transactions_paged to retrieve transactions within a specified date range. Handles potential GatewayExceptions.

```python
from datetime import datetime, timedelta, timezone
from globalpayments.api.services import ReportingService
from globalpayments.api.entities.enums import SearchCriteria, TransactionSortProperty, SortDirection
from globalpayments.api.entities.exceptions import GatewayException

start_date = (datetime.now() - timedelta(days=30)).replace(tzinfo=timezone.utc)
end_date = datetime.now().replace(tzinfo=timezone.utc)

try:
    # Paginated transaction search with date filter
    paged_response = (
        ReportingService.find_transactions_paged(1, 10)
        .where(SearchCriteria.StartDate, start_date)
        .and_with(SearchCriteria.EndDate, end_date)
        .execute()
    )
    print(f"Total Count: {paged_response.total_record_count}")
    for txn in paged_response.result:
        print(f"  {txn.transaction_id} - {txn.amount} {txn.currency} - {txn.status}")

    # Look up a specific transaction by ID
    detail = ReportingService.transaction_detail("TXN_ID_HERE").execute()
    print(f"Detail: {detail.transaction_id}, Auth: {detail.auth_code}")

    # Activity report (all gateway activity, Portico)
    activity = ReportingService.activity().execute()

    # Filter by card brand
    visa_txns = (
        ReportingService.find_transactions_paged(1, 25)
        .where(SearchCriteria.StartDate, start_date)
        .and_with(SearchCriteria.CardBrand, "VISA")
        .execute()
    )

except GatewayException as e:
    print(f"Reporting error: {str(e)}")
```

--------------------------------

### Close Batch with BatchService

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Use BatchService.close_batch to settle all authorized transactions in the current open batch. Handles GatewayExceptions if no open batch exists. Can specify a configuration name.

```python
from globalpayments.api.services import BatchService
from globalpayments.api.entities.exceptions import GatewayException

try:
    batch = BatchService.close_batch()
    print(f"Batch ID: {batch.id}")
    print(f"Transaction Count: {batch.transaction_count}")
    print(f"Total Amount: {batch.total_amount}")

    # Close a named config's batch
    batch2 = BatchService.close_batch("portico")

except GatewayException as e:
    # Raised if no open batch exists
    print(f"Batch error [{e.response_code}]: {e.response_message}")
```

--------------------------------

### CreditCardData - Core Operations

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Represents a manually entered credit card. It auto-detects card type and supports charge, authorize, verify, refund, reverse, and tokenize operations.

```APIDOC
## CreditCardData — Credit Card Payments

`CreditCardData` represents a manually entered credit card. It auto-detects card type (Visa, MasterCard, Amex, Discover, JCB, Diners) from the card number and exposes `charge()`, `authorize()`, `verify()`, `refund()`, `reverse()`, and `tokenize()`.

```python
from globalpayments.api import ServicesContainer, GpApiConfig
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import CardChannel, AddressType
from globalpayments.api.entities.exceptions import ApiException, GatewayException
from globalpayments.api.payment_methods import CreditCardData

ServicesContainer.configure(GpApiConfig(app_id="APP_ID", app_key="APP_KEY",
                                         channel=CardChannel.CARD_NOT_PRESENT))

card = CreditCardData()
card.number = "4263970000005262"
card.exp_month = "12"
card.exp_year = "2025"
card.cvn = "131"
card.card_holder_name = "James Mason"

billing_address = Address()
billing_address.street_address_1 = "123 Main St."
billing_address.city = "Dallas"
billing_address.state = "TX"
billing_address.postal_code = "98765"
billing_address.country = "USA"

try:
    # Charge (sale) — captures immediately
    response = (
        card.charge(29.99)
        .with_currency("USD")
        .with_address(billing_address)
        .with_invoice_number("INV-001")
        .with_description("Order #1234")
        .execute()
    )
    print(f"Response Code: {response.response_code}")   # "SUCCESS"
    print(f"Transaction ID: {response.transaction_reference.transaction_id}")
    print(f"Auth Code: {response.transaction_reference.auth_code}")

    # Authorization only — capture later
    auth_response = (
        card.authorize(50.00)
        .with_currency("USD")
        .with_address(billing_address)
        .execute()
    )
    txn_id = auth_response.transaction_reference.transaction_id

    # Capture the authorization
    capture_response = auth_response.capture(50.00).execute()

    # Refund a previous transaction
    refund_response = (
        card.refund(10.00)
        .with_currency("USD")
        .with_address(billing_address)
        .execute()
    )

    # Void/reverse a transaction
    void_response = auth_response.void().execute()

    # Verify card without charging
    verify_response = card.verify().execute()

except GatewayException as e:
    print(f"Gateway error [{e.response_code}]: {e.response_message}")
except ApiException as e:
    print(f"API error: {str(e)}")
```
```

--------------------------------

### Address — Billing and Shipping Addresses

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Represents a billing or shipping address. Auto-resolves country codes from country names (and vice versa) using a built-in ISO 3166-1 country map.

```APIDOC
## Address — Billing and Shipping Addresses

`Address` represents a billing or shipping address. Auto-resolves country codes from country names (and vice versa) using a built-in ISO 3166-1 country map.

```python
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import AddressType
from globalpayments.api.payment_methods import CreditCardData

# Billing address (used for AVS)
billing = Address()
billing.street_address_1 = "6860 Dallas Pkwy"
billing.street_address_2 = "Suite 200"
billing.city = "Plano"
billing.state = "TX"                # also accessible as .province
billing.postal_code = "75024"
billing.country = "United States of America"  # auto-resolves to country_code = "US"

print(f"Country Code: {billing.country_code}")  # "US"
```
```

--------------------------------

### Card Present / Swiped Credit Transactions

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Use CreditTrackData for card-present transactions (POS). Supports swipe and proximity (NFC/tap) entry methods. Requires the track data value and the entry method to be specified.

```python
from globalpayments.api.payment_methods.credit import CreditTrackData
from globalpayments.api.entities.enums import EntryMethod
from globalpayments.api.entities.exceptions import GatewayException

track = CreditTrackData()
track.value = "%B4012002000060016^VI TEST CREDIT^251210118039000000000396?;4012002000060016=25121011803939600000?"
track.entry_method = EntryMethod.Swipe

try:
    response = (
        track.charge(15.00)
        .with_currency("USD")
        .with_allow_duplicates(True)
        .execute()
    )
    print(f"Response: {response.response_code}")
    print(f"Card Type: {response.card_type}")

    # Proximity (contactless/NFC) entry
    tap_track = CreditTrackData()
    tap_track.value = "%B4012002000060016^VI TEST CREDIT^251210118039000000000396?"
    tap_track.entry_method = EntryMethod.Proximity

    tap_response = tap_track.charge(20.00).with_currency("USD").execute()

except GatewayException as e:
    print(f"Gateway error: {e.response_message}")
```

--------------------------------

### Address Entity for Billing and Shipping

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Represents a billing or shipping address. Auto-resolves country codes from country names (and vice versa) using a built-in ISO 3166-1 country map. Used for AVS checks.

```python
from globalpayments.api.entities import Address
from globalpayments.api.entities.enums import AddressType
from globalpayments.api.payment_methods import CreditCardData

# Billing address (used for AVS)
billing = Address()
billing.street_address_1 = "6860 Dallas Pkwy"
billing.street_address_2 = "Suite 200"
billing.city = "Plano"
billing.state = "TX"                # also accessible as .province
billing.postal_code = "75024"
billing.country = "United States of America"  # auto-resolves to country_code = "US"

print(f"Country Code: {billing.country_code}")  # "US"
```

--------------------------------

### CreditCardData.tokenize - Tokenization

Source: https://context7.com/globalpayments/python-sdk/llms.txt

Stores the card at the gateway and returns a reusable token, removing PCI scope from your application. The token can be used for future charges.

```APIDOC
## CreditCardData.tokenize — Tokenization

`tokenize()` stores the card at the gateway and returns a reusable token, removing PCI scope from your application. The token can be used for future charges.

```python
from globalpayments.api.payment_methods import CreditCardData
from globalpayments.api.entities.exceptions import ApiException

card = CreditCardData()
card.number = "4111111111111111"
card.exp_month = "12"
card.exp_year = "2026"
card.cvn = "123"

try:
    # Tokenize and verify simultaneously (default behavior)
    response = card.tokenize().execute()
    token = response.token
    print(f"Token: {token}")  # e.g. "supt_ABCdef123..."

    # Use token for future charges
    token_card = CreditCardData()
    token_card.token = token

    charge_response = (
        token_card.charge(19.99)
        .with_currency("USD")
        .execute()
    )
    print(f"Charge with token: {charge_response.response_code}")

    # Tokenize without verification
    response2 = card.tokenize(verify=False).execute()
    token2 = response2.token

    # Update token expiry
    token_card.exp_month = "01"
    token_card.exp_year = "2028"
    token_card.update_token()

    # Delete token
    token_card.delete_token()

except ApiException as e:
    print(f"Tokenization error: {str(e)}")
```
```