Skip to main content
Idempotency ensures that an API call produces the same result regardless of how many times it’s executed. This is critical for handling network timeouts and ensuring reliable payment processing.

​
What is Idempotency?

An API call is idempotent if it has the same result no matter how many times the call is applied. When a request reaches a final status (Success or Failure), the system returns an identical result on subsequent attempts with the same idempotency identifier.
Idempotency prevents accidental duplicate transactions when retrying requests after network timeouts or failures.

​
When to Use Idempotency

The primary use case is handling timeout errors:
  1. You send a payment request
  2. Network issues cause a timeout before receiving a response
  3. You don’t know if the payment was processed
  4. You safely retry using the same idempotency key
  5. If the original request succeeded, you receive the same successful response
  6. If the original request failed, you receive the same failure response
  7. No duplicate payment is created

​
Idempotency Fields by API

Different APIs use different fields as idempotency keys:
API EndpointIdempotency FieldPurpose
/v2/payments/paypaymentRequestIdPrevents duplicate charges
/v2/payments/refundrefundRequestIdEnsures single refund processing
/v2/payments/retailPaypaymentRequestIdPrevents duplicate retail payments
/v2/payments/linkPayCreatepaymentRequestIdPrevents duplicate link pay orders
/v2/payments/createQrOrderpaymentRequestIdPrevents duplicate QR orders
/v2/messages/sendPushrequestIdReturns same messageId for duplicates
/v2/messages/sendInboxrequestIdReturns same messageId for duplicates

​
Implementation Guidelines

​
Generate Unique Identifiers

Always generate unique, consistent identifiers for each operation: 
// Good: UUID or unique combination
const paymentRequestId = `PAY-${orderId}-${Date.now()}`;

// Bad: Reusing the same ID for different transactions
const paymentRequestId = "payment-1"; // Don't do this!

​
Retry Strategy

1

Initial Request

Send your request with a unique idempotency key
2

Handle Timeout

If you receive a timeout or network error, the request status is unknown
3

Retry with Same Key

Retry using the exact same idempotency key
4

Process Response

The system returns the same response as the original request (if it completed)

​
Best Practices

​
Example: Payment Retry

async function processPayment(orderId, amount, maxRetries = 3) {
  // Generate idempotency key once
  const paymentRequestId = `PAY-${orderId}-${Date.now()}`;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await rebellAPI.retailPay({
        paymentRequestId, // Same key for all retries
        paymentAmount: amount,
        // ... other fields
      });

      return response;
    } catch (error) {
      if (error.code === 'TIMEOUT' && attempt < maxRetries) {
        console.log(`Attempt ${attempt} timed out, retrying...`);
        await sleep(1000 * attempt); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

​
Important Considerations

Key Uniqueness: Once a request with an idempotency key reaches a terminal state (success or failure), any subsequent request with the same key will return the cached response. This means:
  • You cannot change request parameters and use the same key
  • A failed request with key X will always return the same failure
  • To retry with different parameters, you must use a new key
Idempotency Window: Idempotency keys are typically valid for a limited time period (usually 24-48 hours). After this window, the key may be reused, but this is not recommended.