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