What is Idempotency?

Idempotency refers to the individual tokenization of a request, preventing duplicate transactions.

Idempotency (REQUEST-TOKEN) is useful because it prevents duplicate requests, such as creating or updating transactions, from being processed twice.

Within the Payrix API platform, all request tokens are shared across all requests and expire after 48 hours. This prevents customers from submitting a payment transaction twice and subsequently being double-charged.

The request_tokens database table stores customer tokens for idempotency protection in API requests.

Model Class	`Payrix\Models\RequestTokens`
Resource Category Number	129
Short Name	`rqt`

The request_tokens table keeps a record of all requestTokens in Payrix. A RequestToken represents a unique token for idempotency protection.

When the API successfully completes a request with this identifier, a requestToken is stored with the identifier set as the token and the resource/resourceID set to the resource category number and record ID of the resource created. When future creation requests for the same resource are received with the same identifier, the API will retrieve the original record and return it along with a field indicating that this request was already made and completed successfully.

Idempotency Protection using the API:

1. Send a REQUEST-TOKEN with a Created or Updated transaction.

CODE SNIPPET

CODE

POST: /txns
HEADERS: 
  REQUEST-TOKEN: abcdef123456
BODY:
  {
    "type":"1",
    "merchant":"000000000000007",
    "mid":"01242567",
    "origin":"2",
    "total":"4500",
    "terminal":"123654789",
    "payment":{
      "number":"4111111111111111",
      "expiration":"0818",
      "cvv":"123"
    },
    "zip":"99999"
  }

A record in the RequestTokens table will be created containing:

- The ID of the Logged-In User

- The Given Token

- The Primary Resource Category Number

- The ID of the Created/Updated resource.

NOTE: The RequestTokens table is not available to all users (only ADMINs have access to the table) and records can be created, queried, or deleted.

2. Request to create a new transaction will be blocked:
(Note it’s still using the same REQUEST-TOKEN)

CODE SNIPPET

CODE

POST: /txns
HEADERS: 
  REQUEST-TOKEN: abcdef123456
BODY:
  {
    "type":"1",
    "merchant":"000000000000007",
    "mid":"01242567",
    "origin":"2",
    "total":"4500",
    "terminal":"123654789",
    "payment":{
      "number":"4111111111111111",
      "expiration":"0818",
      "cvv":"123"
	},
    "zip":"99999"
  }
RESPONSE:
  "details": {
    "duplicateRequest": true
  }

3. Request to update the transaction will be blocked:
(Note it’s still using the same REQUEST-TOKEN)

CODE SNIPPET

CODE

PUT: /txns/00000000000000001
HEADERS: 
  REQUEST-TOKEN: abcdef123456
BODY:
  {
    "batch":null
  }
RESPONSE:
  "details": {
    "duplicateRequest": true
  }

4. Request to update the transaction will be processed:
(Note the New REQUEST-TOKEN)

CODE SNIPPET

CODE

PUT: /txns/00000000000000001
HEADERS: 
  REQUEST-TOKEN: 123456abcdef
BODY:
  {
    "batch":null
  }

5. The Request to create a new transaction will be processed even though the transaction seems to be
a duplicate:
(Note the New REQUEST-TOKEN)

CODE SNIPPET

CODE

POST: /txns
HEADERS: 
  REQUEST-TOKEN: 654321fedcba
BODY:
  {
    "type":"1",
    "merchant":"000000000000007",
    "mid":"01242567",
    "origin":"2",
    "total":"4500",
    "terminal":"123654789",
    "payment":{
      "number":"4111111111111111",
      "expiration":"0818",
      "cvv":"123"
    },
    "zip":"99999"
  }

Additional Information

To find more information about the RequestToken table, visit our API Documentation Portal.