Zero merchants in Ben Fisher's 4,024-merchant UCP dataset support native payment. I've been building toward closing that gap since March. Today it's done — at least on the business side.
This post is about AP2 Mandates: what they are, why they're the only spec-compliant path to autonomous card payment on UCP, and what it took to implement them correctly on WooCommerce.
Why every UCP checkout still ends with a browser redirect
When an AI agent completes a UCP checkout today, it gets a continue_url. The buyer clicks a link, lands on the WooCommerce checkout page, fills in their card, and pays. The agent handled discovery and session setup. The human handled payment.
That handoff exists because the spec requires it — unless one specific extension is active.
From the UCP checkout specification:
"The checkout has to be finalized manually by the user through a trusted UI unless the AP2 Mandates extension is supported."
That "unless" is the entire autonomous payment story in UCP. Not Stripe tokens. Not saved cards. Not wallet APIs. AP2 Mandates.
What AP2 Mandates actually are
AP2 is a cryptographic authorization framework. When it's negotiated between a business and a platform, the checkout session is "security locked" — neither party can revert to an unprotected flow.
The flow has two sides:
Business side: Every checkout response must include ap2.merchant_authorization — a JWS detached signature proving the checkout terms (price, line items, totals) are authentic and haven't been tampered with. The signature is ES256, JCS-canonicalized per RFC 8785, with the payload excluded from the JWS body (RFC 7515 Appendix F detached content format).
Platform side: When the user confirms the purchase, the platform generates a cryptographically signed mandate — an SD-JWT credential proving the user explicitly authorized this specific transaction. It submits that mandate at complete_checkout. The business verifies it. If valid, payment proceeds without a browser redirect.
The checkout mandate contains the full checkout response including the business's merchant_authorization. So the platform's signature covers the business's signature. It's a nested cryptographic binding: the business proves the terms, the platform proves the user consented to those exact terms.
What implementing this actually required
Getting the signing right
The spec says ES256 with detached JWS. In PHP, openssl_sign() on a P-256 key produces a DER-encoded ECDSA signature. JWS ES256 requires raw r||s — 64 bytes for P-256. Those are not the same format.
Every JWS library you'd use on the platform side (jose, python-jose, jsonwebtoken) expects raw r||s. A DER signature will fail verification silently or throw a malformed signature error. The fix is a DER-to-raw-rs converter:
// openssl_sign() → DER. JWS ES256 → raw r||s. Not the same.
openssl_sign( $signing_input, $signature_der, $private_key, OPENSSL_ALGO_SHA256 );
$r = substr( $der_inner, $r_offset, $r_len );
$s = substr( $der_inner, $s_offset, $s_len );
$signature_raw = str_pad( ltrim($r, "\x00"), 32, "\x00", STR_PAD_LEFT )
. str_pad( ltrim($s, "\x00"), 32, "\x00", STR_PAD_LEFT );
The JCS canonicalization (RFC 8785) is the other non-obvious requirement. Before signing, the checkout payload is canonicalized — keys sorted recursively, Unicode normalized, numbers in IEEE 754 format. This ensures the signature is reproducible across systems that may re-serialize JSON differently.
Enforcing the mandate at complete_checkout
The spec is explicit: if AP2 was negotiated, complete_checkout MUST reject requests without ap2.checkout_mandate. This is the security boundary. Without it, AP2 is advertised but provides no protection — a platform could skip the mandate entirely and the checkout would succeed.
The enforcement block runs before order creation:
if ( $ap2_ext->is_ap2_configured() ) {
$mandate_jwt = $body['ap2']['checkout_mandate'] ?? null;
if ( empty( $mandate_jwt ) ) {
// Return mandate_required error — session stays ready_for_complete
return $this->mandate_error_response( 'mandate_required', $session );
}
$mandate_error = $ap2_ext->verify_checkout_mandate( $mandate_jwt, $session, $request );
if ( null !== $mandate_error ) {
return $this->mandate_error_response( $mandate_error['code'], $session );
}
}
Verifying the mandate
When a mandate is present, the full verification chain runs:
- Parse the SD-JWT structure (
header.payload.signature~disclosures~keybinding) - Check expiry (
expclaim) - Extract the embedded checkout from mandate claims
- Re-verify
merchant_authorization— confirm the platform wrapped our own signature, not a different checkout - Verify checkout ID matches the current session
- Verify totals match — no bait-and-switch between what the user saw and what gets charged
Platform key verification
The final step: verifying the SD-JWT outer signature using the platform's public key. This is what proves the mandate is genuinely from the platform and not forged.
The flow: decode the JWS header → extract alg and kid → fetch the platform's UCP profile from the UCP-Agent header → pull signing_keys → find the JWK matching kid → build an OpenSSL public key from the JWK x/y coordinates → verify.
Building an EC public key from JWK coordinates without a library means constructing the SubjectPublicKeyInfo DER by hand in PHP — OID encoding, SEQUENCE wrapping, BIT STRING for the uncompressed EC point. It's ~80 lines but removes a runtime dependency and works on any WordPress host.
The platform profile is fetched over HTTPS and cached with WP transients, respecting Cache-Control max-age with a 60-second floor. Verification result is logged with kid, algorithm, and session ID for auditability.
The capability name that broke everything
Before any of this verification mattered, there was a simpler bug: the capability was advertised as dev.ucp.shopping.ap2_mandates — plural. The spec uses dev.ucp.shopping.ap2_mandate — singular.
Capability negotiation is a string equality check. The intersection algorithm finds no match between ap2_mandates and ap2_mandate. AP2 is never activated. Every checkout session falls back to delegate payment. No error, no warning — it silently never negotiates.
One character. Every implementation should validate capability names against the spec registry rather than trusting their own strings.
What's live now
When dev.ucp.shopping.ap2_mandate is enabled in UCPReady and a compatible platform connects:
- Every checkout response includes
ap2.merchant_authorization(JWS ES256, detached, JCS payload) -
complete_checkoutrejects requests withoutap2.checkout_mandate - Verification runs: SD-JWT parse → expiry → embedded checkout extraction → merchant_authorization re-verification → ID and totals match → platform key verification
- If all checks pass, payment proceeds — no browser redirect
The one remaining piece is ecosystem readiness: a platform that supports AP2 mandate submission and forwards the access token that proves identity linking. Ben Fisher's UCPPlayground is the logical first test. Once that's connected, UCPReady will produce the first confirmed AP2-mandate-verified autonomous purchase on WooCommerce.
Why this matters beyond WooCommerce
Ben's dataset of 4,024 merchants shows zero native payment support. Part of that is the SPT/ACS story — Stripe's Shared Payment Token is US-only right now and requires Stripe to host the checkout flow. That's a different architecture than UCP.
On UCP, AP2 Mandates is the spec's answer. It's protocol-agnostic — the mandate can cover any payment method handled by any PSP. The platform proves user consent cryptographically. The business verifies that proof and charges via their existing payment gateway. No card data crosses protocol boundaries. PSD2 SCA compliance comes from the mandate being platform-issued and buyer-authenticated at mandate creation time.
This is what autonomous agent commerce looks like when the merchant controls the checkout instead of delegating it to Stripe's infrastructure.
UCPReady is available at zologic.nl/ucpready.
If you're building a platform that supports UCP and want to test AP2 mandate submission against a live endpoint, reach out. houseofparfum.nl is running UCPReady 1.8.23 with AP2 ready to activate.
Top comments (0)