Skip to main content
Networks fail in awkward places. A timeout does not tell you whether Perkstar accepted a request, so every production integration must be safe to retry.

​
Request idempotency

Send an Idempotency-Key with every POST request:
Use a stable value for one logical operation, not a new random value on each retry. Perkstar keeps the result for 24 hours and returns the same outcome when the same request is repeated.
OAuth REST-hook creation has a resource-lifecycle exception. For POST /webhooks, the idempotency key remains bound to the live subscription until that row is deleted, and a retry returns its signing secret. The event set must stay the same; apply a current callback URL, card, live/test mode, or active state with PATCH /webhooks/:id. Deleting the subscription releases the key immediately.
Reusing one key for a different request body is an integration error. Create a new key only when you intend to perform a new operation.

​
Permanent transaction deduplication

POS and commerce integrations should also send transaction.external_transaction_id to /marketplace/accrue.
This reference is unique for the business and remains a deduplication key after the 24-hour request cache expires. A repeated call returns the existing transaction with idempotent_replay: true. Use an upstream ID that is:
  • stable across webhook retries;
  • unique to one loyalty operation;
  • available again when a refund must reverse the operation; and
  • namespaced when several stores can produce the same numeric order ID.
Good: odoo:shop_12:pos_order:94721 Risky: 94721 Keep test and live references in separate namespaces, for example test:odoo:shop_12:pos_order:94721 and live:odoo:shop_12:pos_order:94721. Perkstar rejects a permanent transaction reference that already belongs to the other environment instead of silently replaying it.

​
Retry policy

A practical schedule is 1 second, 2 seconds, 4 seconds, then a background retry queue. Cap attempts and surface terminal failures for an operator to inspect.

​
Reversals

Reverse a transaction by Perkstar ID or by its original external_transaction_id. Give the reversal its own idempotency key. Test and live transactions cannot be reversed across environments. Use an identifier namespace owned by your integration; provider-managed prefixes such as sq_payment_ are reserved.