Idempotency

If a payment attempt is made repeatedly, Stax will send a message stating that this operation has been performed and will not reattempt the same transaction. This is done by adding a key to the request that is checked to see if it is unique. If every item in the payment request is identical to the previous call, the request is not retried, and the system warns that this has been submitted before.

If the idempotency key is identical to previous ones, but the payment information differs, the system will return an error related to the different parameters.

The StaxJS .pay function, POST /charge endpoint, and POST invoice/{id}/pay endpoint all support an idempotency_id parameter. This string value is expected to be unique across every request.

However, if the same idempotency_id is given in a subsequent POST /charge request, the API will identify it as a duplicate request and will not create a new charge. Instead, the API will respond with the original transaction for that idempotency_id.

const idempotencyId = uuid();

const extraDetails = {
  idempotency_id: idempotencyId, // optional, unique - if a duplicate value is given, will not make a new payment and will instead return the original
  total: 26,
  firstname: "John",
  lastname: "Doe",
  month: "10",
  year: "2020",
  phone: "5555555555",
  address_1: "100 S Orange Ave",
  address_2: "Suite 400",
  address_city: "Orlando",
  address_state: "FL",
  address_zip: "32811",
  address_country: "USA",
  send_receipt: false,
  validate: false,
  meta: {
    subtotal: 20.0, // optional - will show up in emailed receipts
    tax: 4.0, // optional - will show up in emailed receipts, and used for L2 processing. Accepts the tax in dollar amount. To qualify for L2 processing rates, the tax dollar amount must be equivalent to 0.1% and 30% of the transaction's total.
  },
};

staxjs
  .pay(extraDetails)
  .then((response) => {
    console.log("invoice object:", response);
    console.log("transaction object:", response.child_transactions[0]);
  })
  .catch((err) => {
    console.log("unsuccessful payment:", err);
  });

An idempotency key is a unique value generated by the user. This key is used to recognize subsequent retries of the same request. Idempotency keys can be 255 characters.

The user is expected to generate this idempotency_id value and provide it in the request.

Note: Using a UUID for this value is recommended.

You can use a library to generate a UUID, or use built-in utils within your preferred programming language. The following are a few generators:

Node: crypto.randomUUID (https://nodejs.org/api/crypto.html#cryptorandomuuidoptions)
PHP: [uniqid] (https://www.php.net/manual/en/function.uniqid.php)

The idempotency process compares parameters to the original request and errors if they are not identical. Results are only saved if an API endpoint starts executing without validation errors or is not concurrently running.