Skip to content
Docs
Payments & banking

Checkout.com

Let hires check payments, look into disputes before evidence is due, make payment links, and ask before any refund.

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

With Checkout.com connected, a hire can:

  • read a payment in full: amount, status, the card (scheme and last four digits), what's been captured and refunded, and every step Checkout.com took on it,
  • find payments by your reference (an order or invoice number), or search them by status, the customer's email or name, amount, currency or card's last four digits,
  • list disputes (chargebacks) and read one: why it was raised, its status, when evidence is due and which evidence would help,
  • read a payment link and see whether it was paid,
  • make a payment link for a customer to pay, and share it themselves,
  • refund a payment, in full or in part, only after a person approves it.

Hires never charge a card, capture, void or pay out in Checkout.com. Those stay with people.

1. Make a secret key in Checkout.com

  1. Sign in to the Checkout.com Dashboard (for the sandbox, dashboard.sandbox.checkout.com). The form in Roster links there too.
  2. Open Developers → Keys and click Create a new key. Choose Secret API key and describe it as Roster.
  3. Under scopes, choose Customize and tick only what hires need:
    • gateway:payment-details, to read payments,
    • payments:search, to search payments,
    • disputes:view, to read disputes,
    • payment links, to make them,
    • gateway:payment-refunds, only if hires may ask for refunds.
  4. Click Submit and copy the key (it starts with sk_, or sk_sbox_ in the sandbox). It's shown only once.
  5. Note your account prefix: under Settings → Account structure, your client ID is shown as cli_ followed by letters and digits. The prefix is the first 8 after cli_. Live and sandbox have different ones.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Checkout.com and choose it.
  2. Secret API key: paste the key.
  3. Environment: Live, or Sandbox to try it first with test payments.
  4. Account prefix: the 8 characters from step 1.
  5. Optionally:
    • Processing channel: needed for payment links if your key may use more than one channel (pc_…, from the Dashboard).
    • Name on payment pages: your business's name, shown to customers.
    • Customers' usual country: Checkout.com needs a billing country on every payment link, like AE. Hires use this one unless they give another.
  6. Click Connect.

Roster checks the key by looking up a payment, and the connection shows Connected with the environment and your account's address. Checkout.com doesn't tell Roster your account's name. If Checkout.com refuses the key or the prefix, Roster says so and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on Checkout.com:

  • Read only: it can read and search payments, disputes and payment links. It can't change anything.
  • Read and write: it can also make payment links and ask for refunds.

Amounts are given as you'd write them (120.50 AED, 12.345 KWD); Roster converts them for Checkout.com.

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, the amount and why; when the approver says yes, Roster makes exactly that refund, once. Before refunding, Roster reads the payment again and refunds only what's still left, and it never refunds in another currency.

Watching disputes

A hire's responsibility can watch Checkout.com: it's woken when a dispute arrives or changes, with the amount, the reason and when evidence is due. Checking costs nothing when nothing happened.

If something goes wrong

  • "base_url_invalid": the account prefix is wrong, or it's the live prefix with Sandbox chosen (or the other way round). Fix it on the connection.
  • "Didn't accept the connection's credential": the key was deleted, or it's a sandbox key used with Live.
  • Search refused: the key lacks the payments:search scope. Finding payments by reference still works.
  • A payment link isn't made: give the billing country, or set the processing channel on the connection.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Checkout.com 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 Checkout.com's Dashboard: Developers → Keys → Create a new key → Secret API key (sk_… or, in the sandbox, sk_sbox_…). Copy it when it's shown: it's only shown once.

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

  • gateway:payment-details (read payments)
  • payments:search (search payments)
  • disputes:view (read disputes)
  • Payment Links (to make payment links)
  • gateway:payment-refunds (only to allow refunds a person approves)

Connection fields

Checkout.com connection fields
FieldWhat to provide
Secret API key
token
Required · sealed secret		In Checkout.com's Dashboard: Developers → Keys → Create a new key → Secret API key (sk_… or, in the sandbox, sk_sbox_…). Copy it when it's shown: it's only shown once.
Environment
environment
Optional		Use the value for your account or connection.

Choices: Live (production) (production); Sandbox (test payments only) (sandbox).

Starts with: production.

Account prefix
prefix
Required		The first 8 characters of your client ID after cli_ (Dashboard → Settings → Account structure). Live and sandbox have different ones.
Processing channel (optional)
processingChannel
Optional		Needed for payment links if your key may use more than one processing channel.
Name on payment pages (optional)
displayName
Optional		Use the value for your account or connection.
Customers' usual country (optional)
country
Optional		Checkout.com needs a billing country on every payment link; hires use this one unless they give another.

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: 6 only read and 2 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_paymentRead only

One payment in full by its id (pay_…): amount, status, card or method, customer, what's been captured and refunded, and every action on it (authorisation, capture, refund…) with Checkout.com's answer.

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": "^(pay|sid)_\\w{26}$"
    }
  },
  "required": [
    "payment"
  ]
}
find_paymentsRead only

Payments with your reference (an order or invoice number), newest first: the quickest way to see whether an order was paid.

Approval: Uses your workspace and hire approval settings.

Arguments for find_payments
ArgumentTypeDetails
referenceRequiredstringSee input schema below.
limitOptionalintegerSee input schema below.Default: 20
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "reference"
  ]
}
search_paymentsRead only

Search payments, from the last 90 days unless dates are given: by status, the customer's email or name, your reference, currency, amount, or card's last four digits.

Approval: Uses your workspace and hire approval settings.

Arguments for search_payments
ArgumentTypeDetails
statusOptional"Authorized" | "Captured" | "Declined" | "Pending" | "Partially Captured" | "Partially Refunded" | "Refunded" | "Voided" | "Expired" | "Canceled" | "Disputed" | "Paid" | "Returned"See input schema below.
emailOptionalstringSee input schema below.
nameOptionalstringSee input schema below.
referenceOptionalstringSee input schema below.
currencyOptionalstringSee input schema below.
amountOptionalnumberthe exact amount, e.g. 120.50; needs currency
last4OptionalstringSee input schema below.
fromOptionalstringyyyy-mm-dd
toOptionalstringyyyy-mm-dd
limitOptionalintegerSee input schema below.Default: 25
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "Authorized",
        "Captured",
        "Declined",
        "Pending",
        "Partially Captured",
        "Partially Refunded",
        "Refunded",
        "Voided",
        "Expired",
        "Canceled",
        "Disputed",
        "Paid",
        "Returned"
      ]
    },
    "email": {
      "type": "string",
      "maxLength": 255
    },
    "name": {
      "type": "string",
      "maxLength": 100
    },
    "reference": {
      "type": "string",
      "maxLength": 80
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "amount": {
      "description": "the exact amount, e.g. 120.50; needs currency",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "last4": {
      "type": "string",
      "pattern": "^\\d{4}$"
    },
    "from": {
      "description": "yyyy-mm-dd",
      "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])))$"
    },
    "to": {
      "description": "yyyy-mm-dd",
      "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])))$"
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
list_disputesRead only

Disputes (chargebacks), most recently updated first: what's disputed, why, its status and when evidence is due. Optionally by status, one payment, or updated between dates.

Approval: Uses your workspace and hire approval settings.

Arguments for list_disputes
ArgumentTypeDetails
statusesOptional"evidence_required" | "evidence_under_review" | "resolved" | "won" | "lost" | "canceled" | "expired" | "accepted" | "arbitration_under_review" | "arbitration_won" | "arbitration_lost"[]See input schema below.
paymentOptionalstringSee input schema below.
fromOptionalstringupdated on or after, yyyy-mm-dd
toOptionalstringupdated 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": {
    "statuses": {
      "maxItems": 11,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "evidence_required",
          "evidence_under_review",
          "resolved",
          "won",
          "lost",
          "canceled",
          "expired",
          "accepted",
          "arbitration_under_review",
          "arbitration_won",
          "arbitration_lost"
        ]
      }
    },
    "payment": {
      "type": "string",
      "pattern": "^pay_\\w{26}$"
    },
    "from": {
      "description": "updated on or after, yyyy-mm-dd",
      "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])))$"
    },
    "to": {
      "description": "updated on or before, yyyy-mm-dd",
      "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])))$"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
get_disputeRead only

One dispute in full (dsp_…): the payment, category and reason, status, when evidence is due, and which evidence the card scheme would accept.

Approval: Uses your workspace and hire approval settings.

Arguments for get_dispute
ArgumentTypeDetails
disputeRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "dispute": {
      "type": "string",
      "pattern": "^dsp_\\w{22,26}$"
    }
  },
  "required": [
    "dispute"
  ]
}
get_payment_linkRead only

One payment link (pl_…): amount, whether it's been paid or expired, and the payment made through it.

Approval: Uses your workspace and hire approval settings.

Arguments for get_payment_link
ArgumentTypeDetails
linkRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "pattern": "^pl_[\\w-]{6,40}$"
    }
  },
  "required": [
    "link"
  ]
}
create_payment_linkRead and write

Make a payment link: a Checkout.com payment page for one amount that the customer chooses to pay. Nobody is notified: share the address yourself.

Approval: Uses your workspace and hire approval settings.

Arguments for create_payment_link
ArgumentTypeDetails
amountRequirednumbere.g. 1250.50
currencyRequiredstringSee input schema below.
descriptionOptionalstringshown on the page, e.g. Invoice INV-1042
referenceOptionalstringyour invoice or order number
customer_emailOptionalstringSee input schema below.
customer_nameOptionalstringSee input schema below.
countryOptionalstringthe customer's billing country; default the connection's
expires_in_daysOptionalintegerSee input schema below.Default: 14
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000,
      "description": "e.g. 1250.50"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "description": {
      "description": "shown on the page, e.g. Invoice INV-1042",
      "type": "string",
      "maxLength": 100
    },
    "reference": {
      "description": "your invoice or order number",
      "type": "string",
      "maxLength": 80
    },
    "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,}$"
    },
    "customer_name": {
      "type": "string",
      "maxLength": 100
    },
    "country": {
      "description": "the customer's billing country; default the connection's",
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "expires_in_days": {
      "default": 14,
      "type": "integer",
      "minimum": 1,
      "maximum": 60
    }
  },
  "required": [
    "amount",
    "currency"
  ]
}
refund_paymentRead and writeApproval required · locked

Refund a captured payment, 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. AED; needed with amount
noteOptionalstringwhy, kept on the refund in Checkout.com
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "payment": {
      "type": "string",
      "pattern": "^pay_\\w{26}$"
    },
    "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 Checkout.com",
      "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.
  • 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

Chargebee

Subscriptions, invoices and customers in Chargebee.

Lemon Squeezy

Orders, subscriptions, customers and license keys.

On this page

1. Make a secret key in Checkout.com2. Connect it in Roster3. Give hires accessRefunds wait for approvalIf something goes wrongTools and permissions reference