Payment Gateway

Merchant onboarding guide

How merchants are reviewed, approved, provisioned, and connected to WooCommerce or custom storefronts.

Current Production Links

Plugin API base URL

https://api.noramp.dev

Onboarding Paths

1. Public Application With AI Review

Use this when the merchant has not already been approved.

Merchant submits business name, email, website URL, catalog URL, support email, and support phone.
The platform fetches the public site and catalog.
Deterministic compliance checks run first.
Claude AI review runs when configured.
Merchant receives immediate feedback: preapproved or needs changes.
No processor account is created from the public application page.
Admin reviews the application and creates the onboarding link.

2. Admin Precheck Onboarding

Use this when an admin wants a full site precheck before account creation.

Admin enters identity, support info, site URLs, evidence, tier, and callback URL.
The platform runs deterministic checks and Claude review when configured.
If the precheck passes, the processor account is created through the platform API.
The account receives the selected category MCC, approved description, fee policy, reserves, and metadata.
Admin sends the hosted onboarding URL to the merchant.
Merchant completes hosted KYC.
Merchant receives API Base URL and Merchant Token after completion.

3. Trusted Short-Link Onboarding

Use this when the merchant is already manually approved and you do not want to run the AI/site assessment again. Create it from the admin onboarding page with the trusted onboarding form.

https://api.noramp.dev/t/<short_code>

Example:

https://api.noramp.dev/t/t_oneday1

Trusted Short-Link Rules

Skips AI/site assessment.
Still creates the processor account through the platform API.
Still forces the selected category MCC.
Still applies the selected tier fee policy.
Still attaches platform metadata and callback URL.
Hides merchant payload details from the URL.
Can expire, be marked used, and be audited.

Do not use native processor account links directly for these merchants. Native links do not guarantee the correct MCC or business profile setup.

What The Platform Sends

When the merchant clicks a normal or trusted onboarding link, the connected account is created with:

country = US
email

capabilities:
card_payments
link_payments
transfers

business_profile:
mcc = selected category MCC
name = business name / legal entity / email
product_description = selected category product description
support_email
support_phone
support_url
url = merchant site URL

controller:
fees.payer = application
losses.payments = application
requirement_collection = stripe
stripe_dashboard.type = express

settings:
statement_descriptor
statement_descriptor_prefix = category prefix, such as RSCH or COACH
payouts.schedule.interval = manual
branding.primary_color, if provided

metadata:
internal_merchant_id
merchant_category = selected category key
vertical = selected category vertical
industry = selected category industry
mcc = selected category MCC
compliance_template
tier
platform_fee_percent
estimated_all_in_fee_percent
reserve_percent
merchant_site_url
merchant_callback_url
processor_profile_locked = true

The merchant still completes unavoidable hosted KYC: owner information, tax details, address, bank account, TOS acceptance, and requested verification forms.

Fee Policy

Standard

18% estimated all-in 15% platform fee 10% reserve

Growth

10% estimated all-in 7% platform fee 10% reserve

Enterprise

9% estimated all-in 6% platform fee 10% reserve

The platform fee is the application fee charged by the gateway. The all-in number assumes roughly 3% processor cost.

Admin Intake Fields

Normal precheck onboarding

Internal merchant ID
Legal entity name
DBA / customer-facing name
Merchant email
Website URL and catalog URL
Support email, phone, and URL
Statement descriptor
Brand primary color
Merchant category
Sample CoA URL, when required for the selected category
Age gate screenshot URL, when required for the selected category
Shipping label example URL, when required for the selected category
Tier, estimated volume, banking jurisdiction, and callback URL

Trusted onboarding

Internal merchant ID
DBA / customer-facing name
Merchant email
Merchant category
Website URL
Support email and phone
Statement descriptor
Tier
Approval reason

Compliance Precheck

Before normal account creation, the platform checks:

Reachable catalog URL.
US banking jurisdiction.
Category-specific positioning signals, including MCC 5169 research-biochemical signals or MCC 8299 coaching/education signals.
Category-specific evidence, such as research-use-only language, CoA references, sample CoA URL, and shipping label example URL for research merchants.
No medical, consumer-use, guaranteed-income, gambling, adult, crypto/forex, or regulated-advice positioning when those are incompatible with the selected category.
No master restricted keyword matches.
Claude AI analysis, when configured.

The reason this happens before processor account creation is applicant-pool hygiene. Processor risk teams can infer who a platform is attracting from rejected and attempted applications, not only approved merchants. See the business model thesis for the operating rationale.

Read the business model thesis

Merchant Credentials

After hosted onboarding, the merchant receives:

Payment Gateway API Base URL.
Payment Gateway Merchant Token.
Connected account ID.
Account status.
Tier, platform fee, and estimated all-in fee.

The merchant token is signed and stored only as a hash in Neon. Admins can rotate or revoke tokens.

Credential portal

https://api.noramp.dev/merchant/credentials?token=<merchant_token>

WooCommerce Callback URL

The merchant plugin exposes this callback URL:

https://merchant-domain.com/wp-json/payment-gateway/v1/callback

If a merchant accidentally provides wp-jsn, the platform normalizes it to wp-json.

Shopify Bridge

Shopify stores use the manual offsite bridge instead of native Shopify payment-app checkout. The merchant creates a manual payment method named Secure Card Payment, then the platform creates and reconciles the hosted payment link from the Shopify orders/create webhook.

https://api.noramp.dev/webhooks/shopify/orders-create

Read Shopify bridge setup

Required Platform Environment

STRIPE_SECRET_KEY
STRIPE_PUBLISHABLE_KEY
STRIPE_WEBHOOK_SECRET
DATABASE_URL
PUBLIC_BASE_URL
MERCHANT_TOKEN_SECRET
ADMIN_SESSION_SECRET
DASHBOARD_ADMIN_EMAIL
DASHBOARD_PASSWORD_HASH
ANTHROPIC_API_KEY, optional for AI review
ANTHROPIC_MODEL, optional
SHOPIFY_API_KEY, optional for OAuth app install
SHOPIFY_API_SECRET, optional for Shopify webhooks
SHOPIFY_WEBHOOK_SECRET, optional when different from app secret
RESERVE_HOLD_DAYS=60
RESERVE_PAYOUTS_ENABLED=0

Admin Monitoring

Merchant records and connected account IDs.
KYC/account status and MCC/account readiness checks.
Tier and fee policy.
Active token counts.
Recent checkout audit logs.
Recent callback attempts.
Fulfillment status.
Reserve holds.
Sales-agent referrals and commissions.
Admin audit logs.

Revocation

Per-merchant revocation is database-backed. Revoking a merchant's tokens prevents those token hashes from authenticating future checkout requests.