PayTabs

Let hires look up PayTabs payments and invoices, make invoice links and payment pages for customers to pay, and refund once a person approves.

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

With PayTabs connected, a hire can:

look up a payment by its transaction reference, or every try for an order by its cart reference, with PayTabs' reason when one was declined,
read an invoice: whether it's pending, paid, overdue, expired or cancelled, its items, and the payment that paid it,
make an invoice with a link for the customer to pay, and have PayTabs email or text it, or not,
text a pending invoice's link to the customer,
make a payment page for a customer who is paying right now,
refund a payment, in full or in part, and cancel a pending invoice, each only once a person approves.

Hires never capture, void or charge a saved card in PayTabs. Those stay with people: a hire asks for an approval with the details, and someone does it in PayTabs.

1. Find your keys in PayTabs

Sign in to PayTabs' merchant dashboard and open Developers → Key management.
Copy the server key (not the client key) and note your profile ID.
Note which region your account is in: Saudi Arabia, the UAE, Egypt, Oman, Jordan, Kuwait, Iraq, Morocco, Qatar or Global. A key only works at its own region's address.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for PayTabs and choose it.
Paste the Server key, enter the Profile ID and choose the Region.
Click Connect.

Roster checks the key by asking PayTabs about a payment that can't exist in the region you chose, and the connection shows Connected with your profile ID and region. PayTabs doesn't tell Roster your account's name. If PayTabs refuses the key, Roster says so and saves nothing.

3. Give hires access

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

Read only: it can look up payments and read invoices. It can't change anything.
Read and write: it can also make invoices and payment pages, text invoices, and ask to refund payments and cancel invoices.

An invoice made with notify left at none isn't sent to anyone: the hire shares the link itself, for example in an email or a WhatsApp message. With email or sms, PayTabs sends it to the customer.

A payment page lasts only 20 minutes, so hires use it when a customer is paying there and then; for anything later they make an invoice.

Hires see a customer's name and email on payments, never their address, phone number or IP address.

Refunds and cancelling wait for approval

A refund always waits for a person's approval, and nobody can turn that off. The hire asks in the thread with the payment, the amount and why; when the approver says yes, Roster makes exactly that refund, once. Before refunding, Roster reads the payment again and everything already refunded on its order, and refunds only what's still left, so a payment can't be refunded twice. Only payments that went through can be refunded.

A cancelled invoice can't be paid or reopened, so cancelling waits for approval the same way. Only pending invoices can be cancelled.

If something goes wrong

"Authentication failed": check the server key, and that the region matches your account.
A payment not found: transaction references look like TST2234701408123; test and live payments are separate, so check the key is the live one.
Hires aren't told when a customer pays: PayTabs can't list payments, so there's nothing to watch yet. Ask a hire to check an invoice or order when you need to know.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect PayTabs 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 PayTabs' dashboard: Developers → Key management → the server key of the profile.

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

A server key of type API, for transactions and invoices

Connection fields

PayTabs connection fields
Field	What to provide
Server key `token` Required · sealed secret	In PayTabs' dashboard: Developers → Key management → the server key of the profile.
Region `region` Optional	Where your PayTabs account is. A key only works at its own region's address. Choices: Saudi Arabia (sau); United Arab Emirates (are); Egypt (egy); Oman (omn); Jordan (jor); Kuwait (kwt); Iraq (irq); Morocco (mar); Qatar (qat); Global (global). Starts with: `are`.
Profile ID `profileId` Required	In PayTabs' dashboard: Developers → Key management, or your profile's details.

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

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

Find an actionAccess

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

get_transactionRead only

One PayTabs payment (or refund, void…) by its transaction reference: amount, whether it went through and PayTabs' reason if not, the customer, card type and cart reference.

Approval: Uses your workspace and hire approval settings.

Arguments for get_transaction
Argument	Type	Details
`tran_ref`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tran_ref": {
      "type": "string",
      "pattern": "^[A-Z0-9]{6,32}$"
    }
  },
  "required": [
    "tran_ref"
  ]
}

find_transactionsRead only

Every PayTabs transaction for one cart or order reference (cart_id), newest first: tries that failed, the one that went through, and any refunds.

Approval: Uses your workspace and hire approval settings.

Arguments for find_transactions
Argument	Type	Details
`cart_id`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "cart_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  },
  "required": [
    "cart_id"
  ]
}

get_invoiceRead only

One PayTabs invoice: its status (pending, paid, overdue, expired or cancelled), amount, dates, items, and the transaction that paid it.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
Argument	Type	Details
`invoice`Required	integer	the PayTabs invoice number, like 2072841

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the PayTabs invoice number, like 2072841"
    }
  },
  "required": [
    "invoice"
  ]
}

create_invoiceRead and write

Make a PayTabs invoice: a page the customer pays on, with its link to share. PayTabs emails it to the customer only if notify is email (or texts it with sms); with none, nobody is notified and you share the link.

Approval: Uses your workspace and hire approval settings.

Arguments for create_invoice
Argument	Type	Details
`customer_name`Required	string	the customer's or company's name
`customer_email`Required	string	where the customer gets the invoice
`lines`Required	object[]	See input schema below.
`currency`Required	string	See input schema below.
`due_date`Optional	string	when it's due, yyyy-mm-dd; default in 14 days
`expires_in_days`Optional	integer	how long the link can be paid, counted from the due dateDefault: `30`
`cart_id`Optional	string	your order or invoice reference, unique to this payment; made up if left out
`description`Required	string	what it's for, shown on the page
`notify`Optional	"none" \| "email" \| "sms"	See input schema below.Default: `"none"`
`phone`Optional	string	the customer's mobile, needed for sms

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the customer's or company's name"
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "where the customer gets the invoice"
    },
    "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",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "expires_in_days": {
      "default": 30,
      "description": "how long the link can be paid, counted from the due date",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    },
    "cart_id": {
      "description": "your order or invoice reference, unique to this payment; made up if left out",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "what it's for, shown on the page"
    },
    "notify": {
      "default": "none",
      "type": "string",
      "enum": [
        "none",
        "email",
        "sms"
      ]
    },
    "phone": {
      "description": "the customer's mobile, needed for sms",
      "type": "string",
      "pattern": "^\\+\\d{6,15}$"
    }
  },
  "required": [
    "customer_name",
    "customer_email",
    "lines",
    "currency",
    "description"
  ]
}

text_invoiceRead and write

Have PayTabs text a pending invoice's link to the customer's mobile.

Approval: Uses your workspace and hire approval settings.

Arguments for text_invoice
Argument	Type	Details
`invoice`Required	integer	the PayTabs invoice number, like 2072841
`phone`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the PayTabs invoice number, like 2072841"
    },
    "phone": {
      "type": "string",
      "pattern": "^\\+\\d{6,15}$"
    }
  },
  "required": [
    "invoice",
    "phone"
  ]
}

refund_paymentRead and writeApproval required · locked

Refund a PayTabs payment to the customer's card, 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
Argument	Type	Details
`tran_ref`Required	string	the reference of the sale or capture to refund
`amount`Optional	number	how much to refund, e.g. 120.50
`currency`Optional	string	the payment's currency, e.g. SAR; needed with amount
`note`Optional	string	why, kept on the refund in PayTabs

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "tran_ref": {
      "type": "string",
      "pattern": "^[A-Z0-9]{6,32}$",
      "description": "the reference of the sale or capture to refund"
    },
    "amount": {
      "description": "how much to refund, e.g. 120.50",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "description": "the payment's currency, e.g. SAR; needed with amount",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "note": {
      "description": "why, kept on the refund in PayTabs",
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "tran_ref"
  ]
}

cancel_invoiceRead and writeApproval required · locked

Cancel a pending PayTabs invoice so it can no longer be paid. PayTabs can't reopen it, so it always waits for a person's approval: Roster asks in the thread and cancels exactly this invoice, once, when they approve.

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

Arguments for cancel_invoice
Argument	Type	Details
`invoice`Required	integer	the PayTabs invoice number, like 2072841
`reason`Required	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "the PayTabs invoice number, like 2072841"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    }
  },
  "required": [
    "invoice",
    "reason"
  ]
}

create_payment_pageRead and write

Make a PayTabs payment page for a customer who is paying right now (on a call or in a chat): it expires 20 minutes after it's made. For anything later, use create_invoice.

Approval: Uses your workspace and hire approval settings.

Arguments for create_payment_page
Argument	Type	Details
`customer_name`Required	string	the customer's or company's name
`customer_email`Required	string	where the customer gets the invoice
`amount`Required	number	See input schema below.
`currency`Required	string	See input schema below.
`description`Required	string	what it's for, shown on the page
`cart_id`Optional	string	your order or invoice reference, unique to this payment; made up if left out

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the customer's or company's name"
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "where the customer gets the invoice"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "what it's for, shown on the page"
    },
    "cart_id": {
      "description": "your order or invoice reference, unique to this payment; made up if left out",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  },
  "required": [
    "customer_name",
    "customer_email",
    "amount",
    "currency",
    "description"
  ]
}

Watches and incoming events

No built-in watch is declared. Give a hire a scheduled responsibility if it should check this service regularly.
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.

Service documentation · Integration source reference

1. Find your keys in PayTabsCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

Refunds and cancelling wait for approvalCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

API key or access token

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Find your keys in PayTabs

2. Connect it in Roster

3. Give hires access

Refunds and cancelling wait for approval

If something goes wrong