How Payshen works

Getting started

From an empty workspace to a payment you can see end to end.

A new workspace starts empty: no sample providers and no made-up payments. Until your first payments arrive, Home shows what each figure will be and what unlocks it. Get live, in the console, walks you through three phases: connect a provider, send a test payment, go live. It ticks each step off on its own when Payshen sees it happen. Business details and documents are only needed for a provider that reviews you; your own account needs neither.

1. 1.Connect a provider you already have, or find one in the Marketplace. Add at least two, so routing has somewhere to fail over to.
2. 2.Routing works with no rules: payments try your providers in the order you added them. Add a rule when you want one provider, your own order, or Smart routing.
3. 3.Create a test API key under Developers and send a payment.
4. 4.Open the payment and read its timeline - which providers were tried, and why the winner won.
5. 5.Add a webhook endpoint so your own systems hear about payments without polling.
6. 6.Invite your team with the role each person actually needs.

Sign-in is passwordless. You receive a single-use link that expires in 15 minutes; there is no password to lose or reuse.

Choosing a reporting period

Why a screen can be empty while your payments are clearly there.

Home, Analytics and Insights report over the same periods: today, 7 days, 30 days, 90 days, or a custom from/to range. The default is 30 days. Test or live payments follow the switch in the top bar.

If a screen is empty while Payments is full, the period is almost always the reason - the payments are older than the period you have selected. The screen says so, tells you how many payments the workspace holds and when the most recent one landed, and offers a link to the 90 days up to it.

Periods never widen by themselves. Approval rates and trends stop meaning anything when stretched over a period nobody chose, so the product would rather show you an empty screen with an explanation than a number you cannot interpret.

Reporting currency and converted figures

What ≈ means, where the rates come from, and what is left out.

Each workspace has one reporting currency, chosen at sign-up and changeable in Settings. When a total adds up payments in more than one currency, it is shown in the reporting currency with ≈ in front. The sign means the figure is converted for reporting: close, but not what any provider charged or paid out. The original amounts are listed under it, and the currency switcher shows any one currency on its own, exactly.

Your money is never converted. Payments, refunds, settlements, disputes and invoices keep the currency they were made in, and nothing stored is changed. Conversion happens only when a report is drawn, so the rate your provider applied is the one on your settlement file, not this one.

Where the rates come from. Each payment is converted at the rate for the day it was made. For 29 currencies that is the European Central Bank euro reference rate, published around 16:00 Central European Time on business days and stored once a day after that. For AED, BAM, BHD, JOD, OMR, QAR, SAR, XAF, XOF, which are fixed to the dollar or the euro by their central bank, it is that official fixed rate applied to the same day's dollar or euro rate. For Serbian dinar (RSD), which the European Central Bank does not publish, it is the daily rate from ExchangeRate-API, a commercial rate service, read once a day with the others. It is not the official middle rate of the National Bank of Serbia, so a dinar figure can differ slightly from one worked out at the NBS rate. Two currencies other than the euro meet through the euro.

Rates By Exchange Rate API. Dinar conversions use the ExchangeRate-API open access rates, which ask for this credit.

Weekends and holidays. A day with no published rate uses the last one before it, going back at most 6 days. A payment made today, before the day's rate is out, uses the last published rate, and the figure says the latest days are provisional until the new rate arrives. A past figure does not move: once a day's rate is stored it is never changed.

“Not converted”. When there is no rate for a currency on a day - a currency neither source covers, or no published rate within 6 days - that money is not guessed. It is listed separately as not converted and left out of the ≈ total, and the note says so. Dinar money from before the first stored dinar rate is not converted either, because that rate service gives no history. RSD can be chosen as a reporting currency while its daily rate is arriving.

A total in one currency, with nothing to convert, carries no ≈ and is exact. Percentages and counts are never converted.

Providers and connections

Bringing your own provider accounts, and what we do with the credentials.

Payshen is bring-your-own-provider. You keep your own contracts, pricing and settlement; we route traffic across the accounts you already hold. Money never passes through us.

A connection holds the provider's API credentials and your rate card. Credentials are encrypted before they reach the database and are never shown again after you save them - if you lose one, replace it rather than trying to read it back.

For providers whose API allows it (Stripe, Checkout.com, PayPal and Revolut today), you paste only the key. When the connection is tested, Payshen sets up the provider's webhook with that key and keeps its signing secret or ID, so there is nothing to create in the provider's dashboard. If the provider refuses, the connection's Callbacks section says why, and payments are still confirmed by asking the provider.

A connection also declares what it is approved for: methods, currencies, countries. Routing only ever considers connections that can actually take the payment in front of them.

To try one provider without touching your routing, open its row's menu on Providers and choose Send test payment (test connections only). You pay on the provider's own page with its test card and come back to a checklist: created, paid, the provider's callback verified, then capture, cancel and refund, each confirmed by the provider. If a callback is refused, the checklist says why and links to the field to fix.

Test and Live

Two separate modes, each with its own providers, keys, webhooks and routing.

The switch at the top of the console moves between Test and Live. They are kept apart the way a Stripe account keeps its test and live modes: each has its own provider connections, API keys, webhook endpoints and routing, and every page shows the mode you are in. Test payments never reach a live account.

Set a provider up in Test first, with its test keys, and send test payments through it. To take real payments, switch to Live and choose Go live with that provider on Providers: it adds a live connection for the same provider, you paste its live keys, and Payshen tests it and switches it on. The test connection stays as it was. A connection never changes mode: a live key pasted into a test connection is refused.

Test outcomes never train live routing and never trip a provider's circuit breaker, so a week of integration testing cannot change where your real money goes. They teach Test mode's routing of its own instead, so you can watch Smart routing learn before you go live.

Routing works the same way. Until you set test routing up, test payments follow your live rules on your test connections. Set up test routing starts from your live rules with each connection swapped for its test one, and Copy test routing to live does the reverse; both make a draft you review and publish.

Routing and failover

Deciding where each payment goes, and what happens when one is declined.

Rules are evaluated in order, and each rule can match on country, currency, amount and payment method. Each rule has one switch, Smart routing. With it off, the rule sends payments one of three ways:

• Always this provider - one connection, nothing else is tried, which is sometimes exactly what a contract requires.
• Try in order - this order, moving to the next after a soft decline or a technical error before anything was executed.
• Backup only on technical errors - the first provider, and the next only after a technical error. An ordinary decline is not retried.

With it on, Payshen picks the provider for each payment, learning from your own outcomes, and you choose what to optimize for: most approvals, lowest fees, a balance of both, the fastest, or let Payshen decide. Opt-in: only a rule you turn it on for uses it.

A payment no rule matches follows the default order: your connections in the order you added them, oldest first, with the same retries as Try in order. It is predictable on purpose - nothing chooses a provider for you by learning until you ask it to. The routing page shows the default order, and every payment says which rule, or the default order, decided it.

Under smart routing Payshen optimises for approval and cost together, per country, currency, method and amount band, and keeps learning from every live payment. A provider that suddenly approves far less loses its traffic within a few dozen payments, and a new provider gets a fair trial even after an unlucky start. A provider that starts failing is pulled out of rotation automatically and re-tested after a cooldown, so one provider having a bad hour does not become your bad hour.

Not every decline is worth retrying. "Insufficient funds" will fail on every provider, so retrying it just costs money. A soft decline, or a technical error before anything was executed, is worth another attempt. A timeout or an unknown result never is: the first provider may have charged, so the payment is marked unknown and nobody else is tried. The product makes that distinction for you and shows it on the payment.

Rule changes are published, not applied instantly. You edit a draft and publish it when it is right, so a half-finished rule never routes a real payment. You can roll back to an earlier version.

Testing a routing change

Try another order, or smart routing, on a share of a rule's payments before you commit to it.

From the menu on any live rule, choose Test another route. The test route is another order of providers, another way to send payments, or smart routing with what it should optimize for. It routes a share of the payments that rule matches, from 5% to 50%, and the rest keep the current routing, so both are measured on the same customers at the same time. A test starts only when you press Start test, and one on live payments also asks you to confirm that it routes real customers' payments.

The same card, order reference or retried request always lands on the same side, so a customer who tries again after a decline is not moved to the other provider halfway through. A payment the test route cannot send at all goes the usual way and is counted on neither side.

The result page compares approval, approval on the first attempt, the average fee, how quickly the provider answered and how often a second attempt was needed, and says how many more or fewer payments the test route approved. It names a winner only once each side has 100 payments that reached an answer and the difference in what you keep per payment is clear at 95% confidence; until then it says it is still collecting.

A safety limit stops a test by itself when the test route approves clearly fewer payments than your current routing, or has twice the technical errors. A test also ends when its time is up or when you publish a new version of the routing. You are emailed when it stops early. Stopping never changes the rule.

When the test route clearly earns more, Payshen makes it the rule on its own; you can also press Make it the rule yourself. Either way it publishes a new version of the routing with the test route on that rule and nothing else changed, and the previous version stays a rollback away.

Payments and the lifecycle

Authorize, capture, void, refund - and what each status means.

Create a payment and it is attempted immediately, unless you asked to authorize only. An authorization can be captured later, in full or in part, or voided if the sale falls through. A captured payment can be refunded, in full or in part.

Each payment carries its own timeline: every provider tried, what each answered, the raw provider code alongside our normalized category, and which attempt finally succeeded. When failover rescues a sale, the payment says so.

Amounts are always integers in the currency's minor unit, and the scale follows the currency - 5000 is 50.00 in euro but 5,000 in yen. The product handles this for you; it matters if you are reading the API or an export.

Disputes

Chargebacks, deadlines, and what is at stake.

A dispute is recorded against the payment it belongs to, with the provider's own reference, its status, and the date by which evidence must be submitted. Disputes arrive from the provider, so what you see is what they told us.

A decided dispute does not un-decide: a late message cannot reopen a case you have already won, because showing money at risk that is not at risk is worse than showing nothing.

Settlement and reconciliation

Checking that what each provider paid you matches what it reported.

Your providers pay you directly; Payshen never holds or moves money. Reconciliation compares each provider's settlement report with the payments, refunds and fees Payshen saw, so missing money or a wrong fee is caught. Until a provider settles, a payment's fee is the expected fee from your pricing; the report replaces it with the fee actually charged.

1. 1.Reports from providers that offer it are read automatically every day. For the others, download the settlement file and upload it as CSV - reference, amount, currency and fee; column order does not matter.
2. 2.Overview answers "is it all there?": what you captured, less refunds and fees, against what your providers' reports say they paid, per currency.
3. 3.Payouts shows each payout a provider made to you; open one to check it line by line.
4. 4.Issues lists every line that did not match, grouped by what went wrong and the most money first. Open one to see the provider's line beside the payment, match it or mark it explained.

A line becomes an issue when it matches no payment, when the amount disagrees, or when the fee is more than 10% away from what your pricing rules predicted. Payshen never holds or moves your money: it only compares the provider's report with the payments it routed. Uploading the same file twice is safe - lines are recognised and not counted again, so a fee is never doubled by a nervous second upload.

Rows the file format cannot express are reported back rather than skipped. A reconciliation that silently ignores what it did not understand is worse than one that refuses.

"Try with a demo report" builds a report from your own captured payments in the selected period. On a workspace with none, it says so instead of producing an empty file.

Insights and analytics

What to change next, and the numbers behind it.

Insights opens on Findings: one list of what is worth changing, most money at stake first - a provider approving less than another on the same traffic, declines nobody retried, fees above your pricing, refund or dispute trends, and the routing and pricing changes the engine proposes. Each row says what was found, what is at stake, the evidence it rests on, and one action; the menu beside it has the rest. Not now hides a finding for a week, Dismiss until the evidence changes, and Accept applies an engine finding the safe way: a test on a slice of payments, or a draft you confirm. Home, Routing and Providers show the findings that concern them, in the same rows.

A money figure is shown only when the data supports it, and then as a lower bound ("at least"). Where the data cannot say how much a change would earn, the card suggests a routing test to measure it instead of guessing.

Home keeps the short version: what needs you, approval rate, volume, money recovered by failover and approval by provider. Analytics has the detail behind it, on tabs - providers side by side, declines, countries and methods, 3-D Secure, refunds and disputes - each against the previous period, and every row opens the payments it counts.

Account review before live payments

Payshen reviews each account once before it takes live payments; test mode never waits.

Anyone can create a workspace and use test mode straight away. Before live keys and live payments work, Payshen reviews the account once: the legal name, country of registration and website on your business profile. Send it from Get live; you get an email with the answer.

If Payshen needs something more, Get live shows what, and you send the account again once it is added. This review is Payshen's own, for access to the platform: each payment provider still reviews you under its own rules, and only the provider decides whether it takes you on.

What Payshen charges

A monthly platform fee and a fixed price per production payment, invoiced monthly.

Settings, Billing shows your plan, the monthly platform fee, the price per payment, how many payments this month has counted so far and what they come to, your live providers and brands against what your plan includes, and every invoice Payshen has issued you with what is still open. A payment counts once, however many providers it was retried on; your contract says whether every production payment counts or only successful ones, and the page says which. Test payments never count.

Payshen invoices once a month and you pay by bank transfer. These are Payshen's own fees: your customers' payments are settled to you by your providers, and their fees are on Insights and Reconciliation, never mixed with what Payshen charges. A workspace set up by a partner is billed by that partner.

When going live is on hold

Why live keys or provider applications can wait for a review.

In a few countries, payment rules are changing or need a check before Payshen can serve a business registered there. If your company is registered in one of them, your workspace works in test mode as usual, but live keys, live connections and provider applications wait until Payshen has reviewed it. Get live shows the hold and the reason; you do not need to do anything.

A country Payshen cannot serve at all is refused when the business is set up, with the reason, rather than after you have done the work.

Marketplace and applications

Finding a provider, connecting it, and opening a new account.

Browse providers by industry, country, currency and payment method, then connect the account you already have in a few minutes. To open a new account, apply with the provider; where the provider takes applications through Payshen, you apply, share documents and see the decision in one place. Our own sandbox provider lets you walk the whole flow, with its review and decision simulated and labelled so.

Payshen never approves or rejects an application to a real provider. Only the provider decides, and the decision is recorded as theirs; the one exception is the sandbox provider above, which is ours and whose decisions are simulated. A capability match in the marketplace is a filter, never a promise of approval.

Document vault

Uploading company documents once and sharing them per application.

The vault holds the paperwork onboarding keeps asking for - incorporation certificates, UBO declarations, bank letters. PDF, PNG or JPEG up to 4 MB, organised into folders you create.

Every file is encrypted with its own key before it reaches storage, and downloads only ever happen through an authorised route - the storage URL is never exposed.

Uploading never exposes anything. A document becomes visible to a provider only when you attach it to a specific application, and you can revoke that share. Documents with an expiry date warn you 30 and 7 days before, so a licence does not lapse in the middle of an application.

Team and roles

Nine roles, enforced on the server rather than hidden in the interface.

Invite people with the role they need. Permissions are checked on the server on every request, so a role that cannot export cannot export by finding the URL.

• Owner - full organization control
• Org Admin - configuration, entities and users
• Payment Admin - PSP connections and routing
• Payment Ops - investigate transactions
• Finance - transactions, exports and billing
• Compliance - applications and documents
• Developer - API keys and webhooks
• Analyst - read-only reporting
• Viewer - restricted read-only

An invitation is bound to the address it was sent to and can be used once. Forwarding it to a colleague does not let them in.

Two-factor authentication

Required to make changes, and what to do when the phone is gone.

Signing in is a single-use link sent to your address, so there is no password to phish or reuse. The trade is that your account sits behind your mailbox: whoever reaches that inbox can reach the workspace. A second factor is what makes that no longer true.

Turn it on in Settings. Scan the QR code with any authenticator app - Google Authenticator, 1Password, Aegis, Bitwarden - or type the key in by hand if the camera will not cooperate. Nothing about signing in changes until you enter a code from the app and it checks out, so a setup you abandon halfway leaves you exactly where you started.

It is required for anyone whose role can change providers, routing, payments, API keys, webhooks, people or settings, and in the partner portal for anyone who reviews or decides applications, messages merchants, or changes the team or settings (partners turn it on under Settings in the portal). Until it is on, such a person can still see everything, and the app says what is needed before anything is changed. Read-only roles may turn it on, and need not.

With it on, a session left alone for 15 minutes locks; enter a code to carry on where you were. Without it, a session left alone for 15 minutes ends, and you sign in again with a new link. Ten wrong codes in a row lock the account for 30 minutes.

You get ten recovery codes when you enable it, and that is the only time they are ever shown - they are stored hashed, so we genuinely cannot print them again. Each works once, in place of the app. Keep them where you keep the things you would need if your phone went in a river.

Turning it off asks for a current code, and so does replacing your recovery codes. That is deliberate: somebody sitting at your unlocked laptop should not be able to strip the second factor off and leave your mailbox as the only thing in the way.

A code works once. If you enter one and immediately need another, wait for your app to roll over rather than retyping the same digits - a code that has been spent is refused even inside the thirty seconds it is still displayed.

Lost the phone and the recovery codes too? Contact support. Once we have confirmed it is you, we remove the second factor, sign you out everywhere and email you; you then sign in with a link and set it up again. The reset is on our audit record, and a change of the address you sign in with is emailed to both the old and the new one.

An account that has not been used for 90 days is disabled, so a forgotten login cannot be picked up later. Contact support to have it enabled again.

API keys and webhooks

Integrating, and staying in sync without polling.

Keys live under Developers, one set for Test and one for Live. A key is shown once, when you create it: store it before you close the dialog. Roll makes a new secret under the same name and leaves the old one working until you revoke it; revoking takes effect immediately. A key can be given an expiry of 90, 180 or 365 days when you make it, and restricted to the scopes it needs (for example only reading payments); a call outside them is refused.

Webhook endpoints receive signed events about payments, refunds, disputes and suggestions; each endpoint takes all of them or the ones you pick (the full list is in the API reference). Verify the signature against the raw body before parsing it. Delivery retries on network errors, timeouts, 5xx and most 4xx; only 400, 410 and 422 stop the retries, because those say the event itself is unwanted. Every attempt is logged with its response code.

If you would rather not host an endpoint, the events API is the same information by polling. The full contract, including the signature format, is on the developer documentation page.

Audit log

Who did what, and why it cannot be edited.

Every administrative action is recorded with the person, the action, what it affected, and the address it came from. Entries come from a fixed catalogue of event types rather than free text, so the log can be filtered and reasoned about rather than merely read.

The product exposes no way to edit or delete an entry, at any role, including the platform's own administrators, and the retention job deliberately skips the audit trail. You can export it.

What the platform will not do

The limits, stated up front rather than discovered later.

It never holds your money. Settlement flows directly from your providers to you. There is no balance and no payout rail here.

It never sees a card number. No screen, API or SDK collects one. Payment details are entered on provider-controlled pages, or in the provider's own fields embedded in your page, and an API call with a card number in any field is refused.

It never approves you. Underwriting is the provider's decision, always.

It cannot over-refund. A refund is clamped to what is actually refundable, and two simultaneous full refunds cannot both succeed.

Troubleshooting

The things people hit first.

A screen is empty but I have payments. Check the period, then the Test/Live filter. Both are at the top of the screen and both are in the URL.

My payment was declined and not retried. Some declines are final - the same card will fail everywhere. Open the payment: it names the category and says whether a retry was worth it.

No payment can be routed. Every connection is either inactive or not approved for that country, currency or method. Providers shows what each one can take.

A webhook is not arriving. The delivery log on Developers records every attempt with its response code. An endpoint answering 400, 410 or 422 is not retried, on purpose; any other answer is retried for about 28 hours.

My sign-in link did not sign me in. A link works once and for 15 minutes; ask for a new one. An account nobody has used for 90 days is disabled, and so is one an administrator has blocked: the sign-in page says so. Contact support to have it enabled again.

My sign-in link expired. They last 15 minutes and work once. Request another.