### AliPay Payment Setup

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Details on setting up payments via AliPay, including required parameters and product information.

```APIDOC
## AliPay Payment Setup

- **$payer**: Your payer object, must implement `AliPayPayerInterface` from the package.
- **$numberOfProducts**: The number of items in this order (integer).
- **$product1**: The first item (implementing `AliPayProductInterface`).
- **$product2**: The second item (implementing `AliPayProductInterface`).

```php
$info = new AliPayBasicInfo($merchantId, $notifyUrl, $order, $payer, $numberOfProducts);
$info = new EnableAliPay($info);

$info = new AliPayProduct($info, 1, $product1);
$info = new AliPayProduct($info, 2, $product2);
```

```

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

### Multi-functional Payment Setup

Source: https://github.com/fall1600/newebpay/blob/master/README.md

This section covers setting up multi-functional payments, enabling various payment methods like credit cards, installments, barcode payments, Google Pay, and Web ATM. It also includes handling offline payments and setting return/cancel URLs.

```APIDOC
## Create Transaction Information (BasicInfo)

- **$merchantId**: Your merchant ID with Newebpay.
- **$notifyUrl**: Callback URL to receive Newebpay payment notifications.
- **$order**: Your order object, must implement `OrderInterface` from the package.
- **$payer**: Your payer object, must implement `PayerInterface` from the package.

```php
$info = new BasicInfo($merchantId, $notifyUrl, $order, $payer);
```

## Enable Payment Methods

Enable payment methods as needed.

```php
// Enable Credit Card
$info = new EnableCredit($info);
// Enable 3, 6, 12 installments
$info = new PayInInstallments($info, '3,6,12');
// Enable Convenience Store Barcode Payment
$info = new EnableBarcode($info);
// Enable Google Pay
$info = new EnableGooglePay($info);
// Enable Web ATM
$info = new EnableWebAtm($info);
// For non-real-time transactions, set the callback URL for Newebpay to notify payment information and the payment deadline.
$info = new OfflinePay($info, $customerUrl, $ttl);
// URL to redirect to after payment completion on Newebpay
$info = new PayComplete($info, $returnUrl);
// Page to redirect to when the customer presses 'back' on the payment page
$info = new PayCancel($info, $clientBackUrl);

// Refer to the document for a mapping of payment methods.
```

## Create NewebPay Object and Initiate Checkout

- **$merchantId**: Your merchant ID with Newebpay.
- **$hashKey**: Your exclusive HashKey with Newebpay.
- **$hashIv**: Your exclusive Hash IV with Newebpay.

```php
$newebpay = new NewebPay();
$newebpay
    ->setIsProduction(false) // Set environment, defaults to production
    ->setMerchant(new Merchant($merchantId, $hashKey, $hashIv))
    ->checkout($info);
```

## Implement OrderInterface

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\OrderInterface;

class Order implements OrderInterface
{
    // your order detail...
}
```

## Implement PayerInterface

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\PayerInterface;

class Member implements PayerInterface
{
    // your member detail...
}
```

## Process Transaction Notifications from Newebpay

```php
$isValid = $merchant->setRawData($request->all())->validateResponse(); // Proceed if true

// The response object encapsulates the notification transaction results. Common methods include:
$response = $merchant->getResponse();
// Payment success or failure
$response->getStatus();
// Get transaction serial number
$response->getTradeNo();
// Get order number, which is getMerchantOrderNo() from OrderInterface implementation
$response->getMerchantOrderNo();
// Payment time
$response->getPayTime();
```

```

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

### Recurring Credit Card Payment Setup

Source: https://github.com/fall1600/newebpay/blob/master/README.md

This section details how to set up recurring credit card payments using the Newebpay API. It covers creating transaction information, adding optional URLs, and initializing the NewebPay object with merchant details.

```APIDOC
## Create Transaction Information (BasicInfo)

- **$order**: Your order object, must implement `OrderInterface` from the package.
- **$contact**: Your contact object, must implement `ContactInterface` from the package.
- **$periodStartType**: Checks card number pattern, refer to document p.13.
- **$version**: Integration version.
  - If version 1.0 is used, the [last three digits of the back] will be a required field.
  - If version 1.1 is used, the [last three digits of the back] will be an optional field.

```php
$info = new \fall1600\Package\Newebpay\Info\Period\BasicInfo($order, $payer, $periodStartType, $version);
```

## Optional Parameters

```php
$info = new ReturnUrl($info, 'https://your.return.url');
$info = new NotifyUrl($info, 'https://your.notify.url');
$info = new BackUrl($info, 'https://your.back.url');
$info = new Memo($info, 'your memo here');
```

## Create NewebPay Object and Issue Recurring Payment

- **$merchantId**: Your merchant ID with Newebpay.
- **$hashKey**: Your exclusive HashKey with Newebpay.
- **$hashIv**: Your exclusive Hash IV with Newebpay.

```php
$newebpay = new NewebPay();
$newebpay
    ->setIsProduction(false) // Set environment, defaults to production
    ->setMerchant(new Merchant($merchantId, $hashKey, $hashIv))
    ->issue($info);
```

## Implement OrderInterface

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\Period\OrderInterface;

class Order implements OrderInterface
{
    // your order detail...
}
```

## Implement ContactInterface

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\Period\ContactInterface;

class Member implements ContactInterface
{
    // your member detail...
}
```

## URL Definitions

| Name          | Purpose                                     | Setting Object | Notes                                                                                                |
|---------------|---------------------------------------------|----------------|------------------------------------------------------------------------------------------------------|
| ReturnURL     | URL to return to after initial credit card authorization is complete | ReturnUrl      | If not set, displayed on Newebpay.                                                                   |
| NotifyURL     | Notification URL for each authorization result | NotifyUrl      | Notifies the merchant of the authorization result for each credit card transaction; if empty, no notification will be sent. |
| BackURL       | URL to return to when canceling a transaction | BackUrl        | If not set, displayed on Newebpay.                                                                   |

```

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

### Configure Credit Card Installments with PayInInstallments

Source: https://context7.com/fall1600/newebpay/llms.txt

Use the PayInInstallments decorator to control which credit card installment terms are offered. Set `$instFlag` to '1' for all terms, '0' to disable, or a comma-separated string like '3,6,12' for specific terms.

```php
use fall1600\Package\Newebpay\Info\Decorator\EnableCredit;
use fall1600\Package\Newebpay\Info\Decorator\PayInInstallments;

$info = new BasicInfo('MS123456789', 'https://yoursite.com/notify', $order, $payer);
$info = new EnableCredit($info);

// Offer 3, 6, and 12-month installments
$info = new PayInInstallments($info, '3,6,12');
// Adds: 'InstFlag' => '3,6,12'

// Open all installment options
$info = new PayInInstallments($info, '1');

// Disable installments explicitly
$info = new PayInInstallments($info, '0');
```

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

### NewebPay Constants for Encryption, Language, and Period Types

Source: https://context7.com/fall1600/newebpay/llms.txt

Use these constants to configure encryption methods, payment page languages, and recurring payment statuses and start behaviors. Ensure correct constants are used for desired functionality.

```php
use fall1600\Package\Newebpay\Constants\Cipher;
use fall1600\Package\Newebpay\Constants\LanguageType;
use fall1600\Package\Newebpay\Constants\Period\AlterType;
use fall1600\Package\Newebpay\Constants\Period\PeriodStartType;
use fall1600\Package\Newebpay\Constants\Period\VersionType;
use fall1600\Package\Newebpay\NewebPay;

// Encryption algorithm
Cipher::METHOD;               // 'AES-256-CBC'

// Payment page language
LanguageType::ZH_TW;          // 'zh-tw'  — Traditional Chinese (default)
LanguageType::EN;             // 'en'     — English
LanguageType::JP;             // 'JP'     — Japanese

// Recurring mandate status changes
AlterType::SUSPEND;           // 'suspend'   — pause authorisations
AlterType::RESTART;           // 'restart'   — resume paused mandate
AlterType::TERMINATE;         // 'terminate' — permanently cancel (cannot restart)

// Recurring mandate start behaviour
PeriodStartType::_1;          // '1' — immediately auth NTD 10, then auto-void
PeriodStartType::_2;          // '2' — immediately auth the full periodic amount
PeriodStartType::_3;          // '3' — no immediate auth; first auth on schedule

// Period API protocol version
VersionType::V1_0;            // '1.0' — CVV is mandatory
VersionType::V1_1;            // '1.1' — CVV is optional
```

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

### Enable Payment Methods for Multi-functional Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Chain objects to enable specific payment methods like credit cards, installments, barcode, Google Pay, or Web ATM. Use OfflinePay for non-real-time transactions and PayComplete/PayCancel for redirect URLs.

```php
// 啟用信用卡
$info = new EnableCredit($info);
// 啟用3, 6, 12 期分期付款
$info = new PayInInstallments($info, '3,6,12');
// 啟用超商條碼
$info = new EnableBarcode($info);
// 啟用Google Pay
$info = new EnableGooglePay($info);
// 啟用Web ATM
$info = new EnableWebAtm($info);
// 搭配非即時交易, 設定藍新通知付款資訊的callback url, 以及繳費期限
$info = new OfflinePay($info, $customerUrl, $ttl);
// 在藍新交易完成後導回的網址
$info = new PayComplete($info, $returnUrl);
// 設定讓消費者在付款頁按下返回時可以回導的頁面
$info = new PayCancel($info, $clientBackUrl);
```

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

### Initialize NewebPay Facade

Source: https://context7.com/fall1600/newebpay/llms.txt

Sets up the Merchant instance and NewebPay facade. Configure production/sandbox environment and optionally set a custom HTML form ID.

```php
use fall1600\Package\Newebpay\NewebPay;
use fall1600\Package\Newebpay\Merchant;

$merchant = new Merchant('MS123456789', 'hashKey32chars__________________', 'hashIV16chars___');

$newebpay = new NewebPay();
$newebpay
    ->setIsProduction(false)   // true (default) = production; false = sandbox
    ->setMerchant($merchant)
    ->setFormId('my-pay-form'); // optional: customise the HTML form's id attribute
```

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

### Configure AliPay Payment with Product Details

Source: https://context7.com/fall1600/newebpay/llms.txt

Use AliPayBasicInfo as the base for AliPay payments and wrap it with EnableAliPay and AliPayProduct decorators for each product. This requires custom Payer and ProductItem classes implementing specific interfaces.

```php
use fall1600\Package\Newebpay\Info\AliPayBasicInfo;
use fall1600\Package\Newebpay\Info\Decorator\AliPayProduct;
use fall1600\Package\Newebpay\Info\Decorator\EnableAliPay;
use fall1600\Package\Newebpay\Contracts\AliPayPayerInterface;
use fall1600\Package\Newebpay\Contracts\AliPayProductInterface;

class AliPayPayer implements AliPayPayerInterface
{
    public function getEmail(): string    { return 'buyer@example.com'; }
    public function getReceiver(): string { return 'Wang Xiaohua'; }
    public function getTel1(): string     { return '0912345678'; }   // primary phone
    public function getTel2(): string     { return '0223456789'; }   // secondary phone
}

class ProductItem implements AliPayProductInterface
{
    public function __construct(
        private int $id, private string $title,
        private string $desc, private int $price, private int $qty
    ) {}
    public function getProductId(): int     { return $this->id; }
    public function getTitle(): string      { return $this->title; }
    public function getDescription(): string{ return $this->desc; }
    public function getPrice(): int         { return $this->price; }
    public function getQuantity(): int      { return $this->qty; }
}

$payer  = new AliPayPayer();
$prod1  = new ProductItem(1001, 'Widget A', 'Blue widget', 500, 2);
$prod2  = new ProductItem(1002, 'Widget B', 'Red widget',  750, 1);

$info = new AliPayBasicInfo(
    'MS123456789',
    'https://yoursite.com/notify',
    $order,   // implements Contracts\OrderInterface
    $payer,
    2         // total number of distinct product types
);
$info = new EnableAliPay($info);          // adds 'ALIPAY' => 1
$info = new AliPayProduct($info, 1, $prod1); // adds Pid1, Title1, Desc1, Price1, Qty1
$info = new AliPayProduct($info, 2, $prod2); // adds Pid2, Title2, Desc2, Price2, Qty2
```

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

### Configure AliPay Payment Basic Info

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Set up the AliPayBasicInfo object for Alipay payments, including payer, product details, and quantity. Ensure the payer implements AliPayPayerInterface and products implement AliPayProductInterface.

```php
$info = new AliPayBasicInfo($merchantId, $notifyUrl, $order, $payer, $numberOfProducts);
$info = new EnableAliPay($info);

$info = new AliPayProduct($info, 1, $product1);
$info = new AliPayProduct($info, 2, $product2);
```

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

### Initialize NewebPay for Multi-functional Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Set up the NewebPay object with merchant credentials and the configured transaction information. Use setIsProduction(false) for testing.

```php
$newebpay = new NewebPay();
$newebpay
    ->setIsProduction(false) // 設定環境, 預設就是走正式機
    ->setMerchant(new Merchant($merchantId, $hashKey, $hashIv))
    ->checkout($info);
```

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

### Initialize NewebPay for Recurring Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Set up the NewebPay object with your merchant credentials and the prepared transaction information. Use setIsProduction(false) to test in a non-production environment.

```php
$newebpay = new NewebPay();
$newebpay
    ->setIsProduction(false) // 設定環境, 預設就是走正式機
    ->setMerchant(new Merchant($merchantId, $hashKey, $hashIv))
    ->issue($info);
```

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

### Implement BasicInfo for NewebPay Transactions

Source: https://context7.com/fall1600/newebpay/llms.txt

Implement the OrderInterface and PayerInterface in your domain objects. Then, build the BasicInfo object with mandatory fields like MerchantID, NotifyURL, and order/payer details.

```php
use fall1600\Package\Newebpay\Info\BasicInfo;
use fall1600\Package\Newebpay\Contracts\OrderInterface;
use fall1600\Package\Newebpay\Contracts\PayerInterface;

// ── 1. Implement the two required interfaces in your domain ──

class MyOrder implements OrderInterface
{
    public function __construct(
        private int    $amt,
        private string $orderNo,
        private string $itemDesc
    ) {}

    public function getAmt(): int          { return $this->amt; }
    public function getMerchantOrderNo(): string { return $this->orderNo; }
    public function getItemDesc(): string  { return $this->itemDesc; }
}

class MyPayer implements PayerInterface
{
    public function __construct(private string $email) {}
    public function getEmail(): string { return $this->email; }
}

// ── 2. Build BasicInfo ──
$order = new MyOrder(1500, 'ORD-20240115-001', 'Widget × 3');
$payer = new MyPayer('buyer@example.com');

$info = new BasicInfo(
    'MS123456789',                           // MerchantID
    'https://yoursite.com/newebpay/notify',  // NotifyURL (server callback)
    $order,
    $payer
);

// $info->getInfo() produces:
// [
//   'MerchantID'      => 'MS123456789',
//   'RespondType'     => 'JSON',
//   'TimeStamp'       => 1705291800,
//   'Version'         => '2.3',
//   'NotifyURL'       => 'https://yoursite.com/newebpay/notify',
//   'Amt'             => 1500,
//   'ItemDesc'        => 'Widget × 3',
//   'MerchantOrderNo' => 'ORD-20240115-001',
//   'Email'           => 'buyer@example.com',
// ]
```

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

### Set Up Recurring Payments with NewebPay PHP SDK

Source: https://context7.com/fall1600/newebpay/llms.txt

Use `PeriodBasicInfo` and decorators to configure recurring payments. Ensure `PeriodOrderInterface` and `ContactInterface` are implemented. The `PeriodStartType` constant determines immediate card verification.

```php
use fall1600\Package\Newebpay\Info\Period\BasicInfo as PeriodBasicInfo;
use fall1600\Package\Newebpay\Info\Period\Decorator\ReturnUrl;
use fall1600\Package\Newebpay\Info\Period\Decorator\NotifyUrl;
use fall1600\Package\Newebpay\Info\Period\Decorator\BackUrl;
use fall1600\Package\Newebpay\Info\Period\Decorator\Memo;
use fall1600\Package\Newebpay\Constants\Period\PeriodStartType;
use fall1600\Package\Newebpay\Constants\Period\VersionType;
use fall1600\Package\Newebpay\Contracts\Period\OrderInterface as PeriodOrderInterface;
use fall1600\Package\Newebpay\Contracts\Period\ContactInterface;

class SubscriptionOrder implements PeriodOrderInterface
{
    public function getMerOrderNo(): string  { return 'SUB-2024-001'; }
    public function getAmount(): int         { return 299; }           // TWD per cycle
    public function getProdDesc(): string    { return 'Monthly Premium Plan'; }
    public function getPeriodType(): string  { return 'M'; }           // D/W/M/Y
    public function getPeriodPoint(): string { return '01'; }          // 1st of each month
    public function getPeriodTimes(): string { return '12'; }          // 12 billing cycles
}

class SubscriberContact implements ContactInterface
{
    public function getPayerEmail(): string       { return 'sub@example.com'; }
    public function getPayerEmailModify(): int    { return 0; }   // 0=locked, 1=editable
    public function getPaymentInfo(): string      { return 'Y'; } // show payment info form
    public function getOrderInfo(): string        { return 'N'; } // hide shipping form
}

$subOrder   = new SubscriptionOrder();
$subscriber = new SubscriberContact();

$info = new PeriodBasicInfo(
    $subOrder,
    $subscriber,
    PeriodStartType::_1,    // verify card with NTD 10 auth then auto-void
    VersionType::V1_1       // CVV non-mandatory
);

// Optional URL decorators
$info = new ReturnUrl($info, 'https://yoursite.com/subscription/success');
$info = new NotifyUrl($info, 'https://yoursite.com/subscription/notify');
$info = new BackUrl($info,   'https://yoursite.com/subscription/cancel');
$info = new Memo($info,      'Monthly subscription — thank you!');

// Dispatch to NewebPay
$newebpay = new \fall1600\Package\Newebpay\NewebPay();
$newebpay
    ->setIsProduction(false)
    ->setMerchant(new \fall1600\Package\Newebpay\Merchant('MS123456789', 'key32chars______________________', 'iv_16chars______'))
    ->issue($info);  // echoes self-submitting HTML page
```

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

### NewebPay Facade Methods

Source: https://context7.com/fall1600/newebpay/llms.txt

This section details the various methods available on the NewebPay facade for different payment scenarios.

```APIDOC
## NewebPay Facade

The `NewebPay` facade is the primary entry point for interacting with the NewebPay service. It allows for various payment operations, including generating HTML for redirects, creating form fragments, and handling API-based transactions.

### Methods

#### `checkout($info)`

**Description**: Outputs a complete self-submitting HTML page for redirecting users to the NewebPay payment gateway.

**Method**: POST (implicitly via HTML form submission)

**Endpoint**: N/A (generates HTML)

**Parameters**: 
- `$info`: An object containing payment details.

**Request Example**: 
```php
$newebpay->checkout($info);
```

#### `generateForm($info)`

**Description**: Returns only the HTML `<form>` fragment for the payment, useful when you control the surrounding page layout.

**Method**: N/A (generates HTML fragment)

**Endpoint**: N/A

**Parameters**: 
- `$info`: An object containing payment details.

**Response**: 
- Returns an HTML string representing the form.

**Request Example**: 
```php
$formHtml = $newebpay->generateForm($info);
```

#### `checkoutForApi($info)`

**Description**: Skips HTML generation and returns an array containing the payment URL and form parameters, intended for headless or API consumers.

**Method**: N/A (returns data structure)

**Endpoint**: N/A

**Parameters**: 
- `$info`: An object containing payment details.

**Response**: 
- `array`: Contains `url` and `form_params` keys.
  - `url` (string): The NewebPay gateway URL.
  - `form_params` (array): Key-value pairs for the form submission.

**Request Example**: 
```php
$params = $newebpay->checkoutForApi($info);
```

#### `query($order)`

**Description**: Performs a server-side trade-status lookup using the provided order information.

**Method**: POST (implicitly)

**Endpoint**: N/A (server-side lookup)

**Parameters**: 
- `$order`: An object implementing `Contracts\OrderInterface`.

**Response**: 
- Returns a decoded JSON array from NewebPay's `QueryTradeInfo` endpoint.

**Request Example**: 
```php
$queryResult = $newebpay->query($order);
```

#### `issue($periodInfo)`

**Description**: Renders a self-submitting HTML page for initiating periodic (recurring) charges.

**Method**: POST (implicitly via HTML form submission)

**Endpoint**: N/A (generates HTML)

**Parameters**: 
- `$periodInfo`: A composed `Info\Period\BasicInfo` object.

**Request Example**: 
```php
$newebpay->issue($periodInfo);
```

#### `alterAmt($merOrderNo, $periodNo, $periodType, $periodPoint, $newAmount)`

**Description**: Modifies the amount of an existing recurring mandate.

**Method**: POST (implicitly)

**Endpoint**: N/A (server-side modification)

**Parameters**: 
- `MerOrderNo` (string): Your order number.
- `PeriodNo` (string): NewebPay's mandate number.
- `PeriodType` (string): Type of period ('D', 'W', 'M', 'Y').
- `PeriodPoint` (string): Specific point within the period (e.g., day of month, weekday, MMDD).
- `newAmount` (int|null): The new amount in TWD. Use `null` to keep the current amount.

**Response**: 
- Returns the result of the alteration operation.

**Request Example**: 
```php
$result = $newebpay->alterAmt('ORDER-2024-001', 'PERIOD-NO-789', 'M', '15', 1500);
```

#### `alterStatus($merOrderNo, $periodNo, $alterType)`

**Description**: Modifies the status of an existing recurring mandate (e.g., suspend, restart, terminate).

**Method**: POST (implicitly)

**Endpoint**: N/A (server-side modification)

**Parameters**: 
- `MerOrderNo` (string): Your order number.
- `PeriodNo` (string): NewebPay's mandate number.
- `alterType` (AlterType): The desired status change (e.g., `AlterType::SUSPEND`, `AlterType::RESTART`, `AlterType::TERMINATE`).

**Response**: 
- Returns the result of the status alteration operation.

**Request Example**: 
```php
$result = $newebpay->alterStatus('ORDER-2024-001', 'PERIOD-NO-789', AlterType::SUSPEND);
```
```

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

### Set Redirect URLs with PayComplete and PayCancel Decorators

Source: https://context7.com/fall1600/newebpay/llms.txt

Use PayComplete to set the ReturnURL for successful payments and PayCancel to set the ClientBackURL for when the buyer clicks 'Cancel' or 'Back'. Without these, the buyer remains on the NewebPay-hosted result page.

```php
use fall1600\Package\Newebpay\Info\Decorator\PayComplete;
use fall1600\Package\Newebpay\Info\Decorator\PayCancel;

$info = new BasicInfo('MS123456789', 'https://yoursite.com/notify', $order, $payer);
$info = new EnableCredit($info);

$info = new PayComplete($info, 'https://yoursite.com/orders/success');
// Adds: 'ReturnURL' => 'https://yoursite.com/orders/success'

$info = new PayCancel($info, 'https://yoursite.com/cart');
// Adds: 'ClientBackURL' => 'https://yoursite.com/cart'
```

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

### Enable Credit Card Token Binding with EnableCredit and QuickCreditInterface

Source: https://context7.com/fall1600/newebpay/llms.txt

When EnableCredit is used with a QuickCreditInterface object, it enables NewebPay's fast-checkout card-binding feature by adding TokenTerm and TokenTermDemand fields. Implement QuickCreditInterface on a model representing the buyer's saved card token.

```php
use fall1600\Package\Newebpay\Contracts\QuickCreditInterface;
use fall1600\Package\Newebpay\Info\Decorator\EnableCredit;

class SavedCard implements QuickCreditInterface
{
    public function __construct(
        private string $memberEmail,   // used as binding key
        private int    $demand          // 1=expiry+CVV, 2=expiry only, 3=CVV only
    ) {}

    public function getTokenTerm(): string { return $this->memberEmail; }
    public function getTokenTermDemand(): int { return $this->demand; }
}

$info = new BasicInfo('MS123456789', 'https://yoursite.com/notify', $order, $payer);

$savedCard = new SavedCard('buyer@example.com', 1);
$info = new EnableCredit($info, $savedCard);
// Adds: 'CREDIT' => 1, 'TokenTerm' => 'buyer@example.com', 'TokenTermDemand' => 1
```

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

### Configure Optional URLs for Recurring Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Chain optional URL configurations like ReturnUrl, NotifyUrl, and BackUrl to the BasicInfo object. These URLs handle post-authorization redirects and notifications.

```php
$info = new ReturnUrl($info, 'https://your.return.url');
$info = new NotifyUrl($info, 'https://your.notify.url');
$info = new BackUrl($info, 'https://your.back.url');
$info = new Memo($info, 'your memo here');
```

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

### Merchant Credentials and Response Handling in PHP

Source: https://context7.com/fall1600/newebpay/llms.txt

Instantiate the Merchant class with your NewebPay credentials. Use setRawData() to process incoming payment notifications and validateResponse() to verify their authenticity. Access parsed response data via getResponse().

```php
use fall1600\Package\Newebpay\Merchant;
use fall1600\Package\Newebpay\Exceptions\TradeInfoException;

// Instantiate with NewebPay-issued credentials
$merchant = new Merchant(
    'MS123456789',                         // MerchantID
    'abcdefghijklmnopqrstuvwxyz012345',    // HashKey (32 chars)
    '1234567890abcdef'                     // HashIV  (16 chars)
);

// ── Receiving a payment notification (POST callback from NewebPay) ──
// $_POST will contain 'TradeInfo' (AES encrypted) and 'TradeSha' (SHA256 checksum)
try {
    $merchant->setRawData($_POST);         // decrypts TradeInfo internally
} catch (TradeInfoException $e) {
    // missing TradeInfo/TradeSha keys, or decryption padding error
    http_response_code(400);
    exit('invalid callback');
}

// Verify the notification really came from NewebPay
if (! $merchant->validateResponse()) {
    http_response_code(403);
    exit('checksum mismatch');
}

$response = $merchant->getResponse();
echo $response->getStatus();          // "SUCCESS" or error code
echo $response->getMessage();         // human-readable result message
echo $response->getMerchantOrderNo(); // your own order number
echo $response->getTradeNo();         // NewebPay's transaction serial number
echo $response->getAmt();             // (int) charged amount in TWD
echo $response->getPaymentType();     // "CREDIT", "WEBATM", "CVS", etc.
echo $response->getPayTime();         // "2024-01-15 10:30:00"
echo $response->getIp();              // buyer's IP at checkout
echo $response->getExpireDate();      // "2024-01-22" for offline payments (ATM/CVS)
echo $response->getEscrowBank();      // escrow bank code
// Full raw decoded array if you need non-standard fields:
$all = $response->getData();          // ['Status'=>'SUCCESS','Message'=>'...','Result'=>[]]

// ── Switch to a different merchant in the same request ──
$merchant->reset('MS987654321', 'newHashKey32chars___________', 'newHashIV16chars');

```

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

### Enable Payment Channels with Decorators

Source: https://context7.com/fall1600/newebpay/llms.txt

Extend InfoDecorator to enable specific payment channels by merging keys into the payload. Decorators are chainable and can be disabled by passing false as the second argument.

```php
use fall1600\Package\Newebpay\Info\BasicInfo;
use fall1600\Package\Newebpay\Info\Decorator\EnableCredit;
use fall1600\Package\Newebpay\Info\Decorator\EnableWebAtm;
use fall1600\Package\Newebpay\Info\Decorator\EnableVacc;
use fall1600\Package\Newebpay\Info\Decorator\EnableCvs;
use fall1600\Package\Newebpay\Info\Decorator\EnableBarcode;
use fall1600\Package\Newebpay\Info\Decorator\EnableLinePay;
use fall1600\Package\Newebpay\Info\Decorator\EnableEzPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableGooglePay;
use fall1600\Package\Newebpay\Info\Decorator\EnableApplePay;
use fall1600\Package\Newebpay\Info\Decorator\EnableSamsungPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableAndroidPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableUnionPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableAmericanExpress;
use fall1600\Package\Newebpay\Info\Decorator\EnableTaiwanPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableBitoPay;
use fall1600\Package\Newebpay\Info\Decorator\EnableCvsCom;
use fall1600\Package\Newebpay\Info\Decorator\EnableEzpalipay;
use fall1600\Package\Newebpay\Info\Decorator\EnableEzpwechat;
use fall1600\Package\Newebpay\Info\Decorator\EnableEsunwallet;
use fall1600\Package\Newebpay\Info\Decorator\EnableTwqr;
use fall1600\Package\Newebpay\Info\Decorator\EnableCreditBonus;

$info = new BasicInfo('MS123456789', 'https://yoursite.com/notify', $order, $payer);

// ── Credit card (instant) ──
$info = new EnableCredit($info);            // adds 'CREDIT' => 1

// ── Web ATM (instant) ──
$info = new EnableWebAtm($info);            // adds 'WEBATM' => 1

// ── ATM bank transfer (non-instant) ──
$info = new EnableVacc($info);              // adds 'VACC' => 1

// ── Convenience store code payment (non-instant, NTD 30–20,000) ──
$info = new EnableCvs($info);               // adds 'CVS' => 1

// ── Convenience store barcode (non-instant, NTD 20–40,000) ──
$info = new EnableBarcode($info);           // adds 'BARCODE' => 1

// ── LINE Pay (instant) ──
$info = new EnableLinePay($info);           // adds 'LINEPAY' => 1

// ── ezPay wallet (instant + non-instant) ──
$info = new EnableEzPay($info);             // adds 'P2G' => 1

// ── Google Pay ──
$info = new EnableGooglePay($info);         // adds 'GOOGLEPAY' => 1

// ── Disable a channel (pass false as second argument) ──
$info = new EnableCredit($info, false);     // adds 'CREDIT' => 0
```

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

### Create Multi-functional Payment Basic Info

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Instantiate the BasicInfo object for multi-functional payments, providing merchant ID, notification URL, and order/payer objects. Ensure your Order and Payer objects implement the respective interfaces.

```php
$info = new BasicInfo($merchantId, $notifyUrl, $order, $payer);
```

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

### API-Friendly Checkout with NewebPay

Source: https://context7.com/fall1600/newebpay/llms.txt

Skips HTML generation and returns an array with `url` and `form_params`. Intended for headless/API consumers, such as a frontend SPA that will POST the data itself.

```php
// ── API-friendly: get POST parameters as array (no HTML) ──
$params = $newebpay->checkoutForApi($info);
// [
//   'url' => 'https://ccore.newebpay.com/MPG/mpg_gateway',
//   'form_params' => [
//     'MerchantID' => 'MS123456789',
//     'TradeInfo'  => '<AES-hex>',
//     'TradeSha'   => '<SHA256>',
//     'Version'    => '2.3',
//   ],
// ]
```

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

### Implement Order Interface for Multi-functional Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Your order class must implement the OrderInterface from the Newebpay package for multi-functional payment processing.

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\OrderInterface;

class Order implements OrderInterface
{
    // your order detail...
}
```

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

### Implement Order Interface for Recurring Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Your order class must implement the OrderInterface from the Newebpay package to be compatible with the recurring payment system.

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\Period\OrderInterface;

class Order implements OrderInterface
{
    // your order detail...
}
```

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

### HTML Redirect Checkout with NewebPay

Source: https://context7.com/fall1600/newebpay/llms.txt

Outputs a complete self-submitting HTML page for redirecting users to NewebPay for checkout. Assumes `$info` is a fully composed Info object.

```php
// ── HTML redirect checkout ──
// (assumes $info is a fully composed Info object — see BasicInfo section)
$newebpay->checkout($info);    // echoes a full HTML page that auto-submits the form
```

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

### Generate NewebPay Form Fragment

Source: https://context7.com/fall1600/newebpay/llms.txt

Returns only the HTML `<form>` fragment for NewebPay transactions. Useful when you control the surrounding layout. The form is initially hidden.

```php
// ── Get only the <form> fragment ──
$formHtml = $newebpay->generateForm($info);
// <form name="newebpay" id="my-pay-form" method="post"
//       action="https://ccore.newebpay.com/MPG/mpg_gateway" style="display:none;">
//     <input type="text" name="MerchantID"  value="MS123456789" .../>
//     <input type="text" name="TradeInfo"   value="<AES-hex>" .../>
//     <input type="text" name="TradeSha"    value="<SHA256>" .../>
//     <input type="text" name="Version"     value="2.3" .../>
// </form>
```

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

### Server-Side Trade Status Query with NewebPay

Source: https://context7.com/fall1600/newebpay/llms.txt

Performs a server-side trade-status lookup using NewebPay's QueryTradeInfo endpoint. The `$order` object must implement `Contracts\OrderInterface`.

```php
// ── Server-side trade status query ──
// $order must implement Contracts\OrderInterface
$queryResult = $newebpay->query($order);
// Returns decoded JSON array from NewebPay's QueryTradeInfo endpoint
```

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

### NewebPay API Version and Endpoint URLs

Source: https://context7.com/fall1600/newebpay/llms.txt

These constants define the NewebPay API version and the endpoint URLs for various services in both test and production environments. Use the appropriate URL based on your current environment.

```php
// NewebPay API version (MPG)
NewebPay::VERSION;            // '2.3'

// Endpoint URLs
NewebPay::CHECKOUT_URL_TEST;           // 'https://ccore.newebpay.com/MPG/mpg_gateway'
NewebPay::CHECKOUT_URL_PRODUCTION;     // 'https://core.newebpay.com/MPG/mpg_gateway'
NewebPay::QUERY_URL_TEST;              // 'https://ccore.newebpay.com/API/QueryTradeInfo'
NewebPay::QUERY_URL_PRODUCTION;        // 'https://core.newebpay.com/API/QueryTradeInfo'
NewebPay::ISSUE_URL_TEST;              // 'https://ccore.newebpay.com/MPG/period'
NewebPay::ISSUE_URL_PRODUCTION;        // 'https://core.newebpay.com/MPG/period'
NewebPay::ALTER_STATUS_URL_TEST;       // 'https://ccore.newebpay.com/MPG/period/AlterStatus'
NewebPay::ALTER_STATUS_URL_PRODUCTION; // 'https://core.newebpay.com/MPG/period/AlterStatus'
NewebPay::ALTER_AMT_URL_TEST;          // 'https://ccore.newebpay.com/MPG/period/AlterAmt'
NewebPay::ALTER_AMT_URL_PRODUCTION;    // 'https://core.newebpay.com/MPG/period/AlterAmt'
```

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

### Issue New Recurring Mandate with NewebPay

Source: https://context7.com/fall1600/newebpay/llms.txt

Renders a self-submitting page for initiating periodic (recurring) charges. The `$periodInfo` must be a composed `Info\Period\BasicInfo` object.

```php
// ── Issue a new recurring mandate (redirects to NewebPay period page) ──
// $periodInfo is a composed Info\Period\BasicInfo object
$newebpay->issue($periodInfo); // echoes self-submitting HTML
```

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

### Create Recurring Payment Basic Info

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Instantiate the BasicInfo object for recurring credit card payments. Ensure your Order and Contact objects implement the respective interfaces. The version parameter affects the requirement for the CVV.

```php
$info = new \fall1600\Package\Newebpay\Info\Period\BasicInfo($order, $payer, $periodStartType, $version);
```

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

### Implement Contact Interface for Recurring Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Your payer class (e.g., Member) must implement the ContactInterface from the Newebpay package for recurring payment processing.

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\Period\ContactInterface;

class Member implements ContactInterface
{
    // your member detail...
}
```

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

### Single Transaction Query

Source: https://github.com/fall1600/newebpay/blob/master/README.md

How to perform a single transaction query using the Newebpay API.

```APIDOC
## Single Transaction Query

```php
$resp = $newebpay
    ->setMerchant($merchant)
    ->query($order);
```

```

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

### Implement Payer Interface for Multi-functional Payments

Source: https://github.com/fall1600/newebpay/blob/master/README.md

Your payer class (e.g., Member) must implement the PayerInterface from the Newebpay package for multi-functional payment processing.

```php
<?php

namespace Your\Namespace;

use fall1600\Package\Newebpay\Contracts\PayerInterface;

class Member implements PayerInterface
{
    // your member detail...
}
```

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

### Merchant Class - Handling Credentials and Callbacks

Source: https://context7.com/fall1600/newebpay/llms.txt

The Merchant class manages NewebPay credentials and processes incoming payment notifications. It handles decryption of trade information and validation of response checksums.

```APIDOC
## Merchant Class - Handling Credentials and Callbacks

### Description
Manages merchant credentials (ID, HashKey, HashIV), handles decryption of AES-256-CBC encrypted trade information from NewebPay callbacks, and validates the SHA-256 checksum to ensure authenticity.

### Instantiation
```php
use fall1600\Package\Newebpay\Merchant;

$merchant = new Merchant(
    'MS123456789',                         // MerchantID
    'abcdefghijklmnopqrstuvwxyz012345',    // HashKey (32 chars)
    '1234567890abcdef'                     // HashIV  (16 chars)
);
```

### Receiving and Validating Payment Notifications
```php
use fall1600\Package\Newebpay\Exceptions\TradeInfoException;

// Assume $_POST contains 'TradeInfo' and 'TradeSha' from NewebPay
try {
    $merchant->setRawData($_POST); // Decrypts TradeInfo internally
} catch (TradeInfoException $e) {
    // Handle decryption or missing data errors
    http_response_code(400);
    exit('invalid callback');
}

if (! $merchant->validateResponse()) {
    // Handle checksum mismatch
    http_response_code(403);
    exit('checksum mismatch');
}

$response = $merchant->getResponse();
// Access response data:
// echo $response->getStatus();
// echo $response->getMerchantOrderNo();
// echo $response->getAmt();
// ... and other methods to retrieve transaction details
```

### Switching Merchant Credentials
```php
// Useful when a single process handles multiple merchants
$merchant->reset('MS987654321', 'newHashKey32chars___________', 'newHashIV16chars');
```

### Response Object Methods
- **getStatus()**: Returns the transaction status (e.g., "SUCCESS").
- **getMessage()**: Returns a human-readable message about the transaction result.
- **getMerchantOrderNo()**: Returns your internal order number.
- **getTradeNo()**: Returns the NewebPay transaction serial number.
- **getAmt()**: Returns the charged amount in TWD (integer).
- **getPaymentType()**: Returns the payment method used (e.g., "CREDIT", "WEBATM").
- **getPayTime()**: Returns the payment timestamp (e.g., "2024-01-15 10:30:00").
- **getIp()**: Returns the buyer's IP address at checkout.
- **getExpireDate()**: Returns the expiry date for offline payments (e.g., "2024-01-22").
- **getEscrowBank()**: Returns the escrow bank code.
- **getData()**: Returns the full raw decoded array of all trade information.
```

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

### Enforce Trade Limit and Control Payer Email Editing

Source: https://context7.com/fall1600/newebpay/llms.txt

Use the TradeLimit decorator to set a countdown timer for payment (1-900 seconds) and PayerEmailEditable to control if the buyer can edit their email address.

```php
use fall1600\Package\Newebpay\Info\Decorator\TradeLimit;
use fall1600\Package\Newebpay\Info\Decorator\PayerEmailEditable;

$info = new BasicInfo('MS123456789', 'https://yoursite.com/notify', $order, $payer);

// Buyer must pay within 5 minutes (300 seconds)
$info = new TradeLimit($info, 300);
// Adds: 'TradeLimit' => 300

// Lock the email field so the buyer cannot change it
$info = new PayerEmailEditable($info, false);
// Adds: 'EmailModify' => 0
```