Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rako.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Checkout

Rako’s production payment architecture routes checkout through Rako’s payment orchestration layer, while Rako keeps the AAP conversion ledger authoritative. The high-level path is: 
Agent → Rako API → payment orchestration → merchant PSP → payment status → AAP conversion ledger
Rako is not the merchant of record and does not hold buyer funds. Checkout is a handoff that preserves attribution metadata through the merchant’s existing payment processor.

​
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 a connected payment connector when the orchestrated checkout backend is enabled
If validation succeeds, Rako creates a checkout object or payment link and marks the session as checkout. 
{
  "transactionId": "01K...",
  "paymentId": "pay_...",
  "checkoutUrl": "https://...",
  "status": "awaiting_payment",
  "backend": "orchestrated",
  "mode": "checkout",
  "amount": 10,
  "currency": "GBP",
  "merchant": { "id": "01J...", "name": "SMARTY" },
  "offer": { "id": "01J...", "name": "30GB Rolling Monthly", "provider": "SMARTY" },
  "session": { "id": "01KN6KV0TWMH8VS6TDS3S7V2EJ", "status": "checkout" }
}

​
AAP metadata

Rako sets attribution metadata when it creates the payment link. Agents and clients should not try to construct or mutate these fields. 
{
  "metadata": {
    "aap_code": "aap://rako.sh/v1/...",
    "aap_recommendation_id": "01KN6KWQDZ6Y5HPW8KFSDPKNSQ",
    "aap_session_id": "01KN6KV0TWMH8VS6TDS3S7V2EJ",
    "aap_offer_id": "01JQXK1001SMARTY1GB000001",
    "aap_merchant_id": "01JQXK0001SMARTY000000001",
    "aap_agent_id": "agent_..."
  }
}
The metadata is stored by the merchant’s PSP and returned on payment webhooks. This creates the join key between the payment event and the AAP recommendation ledger.

​
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 connected a PSP for Rako-orchestrated checkout.
502Could not create checkoutThe payment orchestration layer or downstream connector rejected the payment link request.

​
Relationship to /v1/purchase

Some SDK and MCP integrations may use /v1/purchase for the same 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 checkout URL, and let the user complete payment on the hosted checkout page.