Checkout, Address, and Payment Flow

API examples for address selection, checkout execution, payment handoff, and order summary.

What This Example Demonstrates

This fixture shows the boundaries between ACP Engine, the customer frontend, and the payment integration after a cart is created. ACP Engine coordinates journey state and normalized UI actions. The customer application owns address selection and opens the approved payment surface without exposing raw payment credentials to ACP Engine.

Flow Sequence

1. The runtime asks the customer to select a shipping address.
2. The frontend stores or references the selected address.
3. EXECUTE_CHECKOUT advances shipping preparation.
4. The response requests explicit payment confirmation.
5. The frontend launches the payment provider with a checkout reference.
6. The completed result is rendered as an order summary.

Use references such as addressRef, checkoutId, and a masked card alias. Never send a card number, security code, private key, or payment provider secret in runtime messages or session metadata.

{
  "description": "Example checkout handoff flow. Address and payment are examples of customer-controlled frontend/backend payloads. Do not send card number or CVV to ACP Engine.",
  "addressSelectionMessage": {
    "id": "msg_address_required_001",
    "role": "assistant",
    "content": "Please choose a shipping address to continue.",
    "showActions": true,
    "actionType": "address_required"
  },
  "selectedAddressClientState": {
    "id": 42,
    "title": "Home",
    "first_name": "Example",
    "last_name": "User",
    "address": "Example Street 1",
    "city": "Example City",
    "district": "Manhattan",
    "phone": "+15551112233",
    "is_default": true
  },
  "executeCheckoutRequest": {
    "endpoint": "POST /api/v1/runtime/execute",
    "body": {
      "version": "2026-08-22",
      "agent_id": "{{agent_id}}",
      "session_id": "{{session_id}}",
      "resume_token": "{{resume_token}}",
      "flow_id": "{{flow_id}}",
      "channel": "web",
      "input": {
        "action": "EXECUTE_CHECKOUT",
        "checkoutId": "chk_1234567890abcdef12345678",
        "email": "customer@example.com",
        "addressRef": "addr_42",
        "addressStatus": "selected"
      },
      "client_capabilities": {
        "actions": ["CHECKOUT_HANDOFF", "ACTION_REQUIRED", "APPROVAL_REQUIRED"]
      },
      "idempotency_key": "checkout-chk_1234567890abcdef12345678",
      "mode": "sync"
    }
  },
  "executeCheckoutResponse": {
    "action": "ACTION_REQUIRED",
    "content": "Shipping is ready. Please continue to payment.",
    "checkoutData": {
      "checkoutId": "chk_1234567890abcdef12345678",
      "cartId": "cart_01HX7WJVDGVK3Y9Q",
      "shippingStatus": "ready",
      "paymentStatus": "pending",
      "totalAmount": "129.90",
      "currency": "USD"
    },
    "ui": {
      "message": {
        "id": "msg_payment_confirm_001",
        "role": "assistant",
        "content": "Shipping is ready. Continue to payment?",
        "showActions": true,
        "actionType": "payment_confirm"
      }
    }
  },
  "paymentWidgetLaunch": {
    "provider": "payment_provider",
    "checkoutId": "chk_1234567890abcdef12345678",
    "amountMinor": "12990",
    "currency": "USD",
    "cardSelectionMode": "customer_wallet",
    "returnUrl": "https://store.example.com/checkout/return?checkoutId=chk_1234567890abcdef12345678"
  },
  "orderSummaryMessage": {
    "id": "msg_order_summary_001",
    "role": "assistant",
    "content": "Payment completed. Here is your order summary.",
    "showActions": true,
    "actionType": "order_summary",
    "orderSummary": {
      "orderId": "ord_20260611_0001",
      "orderDate": "2026-06-11T09:45:00Z",
      "productName": "Black Waterproof Hiking Jacket / Medium",
      "productImage": "https://cdn.example.com/products/jacket-black-main.jpg",
      "cardInfo": "payment card ending in 4242",
      "totalAmount": "$129.90",
      "shippingAddress": {
        "name": "Example User",
        "address": "Example Street 1",
        "city": "Example City",
        "district": "Manhattan"
      }
    }
  }
}