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. It does this by adding a key to the request and checking whether it is unique. If every item in the payment request matches the previous call, the system does not retry the request and warns that it was submitted before.

If the idempotency key matches a previous one but the payment information differs, the system returns 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.