Connect Alternative Payments
Alternative Payments is a payments and accounts-receivable platform built for MSPs. You create customers and invoices in it (or sync them from your PSA or accounting system), your customers pay by…
Written By Christopher Scaminaci
Last updated About 4 hours ago
Alternative Payments is a payments and accounts-receivable platform built for MSPs. You create customers and invoices in it (or sync them from your PSA or accounting system), your customers pay by card or ACH through hosted pages or Autopay, and Alternative Payments pays the money out to you.
Connecting Alternative Payments to StackJack gives your AI assistant a family of altpay_ MCP tools. MCP
(Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack.
With them, your AI can:
- Look up customers - companies, their portal users and the payment methods they have saved
- Follow the money - invoices and their status, payments, refunds, and the payouts that settle to your bank, with each payout's transactions
- Collect (on Pro plans) - create invoices, charge a customer's saved card or bank account, send a hosted payment link, and refund a payment
- Keep the books in step - attach the original PDF to an invoice synced from your accounting system, and read or manage your webhook subscriptions and the events behind them
- Run a hosted checkout - the payer-side calls a checkout page makes, driven for you with a one-hour token that StackJack mints and never shows
- Analyze receivables and cash - aging, collection rates, fees, payout reconciliation and more, computed from your own payment data (Pro; the tools say how much data they read and answer with nothing rather than a guess when the data does not support a number)
How StackJack authenticates to Alternative Payments
Alternative Payments does not use a sign-in screen for integrations. You generate an API key in the Partner Dashboard, which gives you a Client ID and a Client Secret. StackJack exchanges the pair with Alternative Payments for an access token that lasts an hour, sends that token on every call and renews it by itself. You never see the token.
The connection belongs to your organization in StackJack, not to one person, and one key serves your whole team.
Production and Demo are separate
Alternative Payments runs a Production service and a Demo service. They are separate worlds: a key generated in one does not work in the other, and an ID from one does not exist in the other. When you connect, you choose which one the key belongs to. A Demo connection is a safe place to try StackJack without touching real money.
Getting a Client ID and Client Secret
- Sign in to the Alternative Payments Partner Dashboard (the Demo dashboard if you want a Demo key).
- Go to Team Preferences, then API Keys, and click Generate API Key.
- Name it "StackJack" so you can recognize it later.
- Choose its scopes, as described below.
- Copy the Client ID and the Client Secret and keep them safe.
The scopes you choose decide what the key can do
An API key's scopes are fixed when it is generated and cannot be changed afterwards. For read-only use and for every financial analysis tool, tick read on Customers, Invoices, Payments, Payouts, Refunds and Webhooks. Add write scopes only for what you want your AI to do:
- Invoices write to create, archive and restore invoices and to attach PDFs
- Payments write to charge saved methods, add or remove payment methods and create payment requests
- Refunds write to refund
- Customers write to create, change, archive and restore customers and their portal users
- Webhooks write to manage subscriptions
- Checkout write for the hosted-checkout tools
Select all gives full access. A key that lacks a scope still connects; a tool that needs the missing scope answers with a refusal that names the scope to add, and you fix it by generating a new key with the scope ticked. Nothing about the key itself is wrong in that case.
Connect it in StackJack
- Open the Connectors page and choose Alternative Payments.
- Choose the Environment: Production, or Demo for a Demo key.
- Paste the Client ID and the Client Secret.
- Save, then use Test Connection.
Enter the Client ID and Client Secret together each time you save. StackJack stores them encrypted and never shows them again. If you ever need to move a connection between Production and Demo, enter the key for the new environment, because keys do not cross.
What is worth knowing before you start
Charges and refunds move real money, and need an idempotency key
Charging a customer, refunding a payment and paying an invoice through the checkout lane are the three calls that move money. Each one needs an idempotency key: a UUID that you make once per intended charge and reuse unchanged if you retry. Alternative Payments uses it so that a retry can never charge the same payment twice. StackJack never retries a charge or a refund by itself, so if a call times out, your AI looks the payment up first and, if it must retry, sends the same key again.
Charges, refunds, new invoices, archiving an invoice, restoring an invoice, archiving a customer and every change to a saved payment method are marked destructive, so your AI prompts for approval before running them.
Amounts are US dollars, with two decimal places
Every amount is a US dollar figure with at most two decimal places, such as 49.99, never cents. StackJack refuses an amount with more precision rather than rounding it, and refuses a zero or negative amount before anything is sent. Invoices are issued in US dollars only.
Webhook events are the exception: the amounts inside a webhook payload are in cents, which is a different unit from the API. The tools that list webhook events say so.
"sub_total" means three different things
On an invoice, total is the face value and sub_total is what is still outstanding. On a
payment or a refund, total is the gross and sub_total is the net after fees. On a payout,
total is the gross and sub_total is the net after fees. The tool descriptions repeat this where it
matters.
Lists come back in pages, with no total
List tools return up to 100 rows at a time, and Alternative Payments does not say how many exist in all.
Each answer carries has_next_page and end_cursor; your AI passes the end_cursor back as after to get
the next page. StackJack caps a page at 100, a limit it chose because Alternative Payments documents none.
What the API does not tell you
Alternative Payments does not put the date an invoice was paid on the invoice, and it does not say which payment settled which invoice: a payment carries no invoice ID, although you can filter payments by invoice. Nothing about the tools hides this. Where a financial analysis tool needs a paid date it asks Alternative Payments for the payment behind each invoice, says that it sampled, and tells you how many invoices it could not match.
There are two other gaps worth knowing. A failed payment carries no reason, and there is no call that lists payment requests, so keep the ID a payment-request tool returned. Accounts Payable (vendors and bills) is mentioned in Alternative Payments' documentation but has no API calls yet, so StackJack has no Accounts Payable tools.
Cards cannot be typed in
Alternative Payments states that its Web SDK is the only supported way to collect card details: the card goes straight from the payer's browser to a secure vault, and your system only ever sees an encrypted token. So the card tools take that token and cannot take a card number. Bank accounts (ACH) can be saved directly, with the routing and account number, and those numbers go to Alternative Payments only: StackJack does not store or log them.
The hosted checkout tools make two requests per call
The thirteen altpay_checkout_ tools work on the payer's side of the API, using a one-hour token that is
specific to one customer and one invoice. StackJack mints that token for you on every call, uses it for that
one call and never returns it, which is why each of these tools takes a customer and an invoice. Your API key
needs the Checkout write scope for this. One tool, altpay_create_checkout_token, hands you the token
itself, for the rare case where you are building a checkout page of your own.
Attaching a PDF works only for synced invoices
Uploading the original PDF to an invoice (up to 10 MB, as base64 or as a public HTTPS link) works only for invoices that were synced from an accounting integration. An invoice created through StackJack or the API has no original document from your system, and Alternative Payments refuses the upload.
Webhook subscriptions
Your AI can create a subscription for any topic, including the Accounts Payable topics that Alternative Payments documents but does not yet list in its API schema. The shared secret you give is stored only by Alternative Payments, which shows its last four digits afterwards. Webhook subscriptions need an HTTPS address. Retrying failed webhooks resumes a paused delivery queue, so your endpoint may receive a burst of older events.
Plans and limits
Read tools are available on the Free tier. Everything that creates, changes, charges or deletes, and every financial analysis tool, is Pro. Business reaches the same tools as Pro and differs by monthly call quota.
Alternative Payments allows 5 requests per second per API key and answers 429 beyond that. StackJack paces its own requests below that limit and backs off when it is told to slow down.
See the generated Alternative Payments tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.
Financial analysis
The financial analysis tools (Pro) read your invoices, payments, refunds, payouts and customers and work out an answer for you. They do not pass Alternative Payments' own answer through: each one returns figures that StackJack computed, and it tells you what it computed from. Your API key needs read on the areas a tool reads (its description names them), and never a write scope.
How to read an analysis answer
- Coverage. Every answer has a
coverageblock that says, for each list it read, how many records it analyzed, how many pages that took and whether it stopped early. A list is read to the end. If a list is longer than the tool'smaxRecordslimit (5,000 by default, 10,000 at most), the answer saystruncatedand the totals are lower bounds. - No guess. An average, rate, score or ratio that has nothing to be calculated from is
null, never zero. A total of nothing is zero. - Units. Money is US dollars. Rates, shares and ratios are fractions (0.25 is 25 percent). Days are calendar days.
- Invoices. "Invoiced" is the face value of an invoice. "Owed" is what is still outstanding. Archived invoices are never counted, and an invoice in the undefined RECEIVED status is shown apart as a payment in progress. Only succeeded card and ACH payments count as money collected.
- Sampling. Alternative Payments does not say when an invoice was paid. Where a tool needs the paid date it looks
up the payment behind a sample of paid invoices, one request each, spread fairly across your customers, and the
answer says
sampled, how many it checked and how it found the date. Alternative Payments allows 5 requests per second, so a sample of 500 takes about two minutes; every default is far smaller. - Heuristics. Where a figure is an estimate (a forecast, a recovery, a pairing of a refund with an invoice, a recurring-revenue estimate) the tool says so and states the rule it used.
The analysis tools
Alternative Payments does not expose accounts payable, a history of balances, refund reasons, dispute evidence or a list of payment requests, so none of the tools can answer questions that depend on them.
Several Alternative Payments accounts
If you hold more than one Alternative Payments account, or you want a Demo connection beside Production, add one connection per account from the connector's card, name it after the account, and your AI names it on each call. Omit the name and the call runs on the default connection.
Troubleshooting
"Test Connection" fails straight after saving. Check the Environment first. A Demo key sent to Production, or a Production key sent to Demo, is refused exactly like a wrong secret. Then check that the Client ID and Client Secret are both pasted in full.
Alternative Payments did not accept the API key. The key may have been revoked, deleted or replaced. In the Partner Dashboard, open Team Preferences, then API Keys, and check it is still listed. A revoked key is gone for good, so generate a new one, then open the connector in StackJack and enter the new Client ID and Client Secret.
A tool answers that the key does not have the scope it needs. The key is fine. In the Partner Dashboard, generate a new key with the scope the message names ticked (or use Select all), then update the connector in StackJack with the new Client ID and Client Secret. A key's scopes cannot be edited.
A tool answers "not found" for something you can see in the dashboard. Check that the connector's Environment matches the dashboard you are looking at, and that you are passing the ID exactly as a list tool returned it.
A charge or a refund is refused with a message about a rule. Alternative Payments answers 422 when it understands the request but a rule forbids it: a payment method that cannot be charged, an invoice that is already paid, an archived customer, or a card that needs its security code registered first. The message names the rule, and nothing was charged or changed.
A tool answers that Alternative Payments is rate limiting StackJack. Wait a moment and try again, and narrow a large sweep to a shorter date range or one customer at a time.
Alternative Payments tools
altpay_ · 85 tools · Free 33 · Pro 52
Customers
Payment methods
Invoices
Payments
Refunds
Payouts
Webhooks
Account
Hosted checkout
Financial Analytics
Was this helpful?
More in Connector guides
Connect Acronis Cyber Protect CloudConnect Action1Connect AddigyConnect AlertOpsStill need help? Ask the team