Idempotency (Beta)

Idempotency is used to safely retry HTTP POST requests to prevent your requests from being performed multiple times. This ensures transactions will not be accidentally duplicated.

For example, if you create a request that doesn't respond for some reason, such as a network error, you will be able to retry the same request using the same Idempotency-Key in order to guarantee that only one transaction is created.

How does idempotency work?

Start by creating the Idempotency-Key header for your API request. An idempotency key is a unique value generated by the client which the resource server uses to recognize subsequent retries of the same request. See our guidelines for generating a key value in the section below.

If there is an existing request containing the same idempotency key, HTTP parameters and body, the previous response will be returned. The response will include the idempotency key to indicate the request was processed idempotently. Keep in mind that we store keys for up to 24 hours.

Using Idempotency

Generate the Idempotency-Key
An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. You may generate this key however you prefer. We support a maximum of 64 characters and recommend using a UUID that follows established standards.
Add the Idempotency-Key to your request header
Add an Idempotency-Key to your API request using the key you generated in the previous step as the value for your header. See the example below.

Request Example

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-H 'Idempotency-Key: 59a3401e-55f1-40f3-b582-90ae2265c709' \
-d '
{
  "cardTransactionType": "AUTH_CAPTURE",
  "softDescriptor": "DescTest",
  "amount": "11.00",
  "currency": "USD",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name",
    "zip": "123456"
  },
  "creditCard": {
    "cardNumber": "4263982640269299",
    "securityCode": "837",
    "expirationMonth": "02",
    "expirationYear": "2023"
  }
}'

APIs with Idempotency

Idempotency applies to all our transactional APIs.The Idempotency-Key header is accepted by the following APIs:

URL	API Names
/services/2/transactions	Auth Capture Auth Only Capture Auth Reversal
/services/2/alt-transactions	Create PayPal Transaction Create ECP Transaction
/services/2/transactions/refund/:transactionId	Refund
/services/2/vaulted-shoppers	Create Vaulted Shopper
/services/2/recurring/plans	Create Plan
/services/2/recurring/subscriptions	Create Subscription
/services/2/recurring/ondemand	Create Merchant-Managed Subscription
/services/2/recurring/ondemand/:subscriptionId	Create Merchant-Managed Subscription Charge
/services/2/vendors	Create Vendor
/services/2/wallets/onboarding	Onboard Apple Pay
/services/2/report/dynamic-def	Create Custom Report
/services/2/account-updater	Create Account Updater
/services/2/cp/user?onbehalfofmid=
/services/2/batch/order-placement
/services/2/orders
/services/2/shoppers
/services/2/catalog/products
/services/2/catalog/products
/services/2/catalog/custom-parameters
/services/2/subscriptions/:subscription-id/subscription-charges

Keep in mind that request types like GET, DELETE, and PUT are already idempotent by definition and do not require the additional header. If the idempotency header is included, it will be ignored.

Troubleshooting

Refer to our Idempotency Errors guide for a complete list of possible errors.