### Initiate Hosted Payment in .NET

Source: https://developer.globalpay.com/ecommerce/payment-methods

Configure the GpEcomConfig and HostedPaymentConfig for gateway and HPP settings. Use HostedPaymentData to provide customer details and select preset payment methods. This example shows how to start a hosted payment session with specific alternative payment types.

```.NET
__ // configure client, request and HPP settings
var config = new GpEcomConfig();
config.MerchantId = "MerchantId";
config.AccountId = "internet";
config.SharedSecret = "secret";
config.ServiceUrl = "https://pay.sandbox.realexpayments.com/pay";

config.HostedPaymentConfig = new HostedPaymentConfig();
config.HostedPaymentConfig.Version = HppVersion.VERSION_2;

var service = new HostedService(config);

var hostedPaymentData = new HostedPaymentData();
hostedPaymentData.CustomerCountry = "DE";
hostedPaymentData.CustomerFirstName = "James";
hostedPaymentData.CustomerLastName = "Mason";
hostedPaymentData.MerchantResponseUrl = "https://www.example.com/returnUrl";
hostedPaymentData.TransactionStatusUrl = "https://www.example.com/statusUrl";

var apmTypes = new AlternativePaymentType[] {
    AlternativePaymentType.SOFORTUBERWEISUNG,
    AlternativePaymentType.PAYPAL,
    AlternativePaymentType.SEPA_DIRECTDEBIT_PPPRO_MANDATE_MODEL_A,
    AlternativePaymentType.TESTPAY
};
hostedPaymentData.PresetPaymentMethods = apmTypes;

            try
            {
    var hppJson = service.Charge(10.01m)
        .WithCurrency("EUR")
        .WithHostedPaymentData(hostedPaymentData)
        .Serialize();
                // TODO: pass the HPP JSON to the client-side
            }

```

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

### .NET SDK Example

Source: https://developer.globalpay.com/ecommerce/remote-api

Example of how to process an auto-capture authorization using the .NET SDK.

```APIDOC
## .NET SDK Example

### Description
This code snippet demonstrates how to configure the service, create a credit card object, and process an auto-capture authorization using the .NET SDK.

### Method
`card.Charge(129.99m).WithCurrency("EUR").Execute()`

### Parameters
#### Request Body
- **card** (CreditCardData) - Object containing card details (number, expiry, CVN, cardholder name).
- **amount** (Decimal) - The transaction amount.
- **currency** (String) - The currency of the transaction (e.g., "EUR").

### Request Example
```csharp
// configure client & request settings
ServicesContainer.ConfigureService(new GpEcomConfig
{
   MerchantId = "MerchantId",
   AccountId = "internet",
   SharedSecret = "secret",
   ServiceUrl = "https://api.sandbox.realexpayments.com/epage-remote.cgi"
});

// create the card object
var card = new CreditCardData
{
   Number = "4263970000005262",
   ExpMonth = 12,
   ExpYear = 2025,
   Cvn = "131",
   CardHolderName = "James Mason"
};

try
{
   // process an auto-capture authorization
   Transaction response = card.Charge(129.99m)
      .WithCurrency("EUR")
      .Execute();

   var result = response.ResponseCode; // 00 == Success
   var message = response.ResponseMessage; // [ test system ] AUTHORISED

   // get the response details to save to the DB for future requests
   var orderId = response.OrderId; // ezJDQjhENTZBLTdCNzNDQw
   var authCode = response.AuthorizationCode; // 12345
   var paymentsReference = response.TransactionId; // pasref 14622680939731425
   var schemeReferenceData = response.SchemeId; // MMC0F00YE4000000715
}

catch (ApiException exce)
{
   // TODO: add your error handling here
}
```

### Response
#### Success Response (200)
- **responseCode** (String) - Transaction response code. "00" indicates success.
- **responseMessage** (String) - Human-readable response message.
- **orderId** (String) - Unique identifier for the order.
- **authorizationCode** (String) - Authorization code from the acquirer.
- **transactionId** (String) - Unique transaction identifier.
- **schemeId** (String) - Scheme-specific transaction identifier.
```

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

### PHP SDK Example

Source: https://developer.globalpay.com/ecommerce/remote-api

Example of how to process an auto-capture authorization using the PHP SDK.

```APIDOC
## PHP SDK Example

### Description
This code snippet demonstrates how to configure the service, create a credit card object, and process an auto-capture authorization using the PHP SDK.

### Method
`$card->charge(19.99)->withCurrency("EUR")->execute()`

### Parameters
#### Request Body
- **card** (CreditCardData) - Object containing card details (number, expiry, CVN, cardholder name).
- **amount** (Float) - The transaction amount.
- **currency** (String) - The currency of the transaction (e.g., "EUR").

### Request Example
```php
<?php
require_once('vendor/autoload.php');

use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\ServicesContainer;
use GlobalPayments\Api\Entities\Exceptions\ApiException;
use GlobalPayments\Api\PaymentMethods\CreditCardData;

$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://api.sandbox.realexpayments.com/epage-remote.cgi";
ServicesContainer::configureService($config);

// create the card object
$card = new CreditCardData();
$card->number = "4263970000005262";
$card->expMonth = 12;
$card->expYear = 2025;
$card->cvn = "131";
$card->cardHolderName = "James Mason";

try {
   // process an auto-capture authorization
   $response = $card->charge(19.99)
      ->withCurrency("EUR")
      ->execute();
} catch (ApiException $e) {
   // TODO: Add your error handling here
}

if (isset($response)) {
   $result = $response->responseCode; // 00 == Success
   $message = $response->responseMessage; // [ test system ] AUTHORISED

   // get the details to save to the DB for future requests
   $orderId = $response->orderId; // N6qsk4kYRZihmPrTXWYS6g
   $authCode = $response->authorizationCode; // 12345
   $paymentsReference = $response->transactionId; // pasref: 14610544313177922
   $schemeReferenceData = $response->schemeId; // MMC0F00YE4000000715
}
```

### Response
#### Success Response (200)
- **responseCode** (String) - Transaction response code. "00" indicates success.
- **responseMessage** (String) - Human-readable response message.
- **orderId** (String) - Unique identifier for the order.
- **authorizationCode** (String) - Authorization code from the acquirer.
- **transactionId** (String) - Unique transaction identifier.
- **schemeId** (String) - Scheme-specific transaction identifier.
```

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

### Java SDK Example

Source: https://developer.globalpay.com/ecommerce/remote-api

Example of how to process an auto-settle authorization using the Java SDK.

```APIDOC
## Java SDK Example

### Description
This code snippet demonstrates how to configure the client, create a credit card object, and process an auto-settle authorization using the Java SDK.

### Method
`card.charge(new BigDecimal("19.99")).withCurrency("EUR").execute()`

### Parameters
#### Request Body
- **card** (CreditCardData) - Object containing card details (number, expiry, CVN, cardholder name).
- **amount** (BigDecimal) - The transaction amount.
- **currency** (String) - The currency of the transaction (e.g., "EUR").

### Request Example
```java
// configure client & request settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://api.sandbox.realexpayments.com/epage-remote.cgi");
ServicesContainer.configureService(config);

// create the card object
CreditCardData card = new CreditCardData();
card.setNumber("4263970000005262");
card.setExpMonth(12);
card.setExpYear(2025);
card.setCvn("131");
card.setCardHolderName("James Mason");

try {
   // process an auto-settle authorization
   Transaction response = card.charge(new BigDecimal("19.99"))
                           .withCurrency("EUR")
                           .execute();

   String result = response.getResponseCode(); // 00 == Success
   String message = response.getResponseMessage(); // [ test system ] AUTHORISED

   // get the details to save to the DB for future requests
   String orderId = response.getOrderId(); // ezJDQjhENTZBLTdCNzNDQw
   String authCode = response.getAuthorizationCode(); // 12345
   String paymentsReference = response.getTransactionId(); // pasref 14622680939731425
   String schemeReferenceData = response.getSchemeId(); // MMC0F00YE4000000715
}

catch (ApiException exce) {
   // TODO: add your error handling here
}
```

### Response
#### Success Response (200)
- **responseCode** (String) - Transaction response code. "00" indicates success.
- **responseMessage** (String) - Human-readable response message.
- **orderId** (String) - Unique identifier for the order.
- **authorizationCode** (String) - Authorization code from the acquirer.
- **transactionId** (String) - Unique transaction identifier.
- **schemeId** (String) - Scheme-specific transaction identifier.
```

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

### Network Tokens Guide

Source: https://developer.globalpay.com/ecommerce/network-tokens-SBS

A guide on how to implement and use Network Tokens in your integration.

```APIDOC
## Network Tokens Guide

### Description
This guide provides step-by-step instructions and best practices for integrating Network Tokens into your payment flow. It covers the process from token creation to using tokens for transactions.

### Key Steps
1. **Tokenization**: Initiate the process to generate a network token for a customer's card.
2. **Storage**: Securely store the generated network token associated with the customer.
3. **Transaction**: Use the stored network token for subsequent payment authorizations and captures.
4. **Management**: Understand how to manage, update, or delete network tokens as needed.
```

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

### Click to Pay Guide

Source: https://developer.globalpay.com/ecommerce/expand-overview

Implement Click to Pay for a streamlined checkout experience.

```APIDOC
## Click to Pay

### Overview
An introduction to the Click to Pay service.

### Guide
[Link to Click to Pay Guide]
```

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

### Installment Service Guide

Source: https://developer.globalpay.com/ecommerce/expand-overview

Offer installment payment options to your customers.

```APIDOC
## Installment Service

### Overview
An overview of the installment payment service.

### Guide
[Link to Installment Service Guide]
```

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

### Configure and Charge with Hosted Service (.NET)

Source: https://developer.globalpay.com/ecommerce/avs

This .NET example shows how to initialize the HostedService with necessary gateway and HPP details, including the billing address. Implement robust error handling for any ApiException.

```csharp
__// configure client, request and HPP settings
var service = new HostedService(new GpEcomConfig
{
   MerchantId = "MerchantId",
   AccountId = "internet",
   SharedSecret = "secret",
   ServiceUrl = "https://pay.sandbox.realexpayments.com/pay",
   HostedPaymentConfig = new HostedPaymentConfig
   {
      Version = "2"
   }
});

var billingAddress = new Address
{
   Country = "US",
   PostalCode = "50001|Flat 123"
};

try
{
   var hppJson = service.Charge(19.99m)
      .WithCurrency("EUR")
      .WithAddress(billingAddress, AddressType.Billing)
      .Serialize();

   // TODO: pass the HPP JSON to the client-side
}

catch (ApiException exce)
{
   // TODO: add your error handling here
}
```

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

### Create Customer in .NET

Source: https://developer.globalpay.com/ecommerce/card-storage

Configure the service and create a new customer using C#. This example shows how to set up the GpEcomConfig and customer details.

```.NET
// configure client & request settings
ServicesContainer.ConfigureService(new GpEcomConfig
{
   MerchantId = "MerchantId",
   AccountId = "internet",
   SharedSecret = "secret",
   ServiceUrl = "https://api.sandbox.realexpayments.com/epage-remote.cgi"
});

// supply the the payer/customer details
var customer = new Customer
{
   Key = Guid.NewGuid().ToString(),
   Title = "Mr.",
   FirstName = "James",
   LastName = "Mason",
   Company = "Realex Payments",
   Address = new Address
   {
      StreetAddress1 = "Flat 123",
      StreetAddress2 = "House 456",
      StreetAddress3 = "The Cul-De-Sac",
      City = "Halifax",
      Province = "West Yorkshire",
      PostalCode = "W6 9HR",
      Country = "United Kingdom"
   },
   HomePhone = "+35312345678",
   WorkPhone = "+3531987654321",
   Fax = "+124546871258",
   MobilePhone = "+25544778544",
   Email = "text@example.com",
   Comments = "Campaign Ref E7373G"
};

try
{
   var response = customer.Create();
   // get the stored payer/customer reference for future transactions
   var payerRef = response.Key;
   // TODO: add a card/payment method to the payer, see next step
}

catch (ApiException exce)
{
   // TODO: add your error handling here
}
```

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

### Installment Service - Retrieve Installment Plans

Source: https://developer.globalpay.com/ecommerce/PDRC

Retrieves available installment plans for a transaction.

```APIDOC
## GET /v1/installments/plans

### Description
Retrieves available installment plans for a given transaction amount and currency.

### Method
GET

### Endpoint
/v1/installments/plans

### Parameters
#### Query Parameters
- **amount** (decimal) - Required - The transaction amount.
- **currency** (string) - Required - The transaction currency.

### Response
#### Success Response (200)
- **plans** (array) - A list of available installment plans.
  - **numberOfInstallments** (integer) - The number of installments.
  - **monthlyPayment** (decimal) - The monthly payment amount.
  - **totalAmount** (decimal) - The total amount payable.

#### Response Example
```json
{
  "plans": [
    {
      "numberOfInstallments": 3,
      "monthlyPayment": 33.33,
      "totalAmount": 99.99
    },
    {
      "numberOfInstallments": 6,
      "monthlyPayment": 16.67,
      "totalAmount": 100.02
    }
  ]
}
```
```

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

### Configure and Charge with Hosted Service (PHP)

Source: https://developer.globalpay.com/ecommerce/avs

This PHP snippet demonstrates setting up the HostedService with gateway and HPP configurations, including billing address. Remember to include the vendor autoloader and handle potential API exceptions.

```php
__<?php
require_once('vendor/autoload.php');

use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\HostedPaymentConfig;
use GlobalPayments\Api\Services\HostedService;
use GlobalPayments\Api\Entities\Address;
use GlobalPayments\Api\Entities\Enums\AddressType;
use GlobalPayments\Api\Entities\Enums\HppVersion;
use GlobalPayments\Api\Entities\Exceptions\ApiException;

$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://pay.sandbox.realexpayments.com/pay";
$config->hostedPaymentConfig = new HostedPaymentConfig();
$config->hostedPaymentConfig->version = HppVersion::VERSION_2;
$service = new HostedService($config);

// billing address
$billingAddress = new Address();
$billingAddress->postalCode = "50001|Flat 123";
$billingAddress->country = "US";

try {
   $hppJson = $service->charge(19.99)
      ->withCurrency("EUR")
      ->withAddress($billingAddress, AddressType::BILLING)
      ->serialize();
   // TODO: pass the HPP JSON to the client-side
} catch (ApiException $e) {
   // TODO: Add your error handling here
}
```

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

### Sample Installment Plan Response

Source: https://developer.globalpay.com/ecommerce/installments-sbs

This JSON object represents a sample response from the Installment Service, detailing available installment plans for a transaction.

```json
{
  "amount": 1000000,
  "currency": "CAD",
  "matched_plans": [
    {
      "name": "plan24CwAPR",
      "type": "ISSUER_DEFAULT",
      "number_of_installments": 24,
      "installment_frequency": "MONTHLY",
      "terms_and_conditions": [
        {
          "url": "http://www.myurl.com",
          "version": "25798469",
          "text": "You are selecting a 24-month installment plan. The total purchase amount will be deducted from your available credit limit. As set forth in your terms, your installment fee will be 13.99% APR calculated for 24 months. If you miss an installment payment, the standard rate of purchases will apply to the remaining installment balance.",
          "language_code": "ENG"
        }
      ],
      "cost_info": {
        "annual_percentage_rate": 13.99,
        "fee_info": [
          {
            "type": "CONSUMER",
            "rate_percentage": 5,
            "flat_fee": 0
          }
        ],
        "total_plan_cost": 1130500,
        "total_fees": 130500,
        "total_upfront_fees": 100000,
        "total_recurring_fees": 30500,
        "first_installment": {
          "upfront_fee": 100000,
          "installment_fee": 1270,
          "amount": 41666
        },
        "last_installment": {
          "installment_fee": 1270,
          "amount": 41666
        },
        "currency": "CAD"
      },
      "plan_id": "7533d4f7-6a10-5557-2e92-132d06157502"
    }
  ]
}
```

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

### Initiate Hosted Payment in PHP

Source: https://developer.globalpay.com/ecommerce/payment-methods

Set up the GpEcomConfig and HostedPaymentConfig for gateway and HPP settings. Utilize HostedPaymentData for customer information and preset payment methods. This example demonstrates initiating a hosted payment session with various alternative payment types.

```PHP
__require_once('vendor/autoload.php');

use GlobalPayments\Api\Entities\Enums\AlternativePaymentType;
use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\HostedPaymentConfig;
use GlobalPayments\Api\Entities\HostedPaymentData;
use GlobalPayments\Api\Entities\Enums\HppVersion;
use GlobalPayments\Api\Entities\Exceptions\ApiException;
use GlobalPayments\Api\Services\HostedService;
use GlobalPayments\Api\Tests\Integration\Gateways\RealexConnector\Hpp\RealexHppClient;

// configure client, request and HPP settings
$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://pay.sandbox.realexpayments.com/pay";

$config->hostedPaymentConfig = new HostedPaymentConfig();
$config->hostedPaymentConfig->version = HppVersion::VERSION_2;

$service = new HostedService($config);

$hostedPaymentData = new HostedPaymentData();
$hostedPaymentData->customerCountry = 'DE';
$hostedPaymentData->customerFirstName = 'James';
$hostedPaymentData->customerLastName = 'Mason';
$hostedPaymentData->merchantResponseUrl = 'https://www.example.com/returnUrl';
$hostedPaymentData->transactionStatusUrl = 'https://www.example.com/statusUrl';

$apmTypes = [
    AlternativePaymentType::SOFORTUBERWEISUNG,
    AlternativePaymentType::PAYPAL,
    AlternativePaymentType::SEPA_DIRECTDEBIT_PPPRO_MANDATE_MODEL_A,
    AlternativePaymentType::TEST_PAY
];
$hostedPaymentData->presetPaymentMethods = $apmTypes;

try {
    $hppJson = $service->charge(10.01)
        ->withCurrency("EUR")
        ->withHostedPaymentData($hostedPaymentData)
        ->serialize();
    // TODO: pass the HPP JSON to the client-side
} catch (ApiException $e) {
    // TODO: Add your error handling here
}
```

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

### Create Customer in PHP

Source: https://developer.globalpay.com/ecommerce/card-storage

Configure the service and create a new customer using PHP. Ensure the vendor autoload is included for dependencies.

```PHP
<?php
require_once('vendor/autoload.php');

use GlobalPayments\Api\ServiceConfigs\Gateways\GpEcomConfig;
use GlobalPayments\Api\ServicesContainer;
use GlobalPayments\Api\Entities\Address;
use GlobalPayments\Api\Entities\Customer;
use GlobalPayments\Api\Utils\GenerationUtils;
use GlobalPayments\Api\Entities\Exceptions\ApiException;

$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "internet";
$config->sharedSecret = "secret";
$config->serviceUrl = "https://api.sandbox.realexpayments.com/epage-remote.cgi";
ServicesContainer::configureService($config);

// supply the the payer/customer details
$customer = new Customer();
$customer->key = GenerationUtils::getGuid();
$customer->title = "Mr.";
$customer->firstName = "James";
$customer->lastName = "Mason";
$customer->company = "Acme Ltd";
$customer->email = "text@example.com";
$customer->address = new Address();
$customer->address->streetAddress1 = "Flat 123";
$customer->address->streetAddress2 = "House 456";
$customer->address->city = "Halifax";
$customer->address->postalCode = "E77 4QJ";
$customer->address->country = "GB";
$customer->mobilePhone = "+353123456789";

try {
   $response = $customer->create();
   // TODO: add a card/payment method to the payer, see next step
} catch (ApiException $e) {
   // TODO: Add your error handling here
}
```

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

### Installment Service

Source: https://developer.globalpay.com/ecommerce/paypal

APIs for managing installment payment plans.

```APIDOC
## Installment Service

### Description
APIs to retrieve installment plans and confirm customer selections for installment payments.

### Operations

#### Retrieve Installment Plans
**Description:** Retrieves available installment plans for a transaction.
**Method:** GET
**Endpoint:** `/installment/plans`

#### Confirm Selected Plan
**Description:** Confirms the customer's selected installment plan.
**Method:** POST
**Endpoint:** `/installment/confirm`

#### Error Codes
**Description:** Lists and explains error codes related to the installment service.
**Method:** GET
**Endpoint:** `/installment/error-codes`

#### Generate Hash
**Description:** Generates a hash for request security.
**Method:** POST
**Endpoint:** `/installment/hash/generate`

#### Check Hash
**Description:** Verifies the integrity of a request using a hash.
**Method:** POST
**Endpoint:** `/installment/hash/check`
```

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

### XML Request Example

Source: https://developer.globalpay.com/ecommerce/remote-api

Example of an XML request for an auto-settle authorization.

```APIDOC
## XML Request Example

### Description
This is an example of an XML request payload for initiating an auto-settle authorization.

### Method
POST (Implied by XML request structure for an API endpoint)

### Endpoint
`https://api.sandbox.realexpayments.com/epage-remote.cgi` (Inferred from SDK examples)

### Request Body
```xml
<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180613141207">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>0425</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>
```

### Parameters
#### Request Body Fields
- **merchantid** (String) - Your merchant ID.
- **account** (String) - Your account ID.
- **channel** (String) - The channel, typically "ECOM" for e-commerce.
- **orderid** (String) - A unique identifier for the order.
- **amount** (Integer) - The transaction amount (in cents or smallest currency unit).
  - **currency** (Attribute) - The currency code (e.g., "EUR").
- **card** (Object) - Contains card details.
  - **number** (String) - The primary account number (PAN).
  - **expdate** (String) - Expiry date in MMYY format.
  - **chname** (String) - Cardholder name.
  - **type** (String) - Card type (e.g., "VISA").
  - **cvn** (Object) - Card Verification Number details.
    - **number** (String) - The CVN number.
    - **presind** (String) - Presence indicator for CVN (e.g., "1" if provided).
- **autosettle** (Object) - Controls auto-settlement.
  - **flag** (Attribute) - "1" for auto-settle, "0" otherwise.
- **sha1hash** (String) - SHA1 hash of the request for security.
```

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

### Configure and Charge with Hosted Service (Java)

Source: https://developer.globalpay.com/ecommerce/avs

Use this Java snippet to configure the HostedService with gateway and HPP settings, then initiate a charge with billing address details. Ensure proper error handling for API exceptions.

```java
__// configure client, request and HPP settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://pay.sandbox.realexpayments.com/pay");

HostedPaymentConfig hostedPaymentConfig = new HostedPaymentConfig();
hostedPaymentConfig.setVersion(HppVersion.Version2);
config.setHostedPaymentConfig(hostedPaymentConfig);

HostedService service = new HostedService(config);

Address billingAddress = new Address();
billingAddress.setCountry("US");
billingAddress.setPostalCode("50001|Flat 123");

try {
   String hppJson = service.charge(new BigDecimal("19.99"))
      .withCurrency("EUR")
      .withAddress(billingAddress, AddressType.Billing)
      .serialize();
   // TODO: pass the HPP JSON to the client-side
} catch (ApiException exce) {
   // TODO: add your error handling here
}
```

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

### SDK Reference - Installment Service

Source: https://developer.globalpay.com/ecommerce/sdks

Manage installment payment plans using the SDK reference.

```APIDOC
## SDK Reference: Installment Service

This section details the SDK methods for the Installment Service.

### Retrieve Installment Plans

Retrieves available installment plans for a transaction.

*   **Method:** `getInstallmentPlans`
*   **Parameters:**
    *   `transactionDetails` (object) - Required - Details of the transaction for which to find plans.
*   **Response:**
    *   `plans` (array) - A list of available installment plans.

### Confirm Selected Plan

Confirms the customer's selected installment plan.

*   **Method:** `confirmInstallmentPlan`
*   **Parameters:**
    *   `planId` (string) - Required - The ID of the selected plan.
    *   `transactionId` (string) - Required - The ID of the associated transaction.
*   **Response:**
    *   `confirmationStatus` (string) - The status of the plan confirmation.
```

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

### Configure and Use Hosted Service

Source: https://developer.globalpay.com/ecommerce/payment-methods

Configure the `GpEcomConfig` with your merchant details and service URL. Then, instantiate the `HostedService` to process payment responses. This snippet demonstrates parsing a JSON response and extracting key transaction details.

```csharp

// configure client settings
var config = new GpEcomConfig();
config.MerchantId = "MerchantId";
config.AccountId = "internet";
config.SharedSecret = "secret";
config.ServiceUrl = "https://pay.sandbox.realexpayments.com/pay";

var service = new HostedService(config);

            /**
              TODO: grab the response JSON from the client-side.
              Sample response JSON (values will be Base64 encoded):

              var responseJson = "{
                \"MERCHANT_ID\":\"MerchantId\",
                \"ACCOUNT\":\"internet\",
                \"ORDER_ID\":\"xS_1TgGYk06TIICK6BWfIQ\",
                \"TIMESTAMP\":\"20230413121749\",
                \"RESULT\": \"01\",
                \"PASREF\": \"16371434569622613\",    
                \"MERCHANT_RESPONSE_URL\":\"https://www.example.com/returnUrl\",
                \"MESSAGE\": \"PENDING\",
                \"AMOUNT\": \"1001\",
                \"SHA1HASH\": \"a429120031e3f6ff5cbcf0960acf826cc71c04e3\",
                \"HPP_CUSTOMER_FIRSTNAME\": \"James\",
                \"HPP_CUSTOMER_LASTNAME\": \"Mason\",
                \"HPP_CUSTOMER_COUNTRY\": \"DE\",
                \"PAYMENTMETHOD\": \"sofort\",
                \"PAYMENTPURPOSE\": \"4JQBVNK REALEXTEST\",
                \"HPP_CUSTOMER_BANK_ACCOUNT\": \""
";
*/


            try
            {
    // create the response object from the response JSON
    var parsedResponse = service.ParseResponse(responseJson);
    string responseCode = parsedResponse.ResponseCode; // 01
    string responseMessage = parsedResponse.ResponseMessage; // PENDING
    Dictionary<string, string> responseValues = parsedResponse.ResponseValues; // get values accessible by key

    string pasref = responseValues["PASREF"]; // 1636457734629657
    string setupMessage = responseValues["MESSAGE"]; // Successful
    string orderId = responseValues["ORDER_ID"]; // MTVmNmY4MGMtMjIyMzJlNA

    string merchantResponseUrl = responseValues["MERCHANT_RESPONSE_URL"]; // https://www.example.com/responseUrl
    string paymentMethodType = responseValues["PAYMENTMETHOD"]; // sofort
    string cardReference = responseValues["PAYMENTPURPOSE"]; // 4NPL0A7 REALEXTEST
    string customerFirstName = responseValues["HPP_CUSTOMER_FIRSTNAME"]; // James
    string customerLastName = responseValues["HPP_CUSTOMER_LASTNAME"]; // Mason
    string customerCountry = responseValues["HPP_CUSTOMER_COUNTRY"]; // DE

                // TODO: update your application and display transaction outcome to the customer
            }
            catch (ApiException e) {
                // For example if the SHA1HASH doesn't match what is expected
                // TODO: add your error handling here
            }

            }

```

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

### Installment Service API

Source: https://developer.globalpay.com/ecommerce/payments-start

Endpoints for managing installment payment plans, including retrieval and confirmation.

```APIDOC
## Installment Service API Reference

### Retrieve Installment Plans

**Description**: Retrieves available installment plans for a purchase.

### Confirm Selected Plan

**Description**: Confirms the customer's selected installment plan.

### Error Codes

**Description**: Lists and explains error codes related to the installment service.

### Generate Hash

**Description**: Generates a hash for data integrity.

### Check Hash

**Description**: Verifies the integrity of data using a hash.
```

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

### Initiate Hosted Payment in Java

Source: https://developer.globalpay.com/ecommerce/payment-methods

Configure the GatewayConfig and HostedPaymentConfig to set up the payment gateway and HPP settings. Use HostedPaymentData to specify customer details and preset payment methods. This snippet is useful for initiating a hosted payment session with specific alternative payment types.

```Java
__import com.global.api.entities.HostedPaymentData;
import com.global.api.entities.enums.AlternativePaymentType;
import com.global.api.entities.enums.HppVersion;
import com.global.api.entities.exceptions.ApiException;
import com.global.api.serviceConfigs.GatewayConfig;
import com.global.api.serviceConfigs.HostedPaymentConfig;
import com.global.api.services.HostedService;

import java.math.BigDecimal;

// configure client, request and HPP settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://pay.sandbox.realexpayments.com/pay");

HostedPaymentConfig hostedPaymentConfig = new HostedPaymentConfig();
hostedPaymentConfig.setVersion(HppVersion.Version2);

config.setHostedPaymentConfig(hostedPaymentConfig);

HostedService service = new HostedService(config);

HostedPaymentData hostedPaymentData = new HostedPaymentData();
hostedPaymentData.setCustomerCountry("DE");
hostedPaymentData.setCustomerFirstName("James");
hostedPaymentData.setCustomerLastName("Mason");
hostedPaymentData.setMerchantResponseUrl("https://www.example.com/returnUrl");
hostedPaymentData.setTransactionStatusUrl("https://www.example.com/statusUrl");

hostedPaymentData.setPresetPaymentMethods(
        AlternativePaymentType.SOFORTUBERWEISUNG,
        AlternativePaymentType.SEPA_DIRECTDEBIT_PPPRO_MANDATE_MODEL_A,
        AlternativePaymentType.TESTPAY
);

try {
    String hppJson =
            service
                    .charge(new BigDecimal("10.01"))
                    .withCurrency("EUR")
                    .withHostedPaymentData(hostedPaymentData)
                    .serialize();
// TODO: pass the HPP JSON to the client-side
} catch (ApiException e) {
// TODO: Add your error handling here
}
```

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

### Create Customer in Java

Source: https://developer.globalpay.com/ecommerce/card-storage

Configure the client and create a new customer with address details. This customer reference can be used for future transactions.

```Java
// configure client & request settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://api.sandbox.realexpayments.com/epage-remote.cgi");

ServicesContainer.configureService(config);

// supply the the payer/customer details
Address address = new Address();
address.setStreetAddress1("Flat 123");
address.setStreetAddress2("House 456");
address.setStreetAddress3("The Cul-De-Sac");
address.setCity("Halifax");
address.setProvince("West Yorkshire");
address.setPostalCode("W6 9HR");
address.setCountry("United Kingdom");

Customer customer = new Customer();
customer.setKey(UUID.randomUUID().toString());
customer.setTitle("Mr.");
customer.setFirstName("James");
customer.setLastName("Mason");
customer.setCompany("Acme Ltd");
customer.setAddress(address);
customer.setMobilePhone("+25544778544");
customer.setEmail("text@example.com");
customer.setComments("Campaign Ref E7373G");

try {
   Customer response = customer.create();
   // get the stored payer/customer reference for future transactions
   String payerRef = response.getKey();
   // TODO: add a card/payment method to the payer, see next step
} 

catch (ApiException exce) {
        // TODO: add your error handling here
}
```

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

### Confirm Selected Plan

Source: https://developer.globalpay.com/ecommerce/installments-sbs

To confirm the selected installment plan by the user, send the plan details in the Authorization request. After the cardholder selects an installment plan, the merchant should provide installment plan details in Auth and Receipt-in requests under the optional XML tag.

```APIDOC
## POST /installments/confirmations

### Description
Confirms the installment plan selected by the user by sending plan details in the Authorization request.

### Method
POST

### Endpoint
- Sandbox: https://api.sandbox.globalpay-ecommerce.com/installments/confirmations
- Production: https://api.globalpay-ecommerce.com/installments/confirmations

### Request Body
- **installment** (XML) - Required - Contains details of the installment plan.
  - **provider** (string) - Required - The provider of the installment plan (e.g., VIS).
  - **planid** (string) - Required - The unique identifier for the installment plan.
  - **tcversion** (string) - Required - The version of the terms and conditions.
  - **tclang** (string) - Required - The language code for the terms and conditions.

### Request Example
```xml
<installment>
<provider>VIS</provider>
<planid>3fa85f64-5717-4562-b3fc-2c963f66afa6</planid>
<tcversion>2</tcversion>
<tclang>eng</tclang>
</installment>
```

### Response
(Details not provided in the source text)
```

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

### Installment Service API Reference

Source: https://developer.globalpay.com/ecommerce/payments/integrations

Reference for Installment Service API operations including retrieving plans and confirming selections.

```APIDOC
## Installment Service API

### Description
Provides endpoints for managing installment payment plans.

### Endpoints

#### Retrieve Installment Plans
- **Method:** GET
- **Endpoint:** /v1/installments/plans

#### Confirm Selected Plan
- **Method:** POST
- **Endpoint:** /v1/installments/plan/confirm

#### Error Codes
- **Method:** GET
- **Endpoint:** /v1/installments/error_codes

#### Generate Hash
- **Method:** POST
- **Endpoint:** /v1/installments/hash/generate

#### Check Hash
- **Method:** POST
- **Endpoint:** /v1/installments/hash/check
```

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

### Configure and Initiate HPP Request in .NET

Source: https://developer.globalpay.com/ecommerce/card-storage

This .NET snippet shows how to set up the GpEcomConfig and HostedPaymentConfig for HPP, then use the HostedService to generate HPP JSON for a charge, including card storage parameters.

```.net
// configure client, request and HPP settings
var service = new HostedService(new GpEcomConfig
{
   MerchantId = "MerchantId",
   AccountId = "internet",
   SharedSecret = "secret",
   ServiceUrl = "https://pay.sandbox.realexpayments.com/pay",
   HostedPaymentConfig = new HostedPaymentConfig
   {
      Version = "2",
      DisplaySavedCards = true
   }
});

// data to be passed to the HPP along with transaction level settings
var hostedPaymentData = new HostedPaymentData
{
   OfferToSaveCard = true,
   CustomerExists = true,
   CustomerKey = "5e7e9152-2d53-466d-91bc-6d12ebc56b79"
   // supply your own reference for any new card saved
   // PaymentKey = "48fa69fe-d785-4c27-876d-6ccba660fa2b"
};

try
{
   var hppJson = service.Charge(19.99m)
      .WithHostedPaymentData(hostedPaymentData)
      .WithCurrency("EUR")
      .Serialize();

   // TODO: pass the HPP JSON to the client-side
}

catch (ApiException exce)
{
   // TODO: add your error handling here
}
```

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

### C#: Configure Gateway and Initialize 3D Secure

Source: https://developer.globalpay.com/ecommerce/auth-exemp-request

This C# snippet demonstrates how to configure the Global Payments E-commerce gateway with merchant details and notification URLs. It also shows how to initialize a CreditCardData object and perform a 3D Secure enrollment check.

```csharp
GatewayConfig config = new GpEcomConfig();
config.MerchantId = "myMerchantId";
config.AccountId = "ecomeos";
config.SharedSecret = "secret";
config.MethodNotificationUrl = "https://www.example.com/methodNotificationUrl";
config.ChallengeNotificationUrl = "https://www.example.com/challengeNotificationUrl";          
config.MerchantContactUrl = "https://www.example.com";
config.Secure3dVersion = Secure3dVersion.Two;
 
ServicesContainer.ConfigureService(config);
 
CreditCardData card = new CreditCardData();            
card.Number = "4263970000005262";
card.ExpMonth = 12;
card.ExpYear = DateTime.Now.Year + 1;
card.CardHolderName = "John Smith";
 
// Shipping address
Address shippingAddress = new Address();
shippingAddress.StreetAddress1 = "Apartment 852";
shippingAddress.StreetAddress2 = "Complex 741";
shippingAddress.StreetAddress3 = "no";
shippingAddress.City = "Chicago";
shippingAddress.PostalCode = "5001";
shippingAddress.State = "IL";
shippingAddress.CountryCode = "840";
 
// Billing address
Address billingAddress = new Address();
billingAddress.StreetAddress1 = "Flat 456";
billingAddress.StreetAddress2 = "House 789";
billingAddress.StreetAddress3 = "no";
billingAddress.City = "Halifax";
billingAddress.PostalCode = "W5 9HR";
billingAddress.CountryCode = "826";
 
// Browser data
BrowserData browserData = new BrowserData();            
browserData.AcceptHeader = "text/html,application/xhtml+xml,application/xml;q=9,image/webp,img/apng,*/*;q=0.8";
browserData.ColorDepth = ColorDepth.TWENTY_FOUR_BITS;
browserData.IpAddress = "123.123.123.123";
browserData.JavaEnabled = true;
browserData.Language = "en";
browserData.ScreenHeight = 1080;
browserData.ScreenWidth = 1920;
browserData.ChallengeWindowSize = ChallengeWindowSize.WINDOWED_600X400;
browserData.Timezone = "0";
browserData.UserAgent = "Mozilla/5.0 (Windows NT 6.1; Win64, x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36";
 
ThreeDSecure secureEcom = Secure3dService.CheckEnrollment(card)
                .Execute(Secure3dVersion.Two);
 
```

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

### Installment Plan Confirmation Request (XML)

Source: https://developer.globalpay.com/ecommerce/installments-sbs

This XML snippet shows the required format for confirming a selected installment plan in an Authorization request.

```xml
<installment>
<provider>VIS</provider>
<planid>3fa85f64-5717-4562-b3fc-2c963f66afa6</planid>
<tcversion>2</tcversion>
<tclang>eng</tclang>
</installment>
```

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

### Configure and Initiate HPP Request in Java

Source: https://developer.globalpay.com/ecommerce/card-storage

Use this Java snippet to configure the GatewayConfig and HostedPaymentConfig for HPP, then create a HostedService to initiate a charge with hosted payment data, including card storage options.

```java
// configure client, request and HPP settings
GatewayConfig config = new GatewayConfig();
config.setMerchantId("MerchantId");
config.setAccountId("internet");
config.setSharedSecret("secret");
config.setServiceUrl("https://pay.sandbox.realexpayments.com/pay");

HostedPaymentConfig hostedPaymentConfig = new HostedPaymentConfig();
hostedPaymentConfig.setVersion(HppVersion.Version2);
hostedPaymentConfig.setDisplaySavedCards(true);
config.setHostedPaymentConfig(hostedPaymentConfig);

HostedService service = new HostedService(config);

// data to be passed to the HPP along with transaction level settings
HostedPaymentData hostedPaymentData = new HostedPaymentData();
hostedPaymentData.setOfferToSaveCard(true);
hostedPaymentData.setCustomerExists(true);
hostedPaymentData.setCustomerKey("376a2598-412d-4805-9f47-c177d5605853");
// supply your own reference for any new card saved
// hostedPaymentData.setPaymentKey = "376a2598-412d-4805-9f47-c177d5605853"

try {
   String hppJson = service.charge(new BigDecimal("19.99"))
      .withHostedPaymentData(hostedPaymentData)
      .withCurrency("EUR")
      .serialize();
   // TODO: pass the HPP JSON to the client-side

} catch (ApiException exce) {
   // TODO: add your error handling here
}
```

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

### Filtering Installment Plans

Source: https://developer.globalpay.com/ecommerce/installments-sbs

You can filter installment plans by sending specific filter parameters in the request payload. The available filters are HPP_PLAN_TYPE, HPP_MAX_TERM_MONTHS_MERCHANT_FUNDED, and HPP_AMOUNT_THRESHOLD.

```APIDOC
## Filtering installment plans
You can filter installment plans by sending the following filter parameters in the request:
  * `HPP_PLAN_TYPE`
  * `HPP_MAX_TERM_MONTHS_MERCHANT_FUNDED`
  * `HPP_AMOUNT_THRESHOLD`

If available, up to two installment plans will be displayed on the HPP. In the following example, both plans are `CONSUMER_FUNDED` on the HPP if available for a specific user.

#### Sample request (payload)
```json
{
"TIMESTAMP": "20240311160300",
"MERCHANT_ID": "vayuvisa",
"ACCOUNT": "installment",
"CURRENCY": "CAD",
"AMOUNT": "45000",
"ORDER_ID": "853f6574-b02c-4cae-8e14-26506ab69809",
"AUTO_SETTLE_FLAG":"0",
"HPP_PLAN_TYPE":"CONSUMER_FUNDED",
"HPP_MAX_TERM_MONTHS_MERCHANT_FUNDED":"",
"HPP_AMOUNT_THRESHOLD":"",
"SHA1HASH": "7c5be41124b37c40f3b8851ad2dd1bc11a70a972"
}
```
```