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

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:

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.