From 306f4ca6f21f4570bbacaa5fb6b6c84bf38bd41d Mon Sep 17 00:00:00 2001
From: Jaafar <mostafajaafar9869@gmail.com>
Date: Thu, 6 Aug 2026 13:06:49 +0300
Subject: [PATCH] feat: add optional iframe param to invoices->create

Adds an optional `iframe` field to the v2 init request. Passing
`'iframe' => true` enables embedded (iframe) checkout. Like
`payment_mode`, the field is sent in the request body but excluded
from the HMAC signature (unsigned).

- Register `iframe` FieldSpec (signed: false) in invoiceCreate()
- Add unit test proving it lands in the body but not the signature
- Document the param in the README quick start
- Bump version 0.1.0 -> 0.2.0 and add CHANGELOG entry
---
 CHANGELOG.md                      |  9 +++++++++
 README.md                         | 14 ++++++++++++++
 src/Core/Internal/FieldOrders.php |  1 +
 src/Core/Version.php              |  2 +-
 tests/SignRequestTest.php         | 13 +++++++++++++
 5 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 222e584..bc12e20 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,14 @@ All notable changes to this package are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-08-06
+
+### Added
+
+- Optional `iframe` param on `invoices->create` — pass `'iframe' => true` to enable
+  embedded (iframe) checkout. Like `payment_mode`, it is sent in the request body but
+  excluded from the HMAC signature.
+
 ## [0.1.0] - 2026-08-04
 
 ### Added
@@ -18,4 +26,5 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - PSR-3 logging with secret masking, and optional auto-discovered Laravel
   integration (service provider, `Paylink` facade, publishable config).
 
+[0.2.0]: https://github.com/GetPayin-Tech/paylink-php/releases/tag/v0.2.0
 [0.1.0]: https://github.com/GetPayin-Tech/paylink-php/releases/tag/v0.1.0
diff --git a/README.md b/README.md
index 962b93a..1a66f2b 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,20 @@ $checkout = $paylink->invoices->create([
 header('Location: '.$checkout['checkoutUrl']);
 ```
 
+Pass `'iframe' => true` to enable embedded (iframe) checkout instead of a full-page redirect:
+
+```php
+$checkout = $paylink->invoices->create([
+    'firstName'   => 'John',
+    'lastName'    => 'Doe',
+    'email'       => 'john@example.com',
+    'orderTitle'  => 'Gold Plan',
+    'orderAmount' => '250.00',
+    'currency'    => 'USD',
+    'iframe'      => true,       // embed the returned checkout URL in an <iframe>
+]);
+```
+
 Request parameters are passed as `camelCase` arrays; results come back as `camelCase` arrays.
 
 > Using Laravel? Don't construct the client by hand — **inject** the configured `PaylinkClient` from the container instead. See [Using it inside Laravel](#using-it-inside-laravel).
diff --git a/src/Core/Internal/FieldOrders.php b/src/Core/Internal/FieldOrders.php
index 1994461..d998ca8 100644
--- a/src/Core/Internal/FieldOrders.php
+++ b/src/Core/Internal/FieldOrders.php
@@ -39,6 +39,7 @@ public static function invoiceCreate(): EndpointSpec
             new FieldSpec('webhookUrl', 'webhook_url'),
             new FieldSpec('orderDetails', 'order_details'),
             new FieldSpec('paymentMode', 'payment_mode', signed: false),
+            new FieldSpec('iframe', 'iframe', signed: false),
         ]);
     }
 
diff --git a/src/Core/Version.php b/src/Core/Version.php
index 9c159b6..860e100 100644
--- a/src/Core/Version.php
+++ b/src/Core/Version.php
@@ -10,5 +10,5 @@
  */
 final class Version
 {
-    public const VALUE = '0.1.0';
+    public const VALUE = '0.2.0';
 }
diff --git a/tests/SignRequestTest.php b/tests/SignRequestTest.php
index cb7b42a..523e981 100644
--- a/tests/SignRequestTest.php
+++ b/tests/SignRequestTest.php
@@ -31,6 +31,19 @@
         ->and($withMode['signature'])->toBe($withoutMode['signature']);
 });
 
+it('sends iframe in the body but excludes it from the signature', function (): void {
+    $base = [
+        'firstName' => 'A', 'lastName' => 'B', 'email' => 'a@b.co',
+        'orderTitle' => 'X', 'orderAmount' => '5', 'currency' => 'USD',
+    ];
+
+    $withIframe = SignRequest::build(FieldOrders::invoiceCreate(), $base + ['iframe' => true], 'pub', 'secret');
+    $withoutIframe = SignRequest::build(FieldOrders::invoiceCreate(), $base, 'pub', 'secret');
+
+    expect($withIframe['iframe'])->toBe('1')
+        ->and($withIframe['signature'])->toBe($withoutIframe['signature']);
+});
+
 it('appends the US state block after the listed fields', function (): void {
     $body = SignRequest::build(FieldOrders::vccCharge(), [
         'firstName' => 'Sam', 'lastName' => 'Smith', 'currencyId' => 1, 'price' => 100,