Skip to content
Docs
Payments & banking

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.

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

With Telr connected, a hire can:

  • check an invoice or payment link (paid, not paid, cancelled or expired) and a website order,
  • list the last 48 hours of card payments, read one with its refunds, and find payments by cart or order ID or by the customer's email,
  • send an invoice, which Telr emails to the customer with a link to pay,
  • make a payment link that Telr doesn't send to anyone, for the hire to share,
  • refund a payment, only after a person approves that exact refund.

Hires never charge a card, void or capture a payment in Telr. Those stay with people.

1. Find your keys in Telr

Sign in to Telr's merchant administration (the form in Roster links there too). Telr gives each part of its service its own key. Only the first two are needed; each of the others adds what it's for.

WhatWhere in Telr's merchant administrationLets hires
Store IDshown on your store(always needed)
Payment page authentication keyIntegrations → Hosted Payment Pagecheck invoices and orders
Merchant ID and Service API keyIntegrations → Service API → Add new entry, with the transaction services ticked. Open the key to see your merchant IDsee payments
Invoicing remote passwordyour invoice configuration, under Remote: create a passwordsend invoices, make links
Remote API authentication keyask Telr's support to turn on the Remote API for your storerefund payments

If you limit the Service API key to some IP addresses, or when Telr asks which addresses will send refund requests, ask Roster's support for the addresses Roster calls from.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Telr and choose it.
  2. Fill in the Store ID, the Payment page authentication key, and any of the other keys.
  3. Mode: Live, or Test to try it first (invoices are made as test invoices and refunds as test refunds, so no money moves).
  4. Click Connect.

Roster checks the store ID and key with Telr before saving, and, with the Service API key, reads your recent payments to show which store it's connected to (in Live mode or Test mode). If Telr refuses them, Roster says so and saves nothing. Telr answers a wrong payment page key the same way it answers an unknown invoice, so a wrong one of those only shows when a hire first checks an invoice; Roster then says Telr refused the request.

Your keys are kept sealed. Hires never see them; they only give Telr references and amounts.

3. Give hires access

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

  • Read only: it can check invoices and orders and see payments. It can't change anything.
  • Read and write: it can also send invoices, make payment links and ask for refunds.

Telr has no draft invoices: an invoice a hire sends goes to the customer at once. A payment link is a Telr payment page nobody is told about: the hire shares the address, for example in an email or a WhatsApp message.

Refunds 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 and the amount; when the approver says yes, Roster checks the payment and what's already been refunded, then makes exactly that refund, once. A refund can't be more than what's left of the payment, or in another currency.

Watching payments

A hire's responsibility can watch Telr (with the Service API key): it's woken when a payment comes in, fails, or is refunded or voided, with the amount and the customer. Telr's list holds the last 30 payments, so on a very busy store a few could be missed between checks.

If something goes wrong

  • "E01:Invalid request" on an invoice: check the reference, like 1955/5041/031902.
  • "Telr returned 401" when reading payments: the merchant ID or Service API key is wrong, or the key isn't allowed from Roster's address.
  • No refund tool: refunds need both the Remote API key and the Service API key.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Telr 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.

Service credentials

This integration uses the service's own authentication scheme with the credentials in the connection fields below. Follow the connection guide for the exact keys and account permissions.

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

  • Service API: the transaction services (list, details, linked, search)

Connection fields

Telr connection fields
FieldWhat to provide
Store ID
storeId
Required		The number of your store in Telr.
Payment page authentication key
authKey
Required · sealed secret		In Telr's merchant administration: Integrations → Hosted Payment Page → Authentication key. Used to read invoice and order status.
Merchant ID (for payments)
merchantId
Optional		Shown when you open a key under Integrations → Service API. With the key below, hires can see payments.
Service API key (for payments)
apiKey
Optional · sealed secret		Integrations → Service API → Add new entry, with the transaction services ticked.
Invoicing remote password (for invoices and links)
invoicePassword
Optional · sealed secret		In Telr's invoice configuration, under Remote: the password for remote invoice requests.
Remote API authentication key (for refunds)
remoteKey
Optional · sealed secret		Telr gives it when it turns on the Remote API for your store. Refunds also need the payments key above.
Mode
mode
Optional		Use the value for your account or connection.

Choices: Live (live); Test (nothing is charged or refunded) (test).

Starts with: live.

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: 5 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.

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

get_invoiceRead only

A Telr invoice or payment link by its reference (like 1955/5041/031902): amount, who it was sent to, and whether it's paid, not paid, cancelled or expired, with the payment when paid.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
ArgumentTypeDetails
invoiceRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "pattern": "^[\\w/-]{3,40}$"
    }
  },
  "required": [
    "invoice"
  ]
}
get_orderRead only

A payment-page order from your website or shop by its order reference: amount, cart ID and Telr's status for it.

Approval: Uses your workspace and hire approval settings.

Arguments for get_order
ArgumentTypeDetails
orderRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "order": {
      "type": "string",
      "pattern": "^[A-Za-z0-9]{8,128}$"
    }
  },
  "required": [
    "order"
  ]
}
list_recent_paymentsRead only

Card payments, refunds and voids through Telr in the last 48 hours (Telr's limit: at most 30), newest first, with the customer and Telr's answer.

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": {}
}
get_paymentRead only

One Telr transaction by its 12-digit reference, with everything linked to it (the sale, its refunds and voids) and when it was paid out.

Approval: Uses your workspace and hire approval settings.

Arguments for get_payment
ArgumentTypeDetails
transactionRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "transaction": {
      "type": "string",
      "pattern": "^\\d{12}$"
    }
  },
  "required": [
    "transaction"
  ]
}
find_paymentsRead only

Telr transactions for a cart or order ID (your shop's or an invoice's), or for a customer's email address. At most 30.

Approval: Uses your workspace and hire approval settings.

Arguments for find_payments
ArgumentTypeDetails
cartOptionalstringthe cart or order ID
emailOptionalstringthe customer's email address
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "cart": {
      "description": "the cart or order ID",
      "type": "string",
      "minLength": 1,
      "maxLength": 63
    },
    "email": {
      "description": "the customer's email address",
      "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,}$"
    }
  }
}
send_invoiceRead and write

Make a Telr invoice with its lines and have Telr email it to the customer, with a link to pay it on Telr's page. Telr has no drafts: it goes out at once.

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
emailRequiredstringthe customer's email address
nameRequiredstringthe customer's name, or their company's
countryOptionalstringthe customer's country, like AE
titleRequiredstringthe invoice's title, like Invoice INV-104
linesRequiredobject[]See input schema below.
currencyRequiredstringSee input schema below.
noteOptionalstringa note at the foot of the invoice
referenceOptionalstringyour invoice number, kept with it in Telr
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "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": "the customer's email address"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the customer's name, or their company's"
    },
    "country": {
      "description": "the customer's country, like AE",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the invoice's title, like Invoice INV-104"
    },
    "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}$"
    },
    "note": {
      "description": "a note at the foot of the invoice",
      "type": "string",
      "maxLength": 500
    },
    "reference": {
      "description": "your invoice number, kept with it in Telr",
      "type": "string",
      "maxLength": 63
    }
  },
  "required": [
    "email",
    "name",
    "title",
    "lines",
    "currency"
  ]
}
create_payment_linkRead and write

Make a payment link: a Telr payment page for one amount that Telr doesn't email to anyone. Share the address yourself.

Approval: Uses your workspace and hire approval settings.

Arguments for create_payment_link
ArgumentTypeDetails
emailRequiredstringthe customer's email address
nameRequiredstringthe customer's name, or their company's
countryOptionalstringthe customer's country, like AE
amountRequirednumberhow much, e.g. 1250.50
currencyRequiredstringSee input schema below.
descriptionRequiredstringwhat it's for, shown on the page
referenceOptionalstringyour invoice or order number
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "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": "the customer's email address"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "the customer's name, or their company's"
    },
    "country": {
      "description": "the customer's country, like AE",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "how much, e.g. 1250.50"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "what it's for, shown on the page"
    },
    "reference": {
      "description": "your invoice or order number",
      "type": "string",
      "maxLength": 63
    }
  },
  "required": [
    "email",
    "name",
    "amount",
    "currency",
    "description"
  ]
}
refund_paymentRead and writeApproval required · locked

Refund a Telr card payment to the customer, 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
transactionRequiredstringSee input schema below.
amountOptionalnumberhow much to refund, e.g. 120.50
currencyOptionalstringthe payment's currency, e.g. AED; needed with amount
noteOptionalstringwhy, kept on the refund in Telr
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "transaction": {
      "type": "string",
      "pattern": "^\\d{12}$"
    },
    "amount": {
      "description": "how much to refund, e.g. 120.50",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "description": "the payment's currency, e.g. AED; needed with amount",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "note": {
      "description": "why, kept on the refund in Telr",
      "type": "string",
      "maxLength": 63
    }
  },
  "required": [
    "transaction"
  ]
}

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.

Service documentation · Integration source reference

Tap Payments

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

Wise Business

Let hires check balances, read statements and activity, and match incoming payments to invoices in Wise Business. Read only.

On this page

1. Find your keys in Telr2. Connect it in Roster3. Give hires accessRefunds wait for approvalIf something goes wrongTools and permissions reference