Support third-party checkout confirmation

Orders and subscriptions created by untrusted apps are confirmed by the
user on Anikeen ID. confirmationUrl($returnUrl) on Order and
Subscription builds the link with the return URL; checking out such a
draft throws ConfirmationRequiredException carrying the same URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -157,6 +157,32 @@ Each order has `status` (`processing` = current month, still collecting; `pendin
 paid; `completed`; `cancelled`), the totals, `payment_attempts`, `next_payment_attempt_at` (null =
 no more automatic retries) and `last_payment_error`.
 
+### Selling as a third-party app (user confirms on Anikeen ID)
+
+Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
+but can't charge them. The user confirms on Anikeen ID and comes back to your `return_url`:
+
+```php
+use Anikeen\Id\Exceptions\ConfirmationRequiredException;
+
+$order = $user->orders()->create([
+    'billing_address_id' => $addressId,
+    'items' => [['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99']],
+]);
+
+return redirect($order->confirmationUrl(route('shop.done')));
+// later: https://your-app.test/shop/done?status=completed&order=01J…
+```
+
+`return_url` must have the origin of one of your app's redirect URIs. `status` is `completed`,
+`pending` (payment still processing) or `cancelled`; check it with `$user->orders()->find($id)`
+instead of trusting the query string. Subscriptions work the same way
+(`$user->subscriptions()->create([...])->confirmationUrl(...)`, `&subscription=…`).
+Unconfirmed bookings are cancelled after 24 hours.
+
+`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
+points to the same page. Trusted apps keep checking out directly.
+
 ### Change the default access token / refresh token field name
 
 If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:

README.stub

@@ -157,6 +157,32 @@ Each order has `status` (`processing` = current month, still collecting; `pendin
 paid; `completed`; `cancelled`), the totals, `payment_attempts`, `next_payment_attempt_at` (null =
 no more automatic retries) and `last_payment_error`.
 
+### Selling as a third-party app (user confirms on Anikeen ID)
+
+Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
+but can't charge them. The user confirms on Anikeen ID and comes back to your `return_url`:
+
+```php
+use Anikeen\Id\Exceptions\ConfirmationRequiredException;
+
+$order = $user->orders()->create([
+    'billing_address_id' => $addressId,
+    'items' => [['type' => 'digital', 'name' => 'Sticker pack', 'unit' => 'piece', 'units' => 1, 'gross_price' => '9.99']],
+]);
+
+return redirect($order->confirmationUrl(route('shop.done')));
+// later: https://your-app.test/shop/done?status=completed&order=01J…
+```
+
+`return_url` must have the origin of one of your app's redirect URIs. `status` is `completed`,
+`pending` (payment still processing) or `cancelled`; check it with `$user->orders()->find($id)`
+instead of trusting the query string. Subscriptions work the same way
+(`$user->subscriptions()->create([...])->confirmationUrl(...)`, `&subscription=…`).
+Unconfirmed bookings are cancelled after 24 hours.
+
+`checkout()` on such a draft throws `ConfirmationRequiredException`; its `confirmationUrl`
+points to the same page. Trusted apps keep checking out directly.
+
 ### Change the default access token / refresh token field name
 
 If you access / refresh token fields differs from the default `anikeen_id_access_token` / `anikeen_id_refresh_token`, you can specify the field name in the `AppServiceProvider` boot method:

src/Id/Concerns/HasConfirmationUrl.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Anikeen\Id\Concerns;
+
+/**
+ * Orders and subscriptions created by third-party apps are confirmed by the user on Anikeen ID.
+ */
+trait HasConfirmationUrl
+{
+    /**
+     * Where the user confirms (or cancels) this booking, or null once it was checked out.
+     *
+     * Afterwards the user is sent back to $returnUrl with `status` (completed, pending or
+     * cancelled) and `order` or `subscription`. The return URL must have the origin of one of
+     * the app's redirect URIs. Check the status through the API; don't trust the query string.
+     */
+    public function confirmationUrl(?string $returnUrl = null): ?string
+    {
+        $url = $this->confirmation_url ?? null;
+
+        if (!$url || !$returnUrl) {
+            return $url ?: null;
+        }
+
+        return $url . (str_contains($url, '?') ? '&' : '?') . http_build_query(['return_url' => $returnUrl]);
+    }
+}

src/Id/Exceptions/ConfirmationRequiredException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Anikeen\Id\Exceptions;
+
+use Throwable;
+
+/**
+ * Thrown when a third-party app tries to check out an order or subscription itself: the user has
+ * to confirm it on Anikeen ID. Send them to the confirmation URL instead.
+ */
+class ConfirmationRequiredException extends ResourceException
+{
+    public function __construct(string $message, int $code, public readonly ?string $confirmationUrl = null, ?Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}

src/Id/Resources/BaseResource.php

@@ -2,6 +2,7 @@
 
 namespace Anikeen\Id\Resources;
 
+use Anikeen\Id\Exceptions\ConfirmationRequiredException;
 use Anikeen\Id\Exceptions\ResourceException;
 use Anikeen\Id\Result;
 use JsonSerializable;
@@ -19,6 +20,14 @@ abstract class BaseResource implements JsonSerializable
         $this->result = $callable();
 
         if (!$this->result->success()) {
+            if (($this->result->data->error ?? null) === 'confirmation_required') {
+                throw new ConfirmationRequiredException(
+                    $this->result->data->message ?? 'The user has to confirm this on Anikeen ID.',
+                    $this->result->response->getStatusCode(),
+                    $this->result->data->confirmation_url ?? null,
+                );
+            }
+
             throw new ResourceException(sprintf('%s for resource [%s]', rtrim($this->result->data->message, '.'), get_called_class()), $this->result->response->getStatusCode());
         }
 

src/Id/Resources/Order.php

@@ -3,14 +3,17 @@
 namespace Anikeen\Id\Resources;
 
 use Anikeen\Id\Concerns\HasBillable;
+use Anikeen\Id\Concerns\HasConfirmationUrl;
 use Throwable;
 
 /**
  * @property string $id
+ * @property null|string $confirmation_url where the user confirms it (third-party apps)
  */
 class Order extends BaseResource
 {
     use HasBillable;
+    use HasConfirmationUrl;
 
     /**
      * Update given order from the current user.

src/Id/Resources/Subscription.php

@@ -3,6 +3,7 @@
 namespace Anikeen\Id\Resources;
 
 use Anikeen\Id\Concerns\HasBillable;
+use Anikeen\Id\Concerns\HasConfirmationUrl;
 use Anikeen\Id\Contracts\AppTokenRepository;
 use Throwable;
 
@@ -17,10 +18,12 @@ use Throwable;
  * @property string $ends_at
  * @property string $webhook_url
  * @property string $webhook_secret
+ * @property null|string $confirmation_url where the user confirms it (third-party apps)
  */
 class Subscription extends BaseResource
 {
     use HasBillable;
+    use HasConfirmationUrl;
 
     /**
      * Update a given subscription from the current user.

tests/Id/CheckoutConfirmationTest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ConfirmationRequiredException;
+use Illuminate\Database\Eloquent\Model;
+
+class CheckoutConfirmationTest extends TestCase
+{
+    private function owner(): Model
+    {
+        $owner = new class extends Model {
+            use Billable;
+
+            protected $guarded = [];
+        };
+        $owner->anikeen_id = '01JUSER';
+        $owner->anikeen_id_access_token = 'user-token';
+
+        return $owner;
+    }
+
+    public function test_a_draft_order_links_to_its_confirmation_with_the_return_url(): void
+    {
+        $this->respond(200, ['data' => []]); // orders() loads the list first
+        $this->respond(201, ['data' => ['id' => '01JORD', 'status' => 'draft', 'confirmation_url' => 'https://id.anikeen.com/checkout/orders/01JORD']]);
+
+        $order = $this->owner()->orders()->create(['billing_address_id' => '01JADDR', 'items' => []]);
+
+        $this->assertSame('https://id.anikeen.com/checkout/orders/01JORD', $order->confirmationUrl());
+        $this->assertSame(
+            'https://id.anikeen.com/checkout/orders/01JORD?return_url=https%3A%2F%2Fshop.test%2Fdone%3Fcart%3D1',
+            $order->confirmationUrl('https://shop.test/done?cart=1'),
+        );
+        $this->assertSame('POST /api/v1/orders', $this->sent[1]['request']->getMethod() . ' ' . $this->sent[1]['request']->getUri()->getPath());
+    }
+
+    public function test_checked_out_bookings_have_no_confirmation_url(): void
+    {
+        $this->respond(200, ['data' => []]);
+        $this->respond(201, ['data' => ['id' => '01JORD', 'status' => 'completed', 'confirmation_url' => null]]);
+
+        $this->assertNull($this->owner()->orders()->create([])->confirmationUrl('https://shop.test/done'));
+    }
+
+    public function test_checking_out_a_draft_as_a_third_party_app_points_to_the_confirmation(): void
+    {
+        $this->respond(200, ['data' => []]); // subscriptions() loads the list first
+        $this->respond(201, ['data' => ['id' => '01JSUB', 'active' => false, 'confirmation_url' => 'https://id.anikeen.com/checkout/subscriptions/01JSUB']]);
+        $this->respond(403, ['message' => 'The user has to confirm this on Anikeen ID.', 'error' => 'confirmation_required', 'confirmation_url' => 'https://id.anikeen.com/checkout/subscriptions/01JSUB']);
+
+        $subscription = $this->owner()->subscriptions()->create(['name' => 'Pro', 'unit' => 'month', 'price' => 4.99]);
+
+        try {
+            $subscription->checkout();
+            $this->fail('Expected a ConfirmationRequiredException.');
+        } catch (ConfirmationRequiredException $e) {
+            $this->assertSame(403, $e->getCode());
+            $this->assertSame('https://id.anikeen.com/checkout/subscriptions/01JSUB', $e->confirmationUrl);
+        }
+    }
+}