### Install Paymentwall PHP Library via Git

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Clone the Paymentwall PHP library repository using Git to install it in your project.

```bash
git clone git@github.com:paymentwall/paymentwall-php.git
```

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

### Paymentwall Widget Call (Virtual Currency)

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Example of how to initiate a Paymentwall widget for virtual currency transactions.

```APIDOC
## Paymentwall Widget Call (Virtual Currency)

### Description
Initiates a Paymentwall widget for virtual currency transactions. This allows users to purchase virtual currency within your application.

### Method
POST (Implicit via widget rendering)

### Endpoint
`/v1/api/redirect/buy/` (Implicit)

### Parameters
#### Request Body (Implicitly passed to widget)
- **user_id** (string) - Required - The unique identifier of the end-user.
- **widget_code** (string) - Required - The widget code obtained from your Paymentwall merchant account.
- **products** (array) - Optional - An array of products. Leave blank for Virtual Currency API.
- **additional_parameters** (object) - Optional - Additional parameters like user email.
  - **email** (string) - Optional - The email address of the end-user.

### Request Example
```php
$widget = new Paymentwall_Widget(
	'user40012', // id of the end-user who\'s making the payment
	'p1_1',      // widget code, e.g. p1; can be picked inside of your merchant account
	[],     // array of products - leave blank for Virtual Currency API
	['email' => 'user@hostname.com'] // additional parameters
);
echo $widget->getHtmlCode();
```

### Response
Returns HTML code to render the Paymentwall widget.
```

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

### Install Paymentwall PHP Library

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Install the Paymentwall PHP library using Composer. This is the first step before integrating Paymentwall into your PHP application.

```bash
composer require paymentwall/paymentwall-php
```

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

### Initialize Mobiamo Payment (PHP)

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Start a mobile carrier billing payment flow for Mobiamo. Returns instructions for completing the payment via SMS, redirect, or by prompting for a phone number.

```php
<?php
$mobiamo = new Paymentwall_Mobiamo();
$token = $_SESSION['mobiamo_token'];

$response = $mobiamo->initPayment($token, [
    'uid' => 'user123',
    'amount' => 1.00,
    'currency' => 'GBP',
    'country' => 'GB',
    'product_id' => 'coins_100',
    'product_name' => '100 Gold Coins',
    'msisdn' => '447821677123',      // Optional: user's phone number
    'carrier' => '19',                // Optional: carrier ID
    'mcc' => '234',                   // Optional: mobile country code
    'mnc' => '10',                    // Optional: mobile network code
    // Optional: recurring subscription
    'is_recurring' => 1,
    'period' => 'w',                  // d=day, w=week, m=month
    'period_value' => 1
]);

if (!empty($response['success'])) {
    $ref = $response['ref'];          // Store for process step
    $flow = $response['flow'];        // code, msisdn, pinless, or redirect

    switch ($flow) {
        case 'code':
        case 'pinless':
            // User sends SMS with keyword to shortcode
            echo "Send '{$response['instructions']['keyword']}' to {$response['instructions']['shortcode']}";
            break;
        case 'redirect':
            // Redirect user to carrier's payment page
            header('Location: ' . $response['instructions']['redirect_url']);
            break;
        case 'msisdn':
            // Prompt user for phone number
            echo 'Please enter your phone number';
            break;
    }
} else {
    echo 'Error: ' . $response['error'];
}
?>
```

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

### Paymentwall Widget Call (Cart API - Stored Products)

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Example of initiating a Paymentwall widget for cart transactions when products are stored in Paymentwall.

```APIDOC
## Cart API - Widget Call (Stored Products)

### Description
Initiates a Paymentwall widget for cart transactions where products are pre-defined and stored within your Paymentwall merchant account.

### Method
POST (Implicit via widget rendering)

### Endpoint
`/v1/api/cart/build` (Implicit)

### Parameters
#### Request Body (Implicitly passed to widget)
- **user_id** (string) - Required - The unique identifier of the end-user.
- **widget_code** (string) - Required - The widget code obtained from your Paymentwall merchant account.
- **products** (array of Paymentwall_Product objects) - Required - An array containing `Paymentwall_Product` objects, each representing an item in the cart.
  - **product_id** (string) - Required - The unique identifier of the product.
  - **amount** (float) - Required - The price of the product.
  - **currency** (string) - Required - The currency of the product (e.g., 'EUR').
- **additional_parameters** (object) - Optional - Additional parameters.
  - **email** (string) - Optional - The email address of the end-user.

### Request Example
```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_CART,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$widget = new Paymentwall_Widget(
	'user40012', // id of the end-user who\'s making the payment
	'p1_1',      // widget code, e.g. p1; can be picked inside of your merchant account,
	[
		new Paymentwall_Product('product301', 3.33, 'EUR'), // first product in cart
		new Paymentwall_Product('product607', 7.77, 'EUR')  // second product in cart
	],
	['email' => 'user@hostname.com'] // additional params
);
echo $widget->getHtmlCode();
```

### Response
Returns HTML code to render the Paymentwall widget.
```

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

### Configure Paymentwall Library for Virtual Currency API

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Configure the Paymentwall library for the Virtual Currency API using your project and secret keys. This setup is for in-app currency transactions.

```php
// Virtual Currency API Configuration
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### Paymentwall Widget Call (Cart API - Non-Stored Products)

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Example of initiating a Paymentwall widget for cart transactions when products are not stored in Paymentwall.

```APIDOC
## Cart API - Widget Call (Non-Stored Products)

### Description
Initiates a Paymentwall widget for cart transactions where product details are provided dynamically and are not pre-stored in Paymentwall. This is useful for flexible cart configurations.

### Method
POST (Implicit via widget rendering)

### Endpoint
`/v1/api/cart/build` (Implicit)

### Parameters
#### Request Body (Implicitly passed to widget)
- **user_id** (string) - Required - The unique identifier of the end-user.
- **widget_code** (string) - Required - The widget code obtained from your Paymentwall merchant account.
- **products** (array of Paymentwall_Product objects) - Required - An array containing `Paymentwall_Product` objects, each representing an item in the cart.
  - **product_id** (string) - Required - The unique identifier of the product.
  - **amount** (float) - Required - The price of the product.
  - **currency** (string) - Required - The currency of the product (e.g., 'EUR').
  - **product_name** (string) - Optional - The display name of the product.
- **additional_parameters** (object) - Optional - Additional parameters.
  - **email** (string) - Optional - The email address of the end-user.
  - **flexible_cart_api** (integer) - Required - Set to `1` to enable non-stored product mode.

### Request Example
```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_CART,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$widget = new Paymentwall_Widget(
	'user40012', // id of the end-user who\'s making the payment
	'p1_1',      // widget code, e.g. p1; can be picked inside of your merchant account,
	[
		new Paymentwall_Product('product301', 3.33, 'EUR', 'Product 1'), // first product in cart
		new Paymentwall_Product('product607', 7.77, 'EUR', 'Product 2')  // second product in cart
	],
	['email' => 'user@hostname.com', 'flexible_cart_api' => 1] // additional params
);
echo $widget->getHtmlCode();
```

### Response
Returns HTML code to render the Paymentwall widget.
```

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

### GET /getPaymentInfo (Get Payment Info)

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Retrieves the current status and details of a specific payment transaction.

```APIDOC
## GET /getPaymentInfo

### Description
Retrieves detailed information about a payment transaction using the user ID and reference ID.

### Request Body
- **uid** (string) - Required - User ID
- **ref** (string) - Required - Reference ID returned from init request

### Request Example
{
	"uid": "test",
	"ref": "w118678712"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **completed** (boolean) - Indicates if the payment was successful
- **amount** (number) - Payment amount
- **currency** (string) - Currency code
- **country** (string) - Country code
- **product_name** (string) - Name of the product
- **msisdn** (string) - User phone number
- **ref** (string) - Reference ID

#### Response Example
{
	"success": true,
	"completed": true,
	"amount": 1,
	"currency": "GBP",
	"country": "GB",
	"product_name": "test_product_name",
	"msisdn": "447821677123",
	"ref": "w118678712"
}
```

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

### Generate Paymentwall Widget HTML Code

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Create an instance of Paymentwall_Widget to generate HTML code for embedding the Paymentwall payment page. This example includes product details for a subscription.

```php
$widget = new Paymentwall_Widget(
	'user40012',
	'pw',
	[
		new Paymentwall_Product(
			'product301',
			9.99,
			'USD',
			'Gold Membership',
			Paymentwall_Product::TYPE_SUBSCRIPTION,
			1,
			Paymentwall_Product::PERIOD_TYPE_MONTH,
			true
		)
  	],
	['email' => 'user@hostname.com']
);
echo $widget->getHtmlCode();
```

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

### Get Mobiamo Authentication Token (PHP)

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Obtain an authentication token for Mobiamo mobile carrier billing API calls. The token is required for subsequent payment initialization.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$mobiamo = new Paymentwall_Mobiamo();
$response = $mobiamo->getToken([
    'uid' => 'user123'
]);

if (!empty($response['success'])) {
    $token = $response['token'];
    $expireTime = $response['expire_time']; // seconds until expiration (default 86400)

    // Store token for subsequent API calls
    $_SESSION['mobiamo_token'] = $token;
} else {
    echo 'Error: ' . $response['error'];
    echo 'Code: ' . $response['code'];
}
?>
```

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

### Get Mobiamo Token

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Obtain a token from Mobiamo for subsequent payment operations. The token is valid for a default of 86400 seconds. Store the token and its expiration time for future use.

```php
$model = new Paymentwall_Mobiamo();
$tokenParams = [
	'uid' => 'test'
]
$response = $model->getToken($tokenParams);
if (!empty($response['success'])) {
	//store this token and expire time (default is 86400s) to use in all next requests
	//example of success response:
		[
			'success' => 1, 
			'token' => 'randomString',
			'expire_time' => 86400
		]
	var_dump($response['token']);
	var_dump($response['expire_time']);
} else {
	var_dump($response['error']);
	var_dump($response['code']);
}
```

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

### Get Mobiamo Payment Information

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Retrieves details about a specific Mobiamo payment using the user ID and reference ID. This is useful for checking the status and details of a completed or pending payment.

```php
$model = new Paymentwall_Mobiamo();
$getPaymentParams = [
	'uid' => 'test', 
	'ref' => 'w118678712', //reference id returned from init request 
];
//token returned from get token step above
$response = $model->processPayment($token, $getPaymentParams);
if (!empty($response['success'])) {
	/** example of success response: 
		[
			'success' => true,
			'completed' => true, //value: true/false - indicate this payment was already successfull or not
			'amount' => 1,
			'currency' => "GBP",
			'country' => "GB",
			'product_name' => "test_product_name",
			'msisdn' => "447821677123",
			'ref' => "w118678712"
		]
	*/
} else {
	var_dump($response['error']);
	var_dump($response['code']);
}
```

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

### Initialize Paymentwall Configuration

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Set up your Paymentwall API keys. This must be done before making any API calls.

```php
Paymentwall_Config::getInstance()->set([
	'public_key' => 'YOUR_PROJECT_KEY',
	'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### POST /mobiamo/init

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Initializes a payment process through Mobiamo.

```APIDOC
## POST /mobiamo/init

### Description
Initializes a payment session using a previously obtained token.

### Request Body
- **uid** (string) - Required - User ID
- **amount** (float) - Required - Payment amount
- **currency** (string) - Required - ISO 4217 currency code
- **country** (string) - Required - ISO alpha-2 country code
- **product_id** (int) - Required - Product ID
- **product_name** (string) - Required - Product name
- **msisdn** (string) - Optional - User phone number
- **carrier** (string) - Optional - Operator ID
- **mcc** (string) - Optional - Mobile country code
- **mnc** (string) - Optional - Mobile network code
- **is_recurring** (int) - Optional - 1 for recurring, 0 otherwise
- **period** (string) - Required if recurring - Billing period
- **period_value** (int) - Required if recurring - Period value

### Response
#### Success Response (200)
- **success** (boolean) - Status indicator
- **ref** (string) - Payment reference ID
- **flow** (string) - Payment flow type
- **price** (object) - Price details
- **instructions** (object) - Payment instructions
```

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

### Create Brick Subscription in PHP

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Initializes a recurring subscription with optional trial period settings.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY'
]);

$subscription = new Paymentwall_Subscription();
$subscription->create([
    'token' => $_POST['brick_token'],
    'email' => $_POST['email'],
    'currency' => 'USD',
    'amount' => 19.99,
    'fingerprint' => $_POST['brick_fingerprint'],
    'plan' => 'premium_monthly',
    'description' => 'Premium Monthly Subscription',
    'period' => 'month',              // day, week, month, year
    'period_duration' => 1,
    // Optional trial period
    'trial[amount]' => 0.99,
    'trial[currency]' => 'USD',
    'trial[period]' => 'week',
    'trial[period_duration]' => 1
]);

if ($subscription->isSuccessful()) {
    $subscriptionId = $subscription->getId();
    $isActive = $subscription->isActive();
    $isTrial = $subscription->isTrial();

    echo json_encode([
        'success' => true,
        'subscription_id' => $subscriptionId,
        'is_trial' => $isTrial
    ]);
}
```

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

### Initialize Brick API

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Configures the library for Brick API usage.

```php
Paymentwall_Config::getInstance()->set([
	'public_key' => 'YOUR_PUBLIC_KEY',
	'private_key' => 'YOUR_PRIVATE_KEY'
]);
```

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

### Create a Subscription

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Use this to create a new subscription. Ensure you provide all required parameters like token, email, currency, amount, and plan details. The fingerprint is required if the token is generated via brick.js.

```php
$subscription = new Paymentwall_Subscription();
$subscription->create([
	// if generated via backend
	//'token' => $token->getToken(),
	// if generated via brick.js
	'token' => $_POST['brick_token'],
	'email' => $_POST['email'],
	'currency' => 'USD',
	'amount' => 10,
	'fingerprint' => $_POST['brick_fingerprint'],
	'plan' => 'product_123',
	'description' => 'Order #123',
	'period' => 'week',
	'period_duration' => 2,
	// if trial, add following parameters
	'trial[amount]' => 1,
	'trial[currency]' => 'USD',
	'trial[period]'   => 'month',
	'trial[period_duration]' => 1
]);

echo $subscription->getId();
```

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

### Brick API - Initialization

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Initializes the Paymentwall library for Brick API usage.

```APIDOC
## Brick API - Initialization

### Description
Initializes the Paymentwall library with the necessary configuration for using the Brick API, which handles card payments.

### Method
N/A (Configuration step)

### Endpoint
N/A

### Parameters
#### Configuration Settings
- **public_key** (string) - Required - Your Paymentwall public key.
- **private_key** (string) - Required - Your Paymentwall private key.
```

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

### Initialize Mobiamo Payment

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Initiate a Mobiamo payment with detailed parameters. This includes amount, currency, product information, and optional recurring subscription details. The 'token' obtained from the previous step is required.

```php
$model = new Paymentwall_Mobiamo();
$initParams = [
	'uid' => 'test', 
	'amount' => 1, 
	'currency' => 'GBP', //currency of payment in ISO 4217 format
	'country' => 'GB', //country of payment in ISO alpha-2 format
	'product_id' => 123, //product id of payment
	'product_name' => 'test_product_name', //product name of payment
	'msisdn' => '447821677123', //optional - phone number of user in internaltional format
	'carrier' => '19', //mandatory in some countries - Given id of user's operator
	'mcc' => '262', //optional - mobile country code of user
	'mnc' => '007', //optional - mobile netword code of user
	'is_recurring' => 1, //optional and only available in some countries - value: 1/0 - determine if this payment is recurring subscription
	'period' => 'd', //mandatory if is_recurring = 1 - value: d (day) - w (week) - m (month) - period of the recurring
	'period_value' => 1 //mandatory if is_recurring = 1 - value: positive number - value of the recurring period
];
//token returned from get token step above
$response = $model->initPayment($token, $initParams);
if (!empty($response['success'])) {
	/** example of success response: 
		[
			'success' => true,
			'ref' => 'w118678712', //reference id of payment.
			'flow' => 'code', //next flow of this payment. values can be: code/pinless - user send sms contain keyword to shortcode in instructions/ msisdn - user input phone number / redirect - redirect user to redirect_url in intructions
			'price' => [
				'amount' => 1,
				'currency' => 'GBP',
				'formatted' => 'GBP 1.00',
				'carriers' => [
				      0 => [
					    'id' => 19,
					    'name' => 'O2',
					  ],
				],
			],
			'instructions' => [
				'keyword' => 'test_keyword', //return if flow = code/pinless - sms message content for user to send
				'shortcode' => '123456', //return if flow = code/pinless - the number user should send message to
				'redirect_url' => 'http://google.com' //return if flow = redirect - url user should be redirected to
			]
			'product_name' => 'test_product_name',
		]
	*/
	//Store the parameter ref
} else {
	var_dump($response['error']);
	var_dump($response['code']);
}
```

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

### Initialize Cart API

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Configures the library for Cart API usage.

```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_CART,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### Initialize Paymentwall for Virtual Currency API

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Configure the Paymentwall library for the Virtual Currency API by setting the API type, public key, and private key. Ensure the path to the paymentwall.php file is correct.

```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### Initialize Paymentwall for Digital Goods API

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Configure the Paymentwall library for the Digital Goods API by setting the API type, public key, and private key. Ensure the path to the paymentwall.php file is correct.

```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### POST /subscription

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Creates a new subscription using a token generated via backend or brick.js.

```APIDOC
## POST /subscription

### Description
Creates a new subscription for a user.

### Request Body
- **token** (string) - Required - Token generated via brick.js or backend
- **email** (string) - Required - User email
- **currency** (string) - Required - ISO currency code
- **amount** (float) - Required - Subscription amount
- **fingerprint** (string) - Required - Brick fingerprint
- **plan** (string) - Required - Product plan ID
- **description** (string) - Optional - Order description
- **period** (string) - Required - Billing period (e.g., week)
- **period_duration** (int) - Required - Duration of the period
- **trial[amount]** (float) - Optional - Trial amount
- **trial[currency]** (string) - Optional - Trial currency
- **trial[period]** (string) - Optional - Trial period
- **trial[period_duration]** (int) - Optional - Trial period duration

### Response
#### Success Response (200)
- **id** (string) - The created subscription ID
```

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

### Define One-Time Product for Paymentwall

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create a one-time product definition for use in Paymentwall payment widgets. Specify the product ID, price, currency, and name.

```php
<?php
// One-time product
$product = new Paymentwall_Product(
    'product_123',
    9.99,
    'USD',
    'Premium Package'
);
```

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

### Paymentwall Cart API Initialization

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Initializes the Paymentwall library for Cart API usage.

```APIDOC
## Cart API - Initialization

### Description
Initializes the Paymentwall PHP library with the necessary configuration for using the Cart API.

### Method
N/A (Configuration step)

### Endpoint
N/A

### Parameters
#### Configuration Settings
- **api_type** (string) - Required - Set to `Paymentwall_Config::API_CART`.
- **public_key** (string) - Required - Your Paymentwall public key.
- **private_key** (string) - Required - Your Paymentwall private key.
```

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

### Define Subscription Product for Paymentwall

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create a subscription product definition for Paymentwall, including recurring billing details. Specify product ID, price, currency, name, type, period length, period type, and recurrence.

```php
// Subscription product with monthly recurring billing
$subscriptionProduct = new Paymentwall_Product(
    'gold_membership',
    19.99,
    'USD',
    'Gold Membership',
    Paymentwall_Product::TYPE_SUBSCRIPTION,
    1,
    Paymentwall_Product::PERIOD_TYPE_MONTH,
    true
);
```

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

### Charge via Brick

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Executes a charge using a token and handles the response.

```php
$charge = new Paymentwall_Charge();
$charge->create([
	// if generated via backend
	//'token' => $token->getToken(),
	// if generated via brick.js
	'token' => $_POST['brick_token'],
	'email' => $_POST['email'],
	'currency' => 'USD',
	'amount' => 10,
	'fingerprint' => $_POST['brick_fingerprint'],
	'description' => 'Order #123'
]);

$response = $charge->getPublicData();

if ($charge->isSuccessful()) {
	if ($charge->isCaptured()) {
		// deliver s product
	} elseif ($charge->isUnderReview()) {
		// decide on risk charge
	}
} else {
	$errors = json_decode($response, true);
	echo $errors['error']['code'];
	echo $errors['error']['message'];
}

echo $response; // need for JS communication
```

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

### Generate Virtual Currency Widget

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Creates a widget instance for Virtual Currency transactions.

```php
$widget = new Paymentwall_Widget(
	'user40012', // id of the end-user who's making the payment
	'p1_1',      // widget code, e.g. p1; can be picked inside of your merchant account
	[],     // array of products - leave blank for Virtual Currency API
	['email' => 'user@hostname.com'] // additional parameters
);
echo $widget->getHtmlCode();
```

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

### Generate Virtual Currency Widget

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create a virtual currency widget. This is used for in-game currency or other virtual goods where no specific products are pre-defined. An empty products array is used.

```php
// Virtual Currency Widget (empty products array)
$vcWidget = new Paymentwall_Widget(
    'user40012',
    'p1_1',
    [],
    ['email' => 'user@example.com']
);
echo $vcWidget->getHtmlCode();
```

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

### Manage Brick Charges in PHP

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Performs lifecycle operations on existing charges such as refunds, voids, captures, and retrieving details.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY'
]);

// Refund a charge
$charge = new Paymentwall_Charge('CHARGE_ID_HERE');
$charge->refund();

if ($charge->isRefunded()) {
    echo 'Refund successful';
} else {
    echo 'Refund failed';
}

// Void an uncaptured charge
$charge = new Paymentwall_Charge('CHARGE_ID_HERE');
$charge->void();

// Capture a held charge
$charge = new Paymentwall_Charge('CHARGE_ID_HERE');
$charge->capture();

// Get charge details
$charge = new Paymentwall_Charge('CHARGE_ID_HERE');
$charge->get();
$chargeData = $charge->getProperties();
```

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

### POST /subscription

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create recurring subscriptions with automatic billing.

```APIDOC
## POST /subscription

### Description
Create recurring subscriptions with automatic billing using Brick. Supports trial periods with different pricing.

### Request Body
- **token** (string) - Required - Token from brick.js
- **email** (string) - Required - Customer email
- **currency** (string) - Required - Currency code
- **amount** (float) - Required - Subscription amount
- **plan** (string) - Required - Plan identifier
- **period** (string) - Required - Billing interval (day, week, month, year)
- **period_duration** (integer) - Required - Duration of the period
- **trial[amount]** (float) - Optional - Trial amount
- **trial[currency]** (string) - Optional - Trial currency
- **trial[period]** (string) - Optional - Trial period unit
- **trial[period_duration]** (integer) - Optional - Trial period duration
```

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

### Calculate Widget Signature (PHP)

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Manually calculate signatures for widget URLs. Supports MD5 (v1, deprecated), MD5 (v2), and SHA256 (v3, default) hashing algorithms.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$widgetSignatureModel = new Paymentwall_Signature_Widget();

// Version 1 - MD5 of uid + secret key (deprecated)
$signatureV1 = $widgetSignatureModel->calculate(
    ['uid' => 'user123'],
    Paymentwall_Signature_Abstract::VERSION_ONE
);

// Version 2 - MD5 of sorted params + secret key
$signatureV2 = $widgetSignatureModel->calculate(
    [
        'key' => 'YOUR_PROJECT_KEY',
        'uid' => 'user123',
        'widget' => 'pw',
        'amount' => '9.99',
        'currencyCode' => 'USD'
    ],
    Paymentwall_Signature_Abstract::VERSION_TWO
);

// Version 3 - SHA256 of sorted params + secret key (default)
$signatureV3 = $widgetSignatureModel->calculate(
    [
        'key' => 'YOUR_PROJECT_KEY',
        'uid' => 'user123',
        'widget' => 'pw',
        'amount' => '9.99',
        'currencyCode' => 'USD'
    ],
    Paymentwall_Signature_Abstract::VERSION_THREE
);
?>
```

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

### Configure Paymentwall Library for Digital Goods API

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Configure the Paymentwall library for the Digital Goods API using your project and secret keys. Ensure the correct API type is set.

```php
<?php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');

// Digital Goods API Configuration
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);
```

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

### Generate Digital Goods Widget

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create a digital goods widget for subscriptions. Use this when selling recurring services. Ensure all required product and customer details are provided.

```php
<?php
// Digital Goods Widget with subscription product
$widget = new Paymentwall_Widget(
    'user40012',                        // User ID
    'pw',
    [
        new Paymentwall_Product(
            'product301',
            9.99,
            'USD',
            'Gold Membership',
            Paymentwall_Product::TYPE_SUBSCRIPTION,
            1,
            Paymentwall_Product::PERIOD_TYPE_MONTH,
            true
        )
    ],
    [
        'email' => 'user@example.com',
        'customer[firstname]' => 'John',
        'customer[lastname]' => 'Doe'
    ]
);

// Get widget URL for redirect
$widgetUrl = $widget->getUrl();

// Get HTML iframe code with custom dimensions
echo $widget->getHtmlCode([
    'width' => '100%',
    'height' => '600',
    'frameborder' => '0'
]);
```

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

### POST /charge

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Create a new credit card charge using a token generated by brick.js.

```APIDOC
## POST /charge

### Description
Create charges to process credit card payments using tokens. Supports full capture, risk review handling, and 3D Secure authentication.

### Request Body
- **token** (string) - Required - Token from brick.js
- **email** (string) - Required - Customer email
- **currency** (string) - Required - Currency code (e.g., USD)
- **amount** (float) - Required - Charge amount
- **fingerprint** (string) - Required - Fingerprint from brick.js
- **description** (string) - Optional - Charge description
- **customer[firstname]** (string) - Optional - Customer first name
- **customer[lastname]** (string) - Optional - Customer last name
- **customer[ip]** (string) - Optional - Customer IP address
- **customer[country]** (string) - Optional - Customer country code

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **charge_id** (string) - Unique identifier for the charge
- **status** (string) - Status of the charge (e.g., pending_review)
```

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

### Check Paymentwall Test Mode

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Check if the Paymentwall library is currently configured to run in test mode. This is determined by the format of the public and private keys.

```php
// Check if running in test mode (keys starting with 't_')
$isTest = Paymentwall_Config::getInstance()->isTest();
```

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

### Process Brick Charge in PHP

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Creates a charge using a token from brick.js and handles successful captures, risk reviews, and 3D Secure redirects.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY'
]);

$charge = new Paymentwall_Charge();
$charge->create([
    'token' => $_POST['brick_token'],       // Token from brick.js
    'email' => $_POST['email'],
    'currency' => 'USD',
    'amount' => 10.00,
    'fingerprint' => $_POST['brick_fingerprint'],
    'description' => 'Order #12345',
    'customer[firstname]' => 'John',
    'customer[lastname]' => 'Doe',
    'customer[ip]' => $_SERVER['REMOTE_ADDR'],
    'customer[country]' => 'US'
]);

$response = $charge->getPublicData();
$responseData = json_decode($response, true);

if ($charge->isSuccessful()) {
    $chargeId = $charge->getId();
    $card = $charge->getCard();

    if ($charge->isCaptured()) {
        // Payment captured, deliver product
        echo json_encode([
            'success' => true,
            'charge_id' => $chargeId
        ]);
    } elseif ($charge->isUnderReview()) {
        // Payment under risk review, wait for pingback
        echo json_encode([
            'success' => true,
            'status' => 'pending_review'
        ]);
    }
} else {
    // Handle error
    $errors = json_decode($response, true);
    echo json_encode([
        'success' => false,
        'error_code' => $errors['error']['code'],
        'error_message' => $errors['error']['message']
    ]);
}

// Handle 3D Secure if required
$publicData = $charge->_getPublicData();
if (isset($publicData['secure'])) {
    // Return 3DS form to client for bank redirect
    echo $publicData['secure']['formHTML'];
}
```

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

### Brick API - Create One-Time Token

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Creates a one-time token for a card payment using the Brick API.

```APIDOC
## Brick API - Create One-Time Token

### Description
Generates a secure, one-time-use token for a credit card. This token can then be used to process a charge without directly handling sensitive card details.

### Method
POST (Implicit via `Paymentwall_OneTimeToken::create()`)

### Endpoint
`/v1/brick/token` (Implicit)

### Parameters
#### Request Body
- **public_key** (string) - Required - Your Paymentwall public key.
- **card[number]** (string) - Required - The credit card number.
- **card[exp_month]** (string) - Required - The expiration month of the card (e.g., '11').
- **card[exp_year]** (string) - Required - The expiration year of the card (e.g., '19').
- **card[cvv]** (string) - Required - The Card Verification Value (CVV).

### Request Example
```php
$tokenModel = new Paymentwall_OneTimeToken();
$token =  $tokenModel->create([
	'public_key' => Paymentwall_Config::getInstance()->getPublicKey(),
	'card[number]' => '4242424242424242',
	'card[exp_month]' => '11',
	'card[exp_year]' => '19',
	'card[cvv]' => '123'
]);
// The token can be retrieved using $token->getToken();
```

### Response
- **token** (object) - An object containing the generated token and its details.
  - **token** (string) - The one-time token.
  - **exp_month** (integer) - Expiration month.
  - **exp_year** (integer) - Expiration year.
  - **type** (string) - Card type (e.g., 'visa').
```

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

### Create One-Time Token for Brick

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Generates a token for Brick charges. Use brick.js client-side for production to ensure PCI compliance.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PUBLIC_KEY',
    'private_key' => 'YOUR_PRIVATE_KEY'
]);

// Server-side tokenization (use brick.js for production)
$tokenModel = new Paymentwall_OneTimeToken();
$token = $tokenModel->create([
    'public_key' => Paymentwall_Config::getInstance()->getPublicKey(),
    'card[number]' => '4242424242424242',
    'card[exp_month]' => '12',
    'card[exp_year]' => '25',
    'card[cvv]' => '123'
]);

// Access token properties
$tokenString = $token->getToken();
$expiresIn = $token->getExpirationTime();
$isActive = $token->isActive();
$isTest = $token->isTest();
```

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

### Create Brick One-Time Token

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Generates a secure token for card processing.

```php
$tokenModel = new Paymentwall_OneTimeToken();
$token =  $tokenModel->create([
	'public_key' => Paymentwall_Config::getInstance()->getPublicKey(),
	'card[number]' => '4242424242424242',
	'card[exp_month]' => '11',
	'card[exp_year]' => '19',
	'card[cvv]' => '123'
]);
// send token to charge via $token->getToken();
```

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

### POST /refund

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Manage existing charges including refunds, voids, and captures.

```APIDOC
## POST /refund

### Description
Issue refunds for previously captured charges, void uncaptured charges, or capture held charges using the charge ID.

### Parameters
#### Path Parameters
- **charge_id** (string) - Required - The unique identifier of the charge to modify
```

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

### Process Virtual Currency Pingback

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Validates and handles pingback requests for Virtual Currency API.

```php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate(true)) {
  $virtualCurrency = $pingback->getVirtualCurrencyAmount();
  if ($pingback->isDeliverable()) {
  // deliver the virtual currency
  } else if ($pingback->isCancelable()) {
  // withdraw the virtual currency
  } else if ($pingback->isUnderReview()) {
  // set "pending" status to order
  }
  echo 'OK'; // Paymentwall expects response to be OK, otherwise the pingback will be resent
} else {
  echo $pingback->getErrorSummary();
}
```

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

### Calculate Pingback Signature (PHP)

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Verify pingback signatures or generate signatures for testing webhook implementations. Supports v2 (MD5) and v3 (SHA256) signature versions.

```php
<?php
Paymentwall_Config::getInstance()->set([
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$pingbackSignatureModel = new Paymentwall_Signature_Pingback();

// Calculate signature for pingback verification
$signature = $pingbackSignatureModel->calculate(
    [
        'uid' => 'user123',
        'goodsid' => 'product301',
        'type' => '0',
        'ref' => 'ref123456'
    ],
    Paymentwall_Signature_Abstract::VERSION_TWO
);

// Version 3 uses SHA256
$signatureV3 = $pingbackSignatureModel->calculate(
    [
        'uid' => 'user123',
        'goodsid' => 'product301',
        'type' => '0',
        'ref' => 'ref123456',
        'sign_version' => '3'
    ],
    Paymentwall_Signature_Abstract::VERSION_THREE
);
?>
```

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

### Calculate Widget Signature

Source: https://github.com/paymentwall/paymentwall-php/blob/master/README.md

Calculate a signature for Paymentwall widgets. This is used to ensure the integrity of widget parameters.

```php
$widgetSignatureModel = new Paymentwall_Signature_Widget();
echo $widgetSignatureModel->calculate(
	[], // widget params
	2 // signature version
);
```

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

### Handle Paymentwall Pingbacks

Source: https://context7.com/paymentwall/paymentwall-php/llms.txt

Validates and processes incoming webhook notifications for different API types. Always respond with 'OK' to acknowledge receipt.

```php
<?php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');

Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_GOODS,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);

// Validate pingback (true = skip IP whitelist check for testing)
if ($pingback->validate(true)) {
    // Get payment details
    $userId = $pingback->getUserId();
    $referenceId = $pingback->getReferenceId();
    $product = $pingback->getProduct();
    $productId = $product->getId();

    // Handle different pingback types
    if ($pingback->isDeliverable()) {
        // Types: REGULAR (0), GOODWILL (1), RISK_REVIEWED_ACCEPTED (201)
        // Deliver the product to user
        deliverProduct($userId, $productId);
    } else if ($pingback->isCancelable()) {
        // Types: NEGATIVE (2), RISK_REVIEWED_DECLINED (202)
        // Revoke access or process refund
        revokeProduct($userId, $productId);
    } else if ($pingback->isUnderReview()) {
        // Type: RISK_UNDER_REVIEW (200)
        // Set order status to pending review
        setOrderPending($userId, $referenceId);
    }

    // Get pingback type for detailed handling
    $type = $pingback->getType();
    switch ($type) {
        case Paymentwall_Pingback::PINGBACK_TYPE_SUBSCRIPTION_CANCELLATION: // 12
            cancelSubscription($userId);
            break;
        case Paymentwall_Pingback::PINGBACK_TYPE_SUBSCRIPTION_EXPIRED: // 13
            expireSubscription($userId);
            break;
        case Paymentwall_Pingback::PINGBACK_TYPE_SUBSCRIPTION_PAYMENT_FAILED: // 14
            notifyPaymentFailed($userId);
            break;
    }

    // REQUIRED: Respond with OK to acknowledge receipt
    echo 'OK';
} else {
    // Log validation error
    echo $pingback->getErrorSummary();
}

// Virtual Currency API Pingback
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$vcPingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($vcPingback->validate(true)) {
    $currencyAmount = $vcPingback->getVirtualCurrencyAmount();
    // Credit virtual currency to user account
    echo 'OK';
}

// Cart API Pingback - Multiple products
Paymentwall_Config::getInstance()->set([
    'api_type' => Paymentwall_Config::API_CART,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
]);

$cartPingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($cartPingback->validate(true)) {
    $products = $cartPingback->getProducts();
    foreach ($products as $product) {
        deliverProduct($cartPingback->getUserId(), $product->getId());
    }
    echo 'OK';
}
```