getOneBalanceTransaction Documentation

Overview

This node is a powerful component of the Vantage analytics and data platform that enables users to retrieve detailed information about a specific balance transaction from the Stripe payment platform. This functionality is essential for businesses that rely on Stripe to track their financial transactions, providing them with the ability to fetch individual transaction details for reconciliation, reporting, or analytical purposes.

Purpose

The primary purpose of this logic is to facilitate the retrieval of a specific balance transaction using a unique transaction ID. By querying the transaction through Stripe's API, users can obtain necessary transaction data, including but not limited to, amounts charged, currency, and transaction date.

Settings

1. inputs.transactionId

• Input Type: String
• Description: This setting accepts the unique identifier of the transaction that needs to be retrieved. The transaction ID is crucial as it determines which transaction's details the logic will fetch.
• Effects of Changing: Changing the value of inputs.transactionId directly affects which transaction details are returned. If the ID is incorrect or does not exist, the process will fail.
• Default Value: Undefined (a value must be provided; otherwise, an error will occur).

2. config.transactionId

• Input Type: String
• Description: This is an optional configuration field that can also provide a transaction ID. If inputs.transactionId is not defined, the logic looks to this setting for a value.
• Effects of Changing: Changing this value changes the retrieved transaction details. If both inputs.transactionId and config.transactionId are present, the inputs.transactionId takes precedence.
• Default Value: Undefined (needs to be provided if used in the absence of inputs.transactionId).

3. context

• Input Type: Object
• Description: Represents contextual information that may be necessary during the integration process with the Stripe API. It may include authentication tokens or metadata required for connecting to Stripe.
• Effects of Changing: Altering the context can impact the successful establishment of the connection to the Stripe API. It is critical for ensuring that the integration can authenticate and retrieve transactions.
• Default Value: An empty object ({}).

How It Works

1. Connection Establishment: The logic first attempts to create a connection instance to the Stripe API using the helper function the integration connection, which takes the string 'stripe' and the provided context as arguments.

2. Transaction ID Acquisition: It retrieves the transaction ID from the inputs object. If not available, it looks for the transactionId key in the config object.

3. Error Handling: If no transaction ID is provided, an error is thrown indicating that this field is required.

4. Data Retrieval: If the transaction ID is valid, the method calls getOneBalanceTransaction on the integration instance, passing the transaction ID to fetch the transaction details.

5. Return Data: The output data from the API call is returned as an object. If any errors are encountered during the process (e.g., issues with the Stripe service), a structured error message is returned instead.

Use Cases & Examples

Use Case 1: Financial Reconciliation

A finance team uses the getOneBalanceTransaction to fetch transaction details needed for periodic reconciliation. It allows them to match charges against their records and ensure accuracy in financial reporting.

Use Case 2: Support Team Analytics

A support team retrieves balance transaction details for a specific user to investigate customer queries regarding charges. By having direct access to transaction details, they can respond effectively to customer inquiries.

Detailed Example

Scenario: A finance department wants to retrieve information for a specific transaction to clarify an accounting record.

Configuration Data:

{
  "inputs": {
    "transactionId": "txn_123456789"
  },
  "config": {
    "transactionId": "txn_987654321" // this will not be used as inputs.transactionId is provided
  },
  "context": {
    "stripeApiKey": "your-stripe-api-key"
  }
}

Step-by-Step:

1. The finance department defines the transactionId in the inputs object with the value of the transaction they want to retrieve.
2. The config.transactionId is provided with a different value, but it will not be utilized because the input transaction ID is prioritized.
3. The context holds necessary Stripe API credentials for remote access.
4. When executed, getOneBalanceTransaction retrieves and returns the details for transaction txn_123456789.

In the event of a missing transaction ID or API failure, the component returns a structured error message for troubleshooting.