> For the complete documentation index, see [llms.txt](https://docs.esimpay.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.esimpay.net/eng/quick-start.md).

# Quick Start

### Prerequisites

1. **Merchant credentials**
   * `CF-MERCHANT-ID` — your merchant identifier
   * `CF-API-SECRET` — the secret key used for signatures
2. **API Secret** — obtain it from your account dashboard

### Step 1: Check your balance (no signature required)

This is the simplest request for testing your connection:

```bash
curl -X GET https://api.esimpay.net/api/v1/customer/balance \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

**answer :**

```json
{
  "status": "completed",
  "message": null,
  "balance": 1000.0
}
```

### Step 2: Get the list of available packages

```bash
curl -X GET https://api.esimpay.net/api/v1/products/list \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

### Step 3: Create an order (signature required)

POST requests require an HMAC-SHA256 signature.

#### Generating a signature (Python)

```python
import json
import hmac
import hashlib
import base64
import requests

MERCHANT_ID = 'your_merchant_id'
API_SECRET = 'your_api_secret'
BASE_URL = 'https://api.esimpay.net/api/v1'

def sign(payload: dict):
    # 1. We sort the keys and remove the spaces.
    json_str = json.dumps(
        payload,
        separators=(',', ':'),
        ensure_ascii=False,
        sort_keys=True,
    )
    
    # 2. HMAC-SHA256
    digest = hmac.new(
        API_SECRET.encode('utf-8'),
        json_str.encode('utf-8'),
        hashlib.sha256,
    ).digest()
    
    # 3. Base64
    signature = base64.b64encode(digest).decode('utf-8')
    return json_str, signature

# Example: creating an order
payload = {
    'orderId': 'order_123',
    'productId': 'b27bfd74-c46d-479c-b628-ec7ca69a146f',
    'activationMode': 'NOW',
}

body, signature = sign(payload)

response = requests.post(
    f'{BASE_URL}/orders/submit',
    data=body,
    headers={
        'Content-Type': 'application/json',
        'CF-MERCHANT-ID': MERCHANT_ID,
        'CF-ACCESS-SIGN': signature,
    },
)

print(response.json())
```

### Step 4: Check the status

```bash
curl -X GET "https://api.esimpay.net/api/v1/customer/history?limit=10" \
  -H "CF-MERCHANT-ID: your_merchant_id"
```

### Next steps

1. Read Authentication to understand the security model
2. Review all API Endpoints
3. Pick the examples for your language
4. Check out Error Handling

#### Tips

#### Use interactive testing

**Open the OpenAPI Interactive Modul**e — here you can:

* Test all endpoints
* See example requests/responses
* Generate code for different languages

#### Keep your API Secret safe

```python
# ✅ Correctly
import os
from dotenv import load_dotenv

load_dotenv()
API_SECRET = os.getenv('ESIMPAY_API_SECRET')
```

```bash
# The .env file (add to .gitignore)
ESIMPAY_API_SECRET=your_secret_key
ESIMPAY_MERCHANT_ID=your_merchant_id
```

***

#### Ready to get started? Head to Authentication!