Skip to main content

Cancellation and Refund

Cancellation and refund are two different operations that can be done on different stages of the payment life cycle.

Cancellation is possible with the two-step payment scheme. This operation can be done after a payment is authorized and before it is captured. At this stage, the customer's money has not been transferred from their account. Instead, it is held on their account waiting to be captured by the merchant. On cancellation, the issuing bank removes the hold from the customer's funds, and the funds are released back to the customer. Another word for cancellation is reversal.

Refund is done after a payment has been completed. At this stage, the customer's money is transferred to the target account so it has to be transferred back to their account. This operation may incur fees.

Please, keep in mind
  • All items to be canceled must be in the authorized status.
  • All items to be refunded must be in the completed status.

Use the status request to check the current item statuses.

Although cancellation and refund are two different operations, the required API properties are the same. The information below applies to both.

You can cancel or refund an entire cart or specific cart items with the cancel and refund requests respectively. There is also an option to partially cancel or refund specific cart items. To do that, the modify request is used.

Please, note

Neither the cancel nor refund request affects item timers. If you need to change timer settings, use the modify request. See the Item Timers for more information.

Entire Cart​

info

After canceling or refunding the entire cart, all cart items enter the canceled or refunded status respectively.

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

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

Specific Items​

info

After canceling or refunding specific cart items, these items enter the canceled or refunded status respectively.

To cancel or refund specific cart items, use the cancel or refund request respectively. The specify the request scope, apart from the mandatory cartId value, provide the criteria for the items to be canceled or refunded 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 canceled/refunded.

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 cancel/refund 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.

Specific Items, partial cancellation/refund​

With OmniCart, it is possible to partially cancel or refund cart items. 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 returned to the customer automatically.

Partial cancellation or refund can be done multiple times. That said, to fully cancel or refund an item, use the cancel and refund requests respectively, as changing an item amount to zero is not allowed.

Please, note

After a partial cancellation or refund, an item remains in the authorized or completed status respectively.