Skip to main content

Capturing Items

The capture request applies to two-stage payments and allows you to manually capture items in the authorized status. After the customer's money has been captured it is transferred from their account to the target account to complete the transaction.

You can capture the entire cart or specific items. There is also an option to use the modify request to reduce an item amount before capturing it (see the Modifying Items section for more information).

Please, note

The difference between the initiated item amount and the modified amount will be canceled. This action is irreversible.

By default, OmniCart provides 2 days (172800 seconds) to capture an item in the authorized status. If the item is not captured within this period, it enters the canceled status.

info

Capture settings may be configurable depending on your agreement with the acquiring bank and privileges in OmniCart. Configuration options are described below on this page.

Configuring capture settings​

The capture request​

Capturing Entire Cart​

info

After capturing the entire cart, all cart items enter the captured status.

To capture an entire cart, use the capture request respectively. The only mandatory property is cartId passed with the init request earlier.

{
  "cartId": "6f891edb-1e1f-48bb-b042-2cb790a0f402"
}

Capturing Specific Items​

info

After capturing specific cart items, these items enter the captured status.

To capture specific cart items, use the capture request. The specify the request scope, apart from the mandatory cartId value, provide the criteria for the items to be captured in the filterBox object.

You can use the tags and itemIds objects and the timerEnabled property.

Please, note

The requested cart must contain the specified tags or item identifiers, otherwise, the request will fail.

{
  "cartId": "6f891edb-1e1f-48bb-b042-2cb790a0f402",
  "filterBox": {
    "tags": [
      "rampart",
      "inferno"
    ]
  }
}

In the example above, only the items with the rampart and inferno tags will be captured.

The tags and itemIds objects and the timerEnabled property can be used in combinations.

The tags criterion ignores overlaps with the itemIds object properties. Consider the following example. You specify a tag and an item that is marked with the specified tag in the same request. OmniCart will capture all items marked with the specified tag and ignore the fact that the item is actually specified twice: with the tag and with its identifier.

If you pass the timerEnabled property, the request scope will be narrowed down to the items based on their timer settings (see the Item Timers section for more information).

  • "timerEnabled": false - the request applies only to the items with disabled (not set) timers.
  • "timerEnabled": true - the request applies only to the items with enabled timers.
  {
    "cartId": "6f891edb-1e1f-48bb-b042-2cb790a0f402",
    "filterBox": {
      "tags": [
        "rampart",
      ],
      "itemIds": [
        "crystal",
        "gems"
      ]
    }
  }

The example above assumes that the crystal item has been marked with the rampart tag and the gems item has no tags at all. The request will affect all items with the rampart tag including the crystal item and the gems item that is untagged.

Partial Item Capture​

With OmniCart, it is possible to reduce an item amount before capturing. For example, this might be needed if a customer paid for a product and, for some reason, the product cannot be (or was not) delivered in full quantity. To do this, use the modify request to change the item amount to a lower value. Note that you cannot increase the item amount with the modify request (see the Modifying Items and the Amounts sections for more information). The difference between the initial amount and the modified amount will be canceled. After that, you can use the capture request to capture the remaining amount.