Stripe

Connect to Stripe for payment processing, subscription management, and financial operations.

Overview

Stripe is a payment infrastructure platform. The integration supports:

Customer Management - Create and manage customer records
Invoicing - Create, send, finalize, and void invoices
Subscriptions - Create and manage recurring billing
Payment Intents - Process one-time payments
Balance - Check account balance and transactions

Prerequisites

Stripe account (Standard or Connect)
API keys or OAuth app credentials
Appropriate scopes for desired operations

Authentication

Stripe uses OAuth 2.0 for authentication via Nango.

curl "http://localhost:3000/api/v1/connections/stripe/auth-url" \
  -H "x-api-key: YOUR_API_KEY"

Available Actions

Customer Actions

getCustomer

Get a customer by ID.

{
  "action": "stripe.getCustomer",
  "config": {
    "customerId": "cus_xxx"
  }
}

createCustomer

Create a new customer.

{
  "id": "create-customer",
  "type": "action",
  "action": "stripe.createCustomer",
  "config": {
    "email": "{{input.email}}",
    "name": "{{input.name}}",
    "description": "Customer from workflow",
    "phone": "{{input.phone}}",
    "address": {
      "line1": "{{input.address.street}}",
      "city": "{{input.address.city}}",
      "state": "{{input.address.state}}",
      "postal_code": "{{input.address.zip}}",
      "country": "{{input.address.country}}"
    },
    "metadata": {
      "source": "workflow",
      "company_id": "{{input.companyId}}"
    }
  }
}

Parameters:

Field	Type	Required	Description
`email`	string	No	Customer email
`name`	string	No	Customer name
`description`	string	No	Description
`phone`	string	No	Phone number
`address`	object	No	Customer address
`metadata`	object	No	Key-value metadata

updateCustomer

Update an existing customer.

{
  "action": "stripe.updateCustomer",
  "config": {
    "customerId": "{{input.customerId}}",
    "email": "{{input.newEmail}}",
    "metadata": {
      "updated_at": "{{now}}"
    }
  }
}

listCustomers

List customers with filters.

{
  "action": "stripe.listCustomers",
  "config": {
    "limit": 100,
    "email": "{{input.email}}",
    "startingAfter": "{{steps.previous.output.data[99].id}}"
  }
}

Invoice Actions

createInvoice

Create a new invoice.

{
  "id": "create-invoice",
  "type": "action",
  "action": "stripe.createInvoice",
  "config": {
    "customerId": "{{steps.customer.output.id}}",
    "autoAdvance": false,
    "collectionMethod": "send_invoice",
    "daysUntilDue": 30,
    "description": "Invoice for services",
    "metadata": {
      "order_id": "{{input.orderId}}"
    }
  }
}

Parameters:

Field	Type	Required	Description
`customerId`	string	Yes	Customer to invoice
`autoAdvance`	boolean	No	Auto-finalize (default: true)
`collectionMethod`	string	No	`charge_automatically` or `send_invoice`
`daysUntilDue`	number	No	Days until due (for send_invoice)
`description`	string	No	Invoice description
`metadata`	object	No	Custom metadata

createInvoiceItem

Add a line item to an invoice.

{
  "action": "stripe.createInvoiceItem",
  "config": {
    "customerId": "{{steps.customer.output.id}}",
    "invoiceId": "{{steps.create-invoice.output.id}}",
    "amount": 9900,
    "currency": "usd",
    "description": "Professional Services - January 2024",
    "quantity": 1
  }
}

getInvoice

Get an invoice by ID.

{
  "action": "stripe.getInvoice",
  "config": {
    "invoiceId": "in_xxx"
  }
}

listInvoices

List invoices with filters.

{
  "action": "stripe.listInvoices",
  "config": {
    "customerId": "{{input.customerId}}",
    "status": "open",
    "limit": 50
  }
}

finalizeInvoice

Finalize a draft invoice.

{
  "action": "stripe.finalizeInvoice",
  "config": {
    "invoiceId": "{{steps.create-invoice.output.id}}"
  }
}

sendInvoice

Send an invoice to the customer.

{
  "action": "stripe.sendInvoice",
  "config": {
    "invoiceId": "{{steps.finalize.output.id}}"
  }
}

voidInvoice

Void an invoice.

{
  "action": "stripe.voidInvoice",
  "config": {
    "invoiceId": "{{input.invoiceId}}"
  }
}

Payment Intent Actions

createPaymentIntent

Create a payment intent for one-time payments.

{
  "id": "create-payment",
  "type": "action",
  "action": "stripe.createPaymentIntent",
  "config": {
    "amount": 9900,
    "currency": "usd",
    "customerId": "{{input.customerId}}",
    "description": "Order #{{input.orderId}}",
    "paymentMethodTypes": ["card"],
    "captureMethod": "automatic",
    "metadata": {
      "order_id": "{{input.orderId}}"
    }
  }
}

Parameters:

Field	Type	Required	Description
`amount`	number	Yes	Amount in cents
`currency`	string	Yes	Three-letter currency code
`customerId`	string	No	Customer to charge
`description`	string	No	Payment description
`paymentMethodTypes`	array	No	Allowed payment methods
`paymentMethod`	string	No	Specific payment method ID
`captureMethod`	string	No	`automatic` or `manual`
`confirm`	boolean	No	Confirm immediately
`offSession`	boolean	No	Off-session payment
`setupFutureUsage`	string	No	`on_session` or `off_session`
`receiptEmail`	string	No	Email for receipt
`statementDescriptor`	string	No	Statement descriptor
`metadata`	object	No	Custom metadata

getPaymentIntent

Get a payment intent by ID.

{
  "action": "stripe.getPaymentIntent",
  "config": {
    "paymentIntentId": "pi_xxx"
  }
}

confirmPaymentIntent

Confirm a payment intent.

{
  "action": "stripe.confirmPaymentIntent",
  "config": {
    "paymentIntentId": "{{steps.create-payment.output.id}}",
    "paymentMethod": "{{input.paymentMethodId}}",
    "returnUrl": "https://example.com/payment/complete"
  }
}

capturePaymentIntent

Capture a payment intent (for manual capture).

{
  "action": "stripe.capturePaymentIntent",
  "config": {
    "paymentIntentId": "{{input.paymentIntentId}}",
    "amountToCapture": 5000
  }
}

cancelPaymentIntent

Cancel a payment intent.

{
  "action": "stripe.cancelPaymentIntent",
  "config": {
    "paymentIntentId": "{{input.paymentIntentId}}",
    "cancellationReason": "requested_by_customer"
  }
}

listPaymentIntents

List payment intents.

{
  "action": "stripe.listPaymentIntents",
  "config": {
    "customerId": "{{input.customerId}}",
    "limit": 50
  }
}

Subscription Actions

createSubscription

Create a new subscription.

{
  "id": "create-subscription",
  "type": "action",
  "action": "stripe.createSubscription",
  "config": {
    "customerId": "{{input.customerId}}",
    "items": [
      { "price": "price_xxx" }
    ],
    "collectionMethod": "charge_automatically",
    "trialPeriodDays": 14,
    "metadata": {
      "plan": "{{input.planName}}"
    }
  }
}

Parameters:

Field	Type	Required	Description
`customerId`	string	Yes	Customer ID
`items`	array	Yes	Subscription items with price IDs
`defaultPaymentMethod`	string	No	Default payment method
`collectionMethod`	string	No	`charge_automatically` or `send_invoice`
`daysUntilDue`	number	No	Days until due (for send_invoice)
`trialPeriodDays`	number	No	Trial period in days
`cancelAtPeriodEnd`	boolean	No	Cancel at period end
`prorationBehavior`	string	No	`create_prorations`, `none`, `always_invoice`
`metadata`	object	No	Custom metadata

getSubscription

Get a subscription by ID.

{
  "action": "stripe.getSubscription",
  "config": {
    "subscriptionId": "sub_xxx"
  }
}

updateSubscription

Update a subscription.

{
  "action": "stripe.updateSubscription",
  "config": {
    "subscriptionId": "{{input.subscriptionId}}",
    "items": [
      { "id": "{{input.itemId}}", "price": "price_new_xxx" }
    ],
    "prorationBehavior": "create_prorations"
  }
}

cancelSubscription

Cancel a subscription.

{
  "action": "stripe.cancelSubscription",
  "config": {
    "subscriptionId": "{{input.subscriptionId}}",
    "invoiceNow": true,
    "prorate": true
  }
}

listSubscriptions

List subscriptions.

{
  "action": "stripe.listSubscriptions",
  "config": {
    "customerId": "{{input.customerId}}",
    "status": "active",
    "limit": 50
  }
}

Balance Actions

getBalance

Get account balance.

{
  "action": "stripe.getBalance",
  "config": {}
}

listBalanceTransactions

List balance transactions.

{
  "action": "stripe.listBalanceTransactions",
  "config": {
    "limit": 100,
    "type": "charge"
  }
}

Webhook Triggers

Stripe webhooks trigger workflows on payment events.

{
  "trigger": {
    "type": "webhook",
    "provider": "stripe",
    "events": ["invoice.paid", "customer.subscription.updated"]
  }
}

Common Events:

Event	Description
`invoice.paid`	Invoice was paid
`invoice.payment_failed`	Payment failed
`customer.subscription.created`	New subscription
`customer.subscription.updated`	Subscription changed
`customer.subscription.deleted`	Subscription cancelled
`payment_intent.succeeded`	Payment completed
`payment_intent.payment_failed`	Payment failed
`charge.refunded`	Charge refunded

Example Workflow

Invoice and payment workflow:

{
  "name": "Create and Send Invoice",
  "trigger": {
    "type": "api"
  },
  "steps": [
    {
      "id": "get-or-create-customer",
      "type": "action",
      "action": "stripe.listCustomers",
      "config": {
        "email": "{{input.email}}",
        "limit": 1
      }
    },
    {
      "id": "check-customer",
      "type": "condition",
      "config": {
        "conditions": {
          "left": "{{steps.get-or-create-customer.output.data.length}}",
          "operator": "gt",
          "right": 0
        },
        "then": ["create-invoice"],
        "else": ["create-customer"]
      }
    },
    {
      "id": "create-customer",
      "type": "action",
      "action": "stripe.createCustomer",
      "config": {
        "email": "{{input.email}}",
        "name": "{{input.name}}"
      }
    },
    {
      "id": "create-invoice",
      "type": "action",
      "action": "stripe.createInvoice",
      "config": {
        "customerId": "{{steps.get-or-create-customer.output.data[0].id || steps.create-customer.output.id}}",
        "autoAdvance": false,
        "collectionMethod": "send_invoice",
        "daysUntilDue": 30
      }
    },
    {
      "id": "add-line-item",
      "type": "action",
      "action": "stripe.createInvoiceItem",
      "config": {
        "customerId": "{{steps.get-or-create-customer.output.data[0].id || steps.create-customer.output.id}}",
        "invoiceId": "{{steps.create-invoice.output.id}}",
        "amount": "{{input.amount}}",
        "currency": "usd",
        "description": "{{input.description}}"
      }
    },
    {
      "id": "finalize",
      "type": "action",
      "action": "stripe.finalizeInvoice",
      "config": {
        "invoiceId": "{{steps.create-invoice.output.id}}"
      }
    },
    {
      "id": "send",
      "type": "action",
      "action": "stripe.sendInvoice",
      "config": {
        "invoiceId": "{{steps.create-invoice.output.id}}"
      }
    }
  ]
}

Rate Limits

Limit	Value
API calls	100/second (read)
API calls	100/second (write)
Webhook delivery	Up to 5 retries

Troubleshooting

Common Errors

Error	Cause	Solution
`card_declined`	Card was declined	Customer should use different card
`invalid_request_error`	Invalid parameters	Check required fields
`rate_limit_error`	Too many requests	Implement backoff
`authentication_error`	Invalid API key	Check connection status

Stripe

On this page