---
name: one-time-payment
description: >-
  Guides through accepting a one-time card payment via Smart Glocal API:
  session creation, payment initiation, confirmation, 3D Secure handling,
  and webhook processing.
---

# One-time Payment by Card

## Purpose

Use this skill to accept a one-time card payment (Mastercard, Visa) via the Smart Glocal API. This covers the full flow from session creation to payment confirmation, including 3D Secure handling.

There are two ways to pass card details:

- **Open parameters** — you collect card data on your side (PCI DSS required). This skill covers this option.
- **Payment widget** — the Smart Glocal widget collects card data, reducing PCI DSS burden. See the [payment-widget](https://developer.smart-glocal.com/assets/skills/payment-widget/SKILL.md) skill.

## Primary references

- [One-time payment docs](https://developer.smart-glocal.com/payments/one-time-payment)
- [Payment parameters](https://developer.smart-glocal.com/payments/params)
- [session/create](https://developer.smart-glocal.com/reference/methods/session-create)
- [session/confirm](https://developer.smart-glocal.com/reference/methods/session-confirm)
- [Webhooks](https://developer.smart-glocal.com/reference/reference-webhooks)
- [Payment widget](https://developer.smart-glocal.com/assets/skills/payment-widget/SKILL.md)

## Preconditions

- [ ] RSA keys and authentication configured (see [getting-started](https://developer.smart-glocal.com/assets/skills/getting-started/SKILL.md))
- [ ] Project ID (`shop1` for sandbox)
- [ ] Test card numbers ready for sandbox testing

## Flow

```
session/create  →  session/start/payment  →  ready_to_confirm (webhook)
    →  session/confirm  →  [action_required → 3DS]  →  payment_finished (webhook)
```

## 1. Create a Payment Session

Send `POST /api/v2/session/create` to the Smart Glocal server.

### Request

```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 '{
    "amount_details": {
      "amount": 10000,
      "currency": "usd"
    },
    "payment_details": {
      "type": "card"
    },
    "customer": {
      "id": "cust_123",
      "email": "buyer@example.com"
    },
    "participant_details": {
      "sender": {
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "city": "New York",
        "street": "5th Ave 1",
        "ipv4": "192.168.1.1",
        "postal_code": "10001",
        "email": "john.doe@example.com"
      }
    },
    "metadata": {
      "order_id": "order_456"
    }
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount_details.amount` | Yes | Amount in the smallest currency unit (10000 = 100 USD) |
| `amount_details.currency` | Yes | Currency code (`usd`, `eur`, etc.) |
| `payment_details.type` | Yes | Payment type (`card`) |
| `customer.id` | No | Customer ID in your system |
| `customer.email` | Yes | Customer email |
| `participant_details.sender` | Yes* | Sender details (improves conversion) |
| `metadata` | No | Any custom data, returned in responses and webhooks |

> * — if you don't pass `participant_details.sender`, Smart Glocal will generate the data automatically, but conversion may be lower.

### Response

```json
{
  "status": "ok",
  "session": {
    "id": "ps_xxx",
    "status": "created",
    "redirect_url": "..."
  }
}
```

Save `session.id` — you will need it in the next steps.

## 2. Start the Payment

Send `POST /api/v2/session/start/payment` with `session.id` and card details.

> **Note:** This step is needed if you did not pass all parameters in `session/create`. If you pass card details directly in `session/create`, use `session/init/payment` instead — it combines steps 1 and 2.

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/start/payment \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx",
    "payment_details": {
      "type": "card",
      "card": {
        "pan": "4000000000000002",
        "expiry": "12/2026",
        "cvv": "123"
      }
    }
  }'
```

## 3. Wait for ready_to_confirm

Smart Glocal processes the data and sends the `ready_to_confirm` webhook. This means the system is ready to proceed and is waiting for your confirmation.

Your server should:
1. Accept the webhook
2. Respond with HTTP 200 OK
3. Check payment details (amount, currency, etc.)
4. If everything is correct — proceed to step 4 (confirm)

## 4. Confirm the Payment

Send `POST /api/v2/session/confirm`:

```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"
  }'
```

### Or Cancel

If the payment needs to be cancelled for any reason:

```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"
  }'
```

## 5. 3D Secure (if required)

If the card is enrolled in 3D Secure, after confirm you will receive an `action_required` webhook with a `redirect_url` for buyer authentication.

Your server:
1. Accepts `action_required`
2. Responds HTTP 200 OK
3. Redirects the buyer to `redirect_url`
4. After 3DS completion — wait for `payment_finished`

## 6. Payment Result

The final `payment_finished` webhook contains the result:

```json
{
  "event": "payment_finished",
  "session_id": "ps_xxx",
  "status": "succeeded",
  "metadata": {
    "order_id": "order_456"
  }
}
```

| Status | Meaning |
|--------|---------|
| `succeeded` | Payment successful |
| `failed` | Payment declined |
| `pending` | Payment is being processed |

Always rely on the webhook status, not the confirm response.

## Widget Flow

To use the Smart Glocal payment widget instead of passing card parameters directly, see the dedicated **payment-widget** skill:

👉 [Payment widget](https://developer.smart-glocal.com/assets/skills/payment-widget/SKILL.md)

The widget handles card collection, token generation, and 3DS — you still call `session/confirm` on your server.

## Test Cards (Sandbox)

| Scenario | PAN |
|----------|-----|
| Successful payment | `4000000000000002` |
| Failed payment | `4000000000000005` |
| 3D Secure | `4000000000000101` |