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
  • Real-time capture
  • Manual capture
  • Delayed capture
• Cancel modes
  • Manual cancel
  • Delayed cancel
• Configuration requirements
• Example requests
  • Example 1: Real-time capture
  • Example 2: Manual capture only
  • Example 3: Delayed capture
  • Example 4: Delayed cancel
• When to use each mode
• 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. 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. Set capture: true to capture the payment immediately after authorization.

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.

{
  "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 or manually capture it in your Yuno dashboard. 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.

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "card_data": {
          // card details
        }
      }
    }
  }
}

🚧

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.

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.

📘

simplified_mode

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

{
  "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 ISO 8601 standard. For example:

• "PT3H" for 3 hours
• "P7D" for 7 days
• "P1M" for 1 month

If you call the capture API before the scheduled time, your call will override the delay and execute the capture immediately. Alternatively, you can capture the payment manually through your Yuno dashboard.

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 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 ISO 8601 standard. For example:

• "PT3H" for 3 hours
• "P7D" for 7 days
• "P30D" for 30 days

📘

simplified_mode

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

{
  "payment_method": {
    "detail": {
      "card": {
        "capture": false,
        "delayed_cancel_settings": {
          "delay": "P30D",
          "simplified_mode": false
        },
        "card_data": {
          // card details
        }
      }
    }
  }
}

If you call the capture API or cancel API before the scheduled time, your call will override the delay and execute the action immediately. Alternatively, you can capture or cancel the payment manually through your Yuno dashboard.

⚠️

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.

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

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "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

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "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

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "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

{
  "country": "US",
  "amount": {
    "currency": "USD",
    "value": "20000"
  },
  "customer_payer": {
    "id": "<customer_id>",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "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"
}

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