merchant_transactionid_duplicate¶
| Property | Value |
|---|---|
| Error Code | merchant_transactionid_duplicate |
| HTTP Status | 422 Unprocessable Entity |
| Title | Business logic error |
Description¶
A transaction with the same merchantReference has already been submitted for your brand. The gateway enforces uniqueness of merchant references to prevent duplicate transactions.
Example Response¶
{
"type": "https://docs.payalo.com/errors/merchant_transactionid_duplicate",
"title": "Business logic error",
"status": 422,
"detail": "Duplicate merchant transaction ID.",
"errorCode": "merchant_transactionid_duplicate"
}
Common Causes¶
| Cause | Description |
|---|---|
| Accidental duplicate | The same request was submitted twice (e.g., due to a client-side retry without checking the first response) |
| Reference reuse | A merchantReference from a previous transaction was reused for a new transaction |
| Race condition | Two concurrent requests used the same merchantReference |
Resolution¶
- If this is an intentional retry of the same transaction, this is expected behavior — the gateway's idempotency logic prevents duplicate processing. Query the Status Check API to get the status of the original transaction.
- If this is a new transaction, generate a unique
merchantReference(e.g., a UUID or order-specific identifier) and resubmit. - Never reuse a
merchantReferencefrom a failed transaction for a different transaction.
Idempotency Behavior¶
The merchantReference uniqueness check has a time-to-live window. During this window:
- Submitting the same
merchantReferencereturns this error. - The original transaction continues processing normally.
- Use the Status Check API to retrieve the original transaction's status.
Note: This error is not retryable with the same
merchantReference. Use a new reference for genuinely new transactions.