feat: optional iframe param on invoices->create (embedded checkout)

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

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).

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),
         ]);
     }
 

src/Core/Version.php

@@ -10,5 +10,5 @@
  */
 final class Version
 {
-    public const VALUE = '0.1.0';
+    public const VALUE = '0.2.0';
 }

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,