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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Capture and cancel modes

> This page describes the way that you can capture or cancel your payments with Payrails.

When authorizing a payment, you can choose to do it in two ways depending on your case:

* **One-step**: Authorize and Capture in the same step.
* **Two-Step**: Authorize first, and then capture in a different step.

Both options have pros and cons, and which one you use will depend on your type of business, use case, and factors like how often you change the authorized amount before actually capturing it.

The availability of each flow will depend on the providers you choose for processing the payment and other factors (payment method, type of card, country, etc.).

Good news! Payrails supports both modes, and it’s easy to configure your workflows to choose one or the other by default. Also, if for a specific workflow execution you need to override the default behavior, you can also do it.

## Capture Mode

| `captureMode` | Description | Recommended if… |
| :- | :- | :- |
| `Instant` | Authorize and capture payments in one step. If the payment provider has a specific endpoint for this type of operation (usually called “sale” or “charge”), we will use it. Otherwise, we will authorize and immediately capture your payment. Regardless of how many calls we make to the provider, you will only get one notification for this operation when it’s captured. | You don’t want to separate the authorization and capture steps in your process. |
| `Manual` (default) | In a two-step authorization, Payrails authorizes the payment but doesn’t capture neither schedule an automatic capture. For capturing the payment, you will have to execute the [Capture action](/reference/captureaction). | You want to have full control of the capture. Or have cases in which the capture amount is different than the authorized. |
| `Delayed` | In a two-step authorization, Payrails authorizes the payment and schedules its capture for the time indicated in the `captureDelay` field. If the payment is [Captured](/reference/captureaction) or [Canceled](/reference/cancelaction) before that time, the schedule is discarded. | You want to have a buffer time between authorizing and capturing your payments, but don’t want to execute the `Capture` yourself. |

## Cancel Mode

<Note>
  **Cancel vs. Refund vs. Void**

  In this case, we use the term “Cancel” to refer to canceling an authorization of a payment that has not been captured yet.

  A Refund can only be performed after a payment is Captured.
</Note>

| `cancelMode` | Description | Recommended if… |
| :- | :- | :- |
| `Manual` (default) | In a two-step authorization, Payrails authorizes the payment but doesn’t capture, cancel, or schedule any of them. This behaviour will leave up to the bank to release the funds eventually (usually up to 7 days), which may create friction with your customers. | You want full control of your payment process and don’t care about releasing the funds automatically. |
| `Delayed` | In a two-step authorization, Payrails authorizes the payment and schedules its canceling in case it’s neither [Captured](/reference/captureaction) or [Canceled](/reference/cancelaction) by you before. The delay time is determined by the `cancelDelay` field. | You want to release the funds automatically in case a capture isn’t made on time. |

<Danger>
  **Delays in both are not allowed**

  Please note that there could be a possible conflict if you set the value `Delayed` to both `captureMode` and `cancelMode`. We will reject that configuration because it can lead to unexpected behaviours.
</Danger>

## Delay defaults and formats

For both `captureDelay` and `cancelDelay`, we use the [ISO 8601 standard](https://tc39.es/proposal-temporal/docs/duration.html). If it’s your first time using it, you may find it a bit strange, but it’s super powerful!

If you choose a captureMode or cancelDelay of type `Delayed` but you don’t indicate a delay time in their respective fields, our **default is 5 minutes**.

## Multiple captures

By default, all our captures are final in the payment processor. If you want a different behaviour, please indicate it to your integration team.

This means, for example, that if you authorized 10 EUR, and then capture 7 EUR, the remaining 3 EUR are immediately released.


## Related topics

- [Create a workflow configuration](/reference/createworkflowconfiguration.md)
- [Cancel a payment](/docs/orchestration/payment-acceptance/cancel-a-payment.md)
- [Get a workflow configuration](/reference/getworkflowconfigurationversion.md)