Understanding the Payment Journey at Trolley: Navigating Through Batches, Statuses, and Webhooks

By: Aman Aalam • 4 min read • 662 words

Posted on March 23, 2024

What happens when a payment is sent? In this post, we go through the journey payments and batches taken at Trolley. This will help with understanding payments and what different statuses and values mean.

Introduction  

At Trolley, we process millions of transactions worth billions of dollars. These transactions move around the world and pass through multiple payment systems. In this post, we demonstrate what happens between the time a new payment is created and when it lands in the recipient’s account.

This article and the resources presented within it are meant to help our users understand the journey of a payment in Trolley, what different statuses mean, and when different fields are populated.

Overview of Payments & Batches  

In Trolley, Payments exist within Batches. During the journey of delivering funds, Batches and Payments go through different stages and are assigned different statuses. These statuses help communicate which stage the Payment and Batch is in so our users can best manage their workflows.

Depending on a few factors, such as the size of the batch, payment methods, etc., the Batches and Payments can pass through different statuses at different timeframes. They can also revert to a previous status depending on the circumstances (e.g. payment return).

Whenever a status changes, we send a webhook request informing the subscribed URLs about the update.

Note: Users can subscribe to Payment and/or Batch-related webhook notifications    to stay informed on Batch status.

Visualizing the Payment Journey  

The following diagram shows the different statuses and stages that Payments and Batches go through. It should help define what actions can be taken on Batches and Payments, which variables are populated at what stage, and what different status values mean.

Reading this Diagram  

The diagram has a legend on the top right, but here are a few hints to help:

• Read the diagram from left to right.
• The actions that can be performed on Payments and Batches are mentioned at the top. They are also highlighted as “Merchant Action” in the legend. Most of these actions can be performed using our public APIs.
• A few actions are performed by internal systems at Trolley, and these are indicated in the legend accordingly.
• Each box with rounded corners represents a Batch and Payment status, which will be returned in the status attribute of API responses.
• A green dot represents Actions and Status, which will also generate a webhook request.
• Every action or status can generate more information, populating attributes exposed via our APIs.
• Every status box has a trailing list of attributes populated when the payment/batch enters the said status.

Additional points to remember about Payments & Batches  

Editing Payments  

Users can edit payments, but only when the Payments are in the pending state, and the Batch containing them is in the open state.

Once the Payment or the Batch moves past this stage, it can’t be edited.

Payment Errors  

Payments and Batches go through different validations, and errors may occur at different stages of those validations.

Depending on the error in the payment and the stage it occurred in, the Batch and the Payment can transition into different statuses, as highlighted in the diagram. Our documentation mentions many of these errors and why they occur: https://developers.trolley.com/api/#payment-and-batch-errors  .

The documentation and the diagram above should help users understand when specific errors occur and how to navigate them.

Processed or Returned payments  

As one can see in the diagram, the payments can be completed in two ways - they’ll either be processed with a successful payout to the recipient, or they’ll be marked as returned where the recipient hasn’t received the money, and we have received the money back.

Conclusion  

We believe a sound understanding of how the payment process works at Trolley and what stages a payment goes through is valuable. It helps all perceive the processes better to avoid common errors and design an efficient integration flow. We hope this article helps you with that understanding and helps your team integrate with Trolley smoothly.

For any questions or feedback, contact our support team or write to us at developers@trolley.com.