Idempotency

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

For example, if you create a request that doesn't respond for some reason, such as a network error, you can 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 that contains the same idempotency key, HTTP parameters, and body, then BlueSnap returns the previous response and includes the idempotency key to indicate that the response was processed idempotently. If a request contains an idempotency key that is already associated with a different HTTP parameter set or request body, then BlueSnap returns an error. BlueSnap stores idempotency 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:

Request types like GET, DELETE, and PUT are already idempotent by definition and do not require the additional header. The idempotency header is ignored when it is included with these request types.

Troubleshooting

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