Skip to content

§5.5 protocols.payment example uses fields not in the field table #5

@benikigai

Description

@benikigai

Inconsistency

§5.5 (SPEC.md:102-105) shows this example of a payment protocol declaration:

```json
"payment": {
"type": "stripe_link",
"agent_op": "checkout.create"
}
```

But the field structure table at SPEC.md:114-117 only defines:

Field Type Required
version string yes
endpoint string (url) conditional

Neither type nor agent_op appears in the field table. The body text at lines 119-121 says additional protocol-specific fields are allowed, but:

  1. The example payment declaration has no version field, which the table says is required.
  2. type and agent_op aren't "protocol-specific" — payment is itself a registered protocol identifier (line 139), so the table should define its fields.

Result: implementations of payment declarations vary wildly. laclawclaw currently ships {version: \"1.0\", type: \"stripe_link\", agent_op: \"create_payment_link\"} — chose to include version anyway, invented agent_op semantics from the example.

Proposed fix (v0.3)

Add a dedicated subsection §5.5.x for the payment identifier:

```

Payment declarations

The payment identifier is for hosted-checkout-link patterns (Stripe Payment Links, Square Checkout, PayPal hosted, etc.) where the agent receives a URL to hand to its human.

Field Type Required
version string yes — the AWP payment subprotocol version (currently "1.0")
type string yes — checkout provider: "stripe_link", "square_checkout", "paypal_hosted", "custom"
agent_op string yes — the action id (in the same agent.json) the agent should invoke to obtain the link

Unlike transport protocols (a2a, mcp), payment declarations omit endpoint because the URL is dynamic per-cart and obtained through the action named in agent_op.
```

Also update the example at line 102 to include version.

This pattern (declare the link-issuing op in the protocol block, then implement that op as an action elsewhere) is what every hosted-checkout integration actually does. The spec should bless it explicitly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions