{"openapi":"3.1.0","info":{"title":"RedVPN — agentic commerce","version":"2026-04-17","description":"Agentic Commerce Protocol (ACP) checkout for RedVPN Premium plus the feeds and discovery documents. Schemas reference the published ACP JSON Schema; the `metadata.redvpn` fulfilment object and the `card_hosted` handler are RedVPN extensions (see docs/AGENTIC-COMMERCE.md)."},"servers":[{"url":"https://vpn.red/agentic"}],"security":[{"agentKey":[]}],"paths":{"/checkout_sessions":{"post":{"operationId":"createCheckoutSession","summary":"Create a checkout session","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"required on POST; replay returns Idempotent-Replayed: true"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionCreateRequest"}}}},"responses":{"201":{"description":"CheckoutSession","content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSession"}}}},"400":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout_sessions/{checkout_session_id}":{"get":{"operationId":"getCheckoutSession","summary":"Retrieve a checkout session","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CheckoutSession","content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSession"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"updateCheckoutSession","summary":"Update a checkout session","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"required on POST; replay returns Idempotent-Replayed: true"},{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionUpdateRequest"}}}},"responses":{"200":{"description":"CheckoutSession","content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSession"}}}},"400":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout_sessions/{checkout_session_id}/complete":{"post":{"operationId":"completeCheckoutSession","summary":"Pay and fulfil","description":"payment_data.handler_id = card_spt (Stripe Shared Payment Token in instrument.credential.token), card_hosted (no instrument; answer carries continue_url and status complete_in_progress), or crypto_<method> when crypto is enabled.","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"required on POST; replay returns Idempotent-Replayed: true"},{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionCompleteRequest"},{"$ref":"#/components/schemas/HostedCardCompleteRequest"}]}}}},"responses":{"200":{"description":"CheckoutSession, with `order` when completed","content":{"application/json":{"schema":{"oneOf":[{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSession"},{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionWithOrder"}]}}}},"400":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout_sessions/{checkout_session_id}/cancel":{"post":{"operationId":"cancelCheckoutSession","summary":"Cancel a checkout session","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"required on POST; replay returns Idempotent-Replayed: true"},{"name":"checkout_session_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CancelSessionRequest"}}}},"responses":{"200":{"description":"CheckoutSession","content":{"application/json":{"schema":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSession"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{order_no}":{"get":{"operationId":"getOrder","summary":"Order + fulfilment for an order this key created","parameters":[{"name":"API-Version","in":"header","required":false,"schema":{"type":"string"},"description":"2026-04-17; omitted = latest"},{"name":"Request-Id","in":"header","required":false,"schema":{"type":"string"},"description":"correlation id, echoed"},{"name":"Signature","in":"header","required":false,"schema":{"type":"string"},"description":"base64 HMAC-SHA256(secret, Timestamp + '.' + body); only for keys with a signing secret"},{"name":"Timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"RFC 3339, with Signature"},{"name":"order_no","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderEnvelope"}}}},"401":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"ACP Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feed.json":{"get":{"operationId":"feedJson","security":[],"summary":"ACP feed (Products)","responses":{"200":{"description":"products"}}}},"/feed.jsonl":{"get":{"operationId":"feedJsonl","security":[],"summary":"OpenAI product-feed lines","responses":{"200":{"description":"application/x-ndjson"}}}}},"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","bearerFormat":"AgentKey (rvk_…)"}},"schemas":{"Error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","enum":["invalid_request","processing_error","service_unavailable"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"supported_versions":{"type":"array","items":{"type":"string"}}}},"HostedCardCompleteRequest":{"type":"object","required":["payment_data"],"properties":{"buyer":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/Buyer"},"payment_data":{"type":"object","required":["handler_id"],"properties":{"handler_id":{"type":"string","enum":["card_hosted"]}}}},"description":"RedVPN extension: the hosted-card handler needs no instrument."},"HostedCardConfig":{"type":"object","properties":{"merchant_id":{"type":"string"},"psp":{"const":"stripe"},"flow":{"const":"redirect"},"result_field":{"const":"continue_url"},"poll":{"type":"string"}}},"HostedCardInstrument":{"type":"object","description":"none — the human pays on continue_url","properties":{}},"CryptoConfig":{"type":"object","properties":{"asset":{"type":"string"},"kind":{"type":"string"},"flow":{"const":"pay_to_address"},"result_field":{"const":"metadata.payment"}}},"CryptoInstrument":{"type":"object","description":"none — send exactly metadata.payment.amount of asset to address","properties":{}},"Fulfilment":{"type":"object","description":"metadata.redvpn on a completed session","properties":{"order_no":{"type":"string"},"brand":{"type":"string"},"plan":{"type":"string"},"period":{"type":"string"},"cid":{"type":"string","description":"the credential the apps/CLI connect with"},"account_code":{"type":"string","description":"RV-XXXX-XXXX-XXXX-XXXX; the human enters it in the app"},"tier":{"type":"string"},"paid_until":{"type":["string","null"],"format":"date-time"},"profile":{"type":"object","description":"redsocket client config"},"profile_url":{"type":"string"},"redeem":{"type":"object","properties":{"app":{"type":"string"},"cli":{"type":"string"},"web":{"type":"string"},"config":{"type":"string"}}}}},"OrderEnvelope":{"type":"object","properties":{"order":{"$ref":"https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/Order"},"checkout_session_id":{"type":"string"},"status":{"type":"string"},"continue_url":{"type":"string"},"redvpn":{"$ref":"#/components/schemas/Fulfilment"}}}}}}