The “Get real-time transactions” API endpoint enables suppliers to retrieve a real-time list of transactions which occurred within the supplier organization during a specified time range.

¶ Use case

The Get Realtime Transactions API is vital for fleet-based organizations, offering transaction monitoring with a data freshness SLA of less than 1 minute for updated data. Users can sort transactions based on the processedAt field and apply time-range filters for focused data retrieval within specific intervals.

¶ Using Dependent API

To retrieve real-time transaction data for drivers, fleet owners should follow a two-step process. Firstly, they need to utilize the Get Organizations API, entering the Fleet Supplier’s unique ID. This step retrieves all associated encrypted organization IDs, ensuring that all linked organizations are identified. Secondly, using these encrypted organization IDs as input, fleet owners can then access the Get Realtime Transactions API to fetch transaction data linked to each specific organization in real-time.

¶ Support for Hierarchical Data

Not Supported. The API returns the transaction information linked to the organization. It doesn’t support fetching transactions linked to their child organizations.

¶ Supported Supplier Types

Fleets

¶ Scopes

Primary - supplier.partner.payments

¶ Resource

/v1/vehicle-suppliers/transactions

¶ HTTP Method

POST

¶ Authorization

Client Credentials

¶ Example Request

curl --location 'https://api.uber.com/v1/vehicle-suppliers/transactions?org_id=<org_id>' \
--header 'Content-Type: application/json' \
--data '{
    "filters": [
        {
            "field": "timeRange",
            "operator": "FILTER_OPERATOR_IN_RANGE",
            "value": [
                "1687731599000",
                "1687732199000"
            ]
        }
    ],
    "sort": [
        {
            "field": "processedAt",
            "direction": "DIRECTION_DESCENDING"
        }
    ],
    "pagination_options": {
        "pageSize": 7,
        "pageToken": "10"
    }
}'

¶ Example Response

{
  "statusCode": 200,
  "body": {
    "transactions":[
      {
        "driverInfo":{
          "driverUUID":"woiwoiewndoinwe",
          "firstName":"abcc",
          "lastName":"xyzz"
        },
        "transactionInfo":{
          "transactionUUID":"wejwdniwubeiubwe",
          "tripUUID":"wediuwicuwehiubcew",
          "processedAt":"2023-03-30T00:13:55.926Z",
          "description":"tripCompleteOrder",
          "breakDown":[
            {
              "categoryName":"paid_to_you",
              "categoryLabel":"Paid to you",
              "amount":{
                "amountE5":7391000,
                "currencyCode":"INR"
              },
              "children":[
                {
                  "categoryName":"your_earnings",
                  "categoryLabel":"Your earnings",
                  "amount":{
                    "amountE5":7391000,
                    "currencyCode":"INR"
                  },
                  "children":[
                    {
                      "categoryName":"fare",
                      "categoryLabel":"Fare",
                      "amount":{
                        "amountE5":7391000,
                        "currencyCode":"INR"
                      },
                      "children":[
                        {
                          "categoryName":"fare",
                          "categoryLabel":"Fare",
                          "amount":{
                            "amountE5":2000,
                            "currencyCode":"INR"
                          }
                        },
                        {
                          "categoryName":"adjustment",
                          "categoryLabel":"Adjustment",
                          "amount":{
                            "amountE5":7389000,
                            "currencyCode":"INR"
                          }
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      }
    ],
    "paginationResult": {
      "nextPageToken": "1"
    }
  }
}

¶ Request Query Parameters

Name	Type	Required	Description
org_id	string	Y	Encrypted organization UUID.

¶ Request Body Fields

Name	Type	Required	Description
filters	Array of Filter	Y	List of filters to be applied on the transactions to be fetched.
sort	Object of Sort	N	List of sorting fields, controls the sorting of transactions in the response.
paginationOptions	Object of PaginationOptions	Y	Pagination options to control the batching.

Filter

Name	Type	Description
field	string	This represents the field on which the filter needs to be applied. (example:- “timeRange”)
operator	Enum Operator	This represents eligible operators we can apply to filter requests.
value	string	Values which need to be applied as filters.

Sort

Name	Type	Description
field	string	This represents the field on which we need to apply the sort.
direction	Enum Direction	This would control the way sorting has to be done.

Operator

Name	Value	Description
FILTER_OPERATOR_IN_RANGE	FILTER_OPERATOR_IN_RANGE	Operator to be used for range filters (example date range filter to add filter between 2 date range a,b)

Direction

Name	Value	Description
DIRECTION_DESCENDING	DIRECTION_DESCENDING	Sorting in descending order.
DIRECTION_ASCENDING	DIRECTION_ASCENDING	Sorting in ascending order.

PaginationOptions

Name	Type	Description
pageToken	string	Page token for the next set of transactions to be fetched in response.
pageSize	integer	Max. number of transactions to be part of response.

¶ Response Body Fields

Name	Type	Nullable	Description
transactions	array of Transaction	N	Transaction and driver’s information.
paginationResult	object of type PaginationResult	N	Pagination info for next pages.

Transaction

Name	Type	Nullable	Description
driverInfo	object of type DriverInfo.	N	Represents driver related information.
transactionInfo	object of type TransactionInfo.	N	Represents transaction related information.

DriverInfo

Name	Type	Nullable	Description
driverUUID	string	N	This would be the raw driver uuid.
firstName	string	Y	This would represent the firstName of the driver.
lastName	string	Y	This would represent the lastName of the driver.

TransactionInfo

Name	Type	Nullable	Description
transactionUUID	string	N	This would be the raw transaction uuid.
tripUUID	string	Y	This represents the trip uuid for which the transaction took place.
processedAt	string	Y	This represents the time of processing the transaction. (This will be in UTC timezone in response)
description	string	Y	This is a single word description giving brief information what the transaction is done for. (eg. tripCompleteOrder)
breakDowns	array of BreakDownItems	Y	This represents the breakdown for the mentioned transaction UUID. This array would provide the granular information for the transaction.

BreakDownItems

Name	Type	Nullable	Description
categoryName	string	Y	This represents the item_type for further bifurcation.
categoryLabel	string	Y	This represents a small description for the bifurcation of the amount.
amount	object of Amount	N	This represents the amount in non-decimal format.
children	array of BreakDownItems	Y	This represents the further bifurcation of the amount.

Amount

Name	Type	Nullable	Description
amountES	integer	Y	This represents the amount with cents precision.
currencyCode	string	Y	This is the currency for the amount returned.

PaginationResult

Name	Type	Nullable	Description
nextPageToken	string	N	Can be empty, if there are no more records

¶ Rate Limit

• Rate limit for this endpoint is 1 request per second per Developer Application.

¶ Endpoint Specific Errors

Http Status Code	Code	Message
400	bad_request	The request parameters are invalid.
500	internal_server_error	Internal server error.
403	unauthenticated	User does not have permission.
429	rate_limited	Number of requests exceeds allowed limit.
503	service_unavailable	Service unavailable.
401	unauthorized	Invalid OAuth 2.0 credentials.

¶ Notes

• If pageToken is not specified, then the default value will be blank.
• If the returned paginationResult object is not empty, further calls to the endpoint can retrieve missing entities in the next subsequent requested data, by including the provided nextPageToken along with a valid pageSize (between 1 and 500).
• We can look back up to 24 hr from the current time.
• The difference in timeRange should be less than or equal to 15 mins.
• The StartTime should not be less than 5 mins from the current time.

¶ FAQ

• Does this endpoint provide the same level of data as Payment Transactions Report?

  • Yes, this endpoint provides the same level of data in realtime where as in payment transaction report it provides the same level of information with a data freshness SLA of 3-4hours. The only difference between the two flows would be the level of bifurcation that would be done. In a few cases, we can expect more granular bifurcation in Payment Transactions Report when compared to Real-time Transactions response. Apart from this, other fields should be in sync with the reporting data.

• Does the API support sandbox environments?

  • No, the API does not currently support sandbox environments.