Payment Gateway Integration Guide for Sri Lankan Websites

A payment gateway integration for a Sri Lankan website should be treated as a business, compliance, operations, and software project. The code is only one part. Before a customer can pay reliably, the business must choose an eligible provider, prepare merchant documents, publish required policies, design a checkout flow, test payment responses, reconcile orders, handle refunds, protect sensitive data, and monitor failures after launch.

For many Sri Lankan businesses, the difficult part is not placing a payment button on a page. The difficult part is choosing the right gateway for the actual business model, getting approved, avoiding unsupported product categories, handling local and international customers, and making sure the website does not create paid orders that staff cannot fulfil.

This guide explains how to plan and implement payment gateway integration for Sri Lankan websites, including e-commerce stores, booking sites, donation-like but commercial collections, service invoices, subscriptions, and custom web applications. It is written for business owners, developers, finance teams, and project managers who need a practical implementation framework rather than a thin provider comparison.

If you are still deciding the whole store architecture, start with the E-Commerce Platform Selection Guide. If your checkout already exists and conversion is weak, use the E-Commerce Checkout Optimization Guide. If the website is still in discovery, define the payment requirements inside the E-Commerce Website Requirements Checklist.

Key Takeaways

• Confirm gateway eligibility before designing the checkout or signing a platform contract.
• Sri Lankan merchant approval usually depends on business validity, bank-account proof, website readiness, policies, contact details, product category, and partner-bank review.
• Do not assume a global provider supports Sri Lankan merchant onboarding; check current official availability.
• Choose the integration model before development: hosted checkout, redirect flow, embedded elements, plugin, API, mobile SDK, payment link, recurring API, or tokenized charging.
• Treat return URLs, cancel URLs, notify/webhook URLs, signature validation, order states, refunds, and reconciliation as first-class requirements.
• Publish clear Terms, Return Policy, Privacy Policy, contact details, business name, and product/service information before applying.
• Test success, cancellation, decline, timeout, duplicate callback, partial fulfilment, refund, and analytics events before launch.
• Never store raw card details unless the business has the compliance maturity to justify it.
• Align payment flow with checkout UX, accessibility, SEO, analytics, finance, and support.
• Keep gateway credentials, merchant accounts, settlement reports, and code ownership under business control.

Table of Contents

1. What a Payment Gateway Does

2. Sri Lankan Payment Gateway Context

3. Decide What the Website Must Accept

4. Compare Gateway Options

5. Merchant Approval Requirements

6. Choose the Integration Model

7. Design the Checkout Payment Flow

8. Implement Order States and Callbacks

9. Security, PCI and Sensitive Data

10. Testing Before Launch

11. Refunds, Reconciliation and Finance

12. Analytics and Conversion Tracking

13. WooCommerce, Shopify and Custom Websites

14. Common Integration Mistakes

15. 100-Point Payment Integration Readiness Score

16. Frequently Asked Questions

What a Payment Gateway Does

A payment gateway lets a website request payment from a customer and receive a transaction result. Depending on the provider and integration model, it may collect card or wallet details, redirect the customer to a secure payment page, process bank authentication, return the customer to the website, notify the website server, support refunds, support recurring payments, and provide settlement reports.

A good integration answers these questions:

• Is this business allowed to use the gateway?
• Which payment methods and currencies are supported?
• What customer information is required?
• What order state is created before payment?
• How is the payment request signed or authenticated?
• What happens when the customer pays successfully?
• What happens when the customer cancels?
• What happens when the provider notifies the server later?
• How are failed, pending, reversed, refunded, and disputed payments handled?
• How does finance reconcile website orders to bank settlements?

The gateway is not a magic sales switch. It is part of the checkout operating system.

Payment gateway, payment processor and merchant account

People often use these terms loosely:

In a Sri Lankan project, clarify who provides each function. The developer, provider, business owner, bank, and platform may each own different parts of the flow.

Sri Lankan Payment Gateway Context

Sri Lanka has local payment providers, bank-linked acquiring routes, wallet and QR initiatives, and global tools that may support customers but not necessarily Sri Lankan merchant onboarding. Current eligibility must be checked provider by provider.

The Central Bank of Sri Lanka regulates payment cards and mobile payment systems. Its payments and settlements information explains that service providers of payment cards and mobile payment systems require authority under the relevant regulation, and it describes LANKAQR as a national QR standard intended to support interoperable, low-cost digital payments. For web projects, this means payment-provider selection should be based on approved, documented, and supportable options, not only on a developer's past habit.

PayHere describes itself as a Central Bank approved aggregated internet payment gateway service for Sri Lankan businesses and provides checkout APIs, plugins, mobile SDKs, recurring, charging, retrieval, refund, authorize, and capture API documentation. WEBXPAY publishes redirect, hosted/token, Shopify, WooCommerce, Magento, OpenCart, Prestashop, WHMCS, API, SDK, and sample-code documentation. These are examples of local provider ecosystems that can be evaluated for Sri Lankan web projects.

Global providers need careful review. Stripe's official payment-method support documentation lists business-location requirements for payment methods, and current public support tables do not make Sri Lanka a general business-location option for standard merchant onboarding. A Sri Lankan business should not assume Stripe can be used directly just because a theme, plugin, or tutorial supports it in another country.

Start with eligibility, not interface

Ask:

• Is the legal business based in Sri Lanka or another country?
• Does the provider accept this business type?
• Are the products or services allowed?
• Is the website complete enough for review?
• Which currencies can be charged?
• Which currencies can be settled?
• Which local bank account is required?
• Are recurring, tokenized, or preauthorized payments allowed?
• Is a plugin available for the platform?
• Is API access available for the required flow?
• Are refunds, voids, disputes, and reports usable by the finance team?

If eligibility fails, the prettiest checkout design does not matter.

Decide What the Website Must Accept

Write payment requirements before requesting proposals or installing plugins.

Payment requirement register

This prevents vague requirements like “add online payment.” A hotel deposit, online course, subscription, custom service invoice, grocery delivery order, and digital download can require different gateway behavior.

Payment models to define

Document whether the website needs:

• One-time checkout payments
• Payment links for invoices or simple services
• Recurring subscriptions
• Automated charging after customer approval
• Authorization and later capture
• Partial capture
• Full and partial refunds
• Multi-currency payments
• International cards
• Wallets or local mobile payment methods
• QR payments
• Cash on delivery as a non-gateway option
• Deposits, balances, and manual reconciliation
• Marketplace or multi-vendor payouts

Some providers support a broad set of features, but support may depend on approval, business category, plan, plugin capability, and integration type.

Compare Gateway Options

Do not compare gateways only by transaction fee. A lower fee can become expensive if the integration is fragile, approval is slow, settlement reports are hard to use, or refunds require manual work.

Comparison criteria

Provider shortlist examples

For Sri Lankan websites, the shortlist often includes:

• A local payment gateway or aggregated gateway such as PayHere.
• A local provider such as WEBXPAY where its integration routes match the project.
• Bank-provided internet payment gateway options for businesses that need direct acquiring relationships.
• Platform-supported local plugins where the provider officially maintains or documents them.
• Manual bank transfer, QR, or cash on delivery as fallback methods where appropriate.
• International providers only when the legal entity, country, and provider terms support the merchant model.

This guide does not rank providers because fees, approval rules, bank relationships, features, and supported business categories can change. Use current official documentation and a written provider response for final selection.

Merchant Approval Requirements

Approval is often where payment projects slow down. Build the website and paperwork to satisfy review before the planned launch date.

PayHere's current application guidance says a Sri Lankan business needs a valid business and a bank account at a local bank. It also notes that the website or app should be complete and ready to go live with actual goods or services, and should clearly display Terms, Return Policy, Privacy Policy, and business contact details such as registered business name, phone, email, and postal address. It further notes that approval is handled by a partner bank, and certain categories or models may be unsupported.

Use that as a practical readiness baseline even if choosing a different provider.

Website readiness checklist

Before applying, prepare:

• Real products or services, not placeholder items
• Accurate prices and currency
• Clear delivery, pickup, booking, or fulfilment process
• Terms and Conditions
• Return, refund, cancellation, or exchange policy
• Privacy Policy
• Contact page with business name, phone, email, and postal address
• About page or business identity details
• Product category clarity
• No prohibited or unsupported products
• Working checkout or payment-intent flow where required
• SSL certificate and live domain
• Bank account proof
• Business registration or allowed alternative documents

If the provider rejects the application, record the reason and whether it can be fixed. Do not build around a gateway that the business cannot actually obtain.

Unsupported or sensitive models

Payment providers may restrict categories such as regulated products, high-risk goods, multi-vendor marketplaces, donations, financial products, adult content, dropshipping, or print-on-demand. The exact list depends on provider and partner-bank policy.

If the business model is unusual, ask the provider before development:

`text

We operate [business model] selling [products/services] to [customer types]

from [legal entity and country]. We need [payment methods], [currency],

[recurring/tokenized/marketplace/refund requirement]. Is this eligible,

and which integration route do you approve?

`

Keep the provider's response with project records.

Choose the Integration Model

The integration model affects checkout UX, security responsibility, developer effort, and failure handling.

Common integration models

Choose the simplest model that supports the real requirement. A hosted or redirect checkout can be the better business choice if it reduces security exposure and approval complexity.

Hosted checkout vs embedded checkout

Hosted or redirect checkout is often suitable when:

• The provider has a strong hosted page.
• The business wants lower card-data handling responsibility.
• Development budget is limited.
• The platform plugin is officially supported.
• Payment approval and bank authentication happen off-site.

Embedded or API-heavy checkout may be suitable when:

• The customer experience requires tight control.
• The business has strong development and security operations.
• The provider supports embedded elements or token flows.
• The site has complex order states, subscriptions, or app checkout.
• The team can maintain and test the integration over time.

Do not choose embedded checkout only because it feels modern. Choose it because the added responsibility is justified.

Design the Checkout Payment Flow

A payment flow should have explicit states. Avoid treating the order as simply paid or unpaid.

Recommended order states

Do not mark an order paid only because the customer browser returned to a success page. Browser redirects can be interrupted, forged, duplicated, or delayed. A trusted server notification, transaction retrieval API, or provider dashboard reconciliation should confirm the payment.

Return, cancel and notify URLs

Most gateway integrations use some combination of:

• Return URL: where the customer goes after payment success or completion.
• Cancel URL: where the customer goes after cancellation.
• Notify URL or webhook: where the provider sends server-to-server payment status.

The notify URL is usually the most important for reliable order state. It should verify the provider signature or hash, confirm the order ID and amount, handle repeated notifications safely, and update the order only through approved state transitions.

Idempotency and duplicate events

Payment systems send repeated events. Customers double-click. Browsers refresh. Providers retry callbacks. Your integration must be idempotent, meaning the same payment event can be received more than once without creating duplicate paid orders, duplicate receipts, or duplicate analytics purchases.

Use:

• Unique order IDs
• Provider transaction IDs
• State transition rules
• Duplicate callback detection
• Transaction ID validation in analytics
• Audit logs for each payment event

Implement Order States and Callbacks

A safe integration trusts server-side verification more than front-end messages.

Payment initiation

When the customer selects payment:

1. Validate cart, stock, price, tax, discount, and shipping.

2. Create or update an order in a non-paid state.

3. Generate a unique order reference.

4. Create the payment request with exact amount and currency.

5. Sign or authenticate the request according to provider docs.

6. Store the payment session or request reference.

7. Redirect or render the gateway component.

If the amount changes after initiation, expire the old payment request and create a new one. Never let a stale payment session complete an order at an old price.

Notification handling

When receiving provider notification:

1. Verify request origin according to provider documentation.

2. Validate signature, hash, or authentication token.

3. Match order ID.

4. Confirm amount and currency.

5. Confirm transaction status.

6. Check whether the event has already been processed.

7. Update order state.

8. Record provider transaction ID and raw safe metadata.

9. Trigger receipt, fulfilment, analytics, or support workflows only once.

If verification fails, log the event and reject the update. Do not silently mark payment as successful.

Customer return page

The return page should:

• Show a clear pending or confirmed state.
• Avoid claiming payment success before server confirmation.
• Poll or refresh order status if confirmation is delayed.
• Provide order reference and support route.
• Preserve cart or retry route if payment failed or cancelled.
• Avoid firing duplicate purchase events.

A customer can return before the server-to-server callback arrives. Design for that timing gap.

Security, PCI and Sensitive Data

Payment security is not optional housekeeping. It affects customer trust, provider approval, legal exposure, and operational continuity.

Do not store card data casually

Most Sri Lankan business websites should avoid storing raw card numbers, CVV, or sensitive authentication data. Use hosted payment pages, provider-controlled fields, or approved tokenization where possible.

The PCI Security Standards Council explains that PCI DSS can still apply when a merchant outsources payment processing, and the merchant remains responsible for provider compliance, agreements, annual monitoring, shared responsibility, and validation such as the applicable Self-Assessment Questionnaire. In practical terms, outsourcing card processing reduces direct technical scope but does not eliminate responsibility.

Security checklist

Require:

• HTTPS everywhere
• Provider-approved integration method
• Secret keys stored outside source code
• Separate sandbox and live credentials
• Restricted admin access
• Webhook signature verification
• Amount and currency verification
• Secure logging without card data or secrets
• Strong password and two-factor protection for provider dashboard
• Credential rotation process
• Backups and incident response
• Dependency updates for payment plugins
• Review after theme or checkout changes

Avoid leaking secrets

Never expose:

• Merchant secret
• API secret key
• Webhook signing secret
• Private certificate
• Database credentials
• Provider dashboard login

Front-end code can expose public keys where provider docs allow it, but server secrets must stay server-side.

Testing Before Launch

Payment testing should cover happy paths and ugly paths. Real customers will find the ugly paths quickly if the team does not.

Sandbox testing

Use the provider sandbox or staging environment where available. Test:

• Successful card payment
• Failed card payment
• Customer cancellation
• Browser closed during payment
• Return without notify callback
• Notify callback without customer return
• Duplicate notify callback
• Wrong amount
• Wrong currency
• Expired session
• Out-of-stock after payment initiation
• Discount removed before payment
• Shipping unavailable
• Mobile browser payment
• Slow network
• Admin refund
• API refund if used

Keep test order references and screenshots as evidence.

Live small-value testing

When allowed, run controlled low-value live transactions before launch. Confirm:

• Customer charge appears correctly.
• Website order state updates correctly.
• Receipt email is accurate.
• Provider dashboard records the payment.
• Settlement report contains usable reference fields.
• Bank settlement reaches the right account.
• Refund process works.
• Analytics records one purchase only.

Do not skip settlement testing. A payment can appear successful at checkout while finance later struggles to match deposits to orders.

Refunds, Reconciliation and Finance

Payment integration is not finished when a customer pays. Finance and support need a complete operating loop.

Reconciliation requirements

Every paid order should store:

• Website order ID
• Provider transaction ID
• Payment method
• Amount
• Currency
• Fee if available
• Settlement batch or date when available
• Customer email or account ID
• Refund status
• Risk or dispute status where available

Finance should be able to export orders and match them with gateway settlement reports and bank deposits. If the provider reports net settlement after fees, the accounting process should record gross revenue, fees, refunds, and net deposits clearly.

Refund workflow

Define:

• Who can approve refunds
• Whether refunds happen in website admin, provider dashboard, or bank transfer
• Whether partial refunds are supported
• Whether returned stock is required first
• How customers are notified
• How refunds appear in analytics
• How finance records refund date and amount
• What happens when a refund fails

Refunds are not only a customer-service issue. They affect inventory, revenue reporting, tax, payment fees, and support trust.

Analytics and Conversion Tracking

Payment integration should preserve measurement quality. Otherwise a business may think checkout is failing when analytics is broken, or think sales are growing when duplicate purchase events are firing.

Recommended events

Track:

• begin_checkout
• add_shipping_info
• add_payment_info
• purchase
• refund
• payment_failed
• payment_cancelled
• payment_pending
• payment_method_selected
• gateway_error

GA4's recommended ecommerce events include begin_checkout, add_shipping_info, add_payment_info, purchase, refund, view_cart, add_to_cart, remove_from_cart, and product-view events for online sales. Use the recommended event names where they fit, then add custom events for provider-specific failures.

Validate purchase tracking

Confirm:

• Purchase fires only after trusted payment confirmation.
• Transaction ID is unique.
• Browser refresh does not duplicate purchase.
• Payment failure does not fire purchase.
• Refund event maps to original transaction where possible.
• Payment redirects preserve attribution as much as consent and browser behavior allow.
• Server order totals reconcile with analytics.

For broader measurement planning, connect this article to the future analytics article in this cluster and use the Marketplace Analytics KPI Guide for business metric discipline.

WooCommerce, Shopify and Custom Websites

The right integration route depends on platform ownership and flexibility.

WooCommerce

WooCommerce can be practical for Sri Lankan payment integration because local providers often publish plugins. Before installing one:

• Confirm the plugin is official or actively maintained.
• Check compatibility with current WooCommerce and WordPress versions.
• Test checkout, refunds, currencies, taxes, shipping, and emails.
• Confirm the plugin does not store sensitive card data.
• Check how it handles callbacks and duplicate notifications.
• Keep a staging copy for updates.

Compare operational ownership in the Shopify vs WooCommerce Guide before committing.

Shopify

Shopify payment options depend on country, provider, app/plugin support, and current platform rules. Confirm whether the selected local gateway has official Shopify documentation or app support, and test the exact flow on the target plan. Some checkout customization may be restricted by Shopify plan and app capability.

For local decision-making, use the Shopify vs WordPress for Sri Lankan Businesses guide.

Custom websites and Next.js applications

Custom sites should use provider APIs and SDKs deliberately:

• Keep secret signing logic server-side.
• Use server actions or API routes carefully.
• Store order and payment states in the database.
• Validate callbacks before updating orders.
• Use environment variables for credentials.
• Separate sandbox and production settings.
• Add automated tests for signature and state transitions.
• Log safely without exposing secrets.

Custom development is justified when the business needs a flow that plugins cannot reliably support. For implementation help, review the E-Commerce Development Service.

Common Integration Mistakes

Avoid these mistakes:

• Building checkout before confirming provider approval.
• Assuming Stripe, PayPal, or another global provider supports direct Sri Lankan merchant onboarding.
• Applying with an unfinished website and placeholder products.
• Missing Terms, Return Policy, Privacy Policy, or business contact details.
• Using a plugin that is outdated or not provider-approved.
• Marking orders paid from the return URL alone.
• Not validating notify/webhook signatures.
• Ignoring amount and currency mismatch.
• Creating duplicate paid orders after callback retry.
• Storing secrets in source code.
• Logging sensitive card or customer data unnecessarily.
• Forgetting refunds and reconciliation.
• Testing only one successful payment.
• Launching without small-value live testing.
• Firing duplicate purchase analytics events.
• Giving the developer sole ownership of the merchant account.

The best integration is boring in production: predictable, testable, logged, reconciled, and easy for staff to operate.

100-Point Payment Integration Readiness Score

Use this score before launch or when auditing a broken integration.

Scoring guidance:

• 90-100: Ready for launch or controlled scaling.
• 75-89: Solid foundation; fix remaining operational gaps before campaigns.
• 60-74: Usable but risky; complete testing, callbacks, or finance workflows.
• 40-59: Not launch-ready; payment success may not equal operational success.
• Below 40: Stop and rebuild the payment plan before accepting real customers.

Frequently Asked Questions

Which payment gateway is best for Sri Lankan websites?

There is no universal best gateway. The right choice depends on business eligibility, product category, customer location, currencies, payment methods, platform, recurring needs, refund process, fees, settlement reporting, and support. Shortlist providers using current official documentation and written eligibility confirmation.

Can a Sri Lankan business use Stripe?

Do not assume direct Stripe merchant onboarding is available for a Sri Lankan business. Stripe support depends on business location, account eligibility, payment method rules, and current country availability. Check official Stripe availability and terms before designing around Stripe.

What does a Sri Lankan website need before gateway approval?

A practical baseline is a valid business, local bank account, complete website, real goods or services, clear Terms, Return Policy, Privacy Policy, business contact details, and provider-accepted product category. The exact requirements depend on provider and partner-bank review.

Should I use a payment plugin or custom API integration?

Use an official, maintained plugin when it satisfies the business requirements and handles callbacks, refunds, currencies, and platform compatibility correctly. Use a custom API integration when the website has requirements that plugins cannot reliably support, such as complex order states, subscriptions, booking deposits, or custom applications.

Is a hosted payment page bad for conversion?

Not necessarily. A trusted hosted page can reduce security scope and simplify approval. It may be better than a fragile embedded checkout. The important questions are whether the flow is clear, mobile-friendly, reliable, trusted, and easy to recover from if payment fails or is delayed.

When should an order be marked paid?

Mark an order paid only after trusted payment confirmation, usually through a verified server notification, transaction lookup, or provider-confirmed status. Do not rely only on the customer returning to a success URL.

What payment tests are required before launch?

Test successful payment, failed payment, cancellation, timeout, duplicate callback, missing callback, wrong amount, wrong currency, expired session, mobile flow, refund, analytics purchase event, and settlement reconciliation. Keep evidence for each test.

Do I need PCI compliance if I use a payment provider?

You may still have PCI responsibilities even when outsourcing payment processing. The PCI Security Standards Council says merchants remain responsible for ensuring provider compliance, written responsibility agreements, annual monitoring, shared responsibilities, and required validation. Confirm the applicable requirements with your provider, acquirer, or compliance-accepting entity.

How do refunds affect the website?

Refunds affect order status, inventory, customer emails, revenue reporting, analytics, fees, tax, and reconciliation. Define whether refunds are handled in the website admin, provider dashboard, or manually, and whether partial refunds are supported.

Who should own the gateway account?

The business should own the merchant account, provider dashboard, bank relationship, credentials, recovery email, settlement reports, and official communications. Developers can be granted limited access for implementation, but account ownership should not sit with an outside contractor.