API Idempotency for Payment Services

6/12/2025

This post introduces the Commerce Payments Protocol, a new system for enabling real-world commerce on-chain. It addresses the limitations of existing crypto payments for commercial purchases by introducing a multi-stage payment commitment process. Key components include an escrow smart contract for authorization and capture, and a new role called 'operator' to facilitate fund movement and manage transaction fees. The protocol defines six core operations: authorize, capture, charge, void, reclaim, and refund, enabling features like delayed settlement, partial captures, and buyer/merchant protection. The initial implementation integrates with the ERC-3009 standard for payer authorization and leverages signing over a hash of payment details to ensure payer intent and prevent tampering by operators. Operators are restricted from modifying payment intents, locking funds in escrow, or impacting other operators' activities.

7/28/2022

This post details the use of ULIDs (Universally Unique Lexicographically Sortable Identifiers) for idempotency keys in payment services. ULIDs, which contain a timestamp, are preferred over UUIDv4 due to their sortable nature, leading to a 50% decrease in INSERT statement duration in high-throughput systems by working better with b-tree data structures used for indexing.

6/29/2022

This post details the technical implementation of Shopify's billing platform to comply with new RBI regulations for recurring payments in India. It covers modeling the e-mandate concept, handling both recurring and one-time payments, integrating with card and UPI payment methods, and working with a new payment provider. Key technical challenges addressed include conceptualizing e-mandates within the existing source object model, managing AFA flows for different payment types to avoid user friction, implementing PCI-compliant card onboarding and subsequent payments (both below and above the RBI threshold), and handling UPI's asynchronous nature and transaction limit complexities by defining a minimum recurring transaction limit and a fallback for larger payments. The post includes sequence diagrams and ER diagrams to illustrate the backend perspective.

7/8/2021

This post details how Shopify uses background jobs to offload work and improve high availability. It explains the concept of background jobs, their benefits (response times, spikeability, retries, parallelization, prioritization, scheduling, code simplicity), and challenges (breaking changes, no exactly-once delivery, non-transactional queuing). It proposes the outbox pattern as a solution for transactional queuing.

8/27/2019

This post details the implementation of API idempotency within Shopify's new Payment Service to ensure transactional resilience. It introduces the concept of idempotency keys (UUIDs) as first-class API parameters, the use of locks based on client and idempotency key to prevent simultaneous duplicate requests, and the tracking of incoming requests via an 'IncomingRequest' model. A key contribution is the 'steps' or 'recovery points' strategy for structuring mutation handlers, partitioning code by side-effect type (no side effects, local, remote) to enable granular progress tracking and recovery. This allows for the resumption of operations from the point of failure, ensuring that even if an initial request fails, subsequent retries can safely complete the transaction. The post also discusses the trade-offs, such as increased database writes and a specific coding style, and emphasizes the importance of remembering side effects for successful recovery.

10/15/2010

This post announces the release of ActiveMerchant version 1.9, which includes support for seven additional payment gateways (DirecPay, Paybox, Inspire Commerce, SecureNet, Netaxept, Iridium, and SagePay Form). This expands the total number of supported gateways to 63 and highlights the collaborative nature of open-source development through community contributions.