Idempotency

Warning: This functionality is not yet available for general use. Before integrating, ensure that you've been in contact with your Relationship Manager.

Idempotency prevents the processing of duplicate authorisation, capture, refund orpayout(offline only) requests by using unique keys. You create Universally Unique Identifiers (UUIDs) that you use as Idempotency Keys, and include these within the Idempotency-Key HTTP header field.

This page covers:

  • How Idempotency works
  • Setting up Idempotency requests
  • Generating and using Idempotency keys
  • Responses
  • Testing Idempotency
  • Error handling
  • Order notifications

Prerequisite: You're using theDirectintegration method (or Direct withClient Side Encryption) for card payments.

How it works

Idempotency flow

For all supported requests:

  1. You send an authorisation/capture/refund/payout request.
  2. You create an Idempotency Key for this request and send it to Worldpay.
  3. We check to see whether we've received the Key before.
    1. If it's an existing Key, we'll provide you with the original response. The request is not processed.
    2. If it's a new Key, we store it and process the request.
  4. We provide you with the response.

Get set up

When you're getting set up with the Idempotency feature, you need to decidehow long) you want your Idempotency Keys and corresponding responses to be stored. You also need to be aware of what happensif we cannot checkthe IK.

Time to Live (TTL)

When you're being set up to use the Idempotency feature, you can choose how long you want us to retain your Idempotency Keys, from 1 to 365 days.

After an Idempotency Key expires we will process a subsequent request using that Key as normal, and will store the new response.

If we cannot check the IK

If we're unable to check an Idempotency Key, we will process the request anyway. If the request is a duplicate, we will detect this and let you know in the Idempotency - Duplicate Keys report. When including Idempotency Keys in your authorisation, capture, refund and payout requests, you will receive certain responses back from us depending on the result of the check. Remember, you submit your requests as you normally would; just include the Idempotency Key within the Idempotency-Key HTTP header field.

Idempotency Keys

HTTP request header

Each Idempotency Key must be a Universally Unique Identifier (UUID), and you must manage the generation of your own keys to ensure that duplicates are not generated accidentally. Duplicate keys are only detected when provided by the same customer, so only submissions you provide can throw a duplicate error.

This is an example of a valid Idempotency-Key header:

Idempotency-Key: eb2c14b9-4b8d-440f-8b31-560eec7e90d9

Best Practices

Use a random UUID generator

UUIDs are very large (128-bit) numbers. To avoid the "accidental" creation of duplicate keys, we recommend using a randomly generated UUID for your Idempotency Keys. This is especially important when generating Idempotency Keys for different request types as duplicates are identified by key and not, for example, the type of request. If you use the same key for a refund as you did for a previous authorisation, you'll get the authorisation response back.

When you try again

When we check Idempotency Keys, the outcome of the original request is not considered. For example, if you want to retry a request that was originally refused, you must use a different Idempotency Key. If you simply replay the exact same request, you will receive the original refused response.

Responses

These are the responses we will provide within the Idempotency-Status HTTP response field.

Response headerMeaningAction
[no header]Idempotency is not enabled for you and you did not send an Idempotency-Key header.
or
Unsupported request type or payment method was used in the request.
Check your integration/setup.
Not RequestedIdempotency Key was not provided for a request type that would have been checked (authorise, capture, refund or payout) if a key had been provided.You may wish to confirm this is expected behaviour for the request type.
Invalid KeyIdempotency Key was not a valid UUID.Check your integration.
UnavailableIdempotency checking was not available.Check the Idempotency - Duplicate Keys report.
DuplicateIdempotency checking done and a duplicate request was found.In some cases, you may want to determine if the duplicate was the result of the expected behaviour.
OKIdempotency checking done and Idempotency Key confirmed not to be a duplicate.N/A
In ProgressIdempotency checking done and an in progress duplicate was found.Retry

Secure test

You can test all Idempotency scenarios in Secure test - take a look at the table below.

ScenarioHow to testExpected outcome
OKSubmit a request with a new and valid IK that we have not seen before.Within the header, you'll receive OK.
The request is processed as normal.
In ProgressSubmit a request with the following IK: 00000000-0000-0000-0000-000000000001Within the header, you'll receive In Progress.
You'll receive the following error: 9 - Request in progress.
DuplicateSubmit a request with a valid IK that you've used before.Within the header, you'll receive Duplicate.
You'll receive the original response from the first request.
[no header]Submit an authorisation request with a valid IK but an unsupported payment method, such as an alternative payment method.If you provide an IK for a payment method that isn't supported, we'll process the request as normal without checking the Idempotency Key.
Invalid KeySubmit a request with an invalid IK.Within the header, you'll receive Invalid Key.
You'll receive the following error: 9 - Invalid Idempotency-key.
UnavailableSubmit a request with the following IK: 00000000-0000-0000-0000-000000000002Within the header, you'll receive Unavailable.
Check the Idempotency - Duplicate Keys report.
Not RequestedSubmit a request for a supported operation/payment method without an IK.Within the header, you'll receive Not Requested.
The request will be processed as normal.

Errors

Idempotent requests can be tested within the Secure Test environment.

All Idempotency errors are reported under error code 9, which is specific to the feature. The errors are returned within the standard error message:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
 "http://dtd.WorldPay.com/paymentService_v1.dtd">
 <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> 
   <reply>
     <orderStatus orderCode="YOUR_ORDER_CODE">
       <error code="9"> <!--This error code is specific to Idempotency-->
         <![CDATA[Error message]]>
       </error>
     </orderStatus>
   </reply>
 </paymentService>

Error table

Error codeDescriptionMeaning
9Request in progressA request with the same Idempotency Key is currently being processed.
9Invalid idempotency-keyThe Idempotency-Key header value is invalid.
9Service not enabledIdempotent requests are not enabled for this customer.

Order notifications

You can add a Worldpay generated Idempotency Key toorder notificationsprovided they are in this format:

  • Protocol: HTTP/S
  • Content: XML

The key is added to the HTTP header as a UUID unique for each payment status event. Should a notification need to be resent the key will be consistent. As we generate the key, the testing scenarios and errors described in this guide do not apply.

To receive keys in your notifications, set the Send Idempotency Key to yes under the Merchant Channel tab in theMAIfor test and production:

MAI idempotency channels

This is an example of an Idempotency-Key in the notification header:

Idempotency-Key: 3751852c-fa40-3fd3-9b7d-5cc865ac80cf