Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fype.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Idempotency

Idempotency is a critical feature for payment systems. It ensures that performing the same operation multiple times has the same effect as performing it once.

​
Why Idempotency Matters

In distributed systems, network requests can fail in ways that leave the state of the request ambiguous. For example:
  • Your server sends a “Create Payment” request to Fype.
  • Fype processes the request and creates the payment.
  • The network connection drops before Fype can send the response.
  • Your server retries the request.
Without idempotency, this would result in two duplicate payments. With idempotency, Fype recognizes the retry and returns the existing payment.

​
Using Idempotency Keys

To perform an idempotent request, provide an Idempotency-Key header with a unique string. 
curl -X POST https://api.fype.dev/v1/payments \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: unique_order_ref_987" \
  -d '{ ... }'

​
How Fype Handles Idempotency Keys

  1. Unique Key: Fype stores the Idempotency-Key and the associated merchant ID for 24 hours.
  2. Matching Request: If a second request arrives with the same key and same merchant, Fype checks if the request body is identical.
  3. Replay Response: If the body matches, Fype returns the cached response from the original request instead of creating a new payment.
  4. Error on Mismatch: If the Idempotency-Key is the same but the request body is different, Fype returns a 400 Bad Request to prevent accidental state corruption.

​
Best Practices

  • Generate Keys on Your End: Use your internal database IDs or a UUID as the Idempotency-Key.
  • Scope Keys: Keys are scoped to your merchant account. You can use the same key in Test and Live modes, as they are isolated.
  • Retry Safely: Always implement a retry strategy with exponential backoff for network-related errors (HTTP 5xx or connection timeouts), using the same Idempotency-Key for every retry.