---
name: delayed-capture
description: >-
  Guides through two-phase (delayed capture) card payments via Smart Glocal
  API: placing a hold on funds, waiting for ready_to_capture webhook, then
  capturing or cancelling before the hold expires.
---

# Delayed Capture (Two-Phase Payment)

## Purpose

Use this skill when you need to place a hold on funds and capture them later — for example, when you need to verify goods before charging, ship before billing, or reduce chargebacks and refunds.

## Primary references

- [Delayed capture docs](https://developer.smart-glocal.com/payments/payment-capture)
- [session/capture](https://developer.smart-glocal.com/reference/methods/session-capture)
- [session/confirm](https://developer.smart-glocal.com/reference/methods/session-confirm)
- [Webhooks](https://developer.smart-glocal.com/reference/reference-webhooks)

## Preconditions

- [ ] Delayed capture enabled by your Account Manager (not available by default)
- [ ] [One-time payment](https://developer.smart-glocal.com/assets/skills/one-time-payment/SKILL.md) flow understood
- [ ] RSA keys and authentication configured

---

A delayed capture payment differs from a regular one in that the funds are not debited immediately. First, the bank **places a hold** on the amount, and you decide whether to capture or release it.

> **Delayed capture must be enabled** by your Account Manager.

## How it Differs from a Regular Payment

```
Regular payment:        confirm → payment_finished
Delayed capture:  confirm → ready_to_capture → capture → payment_finished
```

Between `ready_to_capture` and `capture` you control the timing.

## Hold Period

By default, funds are held for **3 days 23 hours**. If you don't call `session/capture` within this period, the hold is automatically released.

If you need a different period, discuss it with your Account Manager.

## Flow

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

## 1. Create a Session

Same as a regular payment: `POST /api/v2/session/create`

```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": {
      "email": "buyer@example.com"
    },
    "participant_details": {
      "sender": {
        "full_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "city": "New York",
        "street": "5th Ave 1",
        "ipv4": "192.168.1.1",
        "postal_code": "10001"
      }
    }
  }'
```

Save `session.id` from the response.

## 2. Start the Payment

```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. Confirm and Hold

Wait for the `ready_to_confirm` webhook → respond `200 OK` → call `session/confirm`. Smart Glocal will request the bank to place a hold on the funds.

If the card requires 3DS, you will receive `action_required` — complete the authentication.

## 4. ready_to_capture — Hold Successful

The `ready_to_capture` webhook means the bank has successfully held the funds.

```json
{
  "event": "ready_to_capture",
  "session_id": "ps_xxx",
  "amount": 10000,
  "currency": "usd",
  "metadata": { "order_id": "order_456" }
}
```

The funds are not yet debited. You can:

- **Capture** — call `session/capture`
- **Release** — call `session/cancel` (funds are unblocked)
- **Do nothing** — after 3 days 23 hours the hold is automatically released

## 5. Capture

When ready to debit, send `POST /api/v2/session/capture`:

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

You can capture **only part** of the held amount (e.g., capture 70 out of 100 USD). Specify a different amount in `amount_details.amount`.

## 6. Result

The `payment_finished` webhook provides the result:

| Status | Meaning |
|--------|---------|
| `succeeded` | Funds captured successfully |
| `failed` | Capture failed (e.g., insufficient funds) |
| `pending` | Still processing |

## Releasing a Hold Early

Call `session/cancel` before the hold expires:

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

The funds will be returned to the buyer's card (usually within a few days).

## Widget Flow

If using the [payment widget](https://developer.smart-glocal.com/assets/skills/payment-widget/SKILL.md): after `session/confirm` the widget handles 3DS automatically. Everything else is the same — wait for `ready_to_capture` and call `session/capture`.