> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel and Capture Flow

When integrating with Yuno, you have multiple options for implementing capture and cancel operations. This guide outlines all available approaches and explains how to interact with our APIs for each scenario.

We provide simple real-time capture for fast transactions, as well as highly customizable delayed capture and cancel configurations to meet your business needs.

## Overview

* [**Capture modes**](#capture-modes)
  * [Real-time capture](#real-time-capture)
  * [Manual capture](#manual-capture)
  * [Delayed capture](#delayed-capture)
* [**Cancel modes**](#cancel-modes)
  * [Manual cancel](#manual-cancel)
  * [Delayed cancel](#delayed-cancel)
* [**Configuration requirements**](#configuration-requirements)
* [**Example requests**](#example-requests)
  * [Example 1: Real-time capture](#example-1-real-time-capture)
  * [Example 2: Manual capture only](#example-2-manual-capture-only)
  * [Example 3: Delayed capture](#example-3-delayed-capture)
  * [Example 4: Delayed cancel](#example-4-delayed-cancel)
  * [Example 5: Combined delayed capture and cancel](#example-5-combined-delayed-capture-and-cancel-with-enhanced-validation)
* [**When to use each mode**](#when-to-use-each-mode)
* [**Field reference**](#field-reference)

## Capture modes

Yuno provides three options for capturing payments, determined by the `capture` field and optional `delayed_capture_settings` configuration found in the [create payment API](/reference/create-payment). The actual feature availability or specific implementation details may vary depending on which payment provider you're routing your payments through.

### Real-time capture

This mode processes the payment and transfers the funds without any delay, effectively combining authorization and capture into a single **purchase** operation. When `payment_method.detail.card.capture` is set to `true`, the transaction is executed as a purchase, which means the authorization and capture happen simultaneously.

Depending on the payment provider's API, Yuno may execute this as one direct purchase transaction or as an authorization immediately followed by a capture call.

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          // card details
        }
      }
    }
  }
}
```

### Manual capture

With this configuration, Yuno won't capture the payment until you call the [capture API](/reference/capture-authorization) or manually capture it in your [Yuno dashboard](https://dashboard.y.uno/). Set `capture: false` to authorize the payment without capturing it.

Manual captures provide maximum flexibility since they give you full control of when the capture is performed. However, it's important to capture as soon as possible since payment providers enforce time limits on how long authorizations can remain uncaptured, and these limits vary by provider and region.

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          // card details
        }
      }
    }
  }
}
```

<Warning>
  ****Capturing Different Amounts****

  If you need to capture a different amount than originally authorized, you must use manual capture. The real-time and delayed capture modes will always capture the initially authorized amount.
</Warning>

### Delayed capture

Configure `capture: false` along with `delayed_capture_settings` to schedule the capture of the payment for a later time, specified in the `delay` field.

<Warning>
  **Full Amount Captures Only**

  Delayed capture only applies when capturing the **full amount** of the authorization. If you need to capture a partial amount, you must use [manual capture](/docs/capture-payments) instead.
</Warning>

<Note>
  **`simplified_mode`**

  Setting `simplified_mode` to `true` will make Yuno retry the capture operation in case an error occurs during the scheduled capture attempt.
</Note>

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}
```

The `delay` field is required when using delayed capture operations and must follow the <a label="ISO 8601 standard" target="_blank" href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601 standard</a>. For example:

* `"PT3H"` for 3 hours
* `"P7D"` for 7 days
* `"P1M"` for 1 month

If you call the [capture API](/reference/capture-authorization) before the scheduled time, your call will override the delay and execute the capture immediately. **This action automatically cancels the scheduled Yuno trigger**. Alternatively, you can capture the payment manually through your [Yuno dashboard](https://dashboard.y.uno/).

## Cancel modes

When you authorize a payment without immediately capturing it, those funds are temporarily held on the customer's payment method. If you decide not to capture the payment, it's important to cancel the authorization to release those held funds and provide a better customer experience. Cancel modes give you control over when and how these authorizations are voided.

### Manual cancel

With manual cancel mode, authorized payments stay active until you explicitly cancel them. Yuno will not automatically void these authorizations, giving you full control over when to release the funds. You can cancel authorizations using the [cancel API](/reference/cancel-or-refund-a-payment) or through your Yuno dashboard interface.

It's crucial to cancel authorizations you won't capture as soon as possible to release the held funds. Customer experience is significantly impacted when authorizations aren't canceled, as funds may remain reserved for varying periods depending on the customer's region and card network.

### Delayed cancel

Configure `delayed_cancel_settings` to set a delay when canceling uncaptured authorizations, similar to delayed captures. This feature automates the release of customer funds if you decide not to capture them within a specified timeframe, significantly improving the customer experience by preventing indefinite holds on their payment methods.

The `delay` field is required when using delayed cancel operations and must follow the <a label="ISO 8601 standard" target="_blank" href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601 standard</a>. For example:

* `"PT3H"` for 3 hours
* `"P7D"` for 7 days
* `"P30D"` for 30 days

<Note>
  **`simplified_mode`**

  Setting `simplified_mode` to `true` will make Yuno retry the cancel operation in case an error occurs during the scheduled cancellation attempt.
</Note>

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}
```

If you call the [capture API](/reference/capture-authorization) or [cancel API](/reference/cancel-or-refund-a-payment) before the scheduled time, your call will override the delay and execute the action immediately. **This action automatically cancels the scheduled Yuno trigger**. Alternatively, you can capture or cancel the payment manually through your Yuno dashboard.

<Info>
  ****Delayed Capture and Cancel Settings****

  We recommend not using **both** `delayed_capture_settings` and `delayed_cancel_settings` simultaneously to avoid unexpected behaviors. Use only one at a time based on your needs.
</Info>

## Configuration requirements

* `delayed_capture_settings` and `delayed_cancel_settings` are only valid when `capture = false`
* If `capture = true`, these objects must be omitted or set to `null`
* Manual operations can be performed via API endpoints or through your Yuno dashboard

## Example requests

### Example 1: Real-time capture

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": true,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Real-time capture payment",
  "merchant_order_id": "000023"
}
```

### Example 2: Manual capture only

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization only - manual capture",
  "merchant_order_id": "000024"
}
```

### Example 3: Delayed capture

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P7D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed capture",
  "merchant_order_id": "000025"
}
```

### Example 4: Delayed cancel

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        }
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Authorization with delayed cancel",
  "merchant_order_id": "000026"
}
```

### Example 5: Combined delayed capture and cancel with enhanced validation

This example shows a complete payment request with both delayed capture and cancel settings, along with enhanced customer validation fields:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "merchant_customer_validations": {
      "account_is_verified": true,
      "email_is_verified": true,
      "phone_is_verified": true
    },
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "workflow": "DIRECT",
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_capture_settings": {
          "delay": "P20D",
          "simplified_mode": true
        },
        "delayed_cancel_settings": {
          "delay": "P40D",
          "simplified_mode": true
        },
        "card_data": {
          "number": "4111111111111111",
          "expiration_month": 11,
          "expiration_year": 28,
          "security_code": "123",
          "holder_name": "John Doe"
        },
        "verify": false
      }
    },
    "type": "CARD"
  },
  "account_id": "<account_id>",
  "description": "Payment with card details",
  "merchant_order_id": "000023"
}
```

<Info>
  **Note**

  While this example shows both `delayed_capture_settings` and `delayed_cancel_settings` configured together, we recommend using only one at a time to avoid unexpected behaviors.
</Info>

## When to use each mode

### Use real-time capture when:

* You provide goods or services immediately
* You don't need to validate inventory or fraud checks after authorization
* You want the simplest payment flow

### Use manual capture when:

* You need to verify inventory before finalizing the payment
* You want to capture a different amount than authorized
* You have complex business logic that determines whether to capture or cancel
* You need maximum control over the capture timing

### Use delayed capture when:

* You want automatic capture after a specific time period
* You have a predictable fulfillment process
* You want to reduce manual intervention while maintaining control

### Use delayed cancel when:

* You want to automatically release customer funds if you don't capture within a timeframe
* You want to improve customer experience by not holding funds indefinitely
* You have a maximum time limit for your fulfillment process

## Field reference

| Field                                      | Type      | Description                                                                                                                                                                                                                                |
| ------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `capture`                                  | `boolean` | Determines whether the card payment is captured immediately (`true`, purchase) or only authorized (`false`, requires capture or cancel).                                                                                                   |
| `delayed_capture_settings.delay`           | `string`  | Delay before Yuno captures the payment. Must follow <a label="ISO 8601 duration format" target="_blank" href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601 duration format</a> (e.g., "P7D" for 7 days, "PT3H" for 3 hours). |
| `delayed_capture_settings.simplified_mode` | `boolean` | If `true`, Yuno retries the capture if it fails.                                                                                                                                                                                           |
| `delayed_cancel_settings.delay`            | `string`  | Delay before Yuno cancels the authorization. Must follow <a label="ISO 8601 duration format" target="_blank" href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601 duration format</a> (e.g., "P30D" for 30 days).              |
| `delayed_cancel_settings.simplified_mode`  | `boolean` | If `true`, Yuno retries the cancel if it fails.                                                                                                                                                                                            |