Forhopp

ForhoppPay Connect - Merchant Dashboard Guide

Overview

This guide covers everything a merchant needs to know about managing their ForhoppPay Connect integration from the merchant dashboard.

Getting Started

1. Enable Connect

  1. Log in to your ForhoppPay account
  2. Navigate to Settings > Connect
  3. Fill in your business profile:
    • Business Name (required)
    • Business URL
    • Support Email (required)
    • Support Phone
    • Logo URL (displayed on checkout pages)
    • Brand Color (hex code, e.g., #4F46E5)
    • Statement Descriptor (max 22 characters, appears on customer statements)
  4. Click "Enable Connect"

2. Configure Payout Settings

Setting Options Description
Payout Schedule Daily, Weekly, Monthly When payouts are processed
Default Currency USD, EUR, GBP, CAD, AUD, JPY, CHF Currency for payouts
Payout Threshold $25 minimum Minimum balance for payout

Payout timing:

  • Daily: 00:00 UTC every day
  • Weekly: Monday 00:00 UTC
  • Monthly: 1st of month 00:00 UTC

3. Generate API Keys

  1. Go to Connect > API Keys
  2. Click "Create New Key"
  3. Enter a name (e.g., "Production Key")
  4. Select environment: Live or Test
  5. Copy and securely store the secret key (shown only once)

You can have up to 10 active API keys.

API Key Management

Key Types

Key Format Purpose
Live Publishable pk_live_[32 chars] Client-side code (safe to expose)
Live Secret sk_live_[32 chars] Server-side API calls
Test Publishable pk_test_[32 chars] Client-side testing
Test Secret sk_test_[32 chars] Server-side testing

Key Permissions

Default permissions for all keys:

  • charges:write - Create and manage charges
  • charges:read - View charge details
  • webhooks:write - Create and manage webhooks
  • webhooks:read - View webhook details

Revoking Keys

  1. Go to Connect > API Keys
  2. Find the key to revoke
  3. Click "Revoke"
  4. Confirm revocation

Revoked keys immediately stop working. The key record is preserved for audit purposes.

Key Rotation Best Practice

  1. Create a new key pair
  2. Update your application to use the new keys
  3. Verify the new keys work correctly
  4. Revoke the old keys

Transaction Management

Viewing Charges

The dashboard shows all charges with:

  • Charge ID (ch_xxx)
  • Amount and currency
  • Status (pending, authorized, captured, refunded, etc.)
  • Payment method
  • Creation date
  • Fee and net amounts

Charge Statuses

Status Meaning Actions Available
Pending Awaiting customer payment Cancel
Authorized Payment authorized Capture, Void
Captured Payment captured Refund (full or partial)
Failed Payment failed None
Voided Cancelled before capture None
Refunded Fully refunded None
Partially Refunded Partially refunded Refund remaining
Expired Checkout session expired (24h) None
Disputed Customer disputed charge Submit evidence

Issuing Refunds

  1. Find the charge in the dashboard
  2. Click "Refund"
  3. Enter amount (leave blank for full refund)
  4. Enter reason (optional)
  5. Confirm refund

Multiple partial refunds are allowed until the charge is fully refunded.

Webhook Management

Creating Webhooks

  1. Go to Connect > Webhooks
  2. Click "Add Endpoint"
  3. Enter your endpoint URL (must be HTTPS)
  4. Select events to subscribe to
  5. Add a description (optional)
  6. Copy the signing secret (shown only once)

Maximum 10 webhook endpoints per account.

Available Events

Event Description
charge.created New charge created
charge.completed Payment successful
charge.failed Payment failed
charge.refunded Charge refunded (full or partial)
charge.disputed Customer disputed charge
payout.created Payout initiated
payout.completed Payout successful
payout.failed Payout failed

Webhook Health

The dashboard shows webhook endpoint health:

  • Status: Enabled / Disabled / Failing
  • Consecutive failures count
  • Failing since timestamp

After 5 consecutive failures, the endpoint is marked as "failing". Fix the issue and the endpoint will recover automatically on the next successful delivery.

Delivery Logs

View delivery history for each webhook endpoint:

  • Event type and ID
  • Delivery status (delivered, failed, pending)
  • HTTP status code
  • Response body (truncated)
  • Attempt count
  • Timestamps

Logs are retained for 30 days.

Payout History

Viewing Payouts

The dashboard shows all payouts with:

  • Payout ID (po_xxx)
  • Amount, fees, and net amount
  • Status (pending, in_transit, paid, failed)
  • Payout method
  • Expected arrival date
  • Creation date

Payout Statuses

Status Meaning
Pending Payout scheduled
In Transit Funds being transferred
Paid Payout completed
Failed Payout failed (see failure reason)
Canceled Payout cancelled

Payout Calculation

Payout Amount = Captured Charges - Platform Fees - Refunds - Disputed Amounts

The minimum payout threshold is $25. If your balance is below this, the payout is deferred to the next cycle.

Dispute Management

When a Dispute Occurs

  1. Customer disputes a charge with their bank
  2. ForhoppPay creates a dispute record
  3. charge.disputed webhook is sent
  4. Disputed amount is held from payouts
  5. You have a window to submit evidence

Dispute Statuses

Status Meaning
Open Dispute opened, evidence needed
Under Review Evidence submitted, being reviewed
Won Resolved in your favor (funds released)
Lost Resolved in customer's favor

Submitting Evidence

  1. Go to the dispute in your dashboard
  2. Upload supporting documents:
    • Proof of delivery
    • Customer communication
    • Terms of service
    • Product descriptions
  3. Submit evidence before the deadline

Dispute Fees

  • $15 dispute fee charged when dispute is opened
  • Fee is refunded if you win the dispute

Sandbox / Test Mode

Switching to Test Mode

Toggle "Test Mode" in the dashboard to view test data separately from production.

Test Card Numbers

Card Result
4242424242424242 Success
4000000000000002 Declined
4000000000009995 Insufficient funds
4000000000000069 Expired card
4000000000000127 Incorrect CVC
4000000000000119 Processing error

Test PayPal Accounts

Email Result
test-success@sandbox.paypal.com Success
test-decline@sandbox.paypal.com Declined

Sandbox Behavior

  • No real payments processed
  • Webhooks delivered to test endpoints
  • Data isolated from production
  • Lower rate limits (25 req/sec vs 100)

Fee Structure

Transaction Fees

Fee Type Amount
Transaction Fee 2.9% + $0.30 per charge
Currency Conversion 1% above mid-market rate
Dispute Fee $15 (refunded if won)

Fee Example

Charge: $100.00 (10000 cents)
  Percentage fee: 10000 × 0.029 = 290 cents ($2.90)
  Fixed fee: 30 cents ($0.30)
  Total fee: 320 cents ($3.20)
  Net to you: 9680 cents ($96.80)

Monthly Statements

Fee statements are generated monthly and available in the dashboard under Connect > Statements.

Rate Limits & Quotas

Resource Limit
API Keys 10 per merchant
Webhook Endpoints 10 per merchant
Live API Requests 100/second
Test API Requests 25/second
Maximum Charge $999,999.99
Checkout Session 24 hours
Authorized Hold 7 days
Minimum Charge $0.50
Minimum Payout $25.00

Supported Currencies

Currency Code Min Charge Symbol
US Dollar USD $0.50 $
Euro EUR €0.50 €
British Pound GBP £0.50 £
Canadian Dollar CAD CA$0.50 CA$
Australian Dollar AUD A$0.50 A$
Japanese Yen JPY ¥50 ¥
Swiss Franc CHF CHF 0.50 CHF

Support

Last Updated: March 2026

Was this page helpful?

Edit this page