Hosted ramp session

A session describes one money movement (flow) that your user completes on a hosted page.

1. Create the session

POST /api/connect/ramp/core/sessions
X-API-Key: gr_live_...
Connect-Brand: paylink

{
  "flow": "onramp",
  "amount": 10000,
  "asset": "XOF",
  "customer_id": "7b0c1f7e-2a51-4a63-9a43-1d6d2f8e9c10",
  "collection_account": "cash",
  "success_url": "https://app.example.com/ok",
  "failure_url": "https://app.example.com/ko"
}

flow is one of checkout, onramp, offramp, convert, sweep, transfer, treasury_in, treasury_out, menu, onramp_to_user, openconnect_payment. currency, currencies and from_account are refused: use asset, assets and collection_account / payout_account. Send Idempotency-Key (or idempotency_key) to make retries safe.

2. Send the user to the hosted page

POST /api/connect/ramp/core/sessions/{id}/hosted-token returns what the hosted SoftShell needs. The hosted page itself talks to /api/connect/ramp/sessions/public/*. The page uses the session's brand (Connect-Brand).

3. Execute server-side (optional)

POST /api/connect/ramp/core/sessions/{id}/execute

{
  "to": { "asset": "XOF", "chain": "base" },
  "dest_virtual_account_id": "c5a7…",
  "idempotency_key": "ramp-exec-001"
}

For a virtual account destination, the to.asset line must already exist on the account. For a wallet destination, give a token, never a fiat code.

4. Follow it

Subscribe to connect.ramp.session.* (webhooks) or read GET /api/connect/ramp/core/sessions/{id}.