> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zbdpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Ramp Session

> Initialize a new ramp widget session for a user

## API Overview

### Base URL

All API requests should be made to:

```
https://api.zbdpay.com
```

### Authentication

All ZBD endpoints are protected by an API Key. To make requests against these endpoints you must pass a header property called `apikey` with your [ZBD Project API Key](/get-started/api-keys).

```json theme={null}
apikey: "your-api-key-here"
```

<Note>
  Get your API keys by [scheduling a call](https://zbd.one/sales) with our sales team.
</Note>

### SSL / HTTPS Access

**ZBD only provides a secure interface over HTTPS with SSL certificate support**. Any requests that attempt to reach the ZBD API in an insecure fashion (plain-text over HTTP requests) will be rejected.

## Description

This endpoint creates a session token and widget URL that can be used to embed the ZBD Ramp widget in your game or application.

## Usage

The ramp widget allows your users to purchase Bitcoin using their preferred fiat currency. The session creation process involves:

<CardGroup cols={1}>
  <Card title="First" icon="1" color="#000000">
    Create a session with user details and configuration options
  </Card>

  <Card title="Second" icon="2" color="#000000">
    Receive a widget URL and session token to embed in your application
  </Card>
</CardGroup>

## Configuration

### Header Parameters

<ParamField required header="apikey" type="string">
  ZBD Project API Key
</ParamField>

<ParamField initialValue="application/json" header="Content-Type" type="string">
  Content Type
</ParamField>

### Body Parameters

<ParamField required body="email" type="string">
  Email address of the user launching the Ramp
</ParamField>

<ParamField required body="webhook_url" type="string">
  URL to receive webhook notifications
</ParamField>

<ParamField body="access_token" type="string">
  Existing user session token (for returning users)
</ParamField>

<ParamField body="quote_currency" type="string">
  Currency to convert from (e.g., USD)
</ParamField>

<ParamField body="base_currency" type="string">
  Currency to convert to (e.g., BTC)
</ParamField>

<ParamField body="destination" type="string">
  Destination address for the funds (Lightning Address or onchain address)
</ParamField>

<ParamField body="reference_id" type="string">
  Your internal reference ID for this transaction
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the transaction
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.zbdpay.com/api/v1/ramp-widget \
    -H "Content-Type: application/json" \
    -H "apikey: YOUR_API_KEY" \
    -d '{
      "email": "user@example.com",
      "webhook_url": "https://yourapp.com/webhooks/zbd"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.zbdpay.com/api/v1/ramp-widget', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.ZBD_API_KEY
    },
    body: JSON.stringify({
      email: 'user@example.com',
      webhook_url: 'https://yourapp.com/webhooks/zbd'
    })
  });

  const data = await response.json();
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "session_token": "eyJraWQiOiJzLWE1OWNkMjc4...",
      "widget_url": "https://ramp.zbdpay.com/?session=eyJraWQiOiJzLWE1OWNkMjc4...",
      "session_id": "ses_9n3f7h2u4b",
      "expires_at": "2025-06-09T12:00:00Z"
    }
  }
  ```
</ResponseExample>

### Error Responses

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Please provide a valid email address"
  }
}
```

Common error codes:

* `INVALID_EMAIL` - Email format is invalid
* `INVALID_WEBHOOK_URL` - Webhook URL is not accessible
* `UNAUTHORIZED` - Invalid API key
* `RATE_LIMITED` - Too many requests

## Webhook Events

Webhooks are sent as POST requests to your specified `webhook_url`.

### Event Structure

All webhook events follow this structure:

```json theme={null}
{
  "id": "evt_2n4f8gu3nf",
  "type": "ramp.purchase.completed",
  "created_at": "2025-06-09T10:30:00Z",
  "livemode": true,
  "data": {
    // Event-specific data
  }
}
```