Skip to content
Docs
Payments & banking

Stripe

Let hires look up customers, invoices and payments, see who owes what, check the balance and payouts, and draft and send invoices and payment links in Stripe.

Explore 15 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Stripe, a hire can:

  • find customers,
  • list invoices by status (draft, unpaid, overdue, paid, void), customer and date, and read one in full,
  • see who owes what and how late (current, 1–30, 31–60, 61–90 and over 90 days),
  • list payments (succeeded, failed, refunded, disputed) and read one,
  • check the balance (available and pending) and payouts to your bank,
  • draft an invoice, finalise it (so it has a number and a payment page), send it, make a payment link, and mark an invoice paid when the customer paid outside Stripe.

A hire can also refund a payment, but only with a person's approval, every time: it asks in the thread with the payment and the amount, and when the approver says yes, Roster makes exactly that refund, once (more). Nobody can turn that asking off. For refunds, set Charges and Refunds to Write on the restricted key; at Read, Stripe refuses them.

Hires never pay out, charge a card or cancel anything in Stripe. Those stay with people.

1. Make a restricted key in Stripe

A restricted key can do only what you allow, so it's the safest way to connect.

  1. Open API keys in your Stripe dashboard (the form in Roster links there too) and click Create restricted key.
  2. Name it Roster.
  3. Set these permissions and leave everything else at None:
PermissionRead only hiresHires that also draft and send
CustomersReadRead
InvoicesReadWrite
Charges and RefundsReadRead
PaymentIntentsReadRead
BalanceReadRead
PayoutsReadRead
Payment LinksReadWrite
Products and PricesNoneWrite (for payment links)
EventsReadRead
Webhook EndpointsWriteWrite

To let approved refunds through, set Charges and Refunds to Write instead. Webhook Endpoints lets Roster set up its own webhook, so Stripe tells it of changes at once; leave it at None if you'd rather not, and Roster asks Stripe instead.

  1. Click Create key and copy it. It starts with rk_live_ (or rk_test_ in test mode). Roster tells you at once if what you paste isn't a secret or restricted key (a publishable pk_ key won't do).

A key made in test mode only sees test data, which is a good way to try it first.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Stripe and choose it.
  2. Paste the Restricted API key and click Connect.

Roster checks the key with Stripe and the connection shows Connected as your Stripe account (with Test mode for a test key). If Stripe refuses the key, or it's missing a permission Roster needs to check it (Balance: Read), Roster says which and saves nothing.

With Webhook Endpoints: Write on the key, Roster then adds its own webhook in Stripe, for the events hires watch, and keeps its signing secret. There's nothing to paste.

3. Give hires access

On the hire's Tools tab, click Give access on Stripe:

  • Read only: it can look up customers, invoices, payments, the balance and payouts. It can't change anything.
  • Read and write: it can also draft, finalise and send invoices, make payment links, and mark invoices paid outside Stripe, and ask to refund a payment (each refund waits for approval).

Drafting and sending are separate. A draft stays in Stripe until someone finalises or sends it, so a hire can prepare invoices for you to check first. Finalising gives the invoice its number and a payment page to share, without emailing anyone.

Hires refer to invoices by their number, like BAYT-0042 (drafts don't have one yet, so they use the id), and to customers by name or email.

Watching Stripe

A hire's responsibility can watch Stripe: it's woken when an invoice is paid, fails, falls overdue, is sent or voided, when a payment succeeds, fails, is refunded or disputed, and when a payout arrives or fails. Checking costs nothing when nothing happened.

Hear of changes at once (optional)

When the key has Webhook Endpoints: Write, Roster sets this up itself when you connect, and removes its webhook from Stripe when you remove the connection. Otherwise Roster asks Stripe what changed each time a hire checks. To have Stripe tell Roster the moment something happens without giving the key that permission, add the webhook by hand:

  1. In Stripe, open Developers → Webhooks and click Add endpoint.
  2. Endpoint URL: the webhook address Roster shows on the Stripe connection.
  3. Select these events: invoice.paid, invoice.payment_failed, invoice.overdue, invoice.finalized, invoice.sent, invoice.voided, invoice.marked_uncollectible, charge.succeeded, charge.failed, charge.refunded, charge.dispute.created, payout.paid and payout.failed.
  4. Click Add endpoint, then Reveal the signing secret (it starts with whsec_) and paste it as the connection's Webhook signing secret in Roster.

Roster only keeps deliveries signed with that secret.

Things to know

  • Part-payments outside Stripe: Stripe can only mark the whole amount paid. For a part-payment, the hire tells you instead.
  • Notes: Stripe invoices have no comment history, so hires keep notes in the conversation.

If something goes wrong

  • "Doesn't have the required permissions": the key is missing one of the permissions above. Edit the key in Stripe and add it.
  • "Didn't accept the connection's credential": the key was deleted or rolled. Make a new one and paste it on the connection.
  • Nothing found that you can see in Stripe: check the key is from the same mode (live or test) and the same Stripe account.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Stripe and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Stripe: Developers → API keys → Create restricted key. Give it only what hires need (see the guide). A secret key works too, but a restricted one is safer.

When making a key, use these permissions from the connection guide:

  • Customers: Read
  • Invoices: Write (Read for read-only hires)
  • Charges and Refunds: Read (Write to allow approved refunds)
  • PaymentIntents: Read
  • Balance: Read
  • Payouts: Read
  • Payment Links: Write
  • Products and Prices: Write
  • Events: Read
  • Webhook Endpoints: Write (so Roster can set up its own webhook)

Connection fields

Stripe connection fields
FieldWhat to provide
Restricted API key
token
Required · sealed secret		In Stripe: Developers → API keys → Create restricted key. Give it only what hires need (see the guide). A secret key works too, but a restricted one is safer.
Webhook signing secret
webhookSecret
Optional · sealed secret		Optional. To hear of changes the moment they happen: in Stripe, add a webhook endpoint with the address Roster shows on this connection, then paste its signing secret (whsec_…). Without it, Roster asks Stripe for changes instead.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

No additional fields.

Actions

15 actions: 9 only read and 6 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

15 of 15 actions. Open an action for its arguments and full input schema.

list_customersRead only

Customers in Stripe, optionally matching words in their name or an email address.

Approval: Uses your workspace and hire approval settings.

Arguments for list_customers
ArgumentTypeDetails
searchOptionalstringwords in the name, or an email address
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "description": "words in the name, or an email address",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
list_invoicesRead only

Invoices, newest first, filtered by status (draft, unpaid, overdue, paid, void), customer, invoice date and words in the number or memo.

Approval: Uses your workspace and hire approval settings.

Arguments for list_invoices
ArgumentTypeDetails
statusOptional"any" | "draft" | "unpaid" | "overdue" | "paid" | "void"unpaid: sent and not fully paid; overdue: unpaid and past its due dateDefault: "any"
customerOptionalstringa customer's name or id
fromOptionalstringinvoice date on or after, yyyy-mm-dd
toOptionalstringinvoice date on or before, yyyy-mm-dd
searchOptionalstringwords in the invoice number or reference
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "any",
      "description": "unpaid: sent and not fully paid; overdue: unpaid and past its due date",
      "type": "string",
      "enum": [
        "any",
        "draft",
        "unpaid",
        "overdue",
        "paid",
        "void"
      ]
    },
    "customer": {
      "description": "a customer's name or id",
      "type": "string"
    },
    "from": {
      "description": "invoice date on or after, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "invoice date on or before, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "search": {
      "description": "words in the invoice number or reference",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
get_invoiceRead only

One invoice in full: customer, dates, lines, totals, what's paid and owed, and its payment page.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. ACME-0042, or its id (in_…)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. ACME-0042, or its id (in_…)"
    }
  },
  "required": [
    "invoice"
  ]
}
receivables_summaryRead only

Who owes what and how late: open invoices totalled by age (current, 1-30, 31-60, 61-90, over 90 days) and the customers most overdue.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_paymentsRead only

Card and other payments (charges), newest first: succeeded, pending or failed, with refunds and disputes. Optionally one customer's, or from a date.

Approval: Uses your workspace and hire approval settings.

Arguments for list_payments
ArgumentTypeDetails
customerOptionalstringa customer's name, email or id
fromOptionalstringinvoice date on or after, yyyy-mm-dd
toOptionalstringinvoice date on or before, yyyy-mm-dd
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "description": "a customer's name, email or id",
      "type": "string"
    },
    "from": {
      "description": "invoice date on or after, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "invoice date on or before, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
get_paymentRead only

One payment by its id: a charge (ch_…) or a payment intent (pi_…), with its status and receipt.

Approval: Uses your workspace and hire approval settings.

Arguments for get_payment
ArgumentTypeDetails
paymentRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "payment": {
      "type": "string",
      "pattern": "^(ch|py|pi)_\\w+$"
    }
  },
  "required": [
    "payment"
  ]
}
get_balanceRead only

The Stripe balance: what's available to pay out and what's still pending, per currency.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_payoutsRead only

Payouts from Stripe to the bank, newest first, with when each arrives and whether it failed.

Approval: Uses your workspace and hire approval settings.

Arguments for list_payouts
ArgumentTypeDetails
statusOptional"any" | "pending" | "in_transit" | "paid" | "failed" | "canceled"See input schema below.Default: "any"
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "pending",
        "in_transit",
        "paid",
        "failed",
        "canceled"
      ]
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
list_payment_linksRead only

Payment links made in Stripe, with their addresses and whether each still takes payments.

Approval: Uses your workspace and hire approval settings.

Arguments for list_payment_links
ArgumentTypeDetails
activeOptionalbooleanonly active (true) or deactivated (false) links
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "active": {
      "description": "only active (true) or deactivated (false) links",
      "type": "boolean"
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
create_draft_invoiceRead and write

Create a draft invoice for a customer, to be paid by bank transfer or on Stripe's payment page. Nothing is sent and nothing is charged: it stays a draft until someone finalises or sends it.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft_invoice
ArgumentTypeDetails
customerRequiredstringthe customer's name, email or id
linesRequiredobject[]See input schema below.
currencyOptionalstringdefault: the customer's currency
due_dateOptionalstringwhen it's due, yyyy-mm-dd
days_until_dueOptionalintegerinstead of due_date; default 30
memoOptionalstringthe memo shown on the invoice
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "type": "string",
      "minLength": 1,
      "description": "the customer's name, email or id"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          },
          "item": {
            "description": "a product or service id or code from the accounting system",
            "type": "string"
          },
          "account": {
            "description": "an income account code, where the system needs one",
            "type": "string"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      }
    },
    "currency": {
      "description": "default: the customer's currency",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "due_date": {
      "description": "when it's due, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "days_until_due": {
      "description": "instead of due_date; default 30",
      "type": "integer",
      "minimum": 0,
      "maximum": 365
    },
    "memo": {
      "description": "the memo shown on the invoice",
      "type": "string",
      "maxLength": 5000
    }
  },
  "required": [
    "customer",
    "lines"
  ]
}
finalize_invoiceRead and write

Finalise a draft invoice: it gets its number and a payment page to share, and can no longer be edited. Nothing is emailed and the customer isn't charged.

Approval: Uses your workspace and hire approval settings.

Arguments for finalize_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. ACME-0042, or its id (in_…)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. ACME-0042, or its id (in_…)"
    }
  },
  "required": [
    "invoice"
  ]
}
send_invoiceRead and write

Email an invoice to the customer from Stripe, finalising it first if it's a draft. Only for invoices paid by the customer (not charged automatically).

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. ACME-0042, or its id (in_…)
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. ACME-0042, or its id (in_…)"
    }
  },
  "required": [
    "invoice"
  ]
}
create_payment_linkRead and write

Make a payment link: a Stripe page anyone with the address can pay, for the lines given. Nothing is sent: share the address yourself.

Approval: Uses your workspace and hire approval settings.

Arguments for create_payment_link
ArgumentTypeDetails
linesRequiredobject[]See input schema below.
currencyRequiredstringSee input schema below.
purposeOptionalstringwhat it's for, kept on the link for people to see
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "lines": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      }
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "purpose": {
      "description": "what it's for, kept on the link for people to see",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "lines",
    "currency"
  ]
}
record_paymentRead and write

Mark an open invoice as paid outside Stripe (by bank transfer or cash), for the whole amount owed. Stripe doesn't record part-payments made outside it.

Approval: Uses your workspace and hire approval settings.

Arguments for record_payment
ArgumentTypeDetails
invoiceRequiredstringthe invoice number or id
amountRequirednumberSee input schema below.
dateOptionalstringwhen it was paid; default today
referenceOptionalstringthe bank or cheque reference
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number or id"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "date": {
      "description": "when it was paid; default today",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "description": "the bank or cheque reference",
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "invoice",
    "amount"
  ]
}
refund_paymentRead and writeApproval required · locked

Refund a payment to the customer's card or account, in full or in part. Money moving always waits for a person's approval: Roster asks in the thread and makes exactly this refund, once, when they approve. Give the amount with its currency for a part refund; leave both out to refund whatever is left.

Approval: Always asks for approval. This requirement cannot be turned off.

Arguments for refund_payment
ArgumentTypeDetails
paymentRequiredstringSee input schema below.
amountOptionalnumberhow much to refund, e.g. 120.50
currencyOptionalstringthe payment's currency, e.g. USD; needed with amount
reasonOptional"duplicate" | "fraudulent" | "requested_by_customer"See input schema below.
noteOptionalstringwhy, kept on the refund in Stripe
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "payment": {
      "type": "string",
      "pattern": "^(ch|py|pi)_\\w+$"
    },
    "amount": {
      "description": "how much to refund, e.g. 120.50",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "description": "the payment's currency, e.g. USD; needed with amount",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "reason": {
      "type": "string",
      "enum": [
        "duplicate",
        "fraudulent",
        "requested_by_customer"
      ]
    },
    "note": {
      "description": "why, kept on the refund in Stripe",
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "payment"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • Incoming webhooks are supported. Roster can register the connection's callback with the service.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Square

Payments, orders, invoices, customers and catalog in Square.

Tap Payments

Let hires see payments, invoices, customers and payouts in Tap, see who owes what, and draft and send invoices and payment links.

On this page

1. Make a restricted key in Stripe2. Connect it in Roster3. Give hires accessHear of changes at once (optional)Things to knowIf something goes wrongTools and permissions reference