---
name: api-methods
description: >-
  Covers shared Smart Glocal API methods used across all payment scenarios:
  session/status, token generation, idempotency keys, error format, and API
  version differences between v1 and v2.
---

# API Methods

## Purpose

This skill covers shared API methods and concepts that apply across all payment scenarios — session status checks, token generation, idempotency keys, error handling, and API version differences. Use it alongside scenario-specific skills.

## Primary references

- [API interaction](https://developer.smart-glocal.com/reference/reference-format)
- [Error codes](https://developer.smart-glocal.com/reference/reference-errors)
- [All methods](https://developer.smart-glocal.com/reference)
- [API objects](https://developer.smart-glocal.com/reference/reference-objects)

## Preconditions

- [ ] RSA keys and authentication configured
- [ ] Project ID obtained
- [ ] One of the scenario-specific skills loaded (e.g., [one-time-payment](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md))

---

## Session Methods

Most operations in Smart Glocal API are performed within a **payment session**. A session can contain one or more operations (payment, refund, payout).

### session/status

Get full information on a payment session — check whether an operation completed, view holds, refunds, etc.

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/status \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx"
  }'
```

The response contains the session object with all operations (payments, refunds), their statuses, amounts, and timestamps.

### session/confirm

Confirm an operation after receiving `ready_to_confirm` webhook. Available for 240 minutes after creation — after that the session automatically cancels.

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/confirm \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx"
  }'
```

**Response**: `status: ok` — confirmation queued. Wait for `payment_finished` webhook for the final result.

### session/cancel

Cancel an operation before it completes. Releases a hold (delayed capture) or cancels a pending payment.

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/cancel \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx"
  }'
```

**Response**: `status: ok` — cancellation queued. Wait for `payment_finished` webhook.

---

## Token Generation

Generate a **public token** to render Smart Glocal's payment or tokenization widget on the frontend. The token is valid for 24 hours and can only be used once.

### token

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/token \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "acquiring_widget": {
      "session_id": "ps_xxx"
    }
  }'
```

| Parameter | Description |
|-----------|-------------|
| `acquiring_widget.session_id` | Session ID to bind the token to |
| `tokenize_widget` | Use for tokenization widget instead |
| `fps_no_account_widget` | Use for payment form for money transfers |

**Response**: returns `token` string — pass this to the frontend widget.

---

## Idempotency Key

The `X-PARTNER-IDEMPOTENCY-KEY` header prevents duplicate operations. If a request fails (network error, timeout), retry with the same key and the API will not create a duplicate.

- **Length**: 4–64 characters
- **TTL**: 24 hours
- **Scope**: unique per key — a key used for one session cannot be reused for another

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/create \
  -H "X-PARTNER-IDEMPOTENCY-KEY: my_unique_key_12345" \
  ...
```

If a duplicate is detected, the API returns the original response instead of processing a new request.

---

## Error Format

All API errors follow a consistent format:

```json
{
  "status": "error",
  "error": {
    "code": "error_code",
    "description": "Human-readable description"
  }
}
```

Common error codes:

| Code | Meaning |
|------|---------|
| `invalid_parameters` | Missing or invalid fields in the request |
| `expired_card` | Card has expired |
| `insufficient_funds` | Insufficient funds on the card |
| `declined` | Payment declined by the bank |
| `duplicate_request` | Same idempotency key used for different request |
| `session_expired` | Session timed out |

> **Important**: If the payment status is `failed` and the session status is `error`, do not retry immediately. The `error` status may be intermediate. Contact Smart Glocal support.

---

## API Version Differences

Smart Glocal supports **v1** and **v2**. The differences are primarily in field names:

| Concept | v1 | v2 |
|---------|----|----|
| Card payment | `acquiring_payments` | `payment_list` |
| Payout | `payments` | `payout_list` |
| Payment method | `payment_method` | `payment_details` / `payout_details` |

**v2** is recommended for new integrations. The endpoint URL changes:

- v1: `api/v1/session/create`
- v2: `api/v2/session/create`

All other fields (amount_details, customer, participant_details, etc.) are the same across versions.