menu

Payment API

What's on this page

API Reference / Void

Void API

Void Payments is an operation in the CCV Online Payments API to void pending transactions once they become successful. For example, when the actual payment is still pending at CCV, but you, the merchant, have already declined the transaction towards the customer for some reason. As a result of that decision, you would need to send a refund or reversal of the original transaction once it completes successfully.

To allow you to be proactive in the transaction outcome, CCV Online Payments provides the void operation. Once you know the transaction is declined towards the customer, you can send a void API request. When the void operation is accepted, CCV Online Payments will automatically void the transaction once it reaches the status success.

Depending on the transactionType and method of the original transaction, the void operation will result in a new refund or reversal transaction that will appear in your transaction list.

API Reference

API Request

  • Resource: /void
  • Method: POST
  • Content-Type: application/json
  • Authentication: basic auth
  • Supports idempotency
  • Parameters: reference: The unique reference of the transaction
    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/void?reference=I210917163546510CB87E181.2

API Response

  • Status Code: 204 or 400
  • Content Type: application/json

Limitations

Pending transactions

A void API request is only accepted for transactions that still have a pending status. If the transaction has already reached a final status, the API request will be rejected.

Supported payment methods and transaction types

The table below is an overview of what the inverse type will be if the payment is voided.

Method Initial Transaction Type Void Transaction Type
iDeal sale refund
Card authorise reversal
  • Initial Transaction Type: the type of the original transaction that must be voided
  • Void Transaction Type: the type of the resulting void transaction that voids the initial transaction

Examples

  • Voiding a pending payment of type sale, which then succeeds, will result in a refund of the payment
  • Voiding a pending payment of type sale, which then fails, will have no effect, there is nothing to void
  • Voiding a pending payment of type authorise, which then succeeds, will result in a reversal of the payment
  • Voiding a failed payment of type authorise, which then fails, will have no effect, there is nothing to void

If the transaction doesn’t support the void operation, the API request will be rejected.

Example:

{
  "type": "process_error",
  "message": "Transaction with reference I211122112444431CB87E180.1 can not be used for a void payment because the status is already final",
  "reference": "d8ae8cda",
  "failureCode": "rejected"
}

{
  "type": "process_error",
  "message": "Void payment for reference C211122112629960CB87E18B.1 is not supported for method card with Brand VISA or type SALE",
  "reference": "5fe91aa8",
  "failureCode": "rejected"
}

Best practices and use cases

Always request the status of the original transaction before sending a void request. This allows you to determine if you need to send a void request or another type of request depending on the status result of the original transaction.

Use-cases

A use-case where a void operation is well-suited for is a case where the transaction only has a limited timeframe in which it should be updated to the final status. In normal e-commerce situations, it does not matter if the transaction only reaches final status after an extended period of time.

There are cases where it does matter:

  • When using iDEAL in a bar where the customer needs to pay for their/her drinks. The customer will not wait more than a few minutes for their drinks.
  • When using deferred sales fueling cases. The customer is ready to fuel and will not wait more than a few minutes at the pump / gas station.

In these cases, you want to cancel the pending transaction and provide an alternative payment method to your customers. The original transaction should be voided if needed.

Dealing with rejected void requests

Void requests can be rejected by CCV Online Payments. Rejections happen because:

  • the status of the original transaction is already final.
  • the combination of the transaction type and method of the original transaction is not supported.

In case you receive a rejection, you should poll the status of the transaction. If the transaction has already reached a final status, you should send the appropriate action (refund or reversal) instead. If the transaction is still pending, you should check if the original transaction supports the void operation. If not, you should send the appropriate action yourself once the status becomes final.

Dealing with timeouts

If you do not receive an HTTP response of 204 or 400, you can send the void request again.