Tap Payments
Let hires see payments, invoices, customers and payouts in Tap, see who owes what, and draft and send invoices and payment links.
Explore 10 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.
With Tap Payments, a hire can:
- list payments (captured, failed, declined…) and read one, with Tap's reason when it failed,
- list Tap invoices by status (draft, unpaid, overdue, paid, cancelled) and read one,
- see who owes what on Tap invoices and how late,
- find customers saved in Tap and list payouts to your bank,
- save an invoice as a draft, send a draft by email (and SMS), and make a payment link.
Hires never charge a card, refund or cancel a payment in Tap. Those stay with people.
1. Find your secret key in Tap
- Sign in to Tap's dashboard (the form in Roster links there too) and open goSell → API Credentials → Generate Key.
- Copy the secret key. It starts with
sk_live_; to try it first, use the test one (sk_test_), which only sees test payments. Roster tells you at once if what you paste isn't a secret key (the publishablepk_one won't do).
2. Connect it in Roster
- Open Integrations → Tools → Add a tool, search for Tap Payments and choose it.
- Paste the Secret key and click Connect.
Roster checks the key by asking Tap for one payment, and the connection shows Connected, in Live mode or Test mode. Tap doesn't tell Roster your account's name. If Tap refuses the key, Roster says so and saves nothing.
3. Give hires access
On the hire's Tools tab, click Give access on Tap Payments:
- Read only: it can look up payments, invoices, customers and payouts and see who owes what. It can't change anything.
- Read and write: it can also save draft invoices, send them and make payment links.
A draft isn't sent and can't be paid until someone sends it, so a hire can prepare invoices for you to check first. A payment link is an invoice page Tap doesn't send to anyone: the hire shares the address, for example in an email or a WhatsApp message.
Customers are given by their Tap id (cus_…) or by email and name, with a mobile number in
international form (+971501234567) if Tap should also send an SMS.
Watching payments
A hire's responsibility can watch Tap: it's woken when a payment comes in or fails, with the amount, the customer and Tap's reason. Checking costs nothing when nothing happened.
If something goes wrong
- "Invalid API key": the key was regenerated in Tap. Copy the new one onto the connection.
- Nothing found that you can see in Tap: check the key is the live one, not the test one.
- Older invoices missing: invoice lists cover the last 90 days unless the hire gives dates.
Tools and permissions reference
This reference is built from the same definitions Roster uses to connect Tap Payments 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 Tap's dashboard: goSell → API Credentials → your secret key (sk_live_… or, to try it first, sk_test_…).
No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.
Connection fields
| Field | What to provide |
|---|---|
Secret keytokenRequired · sealed secret | In Tap's dashboard: goSell → API Credentials → your secret key (sk_live_… or, to try it first, sk_test_…). |
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
10 actions: 7 only read and 3 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.
10 of 10 actions. Open an action for its arguments and full input schema.
list_chargesRead only
Payments taken through Tap (charges), newest first: captured, failed, declined and the rest, optionally one status, customer or date range (default the last 30 days).
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
statusOptional | "any" | "CAPTURED" | "FAILED" | "DECLINED" | "CANCELLED" | "ABANDONED" | "INITIATED" | "VOID" | See input schema below.Default: "any" |
customerOptional | string | See input schema below. |
fromOptional | string | invoice date on or after, yyyy-mm-dd |
toOptional | string | invoice date on or before, yyyy-mm-dd |
limitOptional | integer | See input schema below.Default: 30 |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"status": {
"default": "any",
"type": "string",
"enum": [
"any",
"CAPTURED",
"FAILED",
"DECLINED",
"CANCELLED",
"ABANDONED",
"INITIATED",
"VOID"
]
},
"customer": {
"type": "string",
"pattern": "^cus_"
},
"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_chargeRead only
One payment (charge) by its id: amount, status and Tap's reason, the customer and references.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
chargeRequired | string | See input schema below. |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"charge": {
"type": "string",
"pattern": "^chg_\\w+$"
}
},
"required": [
"charge"
]
}list_invoicesRead only
Tap invoices (payment pages sent or shared with customers), newest first, by status (draft, unpaid, overdue, paid, void), invoice date (default the last 90 days) and words in the number, customer or description.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
statusOptional | "any" | "draft" | "unpaid" | "overdue" | "paid" | "void" | unpaid: sent and not fully paid; overdue: unpaid and past its due dateDefault: "any" |
customerOptional | string | a customer's name or id |
fromOptional | string | invoice date on or after, yyyy-mm-dd |
toOptional | string | invoice date on or before, yyyy-mm-dd |
searchOptional | string | words in the invoice number or reference |
limitOptional | integer | See 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 Tap invoice in full: customer, items, amount, due date, status and its payment page.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
invoiceRequired | string | See input schema below. |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"invoice": {
"type": "string",
"pattern": "^inv_\\w+$"
}
},
"required": [
"invoice"
]
}receivables_summaryRead only
Who owes what on Tap invoices and how late: unpaid invoices from the last year totalled by age 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_customersRead only
Customers saved in Tap, optionally matching words in their name or email.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
searchOptional | string | See input schema below. |
limitOptional | integer | See input schema below.Default: 30 |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"search": {
"type": "string"
},
"limit": {
"default": 30,
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}list_payoutsRead only
Payouts from Tap to the bank, newest first, from the last 90 days unless dates are given.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
fromOptional | string | invoice date on or after, yyyy-mm-dd |
toOptional | string | invoice date on or before, yyyy-mm-dd |
limitOptional | integer | See input schema below.Default: 20 |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"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": 20,
"type": "integer",
"minimum": 1,
"maximum": 50
}
}
}create_draft_invoiceRead and write
Save a draft Tap invoice for a customer. Nothing is sent and the customer can't pay it yet: someone sends it first.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
customerRequired | string | the customer's Tap id (cus_…) or email |
customer_nameOptional | string | needed with an email: the customer's name |
phoneOptional | string | the customer's mobile, for SMS |
linesRequired | object[] | See input schema below. |
currencyRequired | string | See input schema below. |
due_dateOptional | string | when it's due, yyyy-mm-dd; default in 14 days |
referenceOptional | string | your invoice number or order reference |
descriptionOptional | string | See input schema below. |
noteOptional | string | shown at the foot of 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 Tap id (cus_…) or email"
},
"customer_name": {
"description": "needed with an email: the customer's name",
"type": "string",
"maxLength": 100
},
"phone": {
"description": "the customer's mobile, for SMS",
"type": "string",
"pattern": "^\\+\\d{6,15}$"
},
"lines": {
"minItems": 1,
"maxItems": 50,
"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}$"
},
"due_date": {
"description": "when it's due, yyyy-mm-dd; default in 14 days",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"reference": {
"description": "your invoice number or order reference",
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
},
"note": {
"description": "shown at the foot of the invoice",
"type": "string",
"maxLength": 1000
}
},
"required": [
"customer",
"lines",
"currency"
]
}send_invoiceRead and write
Send a draft Tap invoice to the customer by email (and SMS if it has a mobile), so they can pay it on Tap's page.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
invoiceRequired | string | See input schema below. |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"invoice": {
"type": "string",
"pattern": "^inv_\\w+$"
}
},
"required": [
"invoice"
]
}create_payment_linkRead and write
Make a payment link: a Tap invoice page for the customer to pay, without Tap notifying anyone. Share the address yourself.
Approval: Uses your workspace and hire approval settings.
| Argument | Type | Details |
|---|---|---|
customerRequired | string | the customer's Tap id (cus_…) or email |
customer_nameOptional | string | needed with an email: the customer's name |
phoneOptional | string | the customer's mobile, for SMS |
linesRequired | object[] | See input schema below. |
currencyRequired | string | See input schema below. |
expires_in_daysOptional | integer | See input schema below.Default: 30 |
referenceOptional | string | See input schema below. |
descriptionOptional | string | See input schema below. |
Full input schema (JSON)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"customer": {
"type": "string",
"minLength": 1,
"description": "the customer's Tap id (cus_…) or email"
},
"customer_name": {
"description": "needed with an email: the customer's name",
"type": "string",
"maxLength": 100
},
"phone": {
"description": "the customer's mobile, for SMS",
"type": "string",
"pattern": "^\\+\\d{6,15}$"
},
"lines": {
"minItems": 1,
"maxItems": 50,
"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}$"
},
"expires_in_days": {
"default": 30,
"type": "integer",
"minimum": 1,
"maximum": 365
},
"reference": {
"type": "string",
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 500
}
},
"required": [
"customer",
"lines",
"currency"
]
}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.
- No incoming webhook handler is declared for this integration.
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.
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.
Telr
Let hires check Telr invoices and orders, see card payments, send invoices and make payment links, and refund a payment once a person approves.