Checkout

Checkout is a server-side handoff that preserves recommendation context without treating the browser as the authority for attribution or conversion state. Rako keeps the AAP conversion ledger authoritative. The high-level path is:

Agent or website → Rako API → hosted checkout handoff → outcome evidence → AAP conversion ledger

Rako is not the merchant of record and does not hold buyer funds. Checkout starts the buyer journey; conversion requires later platform-side outcome evidence such as a payment event, merchant report, or configured milestone.

Endpoint

POST /v1/checkout
Authorization: Bearer <agent-api-key>
Content-Type: application/json

{
  "sessionId": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
  "recommendationId": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
  "userDetails": {}
}

Field	Required	Description
`sessionId`	Yes	Session from the offer search that produced the recommendation.
`recommendationId`	Yes	Recommendation recorded with `POST /v1/recommend`.
`userDetails`	No	Reserved for vertical-specific details collected before checkout.

Expected behaviour

Rako validates that:

the session exists and has not expired
the recommendation exists
the recommendation’s offer still exists
the merchant exists
the merchant has checkout configured when hosted checkout is enabled

If validation succeeds, Rako creates a checkout object or hosted checkout link and marks the session as checkout. The returned URL is a handoff, not proof of payment, conversion, commission, or settlement eligibility.

{
  "transactionId": "01K...",
  "paymentId": "pay_...",
  "checkoutUrl": "https://...",
  "status": "awaiting_payment",
  "backend": "orchestrated",
  "mode": "checkout",
  "amount": 10,
  "currency": "GBP",
  "merchant": { "id": "01J...", "name": "Example Merchant" },
  "offer": { "id": "01J...", "name": "30GB Rolling Monthly", "provider": "Example Mobile" },
  "session": { "id": "01KN6KV0TWMH8VS6TDS3S7V2EJ", "status": "checkout" }
}

AAP metadata

Rako sets attribution metadata when it creates the checkout handoff. Agents, browsers, and client-side code should not construct or mutate attribution, source, conversion, or settlement fields.

{
  "metadata": {
    "aap_code": "aap://rako.sh/v1/...",
    "aap_recommendation_id": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
    "aap_session_id": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
    "aap_offer_id": "01JQXK1001EXAMPLEOFFER001",
    "aap_merchant_id": "01JQXK0001EXAMPLEMERCH001",
    "aap_agent_id": "agent_..."
  }
}

The metadata can be stored with the checkout or payment record and returned with platform-side outcome evidence. This creates the join key between the later outcome event and the AAP recommendation ledger.

Metadata joining is not, by itself, production-grade verification. A payment-observed conversion should only be called verified after Rako authenticates the event source and checks the signed AAP Code, recommendation payload, payment amount, and successful payment status. The hosted implementation is still closing this full gate.

Failure responses

Common failure cases:

Status	Error	Meaning
`400`	`sessionId and recommendationId are required`	Required identifiers were not provided.
`404`	`Session not found`	The checkout does not refer to a known session.
`404`	`Recommendation not found`	The checkout does not refer to a recorded recommendation.
`410`	`Session expired`	The recommendation window has expired.
`503`	`Merchant has no connected payment processor`	The merchant has not configured a payment processor for hosted checkout.
`502`	`Could not create checkout`	The checkout or payment-processing layer rejected the hosted checkout request.

Relationship to `/v1/purchase`

Some SDK and MCP integrations may use /v1/purchase for a related infrastructure path. It accepts a recommendationId and can create either:

a user checkout link; or
an autonomous payment attempt when a legitimate stored payment method is supplied.

For most developer integrations, start with /v1/checkout: record the recommendation, request a hosted checkout URL, and let later platform-side evidence determine whether a conversion occurred.

API Reference

Guides

Checkout

Checkout

Endpoint

Expected behaviour

AAP metadata

Failure responses

Relationship to `/v1/purchase`

​Checkout

​Endpoint

​Expected behaviour

​AAP metadata

​Failure responses

​Relationship to /v1/purchase

Checkout

Endpoint

Expected behaviour

AAP metadata

Failure responses

Relationship to `/v1/purchase`