Access and credentials
Get a workspace login, request Sandbox or Production access, and manage credentials safely.
You need a workspace login and a credential for each environment you use. Facto reviews and grants every level of access. Access is never automatic, and an environment rejects API calls until it has a valid credential.
| State | How you reach it | What it gives you |
|---|---|---|
| Registered | Facto creates your organization and gives you a one-time temporary password | A workspace login. No API access |
| Sandbox access | Facto grants Sandbox login and merchant app creation access with your account. The Mandate template has two extra checks: an active Sandbox entitlement and an explicit mandated-payments opt-in | You create your own Sandbox app. Its credential is shown once |
| Production access | An approved production access request, after acceptance | Production credentials, issued fresh |
Get registered
There is no signup page or registration API. Facto creates your account. Ask
your Facto contact for one and provide your organization name and the role you
need: merchant, card_provider, card_program, or more than one.
Facto creates the organization, role, owner membership, and Sandbox access together. You then receive a sign-in address and a one-time temporary password. You must replace that password when you first sign in.
| Symptom | What to do |
|---|---|
| Looking for a signup page | There isn't one. Ask your Facto contact |
| Temporary password rejected | Five failed sign-ins lock the account for 15 minutes. An operator reset is the only recovery, so ask Facto rather than retrying |
| Signed in, but the workspace is empty | The role or the membership is not active. Ask your Facto contact to check both |
| Wrong email on the account | Changing it is an identity change only Facto can make |
Common setup errors
When the workspace refuses an action, the response includes a reason code. You may see these codes before you create your first app.
| Refusal | What it means | What to do |
|---|---|---|
merchant_email_verification_required | The account email is not verified | Verify it, then send the request again |
merchant_sandbox_access_required | The Mandate template cannot be used because its Sandbox access record is missing or inactive | Click Enable mandated payments. It records the opt-in and provisions the missing access when needed. Reselect the workspace context if asked |
merchant_mandate_optin_required | The Mandate template's Sandbox entitlement is active, but mandated payments are not enabled | Click Enable mandated payments |
partner_context_forbidden | Your signed workspace context is out of date. This can happen when password reauthentication expires or when new Sandbox access changes your membership revision | Select the workspace context again, then retry. If the action requires password reauthentication, complete it again and retry within five minutes |
The merchant Quickstart shows where to enable mandated payments.
Get Sandbox access
Facto gives your account access to the Sandbox workspace. The access-request endpoint has no Sandbox request type. Tell your Facto contact your business type, the role you need, what you are building, and who the technical contact is. The review target is 1 to 3 business days.
Registration updates your membership with Sandbox app creation access. This is separate from an API credential. If that general creation access is missing, ask your Facto contact to fix the account. Enable mandated payments handles a missing Mandate-only Sandbox access record as described below.
The Connect and Webhook templates do not require the mandated-payments opt-in. Only the Mandate template does. Enable mandated payments records that explicit opt-in and provisions the Mandate Sandbox access when it is missing; it does not grant the general permission to create apps. The two middle reason codes above distinguish a missing access record from a missing opt-in.
Facto does not send you a Sandbox credential. You create the app and generate
its first credential in the Dashboard, not through the API. Sign in, replace
the temporary password, and select your organization, the merchant role, and
Sandbox. Then open Merchant Sandbox apps:
- If you need the Mandate template, click Enable mandated payments and re-enter your password. Until it succeeds, that template stays disabled. The action provisions missing Mandate Sandbox access when needed. Reselect your workspace context if prompted; contact Facto only if the action itself fails.
- Create the app with the template your integration needs. The merchant
Quickstart uses Approved capability template set to
Merchant Mandate Sandbox. Add your storefront origins under Allowed origins · one per line. There is no origin-update route, so a wrong list means a replacement app. - On the app card, fill in Rotation reason and click Rotate Sandbox credential. This step needs the password step-up.
| From the Dashboard | Shape | You use it as |
|---|---|---|
| App id | mapp_… | FACTO_APP_ID |
| Show-once secret | sandbox_mcsk_… | FACTO_CLIENT_SECRET |
The create-app response has no secret or client id. The rotation response
returns credential_id, new_version, old_version_expires_at,
retrieval_mode, and one_time_secret. It is the only place where the
credential id and secret appear.
Basic auth also needs a username, but the merchant workspace does not display
it. Rotation creates a credential_id shaped sandbox_mcid_…; neither the app
card nor the show-once panel shows it. Ask your Facto contact for the
credential id when you rotate.
Request Production access
Production requires a separate approval. Sandbox access is not promoted. Before Facto grants Production access:
- merchants pass integration acceptance. New card provider onboarding is closed and its documentation is temporarily hidden;
- card programs receive separate approval for the target Production environment;
- a settlement profile is on file for that environment.
Production credentials are issued fresh. Nothing carries over from sandbox.
Show-once credentials
Every secret appears once, in the response that issues it. This is why issuance
returns retrieval_mode: "show_once". The same rule covers app secrets,
Production keys, and provider signing keys. Facto stores only what it needs to
verify a secret. No page, API, or support channel can show the plaintext again.
Save it in your secret manager before leaving the page.
Rotation replaces a secret without an outage. The previous secret remains valid
until the returned old_version_expires_at, five minutes later. Deploy the new
secret during that overlap.
A credential carries the scopes of the capability template its app was created with. You pick the template in the Dashboard at creation and it cannot be changed afterwards.
| Template | Scopes |
|---|---|
merchant_connect_sandbox | readiness.read, checkout.write |
merchant_webhook_sandbox | readiness.read, webhooks.manage |
merchant_mandate_sandbox | readiness.read, authorizations.request, payments.execute |
Refunds need refunds.execute, which no Sandbox template carries. Ask Facto to
issue a credential with it.
Use the secret server-side, never in browser code:
import { createFactoConnectServer } from '@facto/connect/server'
export const facto = createFactoConnectServer({
appId: process.env.FACTO_APP_ID!,
clientId: process.env.FACTO_CLIENT_ID!,
clientSecret: process.env.FACTO_CLIENT_SECRET!,
environment: 'custom',
apiBaseUrl: 'https://<your-facto-api-host>',
hostedConnectUrl: 'https://<your-facto-connect-host>',
})Facto tells you which host your credentials are valid against when it issues them. See SDK reference for the full option list.
If you lose a secret, rotate it. It cannot be recovered. A same-scope rotation shows the new secret once, keeps the old version valid for a short overlap, then rejects the old version. It needs no new approval. Changing the scope, purpose, environment, or identity requires an access request instead.
If you suspect a leak, ask Facto to revoke the key. Revocation takes effect before any resource lookup, applies only to that key, and is recorded in the audit log. A revoked key cannot be reactivated. Facto must issue a new one.
What remains visible after issuance depends on the credential type. It never
includes the secret itself. A merchant app returns app_id, display_name,
environment, capability_template, status, allowed_origins and
credential_version, with no fingerprint, no client id and no secret. A
provider credential keeps a fingerprint, the scopes and environment it is bound
to, its status, and its issue and expiry times.
Your workspace login is not a service credential and cannot be exchanged for one.
Sandbox and production never mix
A credential is bound to one environment at issuance. Used against the other it fails verification before any business logic runs. Apps, credentials, configuration, test data and acceptance state are never copied across. Never send real card numbers, production PII or production settlement files into sandbox.
Organization and roles
Facto has three separate partner roles: merchant, card_provider, and
card_program. One organization can hold more than one, but credentials,
environments, acceptance, and settlement never carry over between roles.
Card Program Connect routes are implemented in the Engine. A Card Program can call them only with an active Program Connection and server credential for the target environment, after Facto enables the APIs that program needs. Sandbox and Production credentials are not interchangeable, and Production requires separate approval.
The member directory is read-only to you: Facto creates users, assigns memberships and sends activations. To change anything about a person, ask your Facto contact, naming the person, the role and the environments. Nobody joins by email domain, and app scopes come only from pre-approved templates.