Idempotency Token
The IdempotencyToken parameter provides a merchant wide unique identifier for any transaction to prevent duplicate authorisations in the event of replays or retries.
For each Monek Merchant ID only one transaction will be allowed against each merchant specified idempotency token.
Request Fields
| Field Name | Description | Req'd | Size | Type |
|---|---|---|---|---|
| IdempotencyToken | Specifies a merchant wide unique identifier for this transaction | O | 50 max. | A |
Idempotency Duplicate Handling
When a duplicate idempotency token is received for the same Monek Merchant ID:
-
If the transaction header details do not match the original header the transaction will be rejected with code "30" and the message "IDEMPOTENCY ERROR".
- Transaction header fields included in this check are: Monek ID, Terminal ID, Message Number, Message Type, Dispatch, Amount, Cashback Amount, Currency Code, Country Code, Cross Reference, Card Token, and Payment Reference.
-
Within an initial processing window, initially 30 minutes, the transaction will return the original authorisation response data along with the DuplicateIndicator "IDEMPOTENCY".
-
After the initial processing window, the transaction will return response code "30" with the message "IDEMPOTENCY REPLAY" along with the Cross Reference of the original transaction and the DuplicateIndicator "IDEMPOTENCY".
- There is no expiry for idempotency values, they will be retained indefinitely.
-
If the authorisation platform detects a duplicate idempotency token for a transaction still in progress it will attempt to wait for the transaction to complete and return the appropriate response as described in 2. If this is not possible the transaction response will return "IDEMPOTENCY HOLD".
- In the event of an "IDEMPOTENCY HOLD" the transaction should typically be retried which would then pick up the original response as described in 2.
-
If a duplicate idempotency token is detected but the original transaction details are unavailable the transaction will be rejected with code "30" and the message "IDEMPOTENCY UNAVBLE".
- This is likely due to the original transaction being rejected prior to processing. e.g. Format or validation errors.
Note: When a transaction is supplied with a different idempotency value it will still be subject to standard duplicate checks and may still be identified as a duplicate transaction.
To disable standard duplicate processing use the DuplicateDelay request parameter or contact support@monek.com to disable by default.
Response Fields
| Field Name | Description | Size | Type |
|---|---|---|---|
| DuplicateIndicator | Contains the reason for a duplicate transaction response. - DUPLICATE - IDEMPOTENCY | 20 max. | A |
Idempotency Response Message Text
The response Message field may now contain one of several key values based on IdempotencyToken processing:
| Message Type | Description |
|---|---|
| IDEMPOTENCY ERROR | A duplicate idempotency token was provided but primary transaction details were different from original transaction. |
| IDEMPOTENCY REPLAY | A duplicate idempotency token was provided for a transaction processed over 30 minutes ago. The transaction response will include the original Cross Reference. |
| IDEMPOTENCY UNAVBLE | A duplicate idempotency token was provided but the original transaction response is unavailable.This is likely due to the original transaction being rejected prior to processing. e.g. Format or validation errors. |
| IDEMPOTENCY HOLD | A duplicate idempotency token was provided but the matching transaction may still be in process, so it was not possible to provide a full response. |
Idempotency Recommendations
- The Idempotency field allows 50 characters and is suitable for several formats:
- GUID
- Base64 encoded SHA-2 256-bit Hash
- Custom merchant transaction reference
- The idempotency format and value is at the merchant's discretion, but care should be taken to ensure it will always be unique.
- To avoid misuse of the idempotency value is should be protected and not made publicly available.
- For Server-to-Server TransactDirect API calls the value would not be directly disclosed.
- For TransactDirect Hosted Page integrations the Prepared Payments feature should be used to ensure the Idempotency value is not exposed to end users.