Online Payments 101 - Transaction Identifiers

What is an Online Payments API

One of the most challenging aspects of managing payments is keeping track of the many stages in the payment lifecycle and tying them back to a single transaction. The Online Payments API simplifies the process by assigning unique identifiers for each transaction. Let’s look at the payment lifecycle through the lens of the Online Payments API and discover how these identifiers are used from request to capture.

The payment lifecycle

The Online Payments API can help to seamlessly capture and accept payments from various sources locally and globally. This API provides multiple operations to manage transactions throughout the entire payment lifecycle:

• Create
• Verify
• Capture
• Update
• Refund 

For each of the operations above, API requests and responses contain identifiers integral to a transaction's management and traceability throughout its lifecycle. Let’s look at each of these identifiers in greater detail.

Transaction identifiers

The Online Payments API makes the payment lifecycle more transparent and easier to follow by assigning unique identifiers to each transaction. The identifiers are split into two categories: One for system-assigned identifiers and one for user-assigned identifiers. Let’s review each of these identifiers, their usage, relationships, and the role they play in a transaction.

System-assigned IDs

The first set of identifiers we want to be aware of are those assigned by the API. These generally aid in the tracing of transactions throughout their lifecycle and cannot be modified. 

transactionId

A transactionID identifies a payment from, or a refund to, a customer. As there may be multiple requests to complete a transaction, the transactionId is provided in each response when a new transaction is created. This is the core identifier for a transaction and is used to perform other actions like capturing, updating, refunding, or canceling a transaction.

paymentRequestId

Vital to transaction traceability, the paymentRequest object includes the transaction details and identifiers for authorizations, captures, and refunds. At the top level of this paymentRequest object, the paymentRequestId is generated on the original authorization and represents the intent to collect a payment.

authorizationId

An authorizationID identifies an authorization request. In some cases, more than one authorizationId can exist for a single purchase. For example, during a hotel stay, a guest’s card can be charged and authorized for the room reservation. Upon checkout, a separate charge and authorization can occur for any incidental charges incurred during the stay that weren’t covered by the original room charges.

Another scenario for more than one authorization would be a merchant that supports partial authorization. An example would be a customer who would like to use a gift card at the coffee shop but only has a small balance left on the card. That small amount would be authorized and captured, and then the merchant would ask for another form of payment for the remaining money owed.

captureId

A captureID is a unique identifier that is generated by the API when a capture request is initiated. This captureId identifies a single occurrence of a payment settlement request after a payment authorization has been approved. 

Multiple captureIDs can exist for a single transaction if multiple captures are needed. A common use case for multiple captures is an online retailer that enables payments to be captured after an item has shipped. Some orders might contain items that immediately ship, while others might not ship at all due to stock availability. A traditional transaction with a single capture would have to go through a messy refund process for the customer to recoup funds for the items that never shipped. With a multi-capture approach, the customer is only charged for the item that ships, and additional charges are not made for unshipped items.

refundId

A refundID is a unique identifier generated by the API when a refund request is created. In some cases, more than one refundId can exist for a single transaction if there are multiple refund requests for the same payment request.

A refund request can be initiated in two different situations for card payments: those linked to a prior payment and those initiated independently. When processing a refund tied to a previous payment, the original transactionID is necessary. Refunds initiated independently only require cardholder information.

As an example, consider the analogy of returning items to a brick-and-mortar retailer. A receipt contains a barcode or other transaction details and serves as the record of the initial transaction. When a receipt is present for a return, the refund is directly tied to the original transaction. Think of the original transactionID as the digital receipt for that API transaction. On the other hand, without a receipt, the refund process can’t be linked to a previous transaction without additional information.

networkTransactionID

A networkTransactionID is a unique transaction identifier that is assigned by a payment network. This identifier serves various purposes, including tracking and managing recurring payments. An example of this is when a customer signs up for a media streaming service with a subscription-based model. The networkTransactionId is assigned to the original payment and should be retained for future recurring transactions where a card is on file for a customer.

User-assigned IDs

The second set of identifiers we want to understand are those assigned by you. While the system-assigned IDs help with traceability through the payment lifecycle via API, the user-assigned IDs can help a developer track and sync transaction data with their internal systems.

requestId

As opposed to implementing a default idempotency method in the Online Payments APIs, we’ve opted to leverage a user-assigned value – the requestId – to evaluate transactions and flag duplicate requests.

Including a unique requestId in each of our request headers allows us to implement a payment system in a way that avoids accidentally executing the same operation twice. If a transaction request is sent using a duplicate request ID, one of two things will happen. Either an HTTP 200 response will be sent with an informational message that a duplicate request was received, or if transaction-level information has changed (e.g., transaction amount, cardholder details), the API flags that transaction as an error due to a duplicate transaction and returns an HTTP 409 response.

merchantOrderNumber

Including a merchant order number as an identifier can be beneficial to the merchant for tying API-level transactions to a purchase order, invoice, or ticket within a merchant’s system. This allows you to supply a unique merchant-assigned ID that provides the merchant with a reference to the prices, quantity, and description of goods or services purchased. This value is generally treated as a passthrough value and doesn’t impact API operations.

Using Online Payments API for Transaction Management

Tracing a transaction through the payment lifecycle can be difficult without a complete understanding of the process. The various identifiers available in the Online Payments API serve as the foundation for transaction management, ensuring clarity and transparency at every stage. With a comprehensive grasp of these concepts, you can optimize your payment processes and help to deliver seamless payment experiences to your customers.

Where to go from here

Visit the Payments Developer Portal to learn more about how to accept, manage, and send payments on a global scale. If you haven’t already signed up for the Payments Developer Portal, register here to get access to your developer dashboard and start building today.