Idempotence

Overview

In the context of payment platforms and REST endpoints, idempotence means that making the same request multiple times has the same effect as making it once.

In general, this is particularly crucial for payment systems where duplicate transactions must be avoided.

The NOAH Business API includes support for idempotence, crucial for safely retrying requests without duplicating operations, which is especially useful to prevent unintended multiple executions in scenarios of failures and retries.

Key aspects of idempotent payment endpoints

• If you submit the same payment request twice (with the same idempotency key), only one payment is processed.
• The server recognizes duplicate requests and returns the same response without executing the operation again.
• This prevents accidental double-charging when network issues or timeouts occur.

For example, if a customer clicks "Pay" twice or if your system retries a payment request due to a timeout, an idempotent endpoint ensures the customer is only charged once.

Implementation approach

Payment platforms typically implement idempotency through:

• Unique idempotency keys or nonces (numbers used once) included in request headers
• Server-side tracking of processed requests by their keys/nonces
• Consistent responses for duplicate requests

Nonces serve a similar purpose to idempotency keys but emphasize their one-time-use nature. Many payment systems use nonces as transaction identifiers to guarantee uniqueness and prevent replay attacks while maintaining idempotent behavior.

This principle is essential for ensuring transaction reliability and preventing financial errors in distributed systems where network failures are inevitable.

NOAH's approach to idempotence

NOAH's idempotence implementation differs from the common idempotency-key header approach in important ways:

1. Transaction idempotency vs. request idempotency:

   • NOAH's nonce ensures a transaction is processed only once (transaction idempotency)
   • Traditional idempotency-key headers often focus on ensuring the exact same request and response (request idempotency)

2. No expiration period:

   • Traditional idempotency keys often have a 24-hour expiry period, which can create uncertainty if you don't receive a response within that timeframe
   • NOAH's nonce approach does not have this limitation, providing more reliable transaction tracking

Use idempotence nonces

All of NOAH's transactional endpoints, that is, endpoints that lead to the creation of a transaction, require a Nonce value, which must be unique for each transaction.

curl -L 'https://api.sandbox.noah.com/v1/transactions/sell' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "CryptoCurrency": "BTC",
  "FiatAmount": "10.1",
  "CryptoAuthorizedAmount": "10.5",
  "FormSessionID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "Nonce": "dc879b38-494b-4de7-98a9-068703144328",
  "ExternalID": "order-123456"
}'

This requirement guarantees that the same endpoint will not overwrite nor duplicate transactions with the same Nonce, allowing for safely retrying requests.

You should ensure that your system uses a unique nonce for each transaction you attempt to create.

Understanding CryptoAuthorizedAmount

The CryptoAuthorizedAmount represents the maximum amount of cryptocurrency that will be locked from your balance to cover the transaction.

For a transaction of 10.1 USD, you might set the CryptoAuthorizedAmount to 10.5 to account for potential fees and price fluctuations. This ensures there are sufficient funds to complete the transaction even if prices shift slightly. The exact value you should use is provided by the prepare endpoint and should be used as-is in your transaction request.

Using ExternalID vs. Nonce

The ExternalID and Nonce fields serve different but complementary purposes:

Field	Purpose	Behavior
Nonce	Ensures transaction idempotence	Must be unique for each transaction attempt; Required field
ExternalID	Links NOAH transactions to your system	Can be reused across multiple transactions; Optional field

Key differences:

1. Multiple transactions can share the same ExternalID (e.g., for retry attempts on the same order), but each must have a unique Nonce
2. ExternalID is optional, while Nonce is required
3. ExternalID is returned in transaction responses and webhooks, making it useful for correlating transactions with your internal systems

Common use cases for ExternalID:

• Correlation with your internal order system
• Tracking webhook events back to specific orders
• Querying transactions related to a specific customer order

Create idempotence nonces

• The choice of method for generating unique nonces is flexible and the maximum length for a nonce is 36 characters.
• Ensure that the Nonce is not used in another transaction.
• You can use, e.g., a high entropy UUID or a unique identifier automatically generated by your database.
• A nonce is specific to a business user.