Payment Gateway Configuration

Payment gateway configuration lets you accept card payments on your store through Stripe or Revolut. Configure API credentials, manage test and production modes, and ensure your store meets production security requirements before going live.

Accessing payment gateway configuration

1. From your admin, go to Settings > Payment Gateway
2. Configure your Stripe and/or Revolut settings
3. Enter your API credentials
4. Click Save changes

Supported payment gateways

Hanut.io supports two payment gateway providers:

Stripe

Accept credit and debit card payments through Stripe's payment processing platform. Stripe handles card data securely and provides comprehensive payment features.

Revolut

Accept payments through Revolut's merchant gateway. Revolut offers competitive processing rates and built-in multi-currency support.

You can enable one or both gateways on your store. Customers will see enabled payment methods at checkout.

Stripe configuration

To accept payments through Stripe, you need three pieces of information from your Stripe account:

API Key (Secret Key)

Your Stripe secret API key authenticates server-side API requests. This key must be kept confidential.

Finding your API key:

1. Log into your Stripe Dashboard
2. Go to Developers > API keys
3. Copy the Secret key (starts with sk_)

Test vs Production:

• Test keys start with sk_test_ - use for testing before launch
• Live keys start with sk_live_ - use only in production

Publishable Key

Your Stripe publishable key identifies your account in client-side code. This key is safe to expose publicly.

Finding your publishable key:

1. In the Stripe Dashboard, go to Developers > API keys
2. Copy the Publishable key (starts with pk_)

Test vs Production:

• Test keys start with pk_test_ - pair with test secret key
• Live keys start with pk_live_ - pair with live secret key

Webhook Signing Secret

The webhook signing secret verifies that webhook events sent to your store genuinely come from Stripe, preventing fraud.

Setting up webhooks:

1. In the Stripe Dashboard, go to Developers > Webhooks
2. Click Add endpoint
3. Enter your webhook URL (provided by Hanut.io support)
4. Select the events to send
5. Copy the Signing secret (starts with whsec_)

Revolut configuration

To accept payments through Revolut, you need two credentials from your Revolut Business account:

API Key

Your Revolut API key authenticates requests to the Revolut merchant API.

Finding your API key:

1. Log into your Revolut Business account
2. Go to Merchant > Settings > API
3. Generate or copy your API key

Publishable Key

Your Revolut publishable key is used for client-side payment form initialization.

Sandbox mode

Revolut provides a sandbox environment for testing payment flows before going live.

Sandbox mode enabled:

• Payments processed through Revolut's test environment
• No real money is charged
• Use for testing and development

Sandbox mode disabled:

• Payments processed through Revolut's production environment
• Real money is charged to customer cards
• Use only when ready for production

Revolut webhooks

Webhooks allow Revolut to notify your store when a payment is completed, so orders are automatically fulfilled after successful payment.

The Revolut Webhooks section appears on the payment gateway page once you have saved a Revolut API key. It shows a table of currently registered webhooks and lets you add or remove them.

Adding a webhook:

1. Go to Settings > Payment Gateway
2. Ensure Revolut is selected as your payment gateway and your API key is saved
3. Scroll to the Revolut Webhooks section
4. Click Add Revolut Webhook
5. A webhook pointing to your store's payment endpoint is registered with Revolut automatically

Deleting a webhook:

1. In the Revolut Webhooks table, find the webhook you want to remove
2. Click Delete on that row
3. The webhook is removed from Revolut

Live Mode and production safety

Live Mode is a store-wide setting that indicates your store is running in production and accepting real customer orders. When Live Mode is enabled, your store automatically enforces production-ready payment gateway configuration.

What is Live Mode?

Live Mode is configured in Settings > Store Configuration. When enabled, it signals that:

• Your store is live and serving real customers
• All payments must use production payment gateways
• Test payment modes are not allowed

Test gateway prevention

When Live Mode is enabled, your store enforces these restrictions:

Revolut:

• Sandbox mode is automatically disabled
• The sandbox mode checkbox is locked and cannot be enabled
• A warning banner explains why sandbox mode is unavailable

Stripe:

• Test API keys (starting with sk_test_ or pk_test_) are rejected
• You must provide live production keys (starting with sk_live_ or pk_live_)
• An informational note reminds you to use production keys

Why these restrictions matter:

• Prevents accidentally running production stores with test gateways
• Ensures customers are charged correctly using real payment processing
• Protects your business from payment processing errors
• Eliminates configuration mistakes when launching

Bidirectional validation

The Live Mode safety system works in both directions:

From Store Configuration:

• Enabling Live Mode checks your payment gateway configuration
• Blocks activation if Revolut sandbox mode is enabled
• Blocks activation if Stripe test keys are configured
• Shows clear error message explaining which gateway needs updating

From Payment Gateway:

• Enabling Revolut sandbox mode checks if Live Mode is active
• Blocks sandbox activation if Live Mode is enabled
• Shows warning banner when Live Mode is active
• Disables test mode controls when Live Mode is active

This bidirectional validation ensures your store can never run with mismatched production/test configurations.

Testing payment gateways

Before going live, thoroughly test your payment gateway configuration:

Testing with test credentials

1. Keep Live Mode disabled in Store Configuration
2. Configure Stripe with test API keys (sktest_ and pktest_)
3. Enable Revolut sandbox mode if using Revolut
4. Place test orders on your website
5. Use Stripe test card numbers (e.g., 4242 4242 4242 4242)
6. Verify successful payment processing
7. Check that orders appear correctly in your admin

Switching to production

When ready to accept real payments:

1. In Settings > Payment Gateway:
   • Update Stripe keys to live keys (sklive_ and pklive_)
   • Disable Revolut sandbox mode
   • Save changes
2. In Settings > Store Configuration:
   • Enable Live Mode
   • Save configuration
3. Place a small test order with a real card
4. Verify the payment appears in your Stripe/Revolut dashboard
5. Confirm the order appears correctly in your admin

Managing credentials

Updating credentials

To update your payment gateway credentials:

1. Go to Settings > Payment Gateway
2. Enter the new credentials in the appropriate fields
3. Click Save changes

Security notes:

• Credentials are stored encrypted
• Only users with Store Configuration permission can view or modify credentials
• The system shows whether credentials are configured but does not display the actual secret values

Credential validation

When you save payment gateway configuration, the system:

• Validates that credentials are in the correct format
• Checks Live Mode compatibility (blocks test keys if Live Mode is enabled)
• Stores credentials securely
• Confirms successful configuration

Removing credentials

To stop using a payment gateway:

1. Go to Settings > Payment Gateway
2. Clear all fields for that gateway
3. Click Save changes

The gateway will no longer appear as a payment option at checkout.

Troubleshooting

"Test keys not allowed in Live Mode"

Problem: You tried to save Stripe test keys while Live Mode is enabled.

Solution:

1. Disable Live Mode in Store Configuration, or
2. Update to Stripe live keys (sklive_ and pklive_)

"Cannot enable sandbox mode - Live Mode is active"

Problem: You tried to enable Revolut sandbox mode while Live Mode is enabled.

Solution:

1. Disable Live Mode in Store Configuration first
2. Then enable Revolut sandbox mode for testing

Revolut orders not confirmed after payment

Problem: A customer completes a Revolut payment but the order stays in a pending state and is not confirmed.

Cause: Your store has no active Revolut webhook registered, so Revolut cannot notify Hanut.io when a payment succeeds.

Solution:

1. Go to Settings > Payment Gateway
2. Scroll to the Revolut Webhooks section
3. Click Add Revolut Webhook to register a webhook
4. Verify the webhook appears in the table

Payments failing at checkout

Problem: Customers see payment errors at checkout.

Common causes:

• Mismatched keys: Test API key paired with live publishable key (or vice versa)
• Invalid credentials: Keys are incorrect or revoked
• Webhook issues: Webhook signing secret is incorrect or webhooks are not configured

Solution:

1. Verify all keys are from the same environment (all test or all live)
2. Check your Stripe/Revolut dashboard for API key validity
3. Confirm webhook configuration matches your endpoint

"Cannot enable Live Mode - test gateway detected"

Problem: You tried to enable Live Mode but have test payment gateways configured.

Solution:

1. Go to Settings > Payment Gateway
2. Update Stripe to use live keys (not test keys)
3. Disable Revolut sandbox mode
4. Save payment gateway changes
5. Return to Store Configuration and enable Live Mode

Permissions

Payment gateway configuration requires the Store Configuration permission. Users without this permission will not see the payment gateway menu item or be able to access the configuration page.

Best practices

Security

Protect your secret keys:

• Never share your secret API keys in emails, chat, or support tickets
• Never commit API keys to version control
• Rotate keys immediately if they are exposed

Use test keys safely:

• Keep test and live keys clearly separated
• Only use test keys in non-production environments
• Switch to live keys only when ready for production

Testing

Test thoroughly before launch:

• Complete full checkout flows with test cards
• Verify order creation in admin portal
• Check payment confirmation emails
• Test refund processing
• Confirm webhook event delivery

Regular validation:

• Periodically test payment flows
• Monitor failed payment rates in gateway dashboards
• Keep webhook endpoints up to date

Production readiness

Before enabling Live Mode:

• Payment gateways configured with production credentials
• Test orders completed successfully
• Refund process tested and understood
• Customer support process in place for payment issues
• Monitoring set up in Stripe/Revolut dashboards

Next steps

• Configure store settings including Live Mode
• Set up wallet configuration for customer credits
• Configure offline payment methods for bank transfers and cash
• Test your checkout flow with a test order