{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Idempotency (Coming Soon)","type":"basic","slug":"idempotency","excerpt":"","body":"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.\n\nFor 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.\n\n###How does idempotency work?\nStart 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. \n\nIf 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.\n\n###Using Idempotency\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Please reach out to your BlueSnap Implementation Specialist to enable idempotency.\"\n}\n[/block]\n1. **Generate the `Idempotency-Key`**\nAn 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.\n\n2. **Add the `Idempotency-Key` to your request header**\nAdd 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.\n\n###Request Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-H 'Idempotency-Key: 59a3401e-55f1-40f3-b582-90ae2265c709' \\\\\\n-d '\\n{\\n  \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n  \\\"softDescriptor\\\": \\\"DescTest\\\",\\n  \\\"amount\\\": \\\"11.00\\\",\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"cardHolderInfo\\\": {\\n    \\\"firstName\\\": \\\"test first name\\\",\\n    \\\"lastName\\\": \\\"test last name\\\",\\n    \\\"zip\\\": \\\"123456\\\"\\n  },\\n  \\\"creditCard\\\": {\\n    \\\"cardNumber\\\": \\\"4263982640269299\\\",\\n    \\\"securityCode\\\": \\\"837\\\",\\n    \\\"expirationMonth\\\": \\\"02\\\",\\n    \\\"expirationYear\\\": \\\"2023\\\"\\n  }\\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"Basic Auth Capture request with Idempotency-Key\"\n    }\n  ]\n}\n[/block]\n###APIs with Idempotency\n\nIdempotency applies to all our transactional APIs.The `Idempotency-Key` header is accepted by the following APIs:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"URL\",\n    \"h-1\": \"API Names\",\n    \"0-0\": \"/services/2/transactions\",\n    \"0-1\": \"* [Auth Capture](https://developers.bluesnap.com/v8976-JSON/docs/auth-capture)\\n* [Auth Only](https://developers.bluesnap.com/v8976-JSON/docs/auth-only)\",\n    \"1-0\": \"/services/2/alt-transactions\",\n    \"1-1\": \"* [Create PayPal Transaction](https://developers.bluesnap.com/v8976-JSON/docs/create-paypal-transaction)\\n* [Create ECP Transaction](https://developers.bluesnap.com/v8976-JSON/docs/create-ecp-transaction)\",\n    \"2-0\": \"/services/2/transactions/refund/:transactionId\",\n    \"2-1\": \"[Refund](https://developers.bluesnap.com/v8976-JSON/docs/refund)\",\n    \"3-0\": \"/services/2/vaulted-shoppers\",\n    \"3-1\": \"[Create Vaulted Shopper](https://developers.bluesnap.com/v8976-JSON/docs/create-vaulted-shopper)\",\n    \"4-0\": \"/services/2/recurring/plans\",\n    \"4-1\": \"[Create Plan](https://developers.bluesnap.com/v8976-JSON/docs/create-plan)\",\n    \"5-0\": \"/services/2/recurring/subscriptions\",\n    \"5-1\": \"[Create Subscription](https://developers.bluesnap.com/v8976-JSON/docs/create-subscription)\",\n    \"6-0\": \"/services/2/recurring/ondemand\",\n    \"6-1\": \"[Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription)\",\n    \"7-0\": \"/services/2/recurring/ondemand/:subscriptionId\",\n    \"7-1\": \"[Create Merchant-Managed Subscription Charge](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription-charge)\",\n    \"8-0\": \"/services/2/vendors\",\n    \"8-1\": \"[Create Vendor](https://developers.bluesnap.com/v8976-JSON/docs/create-vendor)\",\n    \"9-0\": \"/services/2/wallets/onboarding\",\n    \"9-1\": \"[Onboard Apple Pay](https://developers.bluesnap.com/v8976-Tools/docs/onboard-apple-pay-merchant)\",\n    \"10-0\": \"/services/2/report/dynamic-def\",\n    \"10-1\": \"[Create Custom Report](https://developers.bluesnap.com/v8976-Tools/docs/create-custom-report)\",\n    \"11-0\": \"/services/2/account-updater\",\n    \"11-1\": \"[Create Account Updater](https://developers.bluesnap.com/v8976-Tools/docs/create-account-updater)\",\n    \"12-0\": \"/services/2/cp/user?onbehalfofmid=\",\n    \"13-0\": \"/services/2/batch/order-placement\",\n    \"14-0\": \"/services/2/orders\",\n    \"15-0\": \"/services/2/shoppers\",\n    \"16-0\": \"/services/2/catalog/products\",\n    \"17-0\": \"/services/2/catalog/products\",\n    \"18-0\": \"/services/2/catalog/custom-parameters\",\n    \"19-0\": \"/services/2/subscriptions/:subscription-id/subscription-charges\"\n  },\n  \"cols\": 2,\n  \"rows\": 20\n}\n[/block]\nKeep 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.\n\n###Troubleshooting\n\nRefer to our [Idempotency Errors](https://developers.bluesnap.com/v8976-JSON/docs/idempotency-errors) guide for a complete list of possible errors.","updates":[],"order":3,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"610a9e2f2921db01061b0378","createdAt":"2021-08-04T14:03:27.518Z","user":"606df105d9ab93003f73cb10","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"API Usage","slug":"payment-api-essentials","order":1,"from_sync":false,"reference":false,"_id":"60f9b8e6969e03006edca8ec","version":"60f9b8e6969e03006edca94a","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-10-01T16:42:25.324Z","__v":0},"version":{"version":"8976-Basics","version_clean":"8976.0.0-Basics","codename":"3.39 Release","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["60f9b8e6969e03006edca8eb","60f9b8e6969e03006edca8ec","60f9b8e6969e03006edca8ed","60f9b8e6969e03006edca8ee","60f9b8e6969e03006edca8ef","60f9b8e6969e03006edca8f0","5beb278ac442ab0213f00990","60f9b8e6969e03006edca8f1","5c3f542c12c4ac004bc51718","60f9b8e6969e03006edca8f2","5df806ccecebde0059f17225","5dfa8a8f340c2b007418eb8a","60f9b8e6969e03006edca8f3","5e597199fd2b0200117c2c1c"],"_id":"60f9b8e6969e03006edca94a","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"609978ff6a29a202e39f0aa5","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z"},"project":"57336fd5a6a9c40e00e13a0b","__v":0,"parentDoc":null}

Idempotency (Coming Soon)


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

Please reach out to your BlueSnap Implementation Specialist to enable idempotency.

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

  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/transactions/refund/:transactionId

/services/2/vaulted-shoppers

/services/2/recurring/plans

/services/2/recurring/subscriptions

/services/2/recurring/ondemand

/services/2/recurring/ondemand/:subscriptionId

/services/2/vendors

/services/2/wallets/onboarding

/services/2/report/dynamic-def

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