Idempotency helps merchants mitigate operational or financial issues caused by accidental duplicate API calls.

Idempotency requires that the merchantReference field is unique per merchant and per environment. The API verifies this uniqueness and returns an error if the value is a duplicate.

For verification workflows, Trustly recommends using unique merchant references for captures and verifications. This prevents validation errors when reusing a reference from a capture that achieved an Authorized status.

Availability

Idempotency protection applies to transactions that reach the Authorized, Processed, or Completed status. This validation is active for the following transaction types:

Pay
Authorize
Capture
Deposit

If you are unable to support the unique merchant reference requirement, please contact support.

Capture and deposit API usage

To execute the Capture API and Deposit API requests, you must pass the following fields:

splitToken: The Split Token received from the Bank Authorization Notification.
amount: The amount to be captured or deposited.
merchantReference: Your specific, unique identifier for this transaction . This value appears in Event Notifications and Reports.

Duplicate request response

If a duplicate merchantReference is sent for a transaction that is already complete with a status of Authorized,Processed, or Completed, the API ignores the request and returns the following response:

Code	Description
`210`	`This is a duplicate request. It has been ignored`

Idempotency edge cases

This following tables details specific transaction scenarios and statuses where the duplicate merchantReference validation is either not applied or requires special consideration.

Scenario	Idempotency Validation	Rule
Refunds	Not applied.	The duplicate `merchantReference` validation does not apply to the Refund API.
Pending Authorization	Not applied.	If the bank authorization is still `pending`, the same bank authorization can be used again.
Canceled Authorization	Not applied.	If the bank authorization is `canceled`, the same bank authorization can be used again.
Successful Authorization	Applied.	If the bank authorization is `successful`, the same bank authorization cannot be used again using the same `merchantReference`.