Skip to content

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

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

    Fields

    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