# Sibs Payment Gateway Facades

This package provides two facade classes, `ClientFacade` and `ServiceFacade`, to simplify integration with multiple payment gateway providers (`DPG`, `SPG`, and `STARGATE`). These facades provide a unified interface to interact with the different payment clients and services.

## Table of Contents

- [Sibs Payment Gateway Facades](#sibs-payment-gateway-facades)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
  - [Overview](#overview)
  - [ClientFacade](#clientfacade)
    - [Constructor](#constructor)
    - [Methods](#methods)
    - [Usage Example](#usage-example)
  - [ServiceFacade](#servicefacade)
    - [Constructor](#constructor-1)
    - [Methods](#methods-1)
    - [Usage Example](#usage-example-1)
  - [Supported Providers](#supported-providers)
  - [Folders](#folders)
    - [`/stubs`](#stubs)
    - [`/examples`](#examples)
  - [License](#license)

---

## Installation

Install the package via Composer:

```bash
composer require sibs/payment-gateway-sdk
```

Ensure your project includes the necessary interfaces and provider classes (`DpgClient`, `SpgClient`, `StargateClient`, `DpgService`, `SpgService`, `StargateService`) and configuration implementation (`ConfigAbstract`).

```php
require 'vendor/autoload.php';
```

---

## Overview

The facades simplify interactions with different payment providers by abstracting away the provider-specific client/service implementations.
They support the following common operations:

* Checkout
* Capture
* Refund
* Cancel
* Get transaction status

`ClientFacade` works directly with the payment clients using an `ConfigAbstract`.
`ServiceFacade` works with higher-level service abstractions using an `ConfigAbstract` and `OrderAbstract`.

---

## ClientFacade

`ClientFacade` wraps provider-specific clients (`DpgClient`, `SpgClient`, `StargateClient`) by using `ConfigAbstract` and exposes common payment operations.

### Constructor

```php
use Sibs\PaymentGateway\Adapters\WooCommerce\ConfigAdapter;
use Sibs\PaymentGateway\Constants\Currency;
use Sibs\PaymentGateway\Constants\Environment;
use Sibs\PaymentGateway\Constants\Project;
use Sibs\PaymentGateway\Facades\ClientFacade;
use Sibs\PaymentGateway\Providers\Dpg\Constants\AuthorizationType;
use Sibs\PaymentGateway\Providers\Dpg\Constants\CreditCardType;
use Sibs\PaymentGateway\Providers\Dpg\Constants\PaymentMethod;
use Sibs\PaymentGateway\Providers\Dpg\Constants\PaymentType;

global $wpdb;                                                 // Example from WooCommerce Adapter
$wc_logger = wc_get_logger();                                 // Example from WooCommerce Adapter

$config = new ConfigAdapter(Project::DPG, $wc_logger, $wpdb);
$facade = new ClientFacade($config);
```

### Methods

* `checkout(array $paymentData): array` – Initiates a payment.
* `capture(string $transactionId, array $paymentData): array` – Captures a previously authorized payment.
* `refund(string $transactionId, array $paymentData): array` – Refunds a payment.
* `cancel(string $transactionId, array $paymentData): array` – Cancels a payment.
* `getStatus(string $transactionId, array $paymentData, bool $isCheckout = true): array` – Retrieves the status of a payment.

### Usage Example

```php
$clientFacade = new ClientFacade($config);

$dates = DateHelper::getTimestampUTC('now', 3, DateUnit::DAY);

$paymentBrand = [
    // CreditCardType::AMEX,
    // CreditCardType::MAESTRO,
    // CreditCardType::MASTER,
    // CreditCardType::MASTERDEBIT,
    // CreditCardType::VISA,
    // CreditCardType::VISADEBIT,
    // CreditCardType::VISAELECTRON,
    // CreditCardType::VPAY,
    // PaymentMethod::MBWAY,
    PaymentMethod::MULTIBANCO,
];

$paymentType = PaymentType::DEBIT;

$response = $clientFacade->checkout([
    'amount'                                       => 10.5,
    'currency'                                     => Currency::EUR,
    'paymentBrand'                                 => implode(' ', $paymentBrand),
    'paymentType'                                  => $paymentType,
    'entityId'                                     => $config->getClientId(),
    'testMode'                                     => $config->getTestMode(),
    'merchantTransactionId'                        => 'order123',
    'customParameters[SIBS_ENV]'                   => Environment::QLY,
    'customParameters[authorization_type]'         => AuthorizationType::getByPaymentType($paymentType),
    'customer.givenName'                           => 'John',
    'customer.surname'                             => 'Smith',
    'customer.email'                               => 'john.smith',
    'customer.sex'                                 => 'M',
    'customer.birthDate'                           => '1970-01-01',
    'customer.phone'                               => '+351912345678',
    'customer.mobile'                              => '+351912345678',
    'customer.ip'                                  => $config->getCustomerIp(),
    'billing.street1'                              => 'Example Street',
    'billing.street2'                              => 'Apt. 56B',
    'billing.city'                                 => 'Sample City',
    'billing.postcode'                             => '1000-001',
    'billing.country'                              => 'PT',
    'shipping.street1'                             => 'Example Street',
    'shipping.street2'                             => 'Apt. 56B',
    'shipping.city'                                => 'Sample City',
    'shipping.postcode'                            => '1000-001',
    'shipping.country'                             => 'PT',
    'customParameters[sibsEcommerce]'              => $config->getFramework() . ':' . $config->getFrameworkVersion(),
    'customParameters[sibsPlugin]'                 => $config->getPluginVersion(),
    'customParameters[SIBSMULTIBANCO_PtmntEntty]'  => '10000',
    'customParameters[SIBSMULTIBANCO_RefIntlDtTm]' => $dates->initial,
    'customParameters[SIBSMULTIBANCO_RefLmtDtTm]'  => $dates->final,
]);

$status = $clientFacade->getStatus($response['transaction_id'], []);
```

---

## ServiceFacade

`ServiceFacade` wraps provider-specific services (`DpgService`, `SpgService`, `StargateService`) and works with `ConfigAbstract` and `OrderAbstract` objects, adding higher-level order context to operations.

### Constructor

```php
use Sibs\PaymentGateway\Adapters\WooCommerce\ConfigAdapter;
use Sibs\PaymentGateway\Adapters\WooCommerce\OrderAdapter;
use Sibs\PaymentGateway\Constants\Currency;
use Sibs\PaymentGateway\Constants\DateUnit;
use Sibs\PaymentGateway\Constants\Project;
use Sibs\PaymentGateway\Facades\ServiceFacade;
use Sibs\PaymentGateway\Providers\Dpg\Constants\CreditCardType;
use Sibs\PaymentGateway\Providers\Dpg\Constants\PaymentMethod;
use Sibs\PaymentGateway\Providers\Dpg\Constants\PaymentType;

global $wpdb;                                                 // Example from WooCommerce Adapter
$wc_logger = wc_get_logger();                                 // Example from WooCommerce Adapter

$config = new ConfigAdapter(Project::DPG, $wpdb, $wc_logger);

$wc_order = get_wc_order();                                   // Example from WooCommerce Adapter

$serviceFacade = new ServiceFacade($config);
$order = new OrderAdapter($wc_order);
```

### Methods

* `checkout(OrderAbstract $order, array $extraParameters = []): array`
* `capture(string $transactionId, OrderAbstract $order, array $extraParameters = []): array`
* `refund(string $transactionId, OrderAbstract $order, array $extraParameters = []): array`
* `cancel(string $transactionId, OrderAbstract $order, array $extraParameters = []): array`
* `getStatus(string $transactionId, OrderAbstract $order, array $extraParameters = [], bool $isCheckout = true): array`
* `widget(string $transactionId)`
* `form(array $formParameters)`

### Usage Example

```php
$paymentmethods = [
    // CreditCardType::AMEX,
    // CreditCardType::MAESTRO,
    // CreditCardType::MASTER,
    // CreditCardType::MASTERDEBIT,
    // CreditCardType::VISA,
    // CreditCardType::VISADEBIT,
    // CreditCardType::VISAELECTRON,
    // CreditCardType::VPAY,
    // PaymentMethod::MBWAY,
    PaymentMethod::MULTIBANCO,
];

$response = $serviceFacade->checkout($order, [
    'payment_method'    => $paymentmethods,
    'payment_type'      => PaymentType::DEBIT,
    'amount'            => 10.5,
    'currency'          => Currency::EUR,
    'entity'            => '10000',
    'expiry_date_value' => 3,
    'expiry_date_unit'  => DateUnit::DAY,
]);

$serviceFacade->capture($response['transaction_id'], $order);
```

---

## Supported Providers

* `DPG`
* `SPG`
* `STARGATE`

Each facade will throw an `InvalidArgumentException` if an unknown provider is passed.

---

## Folders

### `/stubs`
Example implementations of contracts (e.g., `DemoOrder`, `DemoTranslator`).  
See [stubs/README.md](stubs/README.md) for details.  

### `/examples`
Ready-to-run code samples for checkout and transaction flows.  
See [examples/README.md](examples/README.md).

---

## License

This package is open-sourced under the MIT license.
