Skip to main content

​
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": {}
}
FieldRequiredDescription
sessionIdYesSession from the offer search that produced the recommendation.
recommendationIdYesRecommendation recorded with POST /v1/recommend.
userDetailsNoReserved 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:
StatusErrorMeaning
400sessionId and recommendationId are requiredRequired identifiers were not provided.
404Session not foundThe checkout does not refer to a known session.
404Recommendation not foundThe checkout does not refer to a recorded recommendation.
410Session expiredThe recommendation window has expired.
503Merchant has no connected payment processorThe merchant has not configured a payment processor for hosted checkout.
502Could not create checkoutThe 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.