Subject: Payment Link fails at capture after 3DS approval when order has type: 'DELIVERY' fulfillment

Questions
1

The Issue: We generate hosted payment links via the Checkout API (POST /v2/online-checkout/payment-links) with an inline order object.

  1. Pickup Orders:
    • When the order has fulfillments: [{ type: "PICKUP", pickup_details: { ... } }], the payment on checkout.square.site succeeds cleanly (Apple Pay, Google Pay, and Card all complete and capture).
  2. Delivery Orders:
    • When the order has fulfillments: [{ type: "DELIVERY", delivery_details: { ... } }], the customer enters their card, receives a 3D Secure bank challenge, and approves it in their banking app (bank allows the transaction).
    • However, immediately after bank 3DS approval, the checkout page fails to complete the payment and voids/aborts the authorization.

Questions for Square:

  1. Does Square Online Checkout (checkout.square.site) require a connected On-Demand Delivery courier integration (e.g. Uber/Stuart) to process payments for orders with type: "DELIVERY"?
  2. If a restaurant manages its own local delivery, what is the recommended way to model delivery orders in the Orders / Checkout API so payments capture without courier dispatch errors?
4

The DELIVERY fulfillment type is currently a restricted, closed Beta.

Without enrollment in the Delivery Beta, the API may accept the order creation (HTTP 200), but downstream payment capture and order processing will fail because the seller’s account isn’t provisioned for delivery fulfillment handling.

Additionally, On-Demand Delivery is a feature that is only available for orders places through Square Online - submitting orders with a DELIVERY fulfillment will not trigger the On-Demand Delivery integration.

Some workarounds:

  1. Use SHIPMENT instead of DELIVERY: model your delivery as a shipment fulfillment (type: "SHIPMENT" with shipment_details). This is generally available and will allow payment capture to succeed. You can include recipient address, carrier info, and tracking details. This is the recommended workaround for self-managed delivery.
  2. Use PICKUP and handle delivery logistics externally: if the customer experience allows it, create the order as pickup and manage delivery coordination outside of Square.