---
updatedAt: 2025-11-14T20:16:01.000Z
agentTools:
  projectIndex: https://developers.bluesnap.com/llms.txt
---

# 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 Basic Auth Capture request with idempotency-key
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:

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        URL **/services/2/**
      </th>

      <th>
        API Names
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `transactions`
      </td>

      <td>
        [Auth Capture](https://developers.bluesnap.com/v8976-JSON/reference/auth-capture)  
        [Auth Only](https://developers.bluesnap.com/v8976-JSON/reference/auth-only)  
        [Capture](https://developers.bluesnap.com/v8976-JSON/reference/capture)  
        [Auth Reversal](https://developers.bluesnap.com/v8976-JSON/reference/auth-reversal)
      </td>
    </tr>

    <tr>
      <td>
        `alt-transactions`
      </td>

      <td>
        [Create PayPal Transaction](https://developers.bluesnap.com/v8976-JSON/reference/create-paypal-transaction)  
        [Create ECP Transaction](https://developers.bluesnap.com/v8976-JSON/reference/create-ecp-transaction)
      </td>
    </tr>

    <tr>
      <td>
        `transactions/refund/:transactionId`
      </td>

      <td>
        [Refund](https://developers.bluesnap.com/v8976-JSON/reference/refund)
      </td>
    </tr>

    <tr>
      <td>
        `vaulted-shoppers`
      </td>

      <td>
        [Create Vaulted Shopper](https://developers.bluesnap.com/v8976-JSON/reference/create-vaulted-shopper)
      </td>
    </tr>

    <tr>
      <td>
        `recurring/plans`
      </td>

      <td>
        [Create Plan](https://developers.bluesnap.com/v8976-JSON/reference/create-plan)
      </td>
    </tr>

    <tr>
      <td>
        `recurring/subscriptions`
      </td>

      <td>
        [Create Subscription](https://developers.bluesnap.com/v8976-JSON/reference/create-subscription)
      </td>
    </tr>

    <tr>
      <td>
        `recurring/ondemand`
      </td>

      <td>
        [Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-JSON/reference/create-merchant-managed-subscription)
      </td>
    </tr>

    <tr>
      <td>
        `recurring/ondemand/:subscriptionId`
      </td>

      <td>
        [Create Merchant-Managed Subscription Charge](https://developers.bluesnap.com/v8976-JSON/reference/create-merchant-managed-subscription-charge)
      </td>
    </tr>

    <tr>
      <td>
        `vendors`
      </td>

      <td>
        [Create Vendor](https://developers.bluesnap.com/v8976-JSON/reference/create-vendor)
      </td>
    </tr>

    <tr>
      <td>
        `wallets/onboarding`
      </td>

      <td>
        [Onboard Apple Pay](https://developers.bluesnap.com/v8976-Tools/reference/onboard-apple-pay-merchant)
      </td>
    </tr>

    <tr>
      <td>
        `report/dynamic-def`
      </td>

      <td>
        [Create Custom Report](https://developers.bluesnap.com/v8976-Tools/reference/create-custom-report)
      </td>
    </tr>

    <tr>
      <td>
        `account-updater`
      </td>

      <td>
        [Create Account Updater](https://developers.bluesnap.com/v8976-Tools/reference/create-account-updater)
      </td>
    </tr>

    <tr>
      <td>
        `cp/user?onbehalfofmid=`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `batch/order-placement`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `orders`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `shoppers`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `catalog/products`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `catalog/products`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `catalog/custom-parameters`
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        `subscriptions/:subscription-id/subscription-charges`
      </td>

      <td>

      </td>
    </tr>
  </tbody>
</Table>

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](https://developers.bluesnap.com/v8976-JSON/reference/idempotency-errors) guide for a complete list of possible errors.