Payment Intent API: Creating Intents With Ease

Welcome to the definitive guide on creating payment intents using our robust API! In the fast-paced world of digital transactions, ensuring a smooth and secure payment process is paramount. This article dives deep into the intricacies of the Payment Intent API, focusing specifically on the POST /intents endpoint and how it handles the creation of new payment intents. We'll break down various scenarios, from successful creation to handling duplicates and ensuring idempotency, so you can integrate our API with confidence.

AC-1: Creating a New Payment Intent Successfully

Let's start with the most common and straightforward scenario: creating a new payment intent. Imagine a customer is ready to make a purchase on your platform. They've selected their items, and now it's time to initiate the payment process. Our API is designed to make this as seamless as possible. When you send a valid create intent request to the POST /intents endpoint, and critically, if the intentId you're requesting doesn't already exist, and importantly, no idempotency record exists for the combination of the Payment Service User ID (psuId) and the idempotencyKey, our system springs into action. It efficiently creates a new intent object in our system. This new intent is immediately assigned a status of INITIATED, signifying that the payment process has begun but is not yet complete. To ensure data integrity and reliable processing, this new intent is persisted atomically, meaning it's either fully saved or not saved at all, preventing partial or corrupted records. The response you receive back from the API is designed to give you all the essential information you need at this stage. It includes the newly generated intentId, the current status (which will be 'INITIATED'), and the paymentType that was specified in your request. To confirm the successful creation, the HTTP status code returned is 201 CREATED, a clear signal that your request was processed successfully and a new resource (the payment intent) has been brought into existence. This foundational step is crucial for any payment flow, setting the stage for subsequent steps like authorization and capture.

AC-2: Ensuring Idempotency with Retries

In the real world, network glitches happen, and sometimes requests get lost or duplicated. That's where idempotency comes in, and our API handles it gracefully. Imagine you've successfully sent a request to create a new payment intent. However, due to a temporary network issue, you don't receive a response, or perhaps the response is corrupted. Naturally, your system might retry the same request to ensure the payment intent was actually created. Our API is designed to handle this specific scenario perfectly. If an intent already exists for the exact same (psuId, idempotencyKey) combination, and you retry the POST /intents request with an identical request payload, our system recognizes this. Instead of creating a new intent (which would lead to duplicate charges or inconsistent data), it simply returns the existing intent that was created by the first, albeit unconfirmed, request. The response body you receive will be identical to the original response, providing you with the same intentId, status, and paymentType. Crucially, the HTTP status code returned in this case is 200 OK. This signifies that while the request was processed, no new resource was created because one already existed under those specific, idempotent parameters. This idempotent retry mechanism is vital for building resilient payment systems, preventing accidental duplicate transactions and ensuring that your application state remains consistent even in the face of network uncertainties. It allows you to safely retry operations without fear of unintended side effects, making your integration more robust and reliable.

AC-3: New Intent with Same Key, Different User

Another important consideration in API design is how to handle situations where different users might inadvertently use the same identifier. In our Payment Intent API, we use both psuId and idempotencyKey to uniquely identify a request context. Let's explore a scenario where an idempotency key exists for a different psuId. This means a previous request, possibly from a different user or system, used a specific idempotency key, but now a new request comes in using that same idempotency key but associated with a different psuId. The crucial condition here is that no intent exists with the intentId that might have been provided (or generated). In such a case, when the client submits the POST /intents request, our API correctly interprets this as a unique operation tied to the new psuId. Therefore, a new intent is created. This new intent is correctly associated with the requesting psuId, ensuring that the transaction is linked to the correct user or entity. The API responds with an HTTP status code of 201 CREATED, indicating that a new payment intent has been successfully established, uniquely tied to the current user's session and identifiers. This behavior ensures that while idempotency prevents duplicate operations for the same user and key, it doesn't prevent new operations from different users, even if they reuse an idempotency key that was previously used by someone else. This maintains security and user isolation.

AC-4: New Intent with Different Key, Same User

Complementing the previous scenario, let's consider what happens when the psuId is the same, but the idempotencyKey is different. Imagine a user initiating a payment, but for some reason, a new, unique idempotency key is generated for this subsequent attempt. We're given that a psuId key exists for a different idempotency Key (meaning previous operations by this psuId used other keys), and critically, no intent exists with the intentId that might have been provided. When the client submits the POST /intents request under these conditions, the API recognizes that this is a distinct operation because of the new idempotency key. Consequently, a new intent is created. This intent is then associated with the requesting psuId, correctly linking the transaction to the user. The API signals this successful creation by returning an HTTP status code of 201 CREATED. This scenario highlights how changing the idempotency key, even for the same user, is treated as a fresh request, allowing for multiple distinct payment attempts or processes by the same user using different tracking keys. This provides flexibility in managing different payment flows or sessions for a single user, ensuring that each is uniquely identifiable and managed.

AC-5: Conflict: Intent Exists with Same User ID

Handling existing resources is critical to avoid data corruption and ensure predictable API behavior. One such scenario involves attempting to create an intent when one already exists with a client-provided intentId, and crucially, this existing intent belongs to the same psuId. In this situation, the system identifies that you are trying to create an intent using an intentId that is already in use by the very same user or entity (psuId). To prevent the creation of a duplicate intent and to inform you of the conflict, the API rejects the creation of a new intent. Instead, it returns an HTTP status code of 409 CONFLICT. This status code clearly indicates that the request could not be completed because of a conflict with the current state of the resource. The response body will typically include an error message or code that indicates PSU_ID_MISMATCH or a similar indicator, signaling that an intent with that ID already exists for this specific psuId. This is a protective measure to ensure that each intentId uniquely identifies a single payment process for a given user, preventing accidental overwrites or duplicate entries. It guides the developer to check for existing intents or use different identifiers if a new process is truly intended.

AC-6: Forbidden: Intent Exists with Different User ID

Security and data isolation are paramount in any payment system. This next scenario addresses a critical security check: what happens when you try to create an intent using an intentId that already exists, but this existing intent belongs to a different psuId? This situation represents a potential security breach or a misunderstanding of resource ownership. Our API is designed to strictly prevent such cross-user access. If the intentId provided in the request already exists in the system and is associated with a different psuId than the one making the request, the API will immediately reject the request. This rejection is signaled by an HTTP status code of 403 FORBIDDEN. This status code is specifically used to indicate that the server understood the request but refuses to authorize it, usually due to insufficient permissions or, as in this case, a violation of resource ownership rules. The error response will likely contain an error code such as INTENT_PSU_MISMATCH, explicitly stating that the intent identified by the provided intentId does not belong to the current psuId. This robust check ensures that intents are strictly isolated to their originating users, maintaining the integrity and security of the payment ecosystem.

AC-7: Handling Concurrent Duplicate Requests

In high-traffic systems, it's possible for multiple identical requests to arrive at the API simultaneously. Our Payment Intent API is built to handle these concurrent duplicate requests robustly, especially when they involve the same psuId, intentId (if provided), and idempotencyKey. Imagine a scenario where network latency causes a user's client to send the exact same POST /intents request multiple times within a very short window. Our system employs sophisticated locking mechanisms and checks to ensure that even under such concurrent load, only one intent is created. For all the duplicate requests that arrive while the first one is being processed, the system will recognize the duplicate nature based on the (psuId, idempotencyKey) or the existing intentId. Consequently, all duplicate requests will return the same, single intent that was successfully created. Critically, no duplicate records exist in our database, and the system remains consistent. This ensures that the user is not charged multiple times and that your application receives a single, consistent representation of the payment intent. This mechanism is vital for maintaining data integrity and a reliable user experience, even under heavy or unusual network conditions.

AC-8: Recovering from Partial Failures with Retries

Failures, especially partial ones where an operation is acknowledged but the response isn't received, are a common challenge in distributed systems. Our API addresses this with a strategy that combines acknowledgment with graceful retry handling. Consider a scenario where the intent creation process itself succeeds within our system – an intent is created, its status is set, and it's persisted. However, before the response can be sent back to the client, a network interruption occurs, and the client never receives the confirmation. In such a case, the client's system, not knowing if the operation succeeded, will typically retry the request, using the same (psuId, idempotencyKey) that it used for the initial, partially failed attempt. When the API receives this retry request, it checks its records. Because an intent was already successfully created and persisted for that specific (psuId, idempotencyKey) combination, the system recognizes it. Therefore, the previously created intent is returned in the response. Importantly, no duplicate intent is created, safeguarding against the very issue that retries are meant to solve. The API responds with an HTTP status code of 200 OK, indicating that the request was processed successfully and the existing, correct intent data is being provided. This ensures that even if the client misses the initial success acknowledgment, it can safely retrieve the correct state of the payment intent through a simple retry, maintaining consistency and preventing data loss or duplication.

Conclusion

The Payment Intent API, particularly its POST /intents endpoint, is a cornerstone of modern payment processing. By meticulously handling scenarios like successful creation, idempotency, concurrent requests, and partial failures, it provides a reliable and secure foundation for your payment integrations. Understanding these different acceptance criteria (ACs) is key to building robust applications that offer a seamless experience for your users. Remember, always refer to the official API documentation for the most up-to-date details and specifications.

For more information on secure payment practices and API standards, you can explore resources from reputable organizations like the PCI Security Standards Council (pci.org) or the Open Payment Coalition (openbanking.org).