Let users confirm orders of trusted apps

confirm, return_url and metadata on createOrderForUser() and orders
created with the user's token: the order stays a draft with a
confirmation_url and expires after 24 hours (409 confirmation_expired on
checkout). metadata can be changed on a draft with Order::update().

src/Id/Concerns/ManagesUserBilling.php

@@ -34,6 +34,12 @@ trait ManagesUserBilling
      * away: with the given `transaction` (a payment captured elsewhere) or by charging the user's
      * default payment method (402 when declined; the order stays pending and is retried).
      *
+     * With `confirm`, the user confirms and pays it on Anikeen ID instead (e.g. a top-up): the
+     * order stays a draft with `confirmation_url` (send the user there) and is cancelled if not
+     * confirmed within 24 hours (`expires_at`; afterwards checking it out answers 409
+     * "confirmation_expired"). Webhooks: order.created, order.completed once paid, or
+     * order.cancelled when the user declines or it expires.
+     *
      * @param string $userId The user's Anikeen ID.
      * @param array{
      *     group?: string,
@@ -43,11 +49,18 @@ trait ManagesUserBilling
      *     shipping_address?: array,
      *     items: array<array{type: string, name: string, description?: string, image_url?: string, price?: float|string, gross_price?: float|string, unit: string, units: int}>,
      *     checkout?: bool,
+     *     confirm?: bool,
+     *     return_url?: null|string,
+     *     metadata?: null|array,
      *     transaction_id?: string,
      *     transaction?: array,
      *     invoice_date?: string,
      *     currency_iso?: string
-     * } $attributes
+     * } $attributes confirm: needs items, can't be combined with checkout or a transaction.
+     *               return_url: where the user returns after confirming, with `status` and
+     *               `order` (same origin as one of the app's redirect URIs, 422 otherwise).
+     *               metadata: the app's own data (max. 50 keys), returned as is in the API and
+     *               the order webhooks.
      * @throws Throwable
      */
     public function createOrderForUser(string $userId, array $attributes): Result

src/Id/Resources/Order.php

@@ -8,7 +8,11 @@ use Throwable;
 
 /**
  * @property string $id
- * @property null|string $confirmation_url where the user confirms it (third-party apps)
+ * @property null|string $confirmation_url where the user confirms it (third-party apps, or `confirm`)
+ * @property null|string $group
+ * @property null|object $metadata the app's own data, returned as is
+ * @property null|string $return_url where the user returns after confirming
+ * @property null|string $expires_at when a draft created with `confirm` is cancelled unless confirmed
  */
 class Order extends BaseResource
 {
@@ -53,10 +57,14 @@ class Order extends BaseResource
      *           country_iso: string,
      *           phone_number: null|string,
      *           email: null|string
-     *      }
+     *      },
+     *      group?: null|string,
+     *      metadata?: null|array
      *  } $attributes The order data:
      *    - billing_address:  Billing address (ISO 3166-1 alpha-2 country code)
      *    - shipping_address: Shipping address for physical items (first name, last name, address, postal code, city, ISO 3166-1 alpha-2 country code)
+     *    - group:            The app's group (optional)
+     *    - metadata:         The app's own data (max. 50 keys), only while the order is a draft (optional)
      * @throws Throwable
      */
     public function update(array $attributes = []): self
@@ -69,6 +77,8 @@ class Order extends BaseResource
     /**
      * Checkout given order from the current user.
      *
+     * A draft created with `confirm` can't be checked out once it expired (409 "confirmation_expired").
+     *
      * @throws Throwable
      */
     public function checkout(): self

src/Id/Resources/Orders.php

@@ -48,6 +48,10 @@ class Orders extends BaseCollection
      *          phone_number: null|string,
      *          email: null|string
      *     },
+     *     group?: null|string,
+     *     confirm?: bool,
+     *     return_url?: null|string,
+     *     metadata?: null|array,
      *     items: array<array{
      *         type:         string,
      *         name:         string,
@@ -61,6 +65,10 @@ class Orders extends BaseCollection
      * } $attributes The order data:
      *   - billing_address:  Billing address (ISO 3166-1 alpha-2 country code)
      *   - shipping_address: Shipping address for physical items (first name, last name, address, postal code, city, ISO 3166-1 alpha-2 country code)
+     *   - group:            The app's group, e.g. a team (optional)
+     *   - confirm:          Trusted apps: leave confirming and paying to the user (confirmation_url, expires after 24 hours; optional)
+     *   - return_url:       Where the user returns after confirming (same origin as one of the app's redirect URIs; optional)
+     *   - metadata:         The app's own data (max. 50 keys), returned as is in the API and webhooks (optional)
      *   - items:            Array of order items:
      *       - type:        digital, physical or physical-reduced (VAT category)
      *       - price/gross_price: net or gross unit price, one of both