Skip to content

Stripe Payment Processor

Overview

The Stripe task takes a payment through the account's Stripe connection. It has two actions:

  • Charge Account — charges the card saved on the client's billing account in BaseCloud, at once.
  • Create Payment Link — creates a Stripe payment page for the amount, to send to the client.

The amount is given in the currency's main unit (99.99) and converted to cents for Stripe.

Settings → App Connections & Keys with Select App Type open: a search field and a card for each app that can be connected, including Facebook Lead Ads, Facebook Marketing, Google Ads, Google Docs, Google Sheets, Microsoft Email, Paystack, Stripe, WhatsApp Business and Xero, each marked OAuth2 or API Key

Connections live in Settings → App Connections & Keys, not on the task. Connect the app once and every task that needs it can use it. The badge on each tile says how it authenticates — OAuth2 sends you to the provider to sign in, API Key expects a key you paste in.

Prerequisites

  • A Stripe connection in Settings → App Connections & Keys, with the account's secret key.
  • For Charge Account: the client must have an active billing account with a saved card in BaseCloud. The default one is charged; without one the task fails (see Troubleshooting).

Configuration

Builder fields

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Field Key Type Default Notes
Stripe Connection app_connection_id app-connection –
Action action select charge_account Options: Charge Account · Create Payment Link
Client ID o_client_id textarea – Only shown when action is charge_account
Email email textarea – Only shown when action is create_payment_link
Amount amount textarea – Only shown when action is charge_account, create_payment_link
Currency currency select USD Options: USD — US Dollar · ZAR — South African Rand · EUR — Euro · GBP — British Pound. Only shown when action is charge_account, create_payment_link
Metadata metadata_rows dyn-rows – Only shown when action is charge_account

Charge Account

  • Client ID is the client's o_client_id — the client is looked up by it, and an unknown id fails the task.
  • Amount is read like any accounting amount: 250, $1,250.00 and 1 250,00 all work, and it's rounded to the cent. A blank, zero or unreadable amount stops the run before anything is charged.
  • Currency is one of the four offered.
  • The card is charged straight away (a Stripe Payment Intent, confirmed). Only a payment Stripe reports as succeeded passes: anything else — requires_action (the bank wants 3-D Secure), processing, a decline — fails the task with Stripe's status or message, and the tasks after it do not run.
  • Metadata rows are sent to Stripe with the payment; BaseCloud adds owner_id and client_id. Stripe's limits are checked first — at most 50 keys, keys up to 40 characters, values up to 500 — and a breach fails the task, naming the entry, before anything is charged.

Charging for an invoice

Put the invoice's number, without its INV, in a Metadata row named invoice_id (for example 1024, or {{task_<ID>_quote_invoice_o_id}} from an Accounting step), and map what it still owes to Amount: {{task_<ID>_quote_invoice_balance_due}}, not its total.

  • The charge is capped at what the invoice still owes. A larger Amount charges the balance, and charge_note says so. That way a client whose credit already paid part of the invoice isn't charged the whole total.
  • Nothing is charged when the invoice owes nothing (paid already, or void): charged is false, and run_text says "Nothing is owed on INV…, so the card was not charged."
  • When the payment comes through, BaseCloud records it on the invoice by itself, and workflows on Payment received and Marked as paid run. You don't need a Mark Quote / Invoice Paid step: see the tip under Mark Quote / Invoice Paid.

Without invoice_id, the amount is charged as given and no invoice is marked paid.

  • Email is required. Amount and Currency set the price.
  • Each run creates a new Stripe product and price for the amount, then the payment link — three calls to Stripe. A failure at any step fails the task with Stripe's message (Failed to create product: …, Failed to create price: …).
  • Send the link (data_payment_link_url) to the client with an Email or SMS task.

Output Fields

Reference fields as {{task_<ID>_<field>}}; run_text says what happened.

Charge Account output

{
  "task_40001_run": true,
  "task_40001_run_text": "Payment successful",
  "task_40001_id": "pi_3AbCdEfGhIjKlMnO",
  "task_40001_object": "payment_intent",
  "task_40001_amount": 9999,
  "task_40001_currency": "usd",
  "task_40001_status": "succeeded",
  "task_40001_customer": "cus_AbCdEfGhIjKl",
  "task_40001_payment_method": "pm_1AbCdEfGhIjKlMnO",
  "task_40001_client_secret": "pi_3AbC_secret_dEfGhIjKlMnOpQrS",
  "task_40001_charges_data_0_id": "ch_3AbCdEfGhIjKlMnO",
  "task_40001_charges_data_0_amount": 9999,
  "task_40001_charges_data_0_status": "succeeded",
  "task_40001_charges_data_0_payment_method_details_card_brand": "visa",
  "task_40001_charges_data_0_payment_method_details_card_last4": "4242",
  "task_40001_charged": true,
  "task_40001_amount_charged": "99.99",
  "task_40001_charge_note": ""
}

charged is false and amount_charged is 0.00 when an invoice in the metadata owed nothing. charge_note says when the charge was lowered to what the invoice owed.

{
  "task_40001_run": true,
  "task_40001_run_text": "Payment link created successfully",
  "task_40001_data_payment_link_url": "https://buy.stripe.com/test_xxxxxxxxxxxxx",
  "task_40001_data_payment_link_id": "plink_1AbCdEfGhIjKlMnO",
  "task_40001_data_product_id": "prod_AbCdEfGhIjKl",
  "task_40001_data_price_id": "price_1AbCdEfGhIjKlMnO"
}

Real-World Examples

CRM Trigger  (status changed to "Quote accepted")
  └─ Match to Client   look the client up
      └─ Stripe        generate a payment link
          └─ Email     send the link to the client

Charge a stored card for each unpaid invoice

Timer  (monthly, on the 2nd)
  └─ BaseCloud Accounting   Get Quotes / Invoices: Type Invoice, Paid status Unpaid
      └─ Loop               over quote_invoice_ids
          └─ BaseCloud Accounting   Fetch Quote / Invoice
              └─ Stripe              Charge Account: Amount {{…_quote_invoice_balance_due}},
                                     Metadata invoice_id = {{…_quote_invoice_o_id}}

Record the payment against the client

Webhook In  (Stripe payment succeeded)
  └─ Match to Client     contact_email from the payload
      └─ Workflow Note   log the payment against the client

Troubleshooting

Message Cause and fix
No app connection ID provided. / Failed to fetch app connection. Pick a Stripe connection; reconnect it in Settings › App Connections & Keys if it was removed.
No currency selected. / Amount is not a number. Set the currency; map an amount more than zero.
Nothing is owed on INV…, so the card was not charged. Not an error: the invoice in the metadata was already paid or void.
No client selected. / the client is not found Map the client's o_client_id.
No active billing account found for this client. The client has no saved card — send a payment link instead.
Payment status: requires_action The bank wants 3-D Secure, which an automatic charge cannot complete. Send a payment link, which handles it.
Payment status: processing Stripe has not confirmed the payment yet; the task does not wait for it.
Stripe takes at most 50 metadata keys … Reduce or shorten the metadata rows as the message says.
Rate limited — rescheduled for retry. Nothing — the run is retried automatically.

FAQ

Can I refund a payment here? No — refund in the Stripe Dashboard. BaseCloud records the refund by itself, and the invoice owes the money again: see Refunds made in Stripe or Paystack.

Where do saved cards come from? A client saves their card by ticking Save this card for future payments when they pay an invoice online. The payment page itself never charges a saved card.

Can I test without real charges? Yes — connect Stripe with a test secret key (sk_test_…) and use Stripe's test cards.

Which currencies? USD, ZAR, EUR and GBP, as the Currency setting offers.