{"openapi":"3.1.0","info":{"title":"RoamNow Agent API","version":"1.1.0","description":"Discover eligible travel eSIM plans, create short-lived server-priced quotes, hand an explicitly confirmed user to Stripe Checkout, and poll customer-safe order status. All monetary amounts are integer minor units with minor_unit=2. Current transactions are Sandbox-only: no charge and no live mobile service. Activation material is never returned."},"servers":[{"url":"https://roam-now.com"}],"paths":{"/api/agent/v1/catalogue":{"get":{"operationId":"listCatalogue","summary":"List currently eligible customer-safe plans","parameters":[{"name":"currency","in":"query","schema":{"$ref":"#/components/schemas/Currency","default":"SGD"}}],"responses":{"200":{"description":"Current catalogue and human purchase handoff URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalogue"}}}},"400":{"description":"Unsupported currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pricing.json":{"get":{"operationId":"listPricing","summary":"Alias for the current customer-safe catalogue","responses":{"200":{"description":"Current customer-safe pricing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalogue"}}}}}}},"/capabilities.json":{"get":{"operationId":"getCapabilities","summary":"Describe agent and commerce safety capabilities","responses":{"200":{"description":"Capability and safety declaration."}}}},"/api/agent/v1/quotes":{"post":{"operationId":"createQuote","summary":"Create a short-lived, server-priced itinerary quote","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"},"examples":{"twoCountryTrip":{"value":{"currency":"SGD","usage_profile":"NORMAL","legs":[{"destination":"United Arab Emirates","start_date":"2027-02-01","end_date":"2027-02-05"},{"destination":"Turkey","start_date":"2027-02-06","end_date":"2027-02-10"}]}}}}}},"responses":{"201":{"description":"Eligible quote. Amounts are integer minor units and the quote expires at expires_at.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"},"examples":{"quote":{"$ref":"#/components/examples/QuoteResponse"}}}}},"401":{"description":"Invalid or revoked agent identity.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid or unsupported itinerary.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute or monthly request allowance exceeded.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/checkout-sessions":{"post":{"operationId":"createCheckoutSession","summary":"Create one idempotent Stripe Checkout after explicit user confirmation","description":"The same Idempotency-Key must be reused for retries. Stripe payment remains a human action.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque retry identity. Reuse for the same quote; never reuse for another quote.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"},"example":"telegram_checkout_01JABCXYZ"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"},"examples":{"confirmed":{"value":{"quote_id":"11111111-1111-4111-8111-111111111111","delegation_reference":"telegram-update-opaque-123","consent_confirmed":true}}}}}},"responses":{"201":{"description":"Human Stripe Checkout handoff. No payment has been completed by this response.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutHandoff"},"examples":{"handoff":{"$ref":"#/components/examples/CheckoutResponse"}}}}},"401":{"description":"Invalid or revoked agent identity.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Explicit user confirmation is required.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Quote is expired, changed, used, conflicting, or already processing.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Malformed request or invalid idempotency/delegation value.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute or monthly request allowance exceeded.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Sandbox Checkout is unavailable.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/orders/{checkout_intent_id}":{"get":{"operationId":"getOrderStatus","summary":"Get customer-safe status for an agent-owned Checkout intent","description":"The authenticated client can access only its own Checkout intents. Activation, recipient, supplier, cost, ICCID and private-link data are excluded.","security":[{"bearerAuth":[]}],"parameters":[{"name":"checkout_intent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment, provisioning and delivery status safe for the originating channel.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatus"},"examples":{"fulfilled":{"$ref":"#/components/examples/OrderStatusResponse"}}}}},"401":{"description":"Invalid or revoked agent identity.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No status resource is visible to this client.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Per-minute or monthly request allowance exceeded.","headers":{"X-Request-Id":{"description":"RoamNow request correlation identifier.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"rn_agent opaque key","description":"Hash-only, revocable key issued to an approved channel integration."}},"schemas":{"Currency":{"type":"string","enum":["SGD","USD"]},"TripLeg":{"type":"object","additionalProperties":false,"required":["destination","start_date","end_date"],"properties":{"destination":{"type":"string","minLength":1,"maxLength":100},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"}}},"QuoteRequest":{"type":"object","additionalProperties":false,"required":["legs","usage_profile","currency"],"properties":{"legs":{"type":"array","minItems":1,"maxItems":3,"items":{"$ref":"#/components/schemas/TripLeg"}},"usage_profile":{"type":"string","enum":["LIGHT","NORMAL","HEAVY"]},"currency":{"$ref":"#/components/schemas/Currency"}}},"QuoteItem":{"type":"object","required":["position","sku","destination","trip","data_allowance","validity_days","unit_amount_minor","currency","coverage_basis"],"properties":{"position":{"type":"integer","minimum":1},"sku":{"type":"string"},"destination":{"type":"string"},"trip":{"$ref":"#/components/schemas/TripLeg"},"data_allowance":{"type":"string"},"validity_days":{"type":"integer","minimum":1},"unit_amount_minor":{"type":"integer","minimum":0,"description":"Server-owned price in the currency's minor unit."},"currency":{"$ref":"#/components/schemas/Currency"},"coverage_basis":{"type":"string","enum":["authenticated_country","explicit_regional"]},"inventory_checked_at":{"type":["string","null"],"format":"date-time"},"price_updated_at":{"type":["string","null"],"format":"date-time"}}},"Quote":{"type":"object","required":["quote_id","status","currency","total_amount_minor","minor_unit","expires_at","items","limitations","request_id","checkout_endpoint"],"properties":{"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["OPEN"]},"currency":{"$ref":"#/components/schemas/Currency"},"total_amount_minor":{"type":"integer","minimum":0,"description":"Exact sum of item prices in integer minor units."},"minor_unit":{"type":"integer","const":2},"expires_at":{"type":"string","format":"date-time"},"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/QuoteItem"}},"limitations":{"type":"array","items":{"type":"string"}},"request_id":{"type":"string","format":"uuid"},"checkout_endpoint":{"type":"string","format":"uri"}}},"CheckoutRequest":{"type":"object","additionalProperties":false,"required":["quote_id","delegation_reference","consent_confirmed"],"properties":{"quote_id":{"type":"string","format":"uuid"},"delegation_reference":{"type":"string","minLength":8,"maxLength":200,"description":"Opaque channel-side consent record; retained only as a hash."},"consent_confirmed":{"type":"boolean","const":true}}},"CheckoutHandoff":{"type":"object","required":["request_id","checkout_intent_id","quote_id","checkout_url","payment_mode","payment_required","service_mode"],"properties":{"request_id":{"type":"string","format":"uuid"},"checkout_intent_id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"checkout_url":{"type":"string","format":"uri"},"payment_mode":{"type":"string","const":"human_stripe_checkout"},"payment_required":{"type":"boolean","const":true},"service_mode":{"type":"string","const":"sandbox_no_charge_no_live_service"}}},"OrderItemStatus":{"type":"object","required":["order_id","sku","quantity","status","provisioning_status","delivery_status","esim_activity_state","updated_at"],"properties":{"order_id":{"type":"string","format":"uuid"},"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1},"status":{"type":"string"},"provisioning_status":{"type":"string","enum":["NOT_STARTED","PENDING","SUCCEEDED","UNKNOWN","FAILED"]},"delivery_status":{"type":"string","enum":["NOT_STARTED","PENDING","DELIVERED","FAILED"]},"esim_activity_state":{"type":"string","enum":["NOT_STARTED","IN_USE","EXPIRED","CANCELLED","UNAVAILABLE","UNKNOWN"]},"updated_at":{"type":"string","format":"date-time"}}},"OrderStatus":{"type":"object","required":["request_id","checkout_intent_id","quote_id","status","payment_status","orders","activation_delivery","activation_material_included","refresh_after_seconds","updated_at"],"properties":{"request_id":{"type":"string","format":"uuid"},"checkout_intent_id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["AWAITING_PAYMENT","PAYMENT_VERIFIED_PROCESSING","PROCESSING","ATTENTION_REQUIRED","FULFILLED","REFUND_PENDING","REFUNDED","EXPIRED","FAILED"]},"payment_status":{"type":"string","enum":["CREATING","OPEN","PAID","EXPIRED","FAILED"]},"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemStatus"}},"activation_delivery":{"type":"string","const":"private_email_and_my_esim"},"activation_material_included":{"type":"boolean","const":false},"refresh_after_seconds":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}},"Catalogue":{"type":"object","required":["schema_version","provider","canonical_url","commerce_mode","currency","plans","purchase_flow"],"properties":{"schema_version":{"type":"string"},"provider":{"type":"string","const":"RoamNow"},"canonical_url":{"type":"string","format":"uri"},"commerce_mode":{"type":"string"},"currency":{"$ref":"#/components/schemas/Currency"},"plans":{"type":"array","items":{"type":"object"}},"purchase_flow":{"type":"object"}}},"Error":{"type":"object","required":["error","message","request_id"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}},"examples":{"QuoteResponse":{"value":{"quote_id":"11111111-1111-4111-8111-111111111111","status":"OPEN","currency":"SGD","total_amount_minor":3240,"minor_unit":2,"expires_at":"2027-01-15T10:15:00Z","items":[{"position":1,"sku":"RN-AE-3GB-15D","destination":"United Arab Emirates","trip":{"destination":"United Arab Emirates","start_date":"2027-02-01","end_date":"2027-02-05"},"data_allowance":"3 GB","validity_days":15,"unit_amount_minor":1350,"currency":"SGD","coverage_basis":"authenticated_country","inventory_checked_at":"2027-01-15T09:55:00Z","price_updated_at":"2027-01-15T09:00:00Z"},{"position":2,"sku":"RN-TR-5GB-15D","destination":"Turkey","trip":{"destination":"Turkey","start_date":"2027-02-06","end_date":"2027-02-10"},"data_allowance":"5 GB","validity_days":15,"unit_amount_minor":1890,"currency":"SGD","coverage_basis":"authenticated_country","inventory_checked_at":"2027-01-15T09:55:00Z","price_updated_at":"2027-01-15T09:00:00Z"}],"limitations":["Human Stripe payment is required","Current service is Sandbox only; no charge and no live mobile service"],"request_id":"22222222-2222-4222-8222-222222222222","checkout_endpoint":"https://roam-now.com/api/agent/v1/checkout-sessions"}},"CheckoutResponse":{"value":{"request_id":"22222222-2222-4222-8222-222222222222","checkout_intent_id":"33333333-3333-4333-8333-333333333333","quote_id":"11111111-1111-4111-8111-111111111111","checkout_url":"https://checkout.stripe.com/c/pay/example","payment_mode":"human_stripe_checkout","payment_required":true,"service_mode":"sandbox_no_charge_no_live_service"}},"OrderStatusResponse":{"value":{"request_id":"22222222-2222-4222-8222-222222222222","checkout_intent_id":"33333333-3333-4333-8333-333333333333","quote_id":"11111111-1111-4111-8111-111111111111","status":"FULFILLED","payment_status":"PAID","orders":[{"order_id":"44444444-4444-4444-8444-444444444444","sku":"RN-AE-3GB-15D","quantity":1,"status":"FULFILLED","provisioning_status":"SUCCEEDED","delivery_status":"DELIVERED","esim_activity_state":"NOT_STARTED","updated_at":"2027-01-15T10:20:00Z"}],"activation_delivery":"private_email_and_my_esim","activation_material_included":false,"refresh_after_seconds":0,"updated_at":"2027-01-15T10:20:00Z"}}}},"externalDocs":{"url":"https://roam-now.com/agents"}}