Idempotency

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:

You send a payment request
Network issues cause a timeout before receiving a response
You don’t know if the payment was processed
You safely retry using the same idempotency key
If the original request succeeded, you receive the same successful response
If the original request failed, you receive the same failure response
No duplicate payment is created

Idempotency Fields by API

Different APIs use different fields as idempotency keys:

API Endpoint	Idempotency Field	Purpose
`/v1/payments/pay`	`paymentRequestId`	Prevents duplicate charges
`/v1/payments/refund`	`refundRequestId`	Ensures single refund processing
`/v1/messages/sendEmail`	`requestId`	Returns same `messageId` for duplicates
`/v1/messages/sendSms`	`requestId`	Returns same `messageId` for duplicates
`/v1/messages/sendPush`	`requestId`	Returns same `messageId` for duplicates
`/v1/messages/sendInbox`	`requestId`	Returns 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

Initial Request

Send your request with a unique idempotency key

Handle Timeout

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

Retry with Same Key

Retry using the exact same idempotency key

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.

OpenAPIs

Message Transmission Security

OpenAPIs for Merchants

Reference

What is Idempotency?

When to Use Idempotency

Idempotency Fields by API

Implementation Guidelines

Generate Unique Identifiers

Retry Strategy

Best Practices

Example: Payment Retry

Important Considerations

​What is Idempotency?

​When to Use Idempotency

​Idempotency Fields by API

​Implementation Guidelines

​Generate Unique Identifiers

​Retry Strategy

​Best Practices

​Example: Payment Retry

​Important Considerations

What is Idempotency?

When to Use Idempotency

Idempotency Fields by API

Implementation Guidelines

Generate Unique Identifiers

Retry Strategy

Best Practices

Example: Payment Retry

Important Considerations