Skip to content
Nappai Documentation

Stripe Refund

The Stripe Refund component in Nappai allows you to manage financial reversals seamlessly within your automation workflows. It acts as a bridge between your automation system and Stripe, enabling you to initiate new refunds, retrieve details of existing ones, and keep your financial records up to date. This tool is designed to simplify complex financial tasks, ensuring that your data management processes are accurate and efficient.

How it Works

This component interacts directly with the Stripe Refunds API. When you configure it in your workflow, it communicates with Stripe’s servers to perform specific actions based on your selected mode.

Internally, the component uses a secure authentication method called Credentials. You must first set up your Stripe API key in the Nappai panel. The component then uses this key to securely verify your identity and perform operations on your behalf. It is designed to work in “Mapping Mode,” which means it is optimized to pass data smoothly to other nodes in your workflow, allowing you to connect refund actions to notifications, database updates, or other automated steps.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type Stripe API and fill in the required fields (API Key). You can find your API Key in your Stripe Dashboard.
  3. In your workflow, select the saved credential in the Credential input field of this node.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: Select the type of action you want to perform. Note: This component is designed for data mapping and does not expose traditional “operations” like Create or Update in the standard UI dropdown. Use the Mode field instead.
  • Mode: Choose how you want to retrieve data. ‘By ID’ retrieves one specific record, while ‘All’ lists multiple records.
  • Refund ID: The unique identifier for a specific refund (starts with re_...). This is required when you use the ‘By ID’ mode.
  • Charge ID: The unique identifier for the original charge you want to refund (starts with ch_...). This is required if you are initiating a new refund.
  • Amount: The amount you wish to refund. Enter this in the smallest currency unit (e.g., cents for USD). Leave this blank if you want to refund the entire charge amount.
  • Reason: A dropdown to specify why the refund is being issued (e.g., duplicate, fraudulent, or requested by customer). This helps with record-keeping.
  • Description: A text field to add a specific note or description to the refund’s metadata. This is useful for internal tracking.
  • Limit: A numeric input that limits the number of records returned when listing refunds.

Outputs

When the component executes successfully, it produces data that you can use in subsequent steps of your workflow.

Output Data Example (JSON)json

{ “refund_object”: { “id”: “re_1M2N3O4P5Q6R7S”, “payment”: “ch_1M2N3O4P5Q6R7S”, “amount”: 1500, “currency”: “usd”, “status”: “succeeded”, “reason”: “duplicate”, “created”: 1678901234, “balance_transaction”: “txn_1M2N3O4P5Q6R7S” }, “success”: true }

Connectivity

This component is typically used in financial or customer service workflows. It is logically connected to:

  • Payment Components: Such as StripePayment or StripeCharge, which provide the Charge ID needed for refunds.
  • Communication Components: Like Email or Slack nodes, to notify customers about the status of their refund.
  • Database Components: To update internal records with the new refund status or ID.

Usage Example

Imagine you have a workflow that monitors customer support tickets. When a ticket is marked as “Refund Approved,” you can use the Stripe Refund component to process the money back to the customer.

  1. Set Mode to “By ID” (if you already know the refund ID) or use a previous step to get the Charge ID.
  2. In the Amount field, map the value from the original transaction.
  3. In the Reason field, select “requested_by_customer”.
  4. The component processes the refund and outputs the updated refund details, which you can then send to the customer via email.

Tips and Best Practices

  • Always ensure your Stripe API credentials have the necessary permissions to issue refunds.
  • Use the Reason field to keep clear records for accounting and dispute resolution.
  • If you are processing bulk refunds, consider using the ‘All’ mode with a Limit to manage performance and avoid overloading the system.
  • For partial refunds, always specify the Amount in the smallest currency unit (e.g., 100 for $1.00).

Security Considerations

  • Keep your Stripe API keys secure. Never share them publicly or commit them to version control.
  • Ensure that only authorized users in your Nappai account can access and configure credentials for financial transactions.
  • Always verify the Charge ID before initiating a refund to prevent errors or incorrect reversals.