Our APIs support idempotency for safely retrying requests without accidentally duplicating the result. This can be helpful when your API call fails and you aren't sure if Column received it - it enables you to retry that request without worrying it will cause a duplicate transaction.

In order to perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request for the endpoint that supports it. The <key> can be any string that uniquely identifies your request. Results of successful requests with Idempotency-Key will be saved and returned on every subsequent request with the same Idempotency-Key.

The Idempotency-Key header is currently supported for creating Book, ACH and Wire transfers:

• POST /transfers/book
• POST /transfers/wire
• POST /transfers/ach

Idempotency keys can be up to 255 characters long.

Example

curl https://api.column.com/transfers/ach \
  -XPOST \
  -u :{api-key} \
  -d counterparty_id={couterpary_id} \
  -d bank_account_id={bankaccount_id} \
  -d type=CREDIT \
  -d amount=10000 \
  -d currency_code=USD \
  -d description="payment"

Such API call can be part of various flows in your end-user application, for example in the Web UI to make payouts. If for some reason the call will be repeated, intentionally or not (eg. clicking submit button twice), this can result in creating two transfers and double spending the money.

Use of Idempotency-Key can help prevent this from happening.

By adding Idempotency-Key header and setting it to some user generated value that'll uniquely identify the API call, subsequent call with the same Idempotency-Key won't create another transfer and instead return the one created on first call.

If we'll set the same Idempotency-Key in our application logic for a given action like this:

curl https://api.column.com/transfers/ach
  -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
  -u :{api-key}
  -d counterparty_id="cpty_1vX6b45fQ41k62xEXjjIHe5kiRM"
  -d bank_account_id="bacc_1vX9r5qaj6YDm7y4ohOujR0af1Q"
  -d amount=1000
  -d currency_code=USD
  -d description="idempotent payment"
  -d type=CREDIT

{
  "id": "acht_1zBxTIB8yEQdb2LyptJ1PFZIO8k",
  // <...>
}

curl https://api.column.com/transfers/ach
  -H "Idempotency-Key: 1zByArFNupaumBTijz3XXTlj9ZL"
  -u :{api-key}
  -d counterparty_id="cpty_1vX6b45fQ41k62xEXjjIHe5kiRM"
  -d bank_account_id="bacc_1vX9r5qaj6YDm7y4ohOujR0af1Q"
  -d amount=1000
  -d currency_code=USD
  -d description="idempotent payment"
  -d type=CREDIT

{
  "id": "acht_1zBxTIB8yEQdb2LyptJ1PFZIO8k",
  // <...>
}

We will prevent from double spend! Both responses now will look the same, which you can tell by the ID of ACH object being the same. This means that only the first API call actually created the transfer and second call, because the Idempotency-Key was the same, returned the result of the first one and did not create a new transfer.