How Payshen works

Getting started

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

A workspace starts with sample data so the screens have something to show. Sample rows are labelled as samples everywhere they appear, and they never count as work you have done - the setup guide ignores them.

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.Set your routing: a fixed provider, a priority order, or the adaptive engine.
3. 3.Create a test API key in Settings 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.

Test and live

Two environments that never mix, and how to tell which you are looking at.

Every API key belongs to one environment. A ps_test_ key reads and writes sandbox data only; a ps_live_ key production only. A test key cannot retrieve a live payment even if it has the id.

The separation goes further than the data. Sandbox outcomes never train the routing engine and never trip a provider's circuit breaker, so a week of integration testing cannot change where your real money goes.

Reporting screens show both by default, because a new workspace would otherwise be empty, and they say so with a badge. Switch to Live to see only real trading. A workspace that has processed nothing real will honestly report nothing rather than present test traffic as revenue.

Choosing a reporting period

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

Overview and Analytics report over a period you choose: last week, last month, last 3 months, last 6 months, last year, last 3 years, last 5 years, all time, or a custom from/to range. The default is the last month.

If a screen is empty while Transactions 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 widen to all time.

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.

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.

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.

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. A rule chooses one of:

• Fixed - always this connection. No failover, which is sometimes exactly what a contract requires.
• Priority - this order, with failover to the next after a soft decline or a technical error before anything was executed.
• Adaptive - the engine picks, learning from your own outcomes.

The engine optimises for approval and cost together, per country, currency, method and amount band, and keeps learning from every live payment. 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.

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 what your provider actually took against what you charged.

Until a provider settles, the fee on a payment is an estimate from your rate card. Reconciliation replaces the estimate with the fact.

1. 1.Download the settlement file from your provider, or press Run demo reconciliation to build one from your own recent payments.
2. 2.Upload it as CSV. It needs reference, amount, currency and fee; column order does not matter and common provider spellings are accepted.
3. 3.Read the result: how many lines matched, what settled, and what did not reconcile.
4. 4.Work the exception queue. Nothing is dropped for being inconvenient.

A line lands in the exception queue when it matches no payment, when the amount disagrees, or when the fee is far above what your rate card predicted. 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.

The demo builds its file from your own captured payments in the selected period. On a workspace with none, the button says so instead of producing an empty file.

Marketplace and applications

Finding a provider, applying, and what applying actually does.

Browse providers by industry, country, currency and payment method. Every listing states plainly what applying there does, and we never show a level a provider cannot actually deliver.

• Listed - discovery only. You apply on the provider's own site and we cannot track what happens next. Most third-party listings are here today.
• Referral and Hosted onboarding - you apply on the provider's own page with a Payshen referral reference, and we record when you went there. The decision happens with the provider, so its status is not shown in Payshen.
• Sandbox - our own test provider. When you submit, the review and the decision are simulated at once and labelled as simulated, so you can walk the whole flow.
• Reviewed in Payshen - you apply here, the provider's staff review it here, and requests for documents and the decision all happen in one place.

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 10 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

Optional per person, 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 per person, not per workspace. Turning it on protects your own account; it does not change how anyone else signs in.

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.

API keys and webhooks

Integrating, and staying in sync without polling.

A key is shown once, when you create it. Store it before you close the dialog; if it is lost, revoke it and create another. Revoking takes effect immediately.

Webhook endpoints receive signed events - authorized, captured, voided, refunded, declined. Verify the signature against the raw body before parsing it. Delivery retries on network errors and 5xx, never on a 4xx, because a rejection is an answer. 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.

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 4xx is not retried, on purpose.

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