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

  1. Generate the idempotency-key
    An idempotency key is a unique value generated by the client that 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.

  2. 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

/services/2/alt-transactions

/services/2/transactions/refund/:transactionIdRefund
/services/2/vaulted-shoppersCreate Vaulted Shopper
/services/2/recurring/plansCreate Plan
/services/2/recurring/subscriptionsCreate Subscription
/services/2/recurring/ondemandCreate Merchant-Managed Subscription
/services/2/recurring/ondemand/:subscriptionIdCreate Merchant-Managed Subscription Charge
/services/2/vendorsCreate Vendor
/services/2/wallets/onboardingOnboard Apple Pay
/services/2/report/dynamic-defCreate Custom Report
/services/2/account-updaterCreate 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.