---
name: getting-started
description: >-
  Guides developers through initial Smart Glocal API setup: access request,
  RSA key pair generation, authentication headers, sandbox testing, first
  request (session/create), and going live.
---

# Getting Started with Smart Glocal API

## Purpose

This skill guides you through the initial Smart Glocal API setup — from requesting access to making your first test request in the sandbox environment.

## Primary references

- [AI Playbook](https://developer.smart-glocal.com/ai-playbook)
- [Methods reference](https://developer.smart-glocal.com/reference)
- [Error codes](https://developer.smart-glocal.com/reference/reference-errors)
- [Go-live checklist](https://developer.smart-glocal.com/assets/skills/go-live-checklist/SKILL.md)

## Preconditions

- [ ] Project ID obtained from Account Manager (for sandbox use `shop1`)
- [ ] RSA key pair generated (see section 3 below)

---

Smart Glocal API is a REST API for accepting payments and making payouts. It supports an **agent model**: you (the partner) can initiate payments on your own behalf or on behalf of sub-merchants.

## 1. API Access

To get access, contact your Smart Glocal Account Manager. You will receive:
- **Project ID** — your unique project identifier
- Access to the sandbox environment for testing

> ⚡ **For sandbox demo** you can use a ready Project ID: `shop1`. All examples below work with it.

## 2. Environment

The API is available in two environments:

| Environment | Base URL |
|-------------|----------|
| Sandbox (testing) | `https://demo.smart-glocal.com` |
| Production (live) | `https://proxy.smart-glocal.com` |

All methods are available at: `<base_url>/api/v{version}/{method}`

Two API versions are supported — **v1** and **v2**. **v2** is recommended for new integrations.

## 3. Authentication

Every request must include three headers:

### X-PARTNER-PROJECT
Your project ID (string, provided by your Account Manager).

### X-PARTNER-SIGN
Request body signature. Generated as follows:

1. Generate an RSA key pair (2048 bits)
2. Share your public key with your Account Manager
3. Sign the raw JSON request body using SHA-256 with your private key
4. Encode the signature in Base64

```
Signature = Base64(SHA-256(request_body, private_key))
```

5. Pass it in the `X-PARTNER-SIGN` header

### X-PARTNER-SUBMERCHANT (optional)
If you are initiating a payment on behalf of another legal entity (sub-merchant), pass their ID in this header.

### X-PARTNER-IDEMPOTENCY-KEY (optional)
Idempotency key (4–64 characters). If a request fails, retrying with the same key will not create a duplicate. The key lives for 24 hours.

## 4. Your First Request

Test the API in the sandbox environment. The simplest request is creating a payment session:

### Example curl

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/create \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session": {
      "payment_method": "card",
      "amount": 1000,
      "currency": "USD",
      "description": "Test payment"
    }
  }'
```

### Response

```json
{
  "success": true,
  "session": {
    "id": "sess_abc123",
    "status": "created",
    "redirect_url": "https://checkout.smart-glocal.com/sess_abc123"
  }
}
```

Redirect the buyer to `redirect_url` to complete card payment.

## 5. Testing

In the sandbox environment, use test card numbers to simulate different scenarios:

| Behavior | Card Number |
|----------|-------------|
| Successful payment | `4000000000000002` |
| Failed payment | `4000000000000005` |
| 3D Secure | `4000000000000101` |

See the full list of test cards in the documentation.

## 6. Webhook Verification

Smart Glocal sends webhooks about payment status changes. Verify the webhook signature using Smart Glocal's public key:

- **Live**: [smgl_public.pem](https://developer.smart-glocal.com/assets/smgl_public.pem)
- **Demo**: [smgl_public_demo.pem](https://developer.smart-glocal.com/assets/smgl_public_demo.pem)

## 7. Going Live

When you're ready to move from sandbox to production, see the dedicated **go-live checklist** skill:

👉 [Go-live checklist](https://developer.smart-glocal.com/assets/skills/go-live-checklist/SKILL.md)

It covers credentials, environment switch, webhook configuration, cutover procedure, and rollback plan.

## Important Links

- [Full API documentation](https://developer.smart-glocal.com)
- [AI Playbook](https://developer.smart-glocal.com/ai-playbook)
- [Methods reference](https://developer.smart-glocal.com/reference)
- [Error codes](https://developer.smart-glocal.com/reference/reference-errors)
- [Go-live checklist](https://developer.smart-glocal.com/assets/skills/go-live-checklist/SKILL.md)