---
name: payment-widget
description: >-
  Guides through using Smart Glocal payment widget to accept card payments:
  token generation, widget rendering, 3DS handling, and integration with
  the payment session flow. Use when the user asks about widget, frontend
  integration, or PCI DSS compliance.
---

# Payment Widget

## Purpose

Use this skill when you want to accept card payments using the Smart Glocal payment widget. The widget handles card data collection on the frontend, reducing your PCI DSS compliance scope.

The widget flow works alongside the [standard payment flow](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md) — the widget replaces the manual `session/start/payment` step.

## Primary references

- [One-time payment](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md) — full payment flow details
- [token generation](https://developer.smart-glocal.com/reference/methods/token)
- [Widget integration docs](https://developer.smart-glocal.com/payments/payment-widget)

## Preconditions

- [ ] Payment session created via `session/create` (see [one-time-payment](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md))
- [ ] Frontend page ready to render the widget

## How the Widget Works

```
Your server:                   Frontend (widget):             Smart Glocal:
session/create  ────→          render(token)  ───────────→    collect card
  (get session id)             buyer enters card details      send to server
                                ↓
token generation               widget sends start/payment
  (get public token)                                            ↓
                                ↓                            ready_to_confirm
                              redirect to 3DS (if needed)     webhook
                                ↓                            ──────────→ your server
                              return to your site                      ↓
                                                                  session/confirm
                                                                  or session/cancel
```

## 1. Generate a Public Token

Call `POST /api/v2/token` on your server:

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

The response returns a `token` string — pass it to the frontend.

## 2. Render the Widget

Include the Smart Glocal widget script on your payment page and call the render function:

```javascript
SmartGlocal.render({
  token: '<token_from_server>',
  locale: 'en',            // optional: 'en', 'pt', 'es', etc.
  onSuccess: function(response) {
    // Payment session confirmed — wait for webhook on server side
    console.log('Payment initiated:', response.session_id);
  },
  onError: function(error) {
    // Handle error on the frontend
    console.error('Payment error:', error);
  }
});
```

After rendering, the widget:
1. Shows the card form to the buyer
2. Collects card details (PAN, expiry, CVV)
3. Sends `session/start/payment` to Smart Glocal
4. Handles 3DS redirect inside the widget

## 3. Continue on the Server

The widget does **not** call `session/confirm` — that remains your responsibility on the server side.

After the widget completes:
1. Wait for `ready_to_confirm` webhook from Smart Glocal
2. Verify the payment details
3. Call `session/confirm` or `session/cancel`

## 4. 3D Secure

If the card requires 3DS:
- The widget automatically handles the redirect
- The buyer sees the 3DS challenge inside the widget
- After authentication, the flow continues — no extra action needed from you

## 5. Widget for Tokenization

To collect card data for [recurring payments](https://developer.smart-glocal.com/assets/skills/recurring/SKILL.md) without charging immediately, use the tokenization widget:

```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 '{
    "tokenize_widget": {
      "session_id": "ps_xxx"
    }
  }'
```

## Important Links

- [Widget docs](https://developer.smart-glocal.com/payments/payment-widget)
- [Token method](https://developer.smart-glocal.com/reference/methods/token)
- [One-time payment](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md)