Stripe integration

Overview

Stripe is a payment processing platform. This tool provides access to the Stripe API for managing charges (create, get, list, update), customers (CRUD), coupons (create, list), customer cards (add, get, remove), payment sources (create, delete, get), card tokens (create), billing meter events (create), and balance retrieval. Uses form-urlencoded request bodies per Stripe API conventions. Supports cursor-based pagination for list operations.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Stripe API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Balance	balance
Charge	charge
Coupon	coupon
Customer	customer
Customer Card	customerCard
Meter Event	meterEvent
Source	source
Token	token

Operations

Each resource has its own Operation list, and several resources reuse the values create, get and getAll. Pick the resource first, then the operation.

Resource	Operation	Value
Balance	Get	get
Charge	Create	create
Charge	Get	get
Charge	Get Many	getAll
Charge	Update	update
Coupon	Create	create
Coupon	Get Many	getAll
Customer	Create	create
Customer	Delete	delete
Customer	Get	get
Customer	Get Many	getAll
Customer	Update	update
Customer Card	Add	add
Customer Card	Get	get
Customer Card	Remove	remove
Meter Event	Create	create
Source	Create	create
Source	Delete	delete
Source	Get	get
Token	Create	create

Parameters

Get takes no parameters of its own — see All Operations.

Charge: Create

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Amount	number	Yes	0	Amount in cents to be collected, e.g. enter 100 for $1.00.
Currency	string	Yes	—	Three-letter lowercase ISO currency code, e.g. usd. Must be a Stripe-supported currency.
Source ID (source)	string	Yes	—	ID of the customer’s payment source to be charged (src_… or card_…).
Additional Fields	collection	No	{}
— Description	string	No	—	Arbitrary text to describe the charge.
— Metadata	fixedCollection	No	{}	Set of key-value pairs to attach to the charge.
— — Key	string	No	—
— — Value	string	No	—
— Receipt Email	string	No	—	Email address to which the receipt for this charge will be sent.
— Shipping	fixedCollection	No	{}	Shipping information for the charge.
— — Recipient Name	string	No	—
— — Address	fixedCollection	No	{}
— — — Line 1	string	No	—	Address line 1 (e.g. street, PO Box, or company name).
— — — Line 2	string	No	—	Address line 2 (e.g. apartment, suite, unit, or building).
— — — City	string	No	—	City, district, suburb, town, or village.
— — — State	string	No	—	State, county, province, or region.
— — — Country	string	No	—	Two-letter country code (ISO 3166-1 alpha-2).
— — — Postal Code	string	No	—	ZIP or postal code.

Charge: Get

Parameter	Type	Required	Default	Description
Charge ID	string	Yes	—	ID of the charge to retrieve or update (ch_…).

Charge: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Charge: Update

Parameter	Type	Required	Default	Description
Charge ID	string	Yes	—	ID of the charge to retrieve or update (ch_…).
Update Fields	collection	No	{}
— Description	string	No	—	Arbitrary text to describe the charge.
— Metadata	fixedCollection	No	{}	Set of key-value pairs to attach to the charge.
— — Key	string	No	—
— — Value	string	No	—
— Receipt Email	string	No	—	Email address to which the receipt for this charge will be sent.
— Shipping	fixedCollection	No	{}	Shipping information for the charge.
— — Recipient Name	string	No	—
— — Recipient Address	fixedCollection	No	{}
— — — Line 1	string	No	—	Address line 1 (e.g. street, PO Box, or company name).
— — — Line 2	string	No	—	Address line 2 (e.g. apartment, suite, unit, or building).
— — — City	string	No	—	City, district, suburb, town, or village.
— — — State	string	No	—	State, county, province, or region.
— — — Country	string	No	—	Two-letter country code (ISO 3166-1 alpha-2).
— — — Postal Code	string	No	—	ZIP or postal code.

Coupon: Create

Parameter	Type	Required	Default	Description
Apply	options	Yes	once	How long the discount will be in effect.
				Options: forever, once
Discount Type	options	Yes	percent	Whether the coupon takes a fixed amount off (in cents) or a percentage off.
				Options: fixedAmount, percent
Amount Off	number	Yes	0	Amount in cents to subtract from an invoice total, e.g. enter 100 for $1.00. (shown when Discount Type is fixedAmount)
Currency	string	Yes	—	Three-letter lowercase ISO currency code, e.g. usd. Must be a Stripe-supported currency. (shown when Discount Type is fixedAmount)
Percent Off	number	Yes	1	Percentage to apply with the coupon (1-100). (shown when Discount Type is percent)

Coupon: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)

Customer: Create

Parameter	Type	Required	Default	Description
Name	string	Yes	—	Full name or business name of the customer to create.
Additional Fields	collection	No	{}
— Address	fixedCollection	No	{}	Address of the customer.
— — Line 1	string	No	—	Address line 1.
— — Line 2	string	No	—	Address line 2.
— — City	string	No	—
— — State	string	No	—
— — Country	string	No	—	Two-letter country code (ISO 3166-1 alpha-2).
— — Postal Code	string	No	—
— Description	string	No	—	Arbitrary text to describe the customer.
— Email	string	No	—	Email address of the customer.
— Metadata	fixedCollection	No	{}	Set of key-value pairs to attach to the customer.
— — Key	string	No	—
— — Value	string	No	—
— Phone	string	No	—	Telephone number of the customer.
— Shipping	fixedCollection	No	{}	Shipping information for the customer.
— — Recipient Name	string	No	—
— — Recipient Address	fixedCollection	No	{}
— — — Line 1	string	No	—
— — — Line 2	string	No	—
— — — City	string	No	—
— — — State	string	No	—
— — — Country	string	No	—
— — — Postal Code	string	No	—
— — Recipient Phone	string	No	—

Customer: Delete

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).

Customer: Get

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).

Customer: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)
Filters	collection	No	{}
— Email	string	No	—	Filter customers by exact email match.

Customer: Update

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Update Fields	collection	No	{}
— Address	fixedCollection	No	{}	Address of the customer.
— — Line 1	string	No	—
— — Line 2	string	No	—
— — City	string	No	—
— — State	string	No	—
— — Country	string	No	—
— — Postal Code	string	No	—
— Description	string	No	—	Arbitrary text to describe the customer.
— Email	string	No	—	Email address of the customer.
— Metadata	fixedCollection	No	{}	Set of key-value pairs to attach to the customer.
— — Key	string	No	—
— — Value	string	No	—
— Name	string	No	—	Full name or business name of the customer.
— Phone	string	No	—	Telephone number of the customer.
— Shipping	fixedCollection	No	{}	Shipping information for the customer.
— — Recipient Name	string	No	—
— — Recipient Address	fixedCollection	No	{}
— — — Line 1	string	No	—
— — — Line 2	string	No	—
— — — City	string	No	—
— — — State	string	No	—
— — — Country	string	No	—
— — — Postal Code	string	No	—
— — Recipient Phone	string	No	—

Customer Card: Add

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Card Token	string	Yes	—	Token representing sensitive card information (tok_…).

Customer Card: Get

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Source ID (sourceId)	string	Yes	—	ID of the source or card to act on (src_…, or card_… for a card saved on the customer).

Customer Card: Remove

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Card ID	string	Yes	—	ID of the card to remove (card_…).

Meter Event: Create

Parameter	Type	Required	Default	Description
Event Name	string	Yes	—	The name of the meter event. Must match a configured meter’s event_name.
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Value	number	Yes	1	The value of the meter event. Must be an integer. Can be positive or negative.
Additional Fields	collection	No	{}
— Identifier	string	No	—	A unique identifier for the event. Uniqueness is enforced within a rolling 24 hour window.
— Timestamp	string	No	—	ISO 8601 date string for the event time. Must be within the past 35 calendar days or up to 5 minutes in the future. Defaults to current time if not specified.
— Custom Payload Properties	fixedCollection	No	{}	Additional custom properties to include in the event payload. Cannot overwrite stripe_customer_id or value.
— — Key	string	No	—
— — Value	string	No	—

Source: Create

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Type (sourceType)	options	Yes	wechat	The payment instrument the source represents. Only WeChat sources can be created here.
				Options: wechat
Amount	number	No	0	Amount in cents to be collected, e.g. enter 100 for $1.00.
Currency	string	No	—	Three-letter lowercase ISO currency code, e.g. usd. Must be a Stripe-supported currency.
Additional Fields	collection	No	{}
— Metadata	fixedCollection	No	{}	Set of key-value pairs to attach to the source.
— — Key	string	No	—
— — Value	string	No	—
— Statement Descriptor	string	No	—	Arbitrary text to display on the customer’s statement.

Source: Delete

Parameter	Type	Required	Default	Description
Customer ID	string	Yes	—	ID of the Stripe customer the operation applies to (cus_…).
Source ID (sourceId)	string	Yes	—	ID of the source or card to act on (src_…, or card_… for a card saved on the customer).

Source: Get

Parameter	Type	Required	Default	Description
Source ID (sourceId)	string	Yes	—	ID of the source or card to act on (src_…, or card_… for a card saved on the customer).

Token: Create

Parameter	Type	Required	Default	Description
Type (tokenType)	options	Yes	cardToken	The kind of token to create. Only card tokens are supported.
				Options: cardToken
Card Number	string	No	—	The card number. (shown when Type is cardToken)
CVC	string	No	—	Security code printed on the back of the card. (shown when Type is cardToken)
Expiration Month	string	No	—	Number of the month when the card will expire. (shown when Type is cardToken)
Expiration Year	string	No	—	Year when the card will expire. (shown when Type is cardToken)

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

The Stripe object is merged onto the input item’s JSON at the top level — the returned object’s fields sit alongside the fields the item already carried, so downstream nodes address them directly ({{ $json.id }}) rather than through a wrapper property. A response field with the same name as an existing item field overwrites it. Binary data on the input item is forwarded unchanged onto every output item.

Only the Get Many operations fan out. Each record Stripe returns becomes its own output item, still merged onto the same input JSON, so one input item can produce many output items. A list with no records produces no output items for that input.

Operations	Output
Charge Get Many; Coupon Get Many; Customer Get Many	One output item per record. Paging is handled for you — Return All follows Stripe’s cursor until the list is exhausted, and Limit stops once that many records have been collected.
Balance Get; Charge Create, Get and Update; Coupon Create; Customer Create, Get and Update; Customer Card Add and Get; Meter Event Create; Source Create and Get; Token Create	One output item carrying the fields of the returned Stripe object.
Customer Delete; Customer Card Remove; Source Delete	One output item carrying the deletion confirmation Stripe returns for that object.

Two operations are worth calling out:

• Source: Create creates the source and then attaches it to the customer you named. The output item carries the created source, so {{ $json.id }} is the new src_ ID.
• Token: Create returns the token object. Read {{ $json.id }} for the tok_ value and hand it to Customer Card: Add.

Write operations are sent with a Stripe idempotency key scoped to that execution, node and input item, so an automatic retry of the same item cannot create a duplicate charge, customer or coupon.

Example Configuration

Read the account balance:

{
  "type": "stripe",
  "parameters": {
    "resource": "balance",
    "operation": "get"
  }
}

Charge a customer’s saved card for $20.00:

{
  "type": "stripe",
  "parameters": {
    "resource": "charge",
    "operation": "create",
    "customerId": "{{ $json.stripeCustomerId }}",
    "amount": 2000,
    "currency": "usd",
    "source": "card_123456789",
    "additionalFields": {
      "description": "Payment for order {{ $json.orderNumber }}",
      "receipt_email": "{{ $json.email }}",
      "metadata": {
        "metadataProperties": [
          { "key": "order_id", "value": "{{ $json.orderNumber }}" }
        ]
      }
    }
  }
}

Retrieve a single charge:

{
  "type": "stripe",
  "parameters": {
    "resource": "charge",
    "operation": "get",
    "chargeId": "ch_123456789"
  }
}

List the ten most recent charges:

{
  "type": "stripe",
  "parameters": {
    "resource": "charge",
    "operation": "getAll",
    "returnAll": false,
    "limit": 10
  }
}

Annotate an existing charge:

{
  "type": "stripe",
  "parameters": {
    "resource": "charge",
    "operation": "update",
    "chargeId": "{{ $json.id }}",
    "updateFields": {
      "description": "Updated payment description",
      "metadata": {
        "metadataProperties": [
          { "key": "reconciled", "value": "true" }
        ]
      }
    }
  }
}

Create a $5.00-off coupon that applies once:

{
  "type": "stripe",
  "parameters": {
    "resource": "coupon",
    "operation": "create",
    "duration": "once",
    "type": "fixedAmount",
    "amountOff": 500,
    "currency": "usd"
  }
}

Create a 15%-off coupon that never expires:

{
  "type": "stripe",
  "parameters": {
    "resource": "coupon",
    "operation": "create",
    "duration": "forever",
    "type": "percent",
    "percentOff": 15
  }
}

Create a customer with an address and metadata:

{
  "type": "stripe",
  "parameters": {
    "resource": "customer",
    "operation": "create",
    "name": "{{ $json.fullName }}",
    "additionalFields": {
      "email": "{{ $json.email }}",
      "phone": "+1234567890",
      "description": "Premium customer",
      "address": {
        "details": {
          "line1": "123 Main St",
          "city": "New York",
          "state": "NY",
          "country": "US",
          "postal_code": "10001"
        }
      },
      "metadata": {
        "metadataProperties": [
          { "key": "customer_type", "value": "premium" }
        ]
      }
    }
  }
}

Look a customer up by exact email:

{
  "type": "stripe",
  "parameters": {
    "resource": "customer",
    "operation": "getAll",
    "returnAll": false,
    "limit": 20,
    "filters": {
      "email": "{{ $json.email }}"
    }
  }
}

Attach a card token to a customer:

{
  "type": "stripe",
  "parameters": {
    "resource": "customerCard",
    "operation": "add",
    "customerId": "cus_123456789",
    "token": "{{ $json.id }}"
  }
}

Report metered usage against a configured meter:

{
  "type": "stripe",
  "parameters": {
    "resource": "meterEvent",
    "operation": "create",
    "eventName": "api_calls",
    "customerId": "{{ $json.stripeCustomerId }}",
    "value": 100,
    "additionalFields": {
      "identifier": "{{ $uuid }}",
      "timestamp": "{{ $datetime.iso }}",
      "customPayload": {
        "properties": [
          { "key": "endpoint", "value": "/api/v1/data" }
        ]
      }
    }
  }
}

Create a WeChat source and attach it to a customer:

{
  "type": "stripe",
  "parameters": {
    "resource": "source",
    "operation": "create",
    "customerId": "cus_123456789",
    "type": "wechat",
    "amount": 1000,
    "currency": "usd",
    "additionalFields": {
      "statement_descriptor": "ACME Corp Purchase",
      "metadata": {
        "metadataProperties": [
          { "key": "payment_method", "value": "wechat" }
        ]
      }
    }
  }
}

Create a card token:

{
  "type": "stripe",
  "parameters": {
    "resource": "token",
    "operation": "create",
    "type": "cardToken",
    "number": "4242424242424242",
    "cvc": "123",
    "expirationMonth": "12",
    "expirationYear": "2030"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

This tool interacts with the Stripe service to manage charges, customers, coupons, customer cards, sources, tokens, meter events, and account balances. It is ideal for creating and reading charges, customers, coupons, sources, and tokens, as well as updating and deleting customers, and adding or removing customer cards. It produces confirmation of successful operations, retrieved resource details, or lists of resources.

Common Patterns

Payment flow

1. Create a card token from the customer’s card details.
2. Create the customer.
3. Add the card to the customer with Customer Card: Add, using the token’s ID.
4. Create a charge against that customer and card.

Coupons

Create the coupon with Coupon: Create, then apply it when you create the subscription in Stripe — subscription creation is outside this node.

Meter-based billing

Send a Meter Event: Create each time usage occurs. Values may be positive or negative, so a correction is just a negative event, and Custom Payload Properties carries the extra context you want to see in Stripe.

Working With Amounts and IDs

• Amounts are always in the currency’s smallest unit — 2000 is $20.00, not $2,000.
• Currency codes are lowercase three-letter ISO codes such as usd or eur.
• Check that an ID has the prefix its field expects before sending it: customers are cus_, charges ch_, cards card_, sources src_ and tokens tok_. A card ID in a Source ID field is the most common cause of a “no such source” error.
• Collections (Additional Fields, Update Fields, Filters) are flat objects keyed by the sub-field’s internal name. Metadata and Custom Payload Properties hold a list of key/value entries under metadataProperties and properties; Address nests one record under details.