Coder Legion - Recent posts tagged payment-integration

Why Most Crypto Payment Startups Get Stuck at Compliance (and How to Launch Without a 12-Month Delay

Fri, 16 Oct 2026 07:58:28 +0000

Launching a crypto payment startup is not just a technology challenge. Founders must figure out how payments will move, which jurisdictions they can serve, how customer funds will be handled, and what regulatory obligations apply to their business model.

Many teams start by building a payment dashboard, integrating blockchain networks, and connecting merchants. Then they discover that licensing questions, banking relationships, transaction monitoring, and compliance requirements can affect the entire launch plan.

The result is often months of rework, delayed partnerships, and development costs that continue to grow before the first transaction is processed.

The solution is not to bypass compliance or rush into production. It is to identify regulatory requirements early, choose the right payment architecture, and build compliance considerations into the development process from the beginning.

For founders planning a crypto payment business, this approach can help reduce avoidable delays while preparing the platform for a more controlled launch.

Why Crypto Payment Startups Get Stuck at Compliance?

Compliance problems rarely appear in isolation. They often reveal decisions that should have been addressed before development began.

1. Choosing a Business Model Before Understanding Regulatory Requirements

A crypto payment gateway that allows merchants to accept digital assets may have different obligations from a platform that converts cryptocurrency into fiat currency, holds customer funds, or transfers assets between users.

These distinctions matter because regulatory treatment depends on the activities performed, the jurisdictions involved, and the entities handling the transactions.

For example, a startup that only provides payment software may have a different compliance profile from one that receives, converts, or transmits customer funds.

Founders should map the complete payment flow before choosing a technical architecture. This includes identifying who receives the payment, who controls the assets, whether conversion occurs, and which third parties participate.

2. Treating KYC and AML as Features to Add Later

Know Your Customer (KYC) and Anti-Money Laundering (AML) controls should not be treated as optional dashboard features that can simply be added before launch.

Depending on the business model and applicable law, a payment platform may need customer identification, risk classification, sanctions screening, transaction monitoring, recordkeeping, and suspicious activity reporting processes.

The Financial Action Task Force (FATF) sets international standards for virtual asset service providers, including relevant customer due diligence and transaction monitoring obligations. Local implementation and requirements vary by jurisdiction.

When founders postpone these decisions, they may need to redesign onboarding, transaction processing, data storage, and administrative workflows later.

A better approach is to define the applicable compliance requirements before development and translate them into technical and operational requirements.

3. Underestimating Licensing and Jurisdictional Requirements

A crypto payment startup cannot assume that operating online removes the need for regulatory authorization.

Some jurisdictions require specific licenses or registrations for certain payment, money transmission, or virtual asset activities. Others restrict particular services or impose additional requirements on businesses serving local customers.

For example, in the United States, FinCEN guidance explains that certain virtual currency administrators and exchangers may qualify as money transmitters, depending on their activities and applicable exceptions. State-level requirements may also be relevant.

Founders must assess their actual activities rather than relying on a generic checklist.

Before development begins, determine:

Where the company will be incorporated and operate
Which countries or regions the platform will serve
Whether the business will custody, exchange, or transmit digital
assets
Whether fiat currency conversion or payment processing is involved
Which licenses, registrations, or regulatory approvals may apply
Which banking, payment, and compliance partners are required

Getting these questions answered early helps prevent a platform from being built around an operating model that cannot be used as planned.

4. Waiting Too Long to Approach Banking and Payment Partners

A payment platform may be technically functional but still struggle to launch because its banking, fiat payment, or conversion partners have not approved the proposed business model.

These providers often conduct their own due diligence. They may request information about company ownership, transaction flows, customer profiles, source-of-funds controls, expected volumes, and compliance procedures.

If founders approach potential partners only after development is complete, an approval delay can leave the entire project waiting.

Instead, engage relevant providers during the planning phase. Confirm their supported jurisdictions, onboarding criteria, settlement methods, integration requirements, and restrictions before committing to the final architecture.

5. Building a Payment System That Cannot Support Compliance

A crypto payment gateway needs more than the ability to generate wallet addresses and detect blockchain transactions.

Depending on its operating model, the platform may also require transaction records, payment status tracking, customer verification workflows, risk alerts, administrative review tools, and reporting capabilities.

If these requirements are overlooked, developers may need to rebuild major parts of the system to support them.

A well-planned architecture should account for compliance-related data and workflows from the start, while applying appropriate access controls, data protection, and retention policies.

How to Reduce Compliance Delays Without Cutting Corners

There is no universal way to launch every crypto payment startup within a fixed number of weeks.

However, founders can reduce avoidable delays by handling regulatory planning and technical development in parallel where appropriate.

Step 1: Define the Exact Payment Model

Start by documenting how the platform will operate.

Will merchants receive crypto directly, or will the platform convert payments into fiat currency? Will the company hold customer assets? Will it provide custody, exchange services, or only payment software?

These decisions influence licensing analysis, custody arrangements, third-party integrations, and security requirements.

A clearly defined model also helps developers avoid building unnecessary features or choosing infrastructure that does not fit the business.

Step 2: Conduct a Jurisdiction-Specific Compliance Assessment

Work with qualified legal and compliance professionals to identify the requirements that apply to the proposed activities and target markets.

This assessment should cover relevant licensing or registration obligations, KYC and AML controls, sanctions screening, customer disclosures, data protection, transaction monitoring, and reporting requirements.

Create a compliance checklist that identifies the responsible party, required evidence, dependencies, and expected completion milestones.

Do not assume that a vendor's compliance tools automatically make the entire business compliant. The company remains responsible for understanding its own legal obligations.

Step 3: Choose Suitable Technology and Integration Partners

The development team should understand the business model before selecting blockchain networks, wallet infrastructure, conversion services, and payment integrations.

Evaluate providers based on supported jurisdictions, technical compatibility, security practices, service availability, onboarding requirements, and total operating costs.

For the software itself, prioritize a modular architecture that can support necessary payment workflows and compliance integrations without requiring a complete rebuild whenever requirements change.

Step 4: Build Compliance Workflows Into the Platform

Once the applicable requirements are understood, translate them into system functionality.

Depending on the business model, this could include:

Customer onboarding and identity verification integrations
Risk-based transaction monitoring
Sanctions screening and alert handling
Secure audit logs and transaction records
Payment status tracking and reconciliation
Administrative review and escalation workflows
Role-based access controls and reporting tools

Not every platform needs every feature. The goal is to build the controls required for the specific business rather than adding a long list of generic features.

Step 5: Develop and Validate the Payment Infrastructure

With the business model and core requirements established, the team can develop the payment workflows.

Essential components may include payment request generation, blockchain transaction monitoring, confirmation handling, merchant dashboards, payment notifications, settlement logic, and reconciliation.

Testing should cover failed transactions, delayed confirmations, duplicate payment notifications, incorrect payment amounts, network congestion, integration outages, and other relevant failure scenarios.

Security testing should also examine access permissions, sensitive data handling, API protection, and the security of wallet or custody integrations.

Step 6: Complete Partner Reviews and Pre-Launch Checks

Before accepting live transactions, confirm that the required approvals, partner agreements, technical integrations, and operational procedures are in place.

The pre-launch checklist should include:

Applicable licenses or registrations and required approvals
Completion of required provider onboarding
Verified payment and settlement workflows
Tested compliance controls and escalation procedures
Security assessments and remediation of critical findings
Reconciliation and incident-response procedures
Monitoring, customer support, and operational ownership

A platform should go live only when the relevant legal, operational, and technical conditions have been satisfied.

Can a Crypto Payment Gateway Launch Without a 12-Month Delay?

Yes, some projects can reach launch sooner than 12 months, but the timeline depends on what is being built and which approvals are required.

A startup using established payment infrastructure and supported third-party services may have a shorter development path than a company building its own custody systems, conversion infrastructure, and extensive payment integrations.

The distinction between software readiness and regulatory readiness is particularly important.

Some activities can proceed in parallel, such as developing non-regulated software components while the company works through its legal assessment. Other activities depend on prior decisions or approvals.

A development company can help organize the technical work and reduce unnecessary rework, but it cannot guarantee regulatory approval or eliminate delays controlled by authorities, banks, or third-party providers.

The most useful planning approach is to establish separate milestones for technical development, partner onboarding, compliance readiness, testing, and production authorization.

What Should Founders Look for in a Crypto Payment Gateway Development Company?

Choosing a development partner involves more than comparing feature lists or hourly rates. The team should understand payment workflows and be able to build infrastructure around the startup's actual business requirements.

Experience With Payment Architecture

Look for experience with blockchain integrations, payment processing, transaction monitoring, merchant dashboards, payment notifications, and settlement workflows.

Ask how the proposed architecture handles delayed transactions, failed payments, reconciliation, and service interruptions.

Integration Flexibility

The platform may need to connect with identity verification vendors, blockchain analytics providers, fiat payment processors, conversion services, or custody providers.

Confirm which integrations are available, which require additional development, and whether each provider supports the intended markets and business model.

Security and Operational Controls

Evaluate authentication, access management, sensitive data protection, wallet integration security, logging, incident response, and testing practices.

Request clear documentation of what is included in the development scope and what needs to be supplied by external providers.

Transparent Scope and Delivery Milestones

A reliable development proposal should identify deliverables, dependencies, integration costs, testing requirements, and the responsibilities of both parties.

It should also distinguish software delivery from legal advice, licensing, partner approval, and other activities outside the development team's control.

For businesses evaluating their options, a crypto payment gateway development company can be a useful starting point for discussing payment architecture, blockchain integration, merchant workflows, and the technical requirements of a proposed platform.

Dappfort provides crypto payment gateway development services for businesses planning payment infrastructure around their requirements. Before starting a project, discuss the required payment flows, supported assets, third-party integrations, security expectations, delivery milestones, and the division of responsibilities for compliance.

Common Mistakes That Can Extend the Launch Timeline

Even a well-funded startup can lose months by making avoidable planning decisions.

Building before defining the operating model: Technical decisions made before understanding the business and regulatory requirements may need to be reversed.

Assuming one license covers every market: Requirements can differ across jurisdictions and business activities.

Treating KYC and AML as vendor-only responsibilities: Third-party tools may support compliance, but they do not automatically fulfill every obligation of the business.

Leaving partner onboarding until the end: Banking, conversion, and payment provider reviews can become critical-path dependencies.

Launching before testing the full payment lifecycle: A successful payment request does not prove that confirmations, settlement, reconciliation, refunds, and exception handling work correctly.

Confusing a completed product with launch readiness: Software can be ready before the business has completed the approvals and operational preparations needed to use it.

Avoiding these mistakes does not remove every source of delay. It gives founders better control over the dependencies they can identify and manage.

Final Thoughts

Compliance is not simply a final checkpoint for a crypto payment startup. It influences the business model, payment architecture, partner selection, customer onboarding, and the conditions under which the platform can operate.

Founders who address these questions early can make better technology decisions, avoid preventable redevelopment, and create a more realistic launch plan.

The goal should not be to bypass a 12-month process at any cost. It should be to distinguish necessary regulatory and operational work from avoidable delays caused by poor planning.

With a clearly defined payment model, appropriate legal guidance, suitable integration partners, and a development team that understands the payment lifecycle, startups can work toward a faster and more controlled launch.

Before investing in a full build, document the required payment flows, confirm the relevant compliance obligations, and agree on realistic milestones for development, testing, approvals, and production readiness.

How to Use Invoicing and Payment Gateway Tools for Freelance Web Developers

Mon, 21 Sep 2026 19:57:59 +0000

Freelance web development is not only about writing code, building websites, fixing bugs, or maintaining client projects. The business side matters just as much. A developer can complete a project successfully and still create cash-flow problems by using poor invoicing practices, offering inconvenient payment methods, or failing to track outstanding balances.

Invoicing and payment gateway tools solve much of this administrative work. They allow freelance developers to create professional invoices, collect deposits, accept online payments, track payment status, and maintain records without manually managing every transaction.

The right setup also makes it easier to work with clients in different countries. Tools such as Wise Business, PayPal, and FreshBooks offer different combinations of invoicing, payment links, online payment processing, and financial administration. Their availability, supported currencies, payment methods, fees, and eligibility vary by country and account type, so developers should verify the applicable terms before choosing a service.

Why Freelance Web Developers Need a Proper Payment System
A freelance developer may handle several types of billing:

Fixed-price website projects
Hourly development work
Website maintenance
Hosting and technical support
Monthly retainers
Plugin or theme customization
Emergency bug fixes
Consulting
SEO and technical optimization
Recurring development services
Trying to manage all of these through informal messages and bank-transfer screenshots quickly becomes difficult.

A professional invoice establishes exactly what the client is paying for, how much is due, the payment deadline, and how the client can pay. It also creates a financial record that can be reconciled later.

For international clients, payment gateways and payment platforms can remove some of the friction associated with cross-border payments.

What an Effective Developer Invoice Should Contain
A professional invoice does not need to be complicated. It needs to be complete.

At minimum, include:

Your business or professional name.
Your contact information.
The client's name and billing information.
A unique invoice number.
The invoice date.
A clear description of the services.
The quantity or hours where applicable.
The price for each service.
Applicable taxes or other charges.
The total amount due.
The currency.
The payment deadline.
Available payment methods.
Relevant payment terms.
For a website project, avoid writing only "Website development" as the description. A more useful invoice could separate the work into discovery, design implementation, frontend development, backend development, deployment, and maintenance.

This gives the client a clear record of what was purchased.

Choose Invoicing Software That Matches Your Workflow
There is no single invoicing platform that every freelance developer should use. The important issue is whether the tool fits the developer's clients, location, currencies, payment methods, and accounting workflow.

Wise Business
Wise Business provides invoicing and payment-request functionality for eligible business accounts. Its current documentation states that businesses can create invoices, select the currency, add customer and service details, and send the invoice directly to the customer. Payment methods available through an invoice depend on the account and business location.

Wise also supports payment links. A business can create a payment link for a specified amount and currency, then share it with a customer. Wise states that single-use links can receive one payment, while reusable links can receive multiple payments.

This can be useful for developers who work with international clients and need to receive money in supported currencies.

However, developers should check Wise's current availability and fees for their particular country and account before promising a specific payment method to clients. Wise's documentation also shows that some card-payment features are restricted to particular regions and are unavailable to new customers in some circumstances.

PayPal
PayPal can provide another payment option for freelance developers whose clients already use PayPal.

Its Payment Links system allows businesses to create shareable payment links without building a custom checkout system. According to PayPal's current developer documentation, payment links can be shared through email, text messages, social media, or a website.

A developer could therefore create a payment request for a particular service and send the link to a client rather than asking the client to manually enter bank details.

PayPal also provides an API for businesses that require greater technical control over payment links.

That distinction matters for web developers. A developer who simply wants to collect project payments may only need the dashboard-based payment-link system. A developer building a custom client portal or application may have a reason to investigate API-based payment functionality.

FreshBooks
FreshBooks combines invoicing with online payment functionality. Its current payment documentation describes support for one-time invoices, recurring invoices, deposits, online payment options, and checkout links. FreshBooks Payments is powered by Stripe.

FreshBooks also allows businesses to configure available payment options. Depending on the business location and account, supported methods can include cards, bank transfers, PayPal, and other options.

This type of system can be particularly useful for developers who want invoicing and payment records connected rather than maintaining separate spreadsheets.

Use Deposits for Larger Development Projects
One of the most important payment practices for freelance developers is separating the project into payment stages.

Instead of completing an entire website and requesting 100 percent of the money afterward, a developer can structure the contract around milestones.

For example:

Project total: $2,000

40 percent deposit before development begins: $800
30 percent after the agreed development milestone: $600
30 percent before final delivery or deployment: $600
The exact percentages should be determined by the agreement between the developer and client.

The important point is that invoices should correspond with the agreed payment schedule.

Invoicing software can make this easier because some platforms support deposits, recurring billing, and different billing arrangements. FreshBooks, for example, explicitly supports deposit-based and recurring invoices.

Connect the Payment Method to the Invoice
Sending an invoice and then asking the client to figure out how to pay creates unnecessary friction.

A better system places the payment method directly inside the invoice.

The client should be able to see:

Amount due: $800
Due date: September 30, 2026
Payment method: Online payment
Action: Pay invoice

Payment links can provide another route.

Wise allows businesses to create payment links and share them with customers. PayPal similarly allows businesses to create and distribute payment links through websites and communications channels.

For a developer, this means a client does not necessarily need to navigate through multiple messages to determine where money should be sent.

Use Different Payment Methods for Different Clients
A freelance developer does not necessarily need to offer every payment method available.

Instead, consider where the clients are located and how they normally pay.

A local client may prefer a domestic bank transfer. An international client may prefer a card, PayPal, or another supported payment method.

The objective is to provide practical payment options while controlling transaction costs and administrative complexity.

Before enabling a payment method, check:

Transaction fees
Currency-conversion charges
Settlement time
Supported countries
Supported currencies
Refund procedures
Chargeback rules
Account eligibility
Withdrawal options
Do not advertise a payment method simply because a platform's website mentions it. Availability can depend on the developer's country, business registration, account status, currency, and other conditions.

Keep Payment Records Separate From Client Conversations
WhatsApp messages, email threads, and social-media conversations are poor substitutes for financial records.

Every invoice should have a unique reference.

For example:

INV-2026-001
INV-2026-002
INV-2026-003

When the client pays by bank transfer, the invoice number can also be used as a payment reference where the payment platform supports that workflow.

Wise specifically instructs customers paying invoices by bank transfer to include the invoice number or unique payment reference in the bank's reference field.

This makes reconciliation easier.

A developer should also maintain a simple record showing:

InvoiceClientAmountDue DateStatus
INV-001Client A$800Sept. 25Paid
INV-002Client B$1,200Sept. 30Pending
INV-003Client C$500Oct. 5Draft
The exact system can be a dedicated accounting platform, spreadsheet, or another appropriate financial-management tool.

Automate Recurring Development Payments
Many freelance developers eventually move beyond one-off projects.

Website maintenance, security updates, content changes, technical support, hosting administration, and development retainers can generate recurring revenue.

Instead of manually creating a new invoice every month, use recurring billing where the selected platform supports it.

FreshBooks currently supports recurring invoices and recurring billing profiles, while its payment system can record payments against invoices.

The developer still needs to monitor whether payments are successful and whether the client's contract remains active.

Automation should reduce administrative work, not eliminate financial oversight.

Add Payment Terms to the Contract
An invoice should not be the only place where payment expectations appear.

The freelance development agreement should establish the commercial terms before work begins.

Important terms can include:

Total project price
Deposit requirement
Milestone payments
Final payment requirement
Invoice due dates
Late-payment provisions
Revision limits
Cancellation terms
Refund terms
Ownership or licensing conditions
Hosting and maintenance charges
Third-party software costs
The invoice then implements those agreed terms.

This distinction is important. An invoice records a financial demand for services already governed by an agreement. It should not unexpectedly introduce major commercial conditions after development has started.

Do Not Ignore Transaction Fees
Payment gateways are businesses. Processing payments can involve fees, and international payments can introduce additional costs.

A developer charging $1,000 should know whether the payment platform deducts a processing fee, whether currency conversion applies, and when the funds become available.

For example, FreshBooks states that its payment services have transaction fees and that rates and available methods depend on the service and eligibility.

Wise also states that fees for payment links depend on how the customer pays.

Therefore, do not calculate project profitability solely from the invoice's gross amount.

A developer should track the amount invoiced, payment-processing costs, currency-conversion costs where applicable, taxes, and the final amount received.

Use Payment Links on Your Website
Payment links are not limited to invoices.

A freelance developer can place an appropriate payment link on a service page, client portal, or other controlled part of a website.

For example, a developer offering a fixed-price website audit could have a service page containing:

Website Audit: $150

The page can explain what the service includes and provide an appropriate payment option.

Wise's documentation describes using an open payment link on a business website, while PayPal provides payment links that can be shared through websites and other channels.

The developer should still make sure the payment description is clear. A payment button should not replace proper documentation for larger projects.

Build a Simple Payment Workflow
A freelance developer can reduce administrative problems by creating a standard workflow:

Step 1: Agree on scope

Define exactly what the client is purchasing.

Step 2: Sign the agreement

Confirm price, milestones, deadlines, revisions, and payment terms.

Step 3: Create the invoice

Assign a unique invoice number and include the agreed services.

Step 4: Request the deposit

Do not begin work until the agreed initial payment condition has been satisfied.

Step 5: Track the invoice

Record whether it is pending, partially paid, paid, overdue, or cancelled.

Step 6: Send milestone invoices

Bill according to the contract rather than relying on informal reminders.

Step 7: Confirm payment

Match the payment against the correct invoice.

Step 8: Deliver the agreed work

Follow the contractual delivery and acceptance process.

Step 9: Maintain records

Keep invoices, receipts, contracts, and payment records organized for accounting and tax purposes.

Final Considerations for Freelance Developers
Invoicing and payment gateways are not merely administrative conveniences. They are part of the infrastructure of a freelance development business.

A professional system should make four things clear: what the client purchased, how much is owed, when payment is due, and how the client can pay.

Tools such as Wise Business, PayPal, and FreshBooks provide different combinations of invoicing, payment links, online payments, and financial administration. Their capabilities and eligibility vary, so developers should verify current terms and availability before selecting a platform.

For a developer starting with small projects, the setup can remain simple. Create professional invoices, require deposits where appropriate, provide practical payment options, assign invoice numbers, track outstanding balances, and record every payment.

As the client base grows, recurring billing, automated reminders, payment links, accounting integrations, and more structured financial reporting can reduce the administrative workload.

The goal is straightforward: complete the technical work, document the commercial arrangement, make payment easy for the client, and maintain accurate records from the first invoice to the final payment.

You Are Not Selling Your Code. You Are Selling the Next Commit

Tue, 08 Sep 2026 11:35:30 +0000

I spent the last few weeks reading the documentation, pricing pages and source of every tool I could find that sells access to a private GitHub repo. I expected the comparison to come down to features. It came down to one sentence in GitHub's own docs, and after that the shopping list looked completely different.

Here is the sentence, from the page on removing an outside collaborator: "While forks of private repositories are deleted when a collaborator is removed, the person will still retain any local clones of your repository." The next line tells you the rest of the job is yours - you are responsible for making sure the people who lost access delete what they copied.

A git clone takes ten seconds. No API call reaches it. So whatever you were told about protecting your source, the plain version is this: the only thing a refund can take back is the future.

Revocation is a subscription feature, not a security feature

Once you accept that, the whole category re-sorts itself. Revocation is not there to protect your code. It is there to keep a refunded buyer or a charged-back card away from the next tag, the fixed bug, the private issue tracker, the room where the other buyers talk.

That is a boring plumbing job, and boring plumbing is exactly what you should be shopping for. It also explains the refund policies of the people already doing this at scale: several of the big commercial boilerplates simply say access, once redeemed, is not returnable. The one I found with a proper no-questions window ships a generated download rather than repo access. A refund window is cheap when the product is a snapshot.

There is a pricing consequence hiding in there too. If you sell yearly access and your tool cannot revoke on its own, you are selling lifetime access at a yearly price, whatever the checkout page says.

Three things decide this before any tool does

GitHub's own rules come first. A repo under a personal account can only take collaborator invites; team-based delivery needs an organization. Organizations on a paid plan bill per seat, and a pending invitation is already a seat. Half the tools out there work one way, half the other, and that single fact eliminates most of the list before you have compared a single feature.

Then the invitation itself, which is where sellers actually lose money. GitHub emails the invite to the buyer's primary address, not the address they paid with, and it expires after seven days. There is no page on GitHub where a buyer can see invitations waiting for them - the community request for one was opened in 2018 and people were still adding "any update?" to the thread last year.

So your real timeline is: payment, an email into an inbox you do not control, six days of silence, expiry, a 404 that reads to the buyer as "I paid and got nothing", and a support ticket on day eight. Exactly one tool I looked at treats that as its own problem and re-issues before the deadline. Every other tool, and every tutorial script, leaves you as the retry mechanism.

Then geography and who is merchant of record. Stripe's availability page lists 51 countries and regions, and seven carry an asterisk: India and Indonesia in preview, five African countries handed to Paystack. That leaves 44 where you simply sign up, against 193 UN members. If you are outside that list, the entire "just connect Stripe" branch is closed to you and the question becomes which merchant of record will take you. If you are inside it, you get to choose whether the sales tax work is yours or somebody else's, and that choice costs a few points per sale.

Every option that exists, in one breath

Hosted, nothing to run: Polar has repo access as a built-in benefit, Dodo Payments is the newest merchant of record with a GitHub entitlement, and GitHub Sponsors will do sponsors-only repos at zero percent if monthly billing and an open-source-companion shape fit you.

Storefronts where you stay the merchant: BuyMyRepo, GitPaywall, Anystack. Crypto checkout with tarballs instead of invites: gitbuyer.

Payment platforms with no GitHub feature at all, where you bring your own glue: Gumroad, Lemon Squeezy, Whop, Patreon, Ko-fi, Buy Me a Coffee. The glue is usually Zapier, Make or n8n, and the recipes you will find online reliably cover the invite and quietly skip the revoke.

Self-hosted: Honorbox, Pay2Clone, SellRepo, Lemonrepo, and RepoAccess, which is mine - I will come back to that. Plus a long tail of $7 and $20 scripts and tutorials, which is where most sellers actually start.

And the option nobody frames as an option: skip repo access entirely. Ship a zip behind a license key. If your product is a snapshot rather than a stream of updates, the whole invite lifecycle is a cost with no benefit.

Where the tool sits	Examples	Revokes without you
Hosted, built-in GitHub delivery	Polar, Dodo Payments, GitHub Sponsors	Mostly yes
Self-hosted	Honorbox, Pay2Clone, SellRepo, Lemonrepo, RepoAccess	Depends, and the differences are large
Platform plus glue	Gumroad, Lemon Squeezy, Whop and friends, wired with Zapier or n8n	Usually no

Mine has a gap, and here it is

I built one of these. RepoAccess grants a GitHub team invite when a payment webhook arrives and removes it on refunds and chargebacks, and it runs as a single Cloudflare Worker on your own account.

It does not re-issue an invitation before the seven-day expiry. Honorbox does, at day six, up to three times, reading GitHub's own expiry flag rather than trusting a calendar. That is a real gap, I am naming it in my own comparison rather than hiding it, and it is on my list.

The two-minute test

Whatever you end up choosing, do this before your first sale: issue a refund in test mode, then open your organization's People page.

If the buyer is still sitting there, the tool you bought is a granting tool, and the revoking is you.

The long version - every tool with its actual behaviour, the fee table, what a month of twenty sales costs on each path, and six questions that each end in a name - is here: How to Sell Access to a Private GitHub Repo: Every Option Compared

# We Built a Safer Bitcoin Payment Layer for Zorgax — Here's What We Learned

Sat, 29 Aug 2026 06:45:23 +0000

We Built a Safer Bitcoin Payment Layer for Zorgax — Here's What We Learned

Adding Bitcoin to an application sounds simple.

Generate an address, wait for a transaction, verify the amount, unlock the service.

In a prototype, that might be enough.

In a system designed around AI agents and autonomous infrastructure, it isn't.

We've been working on the Bitcoin payment layer for Zorgax, the AI and knowledge component of the MyZubster ecosystem.

The latest implementation milestone is now complete locally:

60 test suites. 208 tests. All passing.

But the more interesting part isn't the test count.

It's what we had to design around.

One Checkout, One Bitcoin Address

The first architectural decision was to avoid using a single Bitcoin address for every payment.

Each checkout intent receives a different address derived from an Electrum-compatible watch-only wallet.

Payment Intent #001
        ↓
    Address A

Payment Intent #002
        ↓
    Address B

Payment Intent #003
        ↓
    Address C

This gives us a much cleaner relationship between an intent and its blockchain activity.

Instead of asking:

Which customer sent this transaction?

we already have a strong association between the destination address and the checkout.

It also avoids unnecessarily reusing the same public address across unrelated payments.

The Application Doesn't Need the Spending Keys

A payment service needs to observe money.

It doesn't necessarily need permission to spend it.

That's why the architecture uses a watch-only boundary.

             ZORGAX

                ↓

        Watch-Only Wallet

                ↓

              XPUB

                ↓

       Address Derivation

                ↓

       Blockchain Monitoring

The application can derive and monitor addresses without holding the corresponding private spending keys.

That's an important security boundary.

If the web application doesn't need the capability to spend funds, we shouldn't give it that capability.

Bitcoin Amounts Are Integers

Another rule: don't make financial correctness depend on floating-point arithmetic.

Bitcoin gives us a convenient smallest unit:

1 BTC = 100,000,000 satoshis

So internally we verify integer satoshi values.

Instead of reasoning about:

0.00125000 BTC

the system can reason about:

125000 sats

Expected amount:

Received amount:

Comparison:

125000 == 125000

Boring?

Absolutely.

That's exactly what I want from payment arithmetic.

Distributed Systems Retry Everything

Then we reach one of the more important problems.

Imagine the blockchain watcher detects a transaction.

It sends the event to the application.

The application processes it successfully.

But the acknowledgement gets lost.

The watcher retries.

Without protection:

TX detected
    ↓
Payment processed
    ↓
Network problem
    ↓
Retry
    ↓
Payment processed AGAIN

That's unacceptable.

So transaction processing needs to be idempotent.

The TXID becomes part of that boundary.

Incoming TXID
     ↓
Already processed?
   ↙             ↘
 YES             NO
  ↓               ↓
Stop            Verify
                  ↓
                Record

The same blockchain transaction should not create multiple economic effects because a distributed system retried a message.

Valid Doesn't Mean Valid Everywhere

There's another subtle distinction.

A real Bitcoin transaction can be perfectly valid on-chain and still be invalid for a particular checkout.

That's why we also need anti-replay protections.

Payment verification isn't simply:

Is this TX valid?

It is closer to:

Does this transaction
        ↓
belong to this payment intent
        ↓
for this derived address
        ↓
for this expected amount
        ↓
and has it already been consumed?

The transaction has context.

That's especially important once machines start consuming payment APIs automatically.

Database State Is Part of the Deployment

Payment systems don't live entirely inside application code.

Adding new payment behavior changes persisted state too.

For Zorgax, that means MongoDB migration needs to be treated as an explicit deployment operation.

Not:

git push
   ↓
hope

But:

Code
 ↓
Tests
 ↓
Review
 ↓
Migration Plan
 ↓
Infrastructure Check
 ↓
Database Migration
 ↓
Deployment
 ↓
Enable Rail

The migration should be controlled independently from writing the feature.

Feature Flags Are Security Features Too

The Bitcoin rail currently remains disabled.

Not because the implementation hasn't been tested.

Because the surrounding production infrastructure isn't ready yet.

The code still needs production dependencies such as the watch-only wallet XPUB and a reachable Electrum boundary through appropriately protected infrastructure.

This gives us an important rule:

CODE COMPLETE

     ≠

PRODUCTION READY

A payment feature shouldn't become active just because somebody merged the code.

Infrastructure readiness is part of feature readiness.

Where We Are Now

The current local milestone includes per-intent Electrum watch-only addresses, anti-replay protection, TXID idempotency, integer satoshi verification and a controlled MongoDB migration path.

The implementation currently passes:

60 test suites
208 tests
──────────────
ALL PASSING

The generated patch was also checked using:

git apply --check

But no production commit, push, deployment, real database migration or Bitcoin transaction was performed as part of this milestone.

That distinction matters.

Why Are We Doing This Inside an AI Project?

Because Zorgax isn't intended to remain only a chatbot.

We're exploring what happens when AI systems become capable of interacting with services and infrastructure.

Eventually an agent might need to purchase something.

Maybe compute.

Maybe an API request.

Maybe access to a specialized dataset.

Maybe a physical service.

The workflow starts looking like this:

AI Agent
   ↓
Needs Resource
   ↓
Requests Service
   ↓
Receives Payment Intent
   ↓
Payment
   ↓
Verification
   ↓
Resource Unlocked

Now the payment layer becomes part of agent architecture.

Machine Payments Change the Threat Model

Humans are relatively slow.

Agents aren't.

An automated agent could make hundreds of requests, retry failed operations and coordinate multiple services simultaneously.

That means payment infrastructure designed for agents has to assume automation from the beginning.

          AI AGENT
              ↓
       Payment Intent
              ↓
      Per-Intent Address
              ↓
            BTC
              ↓
           Electrum
              ↓
     Blockchain Detection
              ↓
       Verification Layer
        ↙      ↓       ↘
    Amount    TXID    Intent
      ↓        ↓        ↓
    sats   idempotent  replay
              ↓
        Payment State
              ↓
          SERVICE

This is where payments stop being just a UI problem.

They become a distributed-systems problem.

The Bigger Experiment

Bitcoin checkout is useful by itself.

But we're interested in what comes after it.

Imagine autonomous software where:

Agent A
   ↓
discovers
   ↓
Service B
   ↓
requests price
   ↓
Payment Intent
   ↓
settlement
   ↓
verification
   ↓
service delivered

No shopping cart.

No human clicking "Pay Now."

Potentially no traditional account relationship between the two systems.

Just protocols.

That creates a much larger engineering question:

What does payment infrastructure look like when the customer is software?

We don't have the complete answer yet.

But building the boring pieces correctly — integer amounts, idempotency, replay protection, isolated payment intents, watch-only wallets and controlled migrations — is probably where it starts.

Because autonomous payments won't become reliable by making agents smarter.

They'll become reliable by making the infrastructure underneath them predictable.

If you were designing payments specifically for autonomous AI agents, what would you prioritize first: Bitcoin, Lightning, stablecoins, traditional APIs, or protocol-native payments?

Stripe vs 10 Alternatives: Which One Is Right for Your Business? (2026)

Mon, 03 Aug 2026 04:43:28 +0000

You've decided to accept payments on your app. Naturally, you reach for Stripe — everyone does. But then you notice the 2.9% + 30¢ fee, or you realize you're selling to customers in 40 countries and have no idea how sales tax works in each one, or your client specifically asked for PayPal because "that's what their customers trust."

Suddenly "just use Stripe" isn't such an easy call anymore.

Stripe is the default answer for a reason — great docs, clean API, huge ecosystem. But it's not always the right answer. Some businesses need lower fees at scale, some need someone else to handle global tax compliance for them, some need better support for a specific region, and some just need something simpler than Stripe's flexibility gives them.

By the end of this guide, you'll know exactly how Stripe stacks up against 10 real alternatives — what each one costs, who it's actually built for, and which one fits your specific situation.

Worth noting upfront: since acquiring Lemon Squeezy, Stripe has also entered the Merchant of Record space with Stripe Managed Payments, making this comparison even more interesting in 2026 — Stripe is now competing with its own alternatives on this list. More on that later.

Why This Comparison Is Tricky

Payment processors aren't one thing. They fall into a few different categories, and comparing them apples-to-apples only works within a category:

Payment gateways / processors (Stripe, Square, Braintree, Authorize.net) — you're the merchant of record, you handle your own tax compliance, they just move the money.
Merchant of Record (MoR) platforms (Paddle, Lemon Squeezy) — they become the legal seller, they handle sales tax and VAT for you, and they take a bigger cut for it.
Wallet-first checkout (PayPal) — optimized for buyer trust and one-click checkout rather than developer flexibility.
Enterprise-grade processors (Adyen, Checkout.com) — built for large-scale, multi-region businesses with complex routing needs.
Regional specialists (Razorpay, Mollie) — dominant in specific geographies where global players are weaker.

Keep this in mind as you read — "cheaper than Stripe" doesn't matter if the platform doesn't fit your business model in the first place.

Stripe: The Baseline

Before comparing anything, here's what you're actually comparing against.

Pricing: 2.9% + 30¢ per successful card charge (US), with volume discounts available on custom plans
Best for: SaaS products, developer-first products, subscriptions, marketplaces
Strengths: Best-in-class docs, huge library ecosystem, Stripe Checkout/Elements/Payment Element for pre-built UI, strong webhook system, excellent for Next.js/React apps
Weaknesses: You're the merchant of record — you handle your own sales tax and VAT (Stripe Tax helps calculate it, but you still remit it), support can be slow for smaller accounts, standard fees aren't the cheapest at scale

💡 Tip: If you've used Stripe before, you already know most of the vocabulary in this post — Checkout Sessions, webhooks, Payment Intents. Every alternative below borrows the same mental model to some degree.

Who Should NOT Use Stripe?

Stripe isn't the right fit for everyone. Skip it (or at least don't use it alone) if:

You sell digital products globally and don't want to deal with tax registration — Stripe Tax calculates VAT/sales tax, but you're still the one registering and remitting it in every country. A Merchant of Record like Paddle removes that burden entirely.
Your customers are mostly in India — Stripe's support for UPI and local Indian payment rails is weaker than Razorpay's.
You need in-person, physical card readers — Stripe has Terminal hardware, but Square's combined online + in-person experience is more mature.
You're processing enterprise-scale volume across many countries — at that scale, Adyen or Checkout.com's negotiated interchange-plus pricing usually beats Stripe's standard rates.
Your audience specifically expects PayPal or Venmo at checkout — Stripe supports some wallets, but Braintree's PayPal/Venmo integration is more native.

1. PayPal

The one every non-technical customer already recognizes.

Pricing: ~2.99% + fixed fee per transaction (varies by country), similar ballpark to Stripe
Best for: E-commerce stores where buyer trust and one-click checkout matter more than API elegance
Strengths: Massive brand recognition — some customers only buy if PayPal is an option, built-in buyer/seller protection, works well for one-off purchases
Weaknesses: Developer experience is noticeably behind Stripe, account holds and freezes are a common complaint, less flexible for subscription billing logic

⚠️ Common Mistake: Choosing PayPal instead of Stripe. Most stores that succeed with PayPal actually offer both — PayPal as a trust-building option alongside a primary Stripe or Square integration, not as a replacement.

2. Square

Best known for physical point-of-sale, but its online payments API has matured a lot.

Pricing: 2.6% + 10¢ for in-person, ~2.9% + 30¢ for online — comparable to Stripe
Best for: Businesses that need both online and in-person payments under one system (restaurants, retail, service businesses)
Strengths: Unified dashboard for online + POS + invoicing, no monthly fees on the base plan, solid inventory and appointment tools bundled in
Weaknesses: Online-only developer experience is less polished than Stripe's, less suited to complex SaaS billing logic

Choose Square over Stripe if: you also need physical card readers or in-person sales alongside your website.

3. Braintree (a PayPal company)

Braintree is essentially "Stripe for people who also want PayPal and Venmo in one integration."

Pricing: 2.59% + 49¢ typically — slightly cheaper per-transaction than Stripe on paper
Best for: Apps that want PayPal, Venmo, and card payments through a single SDK
Strengths: Owned by PayPal, so PayPal/Venmo integration is native rather than bolted on, solid mobile SDKs (iOS/Android)
Weaknesses: Documentation and community support are noticeably smaller than Stripe's, fewer prebuilt UI components

Choose Braintree over Stripe if: your audience skews toward PayPal/Venmo as a primary payment method (common in US consumer apps).

4. Adyen

The processor institutional fintechs and large marketplaces actually use.

Pricing: Interchange-plus pricing (you pay the real card network fee + a small Adyen markup) — cheaper at high volume, but not built for small businesses
Best for: Large-scale, multi-country businesses processing serious volume (Uber, Spotify, eBay-scale)
Strengths: Single platform for 40+ payment methods across regions, excellent fraud detection (RevenueProtect), true global reach
Weaknesses: Not self-serve — you talk to a sales team, overkill (and often not even available) for early-stage products

Choose Adyen over Stripe if: you're already processing millions per month across multiple countries and need custom pricing.

5. Authorize.net

The processor that's been around since the dot-com era and quietly still works fine.

Pricing: $25/month gateway fee + 2.9% + 30¢ per transaction — more expensive than Stripe once you add the monthly fee
Best for: Traditional businesses already on legacy e-commerce platforms (older WooCommerce/Magento setups)
Strengths: Extremely stable, works with a huge number of existing shopping cart integrations
Weaknesses: Developer experience feels dated compared to Stripe, extra monthly fee makes it a worse deal for low-volume stores

Choose Authorize.net over Stripe if: you're integrating into an existing legacy e-commerce stack that already expects it.

6. Paddle

A true Merchant of Record — Paddle becomes the legal seller so you don't have to.

Pricing: ~5% + 50¢ per transaction (no separate monthly fee) — higher than Stripe, but that fee includes global tax handling
Best for: SaaS companies selling internationally who don't want to deal with VAT/sales tax registration in every country
Strengths: Handles sales tax, VAT, and invoicing compliance automatically, built specifically for SaaS subscription billing, strong checkout localization (currency, language)
Weaknesses: Noticeably higher fees than a raw payment processor, less low-level control over the checkout flow

💡 Tip: The right way to think about the extra ~2% over Stripe is: you're paying Paddle to be your tax accountant and legal seller in every country. For a solo founder, that trade is often worth it.

Where Stripe Managed Payments fits in: since acquiring Lemon Squeezy, Stripe has been building its own Merchant of Record product — Stripe Managed Payments — which entered public preview in early 2026. It's Stripe's answer to exactly what Paddle already does: Stripe becomes the seller of record and handles global tax for you, at a similar ~5% fee. Paddle still has the longer track record and a more mature product for now, but this is a space to watch — you may eventually be able to get MoR-style tax handling without leaving the Stripe ecosystem at all.

7. Razorpay

The dominant payment processor for businesses operating in India.

Pricing: ~2% per transaction domestically, higher for international cards — meaningfully cheaper than Stripe within India
Best for: Businesses primarily serving Indian customers (UPI, Indian net banking, RuPay cards)
Strengths: Deep support for local payment methods Stripe doesn't handle well (UPI, India-specific wallets), strong local compliance and support
Weaknesses: Not the right choice if your customers are mostly outside India, less relevant for Western SaaS products

Choose Razorpay over Stripe if: a meaningful share of your revenue comes from Indian customers.

8. Mollie

A European-focused processor that's become the default for a lot of EU-based SaaS and e-commerce.

Pricing: Pay-per-transaction with no monthly fees, competitive with Stripe in the EU
Best for: Businesses primarily serving European customers who want strong support for local payment methods (iDEAL, Bancontact, SOFORT)
Strengths: Excellent support for European-specific payment rails Stripe supports less natively, simple, clean API
Weaknesses: Smaller ecosystem and community outside Europe, fewer advanced billing features than Stripe Billing

Choose Mollie over Stripe if: your customers are mostly European and rely on local bank-transfer-style payment methods.

9. Checkout.com

An enterprise-grade processor competing directly with Adyen for large global merchants.

Pricing: Custom, interchange-plus — negotiated per contract, not published
Best for: Large enterprises and marketplaces with global, high-volume payment needs
Strengths: Strong presence in Europe/Middle East, excellent uptime and fraud tooling, flexible routing for high-risk industries
Weaknesses: Sales-led onboarding, not something you sign up for and integrate in an afternoon — not built for indie developers or early-stage startups

Choose Checkout.com over Stripe if: you're an enterprise processing serious volume and need a dedicated account manager and custom terms.

10. Lemon Squeezy

Worth including, with an important caveat: Stripe acquired Lemon Squeezy in 2024, and in 2026 Stripe is actively rolling out "Stripe Managed Payments" — its own native Merchant of Record product built using what it learned from that acquisition.

Pricing: 5% + 50¢ per transaction, no monthly fee
Best for: Indie SaaS founders and digital product creators who want MoR-style tax handling with a simpler, more creator-focused feature set (affiliates, license keys, digital delivery) than Paddle offers
Strengths: Very fast to set up, built specifically for solo founders and small teams, handles global tax compliance like Paddle does
Weaknesses: Its long-term roadmap is now tied to Stripe's own Managed Payments product, so some indie-specific features may not carry over if you're forced to migrate down the line

⚠️ Common Mistake: Assuming Lemon Squeezy is a fully independent alternative to Stripe. Since the acquisition, it's best thought of as "Stripe's on-ramp into the Merchant of Record space" rather than a true competitor — worth knowing before you build a long-term dependency on it.

Quick Comparison Table

Platform	Merchant of Record?	Typical Fee	Best For
Stripe	No	2.9% + 30¢	Developer-first SaaS, subscriptions
PayPal	No	~2.99% + fee	Buyer trust, one-off e-commerce
Square	No	2.9% + 30¢	Online + in-person combined
Braintree	No	2.59% + 49¢	PayPal/Venmo-heavy audiences
Adyen	No	Interchange-plus	Large-scale global enterprises
Authorize.net	No	$25/mo + 2.9% + 30¢	Legacy e-commerce stacks
Paddle	Yes	~5% + 50¢	Global SaaS avoiding tax registration
Razorpay	No	~2% domestic	India-focused businesses
Mollie	No	Pay-per-transaction	EU-focused businesses
Checkout.com	No	Custom	Enterprise, high volume
Lemon Squeezy	Yes	5% + 50¢	Indie SaaS, digital products

How to Actually Choose

Instead of picking based on fees alone, walk through these questions in order:

Do you want to handle sales tax/VAT yourself, or pay someone else to? If you'd rather not deal with tax registration in every country you sell to, go with Paddle or Lemon Squeezy. If you're fine using Stripe Tax to calculate (and then remitting it yourself), stick with Stripe or another raw processor.
Where are your customers? Mostly India → Razorpay. Mostly Europe → Mollie. Global and card-based → Stripe.
Do you need in-person payments too? If yes, Square is the only one on this list that does both well out of the box.
Are you doing enterprise-scale volume? If you're processing millions per month, Adyen or Checkout.com's custom pricing will beat any of the self-serve options.
Does your audience specifically expect PayPal? Add it as a secondary option — don't make it your only processor for a SaaS product.

For most Next.js SaaS builds, Stripe remains the safest default: best documentation, largest community, and the easiest to actually ship with. Reach for an alternative only when you have a specific, concrete reason — a region Stripe serves poorly, a tax burden you want off your plate, or a scale where custom pricing genuinely saves money.

Which Stripe Alternative Is Best for...

Quick answers if you already know your use case and just want the pointer:

...SaaS? Stick with Stripe — it's still the most complete toolkit for subscription billing, and its ecosystem of libraries and guides is unmatched.
...Subscriptions? Stripe Billing is the most flexible for custom subscription logic. If you'd rather offload tax compliance too, Paddle is purpose-built for SaaS subscriptions specifically.
...Marketplaces? Stripe Connect is the standard here, but Adyen is worth evaluating once you're processing serious volume across many countries.
...Digital Products? Paddle or Lemon Squeezy — both act as Merchant of Record, which matters a lot for indie creators selling ebooks, courses, or software licenses globally.
...Small Business? Square, if you also sell in person. Stripe or PayPal if you're online-only and want the fastest setup.
...Enterprise? Adyen or Checkout.com — both offer negotiated pricing and dedicated support that self-serve platforms don't.
...International Payments? Mollie for Europe, Razorpay for India, Paddle if you want tax compliance handled everywhere at once.
...Physical Stores? Square, hands down — it's the only option on this list built for combined online + in-person payments from day one.

Frequently Asked Questions

Is Stripe still the best choice for a first-time SaaS product?

For most cases, yes. The documentation, community support, and prebuilt components (Checkout, Payment Element) make it the fastest path to actually shipping payments in a Next.js app.

What's the real difference between a payment processor and a Merchant of Record?

A processor (Stripe, Square, Braintree) just moves money — you're legally the seller and responsible for your own tax compliance. A Merchant of Record (Paddle, Lemon Squeezy) legally becomes the seller on your behalf, which means they handle VAT/sales tax registration and remittance for you, at a higher fee.

Can I use more than one payment processor at once?

Yes, and many businesses do — for example, Stripe as the primary processor plus PayPal as a secondary option for customers who specifically prefer it. Just be aware this adds complexity to your webhook and reconciliation logic.

Are Paddle and Lemon Squeezy worth the extra fees for a solo founder?

Often, yes. If you're a single developer selling globally, the ~2% extra fee can be far cheaper than the time (or accountant fees) it would take to register and file sales tax in dozens of countries yourself.

Does switching payment processors later require rebuilding my whole app?

Not necessarily, if you've kept your payment logic reasonably isolated (a single lib/payments module, for example) rather than scattering Stripe-specific calls across your codebase. It's still real migration work — expect to touch checkout flows, webhooks, and any stored customer/subscription IDs.

Choosing a payment processor isn't a one-time decision carved in stone — plenty of companies start with Stripe and add or switch processors as their business changes shape. The important thing is picking based on your actual constraints (tax burden, region, scale) rather than just going with whichever name is most familiar.

Continue Learning

If you've decided Stripe is still the right call (it usually is), these guides walk through the actual implementation in Next.js 16:

Stripe Checkout vs Payment Element in 2026: Which One Should You Choose?

Thu, 23 Jul 2026 02:58:49 +0000

If you're planning to accept online payments with Stripe, one of the first decisions you'll need to make is how much of the checkout UI you want to build yourself versus let Stripe handle.

Historically, developers framed this as Stripe Checkout vs Stripe Payment Element — two separate products. As of 2026, Stripe has consolidated both under a single API: the Checkout Sessions API, with three selectable UI modes. This guide has been updated to reflect that change.

Many developers, especially beginners working with Next.js, still ask:

Which Stripe integration is easier?
Should I use hosted Checkout, an embedded form, or a fully custom Elements page?
Which one is better for SaaS products?
Which option offers more customization?
Can I switch later if my application grows?

In this guide, we'll compare the three UI modes, explain how each works, and help you decide which fits your project.

2026 Update: It's One API Now, Not Two Products

Stripe's current official guidance:

The Checkout Sessions API is the recommended API for most developers. The Payment Intents API is a lower-level API that you can use to build your own checkout or payments, but it requires significantly more code and ongoing maintenance. We recommend the Payment Element with Checkout Sessions for most integrations because it covers similar payment flows as Payment Intents.

In practice, this means every option below is created through the same call — stripe.checkout.sessions.create() — with a different ui_mode:

checkout.sessions.create({ ui_mode: "hosted_page" })    → full-page redirect
checkout.sessions.create({ ui_mode: "embedded_page" })  → embedded form, no redirect
checkout.sessions.create({ ui_mode: "elements" })  → fully custom UI, most control

This is the framing shift worth internalizing: it's no longer "Checkout vs Payment Element" as two separate integrations — it's one API, three levels of control, plus the older "build a PaymentIntent and drop Payment Element on it yourself" approach that still works but is now positioned as the manual, do-everything-yourself path rather than a default alternative.

Stripe also provides Checkout Studio for configuring and optimizing Checkout experiences without building every part of the UI yourself.

One of the biggest selling points of using a single checkout.sessions.create() API is the backend simplicity. Regardless of which UI mode you choose, you only need to listen for a single webhook event: checkout.session.completed. If you scales from Hosted to Elements later, your backend fulfillment logic doesn't need to change at all?

The Three UI Modes

1. Hosted (formerly "Stripe Checkout")

A full-page payment experience, either via redirect to a Stripe-hosted page or embedded full-page on your site.

         Customer
            ↓
       Your Website
            ↓
Stripe Hosted Checkout Page
            ↓
    Payment Completed
            ↓
 Your Website Success Page

Advantages

Fastest integration — a Checkout Session and a redirect is often under an hour of work
Stripe handles compliance, PCI burden is lowest here
Built-in payment methods (cards, Apple Pay, Google Pay, Link, bank transfers, regional methods) with zero extra config
Continuously optimized by Stripe for conversion and mobile

Disadvantages

Limited branding — colors/logo yes, layout no
Customer technically leaves your page (even the "embedded" hosted variant is still Stripe's iframe content)

2. Embedded (the middle option)

An embedded form on your own page — no redirect, but still Stripe-built and maintained UI, just meaningfully less code than Elements.

        Customer
           ↓
      Your Website (embedded iframe)
           ↓
Stripe Processes Payment
           ↓
      Success Page (same site)

This fills the gap the old "Checkout vs Payment Element" framing treated as binary. If your only objection to hosted Checkout was "the customer leaves my page," embedded mode solves that without taking on Elements-level implementation work.

Best for: sidebars, modals, chat-based checkout, or anyone who wants "stay on my site" without owning the full payment form's state and validation.

The established embedded mode (embedded_page) displays a full checkout form on your website, while the new 2026 preview (elements) provides smaller, modular components optimized for sidebars, chats, and modals.

3. Elements (formerly "Stripe Payment Element")

A fully custom payment form built with Stripe's PaymentElement component, giving you substantially more control over the layout, appearance, and checkout flow.

        Customer
           ↓
      Your Website
           ↓
     Payment Element
           ↓
Stripe Processes Payment
           ↓
      Success Page

Advantages

Full control over layout, branding, UX, multi-step flows
No external redirect
Best fit for complex ecommerce, upsells, custom checkout logic

Disadvantages

More development work — client secrets, form state, confirmation flow all on you
More testing surface since the flow is fully custom

💡 Note on implementation: You can reach Elements-mode UI two ways — through checkout.sessions.create({ ui_mode: "elements" }) (the current recommended path, which still gives you Stripe-managed tax/discounts/subscription logic), or the older pattern of creating a raw PaymentIntent and mounting PaymentElement yourself. The older pattern still works and is what most existing tutorials (including our own Payment Element implementation guide) show — but per Stripe's current docs, it's now the "you rebuild tax/discounts/subscriptions yourself" option, not a default equal to Checkout Sessions.

Feature Comparison

Feature	Hosted	Embedded	Elements
Setup Time	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
Customization	15 configurable settings<br/> via brand settings	70 configurable settings<br/> via the Appearance API	Full CSS customization<br/> via the Appearance API
Stripe-hosted page	Yes	No	No
Embedded on your site	No	Yes	Yes
Customer Stays on Site	No	Yes	Yes
PCI Burden	Lowest	Lowest	Low
Development Effort	Low	Low–Medium	Medium–High
Best for Beginners	Yes	Yes	No
Stripe manages <br/>tax/discounts/subscriptions	Yes	Yes	Yes (via Checkout Sessions)<br/>/ No (raw PaymentIntent)

Next.js 16 Implementation Comparison

All three modes start the same way — one checkout.sessions.create() call, differing only by ui_mode and, for Elements, how you render the result.

Hosted

API Route or Server Action
  → checkout.sessions.create({ ui_mode: "hosted_page" })
  → redirect to session.url

Embedded

API Route or Server Action
  → checkout.sessions.create({ ui_mode: "embedded_page" })
  → return session.client_secret
  → mount <EmbeddedCheckout> client-side, no redirect

Elements

API Route or Server Action
  → checkout.sessions.create({ ui_mode: "elements" })  (recommended)
     — or —
  → paymentIntents.create()  (manual, more control, more to maintain)
  → mount <PaymentElement> client-side
  → handle confirmation flow yourself

The additional flexibility in Elements mode still comes with additional implementation complexity — that part hasn't changed.

When Should You Use Each Mode?

Choose Hosted If

You're new to Stripe or building an MVP
You want the fastest implementation and least maintenance
SaaS subscriptions, digital products, small business checkout

Choose Embedded If

Your only reason to consider Elements was "keep the customer on my page"
You want Stripe-managed tax/discounts/subscriptions but don't need a fully custom form
Sidebar, modal, or chat-based checkout flows

Choose Elements If

Checkout UX is part of your product's differentiation
You need multi-step checkouts, upsells, or deeply custom logic
Enterprise or large ecommerce with requirements Stripe's prebuilt UI can't express

Decision Matrix

Your Situation	Recommendation
First Stripe integration	Hosted
SaaS product	Hosted
Startup MVP	Hosted
Want to stay on your domain, minimal custom code	Embedded
Chat / modal / sidebar checkout	Embedded
Custom checkout design	Elements
Enterprise application	Elements
Large ecommerce store	Elements

Performance & Security

Both dimensions remain effectively a tie across all three modes when implemented correctly — Stripe's infrastructure backs PCI compliance, SCA, 3D Secure, and fraud detection identically regardless of ui_mode. Choose based on UX and development bandwidth, not performance or security differences.

Migration Path

Nothing here has changed conceptually — you're still not locked in:

      Launch MVP
          ↓
   Hosted (fastest)
          ↓
   Validate Product
          ↓
Need to stay on-site → Embedded
          ↓
Need full custom UX → Elements

Since all three now share the same underlying checkout.sessions.create() call, moving between hosted and embedded in particular is a smaller lift than it used to be — you're mostly changing ui_mode and how you render the result, not rebuilding your integration from scratch.

Frequently Asked Questions

Is this still "Checkout vs Payment Element"?

Not officially, as of 2026 — Stripe now frames it as one Checkout Sessions API with three UI modes (hosted, embedded, elements). The old terms still describe the same UX outcomes, which is why this post keeps using them alongside the new framing.

Which is easiest with Next.js 16?

Hosted, by a clear margin. Embedded is a close second and removes the "customer leaves the page" downside with only a modest increase in code.

Should I still use a raw PaymentIntent + Payment Element instead of Checkout Sessions elements mode?

Only if you're deliberately managing tax, discounts, subscriptions, and currency conversion yourself. Stripe's current docs are explicit that Checkout Sessions is the default recommendation; raw PaymentIntents are for when you want to opt out of Stripe managing those pieces.

Can I use subscriptions with all three modes?

Yes — subscription mode works the same across hosted, embedded, and elements.

Can I switch later?

Yes, and it's easier now than before since all three share the same Checkout Sessions foundation.

Final Recommendation

Start with hosted unless you have a specific reason not to — it's still the fastest path to a working, compliant checkout. Reach for embedded the moment "customer leaves my site" is your only objection. Save elements for when checkout UX is a genuine product requirement, not a default choice.

Helpful Resources

Continue Learning

If you'd like step-by-step implementation guides, check out these tutorials:

These guides walk through complete setup, API routes, server actions, webhooks, and production deployment for both Stripe integrations. Note: both linked implementation guides currently show the pre-2026 direct integration pattern (raw Checkout Session redirect / raw PaymentIntent + Elements) rather than the unified Checkout Sessions ui_mode approach — updates to those are planned.

How to Integrate Stripe Payment Element with Next.js 16 (2026 Edition)

Sun, 19 Jul 2026 05:52:33 +0000

Stripe Payment Element is one of the best ways to accept payments in modern web applications. It keeps sensitive card information on Stripe servers, helping reduce PCI (Payment Card Industry) compliance complexity.

In this beginner-friendly guide, you'll learn how to integrate Stripe Payment Element with Next.js 16 using:

App Router
Server Actions
Payment Intents
Stripe Webhooks
TypeScript

By the end of this guide, you'll have a fully working checkout flow.

What We Are Building

In this tutorial, we'll create a simple SaaS pricing page with two packages:

Package	Price
Harmony	399
Legacy	599

When the user clicks a package:

A Stripe Payment Intent will be created
Stripe Payment Element will appear
User enters payment details
Payment is confirmed
Stripe webhook handles payment success

This guide mainly focuses on the Stripe integration rather than UI design, so we will keep the UI simple.

Two Ways to Accept Payments in Stripe

Stripe provides two main checkout methods.

1. Stripe Hosted Checkout

Stripe hosts the entire checkout page.

User flow:

Your Website → Stripe Checkout → Back to Your Website

This method is easier to set up. I've full guide covering this method please visit How to Integrate Stripe Hosted Checkout with Nextjs 16
.

2. Stripe Payment Element (What We'll Use)

Stripe checkout form is embedded directly inside your website.

Benefits:

Better UX
Fully customizable
No redirect before payment

Create a Next.js 16 Project

Run:

npx create-next-app@latest myapp

Choose your preferred setup.

Recommended:

TypeScript
App Router
src directory
React Compiler

Install Stripe Packages

Run:

npm install stripe @stripe/react-stripe-js @stripe/stripe-js

These packages help us:

Package	Purpose
stripe	Server-side Stripe SDK
@stripe/react-stripe-js	React components for Stripe
@stripe/stripe-js	Loads Stripe in browser

Stripe Setup

Create Stripe Server Instance

Create:

lib/stripe/server.ts

import Stripe from "stripe";

export const stripe = new Stripe(
  process.env.STRIPE_SECRET_KEY!,
  {
    apiVersion: "2026-04-22.dahlia",
  }
);

What Does This Do?

This creates a Stripe instance on the server side.

We'll use this object to:

Create Payment Intents
Handle webhooks
Access Stripe APIs securely

Create Stripe Client Instance

Create:

lib/stripe/client.ts

import { loadStripe } from "@stripe/stripe-js";

export const stripePromise = loadStripe(
  process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
);

Why Do We Need This?

Stripe Payment Element runs in the browser.

This file loads Stripe safely on the client side.

Get Stripe API Keys

Go to the Stripe Dashboard:

Open the sidebar
Enable Test Mode

This gives you test keys instead of live keys.

You should use:

sk_test_
pk_test_

while developing locally.

Create Environment Variables

Create:

.env.local

STRIPE_SECRET_KEY=sk_test_xxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
NEXT_PUBLIC_APP_URL=http://localhost:3000

Understanding Environment Variables

Why NEXTPUBLIC?

Variables that start with NEXT_PUBLIC_ can be accessed on the client side.

This is safe for publishable Stripe keys.

Important:

Never expose your Stripe Secret Key to the client side.

Create Package Constants

Create:

lib/constants/package-tier.ts

export const PKG_TIER = {
  HARMONY: "harmony",
  LEGACY: "legacy",
} as const;

export const PACKAGES = {
  harmony: {
    id: "harmony",
    name: "Harmony",
    price: 399,
  },

  legacy: {
    id: "legacy",
    name: "Legacy",
    price: 599,
  },
};

export type PkgTierType = keyof typeof PACKAGES;

Why Store Package Data in One File?

This is a very important practice.

Instead of hardcoding package names and prices everywhere in your app, we keep everything in one place.

Benefits:

Easier maintenance
Easier updates
Less bugs
Better scalability

For example:

If later you rename:

Harmony → Premium

You only update one file.

Create Checkout Form

Create:

src/components/checkout-form.tsx

"use client";

import {
  PaymentElement,
  useElements,
  useStripe,
} from "@stripe/react-stripe-js";

import { useState, SubmitEvent } from "react";

export function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: SubmitEvent<HTMLFormElement>) => {
    e.preventDefault();

    if (!stripe || !elements) return;

    setLoading(true);
    setError(null);

    const result = await stripe.confirmPayment({
      elements,
      confirmParams: {
        return_url:
          `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`,
      },
      redirect: "always",
    });

    if (result.error) {
      setError(result.error.message || "Payment failed");
      setLoading(false);
      return;
    }

    setLoading(false);
  };

  return (
    <form
      onSubmit={handleSubmit}
      className="space-y-4"
    >
      <PaymentElement />

      {error && (
        <div className="text-red-500 text-sm">
          {error}
        </div>
      )}

      <button
        type="submit"
        disabled={!stripe || loading}
        className="w-full rounded-md bg-black px-4 py-3 text-white disabled:opacity-50"
      >
        {loading ? "Processing..." : "Pay Now"}
      </button>
    </form>
  );
}

Understanding the Checkout Form

What is PaymentElement?

PaymentElement is Stripe's prebuilt checkout UI.

It automatically supports:

Cards
Apple Pay
Google Pay
Bank payments
Many regional payment methods

depending on your Stripe settings.

>Important:
>Some methods may not work in development mode.

What Happens on Form Submit?

When the user clicks the Pay button:

stripe.confirmPayment()

Stripe:

Validates card details
Processes payment
Handles authentication
Redirects user after success

Why Use return_url?

After payment, Stripe redirects the user to your payment success page.

Example:

/checkout/success

Create Stripe Provider

Create:

src/components/stripe-provider.tsx

import { Elements } from "@stripe/react-stripe-js";
import { stripePromise } from "@/lib/stripe/client";
import { ReactNode } from "react";

interface Props {
  children: ReactNode;
  clientSecret: string;
}

export function StripeProvider({
  children,
  clientSecret,
}: Props) {
  return (
    <Elements
      stripe={stripePromise}
      options={{
        clientSecret,
        appearance: {
          theme: "night",
        },
      }}
    >
      {children}
    </Elements>
  );
}

Customizing Stripe Appearance

You can customize:

Theme
Colors
Fonts
Border radius
Input styles

using the appearance object.

For more appearance options please visit Stripe Appearance API Docs

Create Payment Intent Server Action

Create:

lib/actions/create-payment-intent.ts

"use server";

export async function createPaymentIntent() {}

What Are Server Actions?

Before creating the payment intent, let's quickly understand Server Actions.

Server Actions are asynchronous functions that run on the server.

They help us:

Handle forms
Access databases
Call APIs securely
Mutate data

without creating traditional API routes.

Create Package List Component

Create:

src/components/package-list.tsx

"use client";

import { useActionState } from "react";

import { CheckoutForm } from "@/components/checkout-form";
import { StripeProvider } from "@/components/stripe-provider";

import { createPaymentIntent } from "@/lib/actions/create-payment-intent";

import { PACKAGES } from "@/lib/constants/package-tier";

export default function PackageList() {
  const [state, action, isPending] = useActionState(createPaymentIntent, { clientSecret: "", error: "" });

  return (
    <div>
      <form action={action}>
        {Object.values(PACKAGES).map(
          (pkg) => (
            <button
              key={pkg.id}
              type="submit"
              name="packageTier"
              value={pkg.id}
              disabled={
                isPending ||
                !!state?.clientSecret
              }
            >
              {pkg.name}
            </button>
          )
        )}
      </form>

      {state?.error && (
        <div>{state.error}</div>
      )}

      {state?.clientSecret && (
        <StripeProvider
          clientSecret={
            state.clientSecret
          }
        >
          <CheckoutForm />
        </StripeProvider>
      )}
    </div>
  );
}

>Important: The name attribute is very important inside form on button element. Later we’ll access value from form data in our server action using this name attribute.

Understanding useActionState

useActionState():

connects forms with Server Actions
manages loading state
handles server responses

It accepts:

your action function
initial state

And returns:

current state
form action
pending state

Why Use "use client"?

Hooks only work in client components.

Since we're using:

useActionState()

we must add:

"use client"

Add Component to Homepage

import PackageList from "@/components/package-list";

export default function Page() {
  return <PackageList />;
}

Update Server Action

Now let's add the actual logic.

"use server";

import { stripe } from "@/lib/stripe/server";

import {
  PACKAGES,
  PkgTierType,
} from "../constants/package-tier";

export async function createPaymentIntent(
  prev: unknown,
  formData: FormData
): Promise<{
  clientSecret?: string;
  error?: string;
}> {
  try {
    const pkgTier =
      formData.get("packageTier");

    if (
      typeof pkgTier !== "string" ||
      !(pkgTier in PACKAGES)
    ) {
      return {
        error: "Invalid package tier",
      };
    }

    const pkg =
      PACKAGES[pkgTier as PkgTierType];

    const paymentIntent =
      await stripe.paymentIntents.create({
        amount: pkg.price * 100,

        currency: "usd",

        automatic_payment_methods: {
          enabled: true,
        },

        metadata: {
          packageTier: pkgTier,
        },
      });

    if (!paymentIntent.client_secret) {
      return {
        error:
          "Failed to create payment intent",
      };
    }

    return {
      clientSecret:
        paymentIntent.client_secret,
    };
  } catch (err) {
    return {
      error:
        err instanceof Error
          ? err.message
          : "Something went wrong",
    };
  }
}

Now let’s understand this action:

Firstly it has two parameters prev we’re not using this, our default state this paramater is provided by useActionState and second formData this paramater is provided by form element.

Now we’ll use that same name attribute packageTier we provided inside form element to get the package that user has clicked on. After validation we’ll create stripe payment intent now let’s understand stripe object.

Understanding Payment Intents

A Payment Intent represents a payment session in Stripe.

It tracks:

Payment amount
Currency
Payment status
Payment method
Authentication steps

Why Multiply Amount by 100?

Stripe expects amounts in cents.

Price	Stripe Amount
$10	1000
$399	39900

What is Metadata?

Metadata allows us to attach extra information to payments.

Example:

metadata: {
  packageTier: pkgTier
}

This becomes very useful later inside webhooks.

What Does automatic_payment_methods Do?

When enabled:

automatic_payment_methods: {
  enabled: true
}

Stripe automatically shows compatible payment methods.

This is the easiest and recommended approach.

Stripe Webhooks

Now the checkout works.
But we still need a secure way to confirm payments.
This is where webhooks come in.

What Are Stripe Webhooks?

Stripe webhooks are server endpoints that Stripe calls automatically whenever events happen.

Examples:

Payment succeeded
Payment failed
Subscription renewed

Webhooks are extremely important because:

Never trust frontend payment success alone.

Always verify payments on the server.

Create Webhook Route

Create:

src/app/api/webhook/route.ts

Configure Webhook in Stripe Dashboard

From Stripe Dashboard:

Developers → Webhooks → Add Destination

Select Events

Choose:

payment_intent.succeeded
payment_intent.payment_failed

Add Webhook URL

Example:

https://yourdomain.com/api/webhook

Localhost Webhook Problem

Stripe cannot access localhost directly.

For local development, use:

ngrok
Stripe CLI

to expose your localhost server publicly. For more info please check:

Add Webhook Secret

Copy the signing secret.

Add to .env.local:

STRIPE_WEBHOOK_SECRET=whsec_xxx

Create Webhook Route Logic

export async function POST(req: Request) {
    try {
        const payload = await req.text();
        const sig = (await headers()).get('stripe-signature')!;
        let event;
        try {
            event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);
        } catch (err) {
            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
            return NextResponse.json(
                { message: `Webhook Error: ${errorMessage}` },
                { status: 400 }
            );
        }
        switch (event.type) {
            case "payment_intent.succeeded": {
                const paymentIntent = event.data.object as Stripe.PaymentIntent;

                if (paymentIntent.status !== 'succeeded') {
                    return NextResponse.json(
                        { message: 'Payment not completed' },
                        { status: 200 }
                    );
                }

                const pkgTier = paymentIntent.metadata?.packageTier;
                console.log("pkgTier", pkgTier);
                console.log("Payment success", paymentIntent.id);

                // Update database
                // Mark order paid
                // Send email
                // Trigger fulfillment

                break;
            }

            case "payment_intent.payment_failed": {
                console.log("Payment failed");
                break;
            }
        }

        return NextResponse.json({ message: 'Received' }, { status: 200 });

    } catch (err) {
        const error = err instanceof Error ? err.message : 'Something went wrong';
        console.error('error', error);

        return NextResponse.json(
            { error },
            { status: 500 }
        );
    }
}

Understanding the Webhook

Why Use req.text()?

Stripe requires the raw request body for signature verification.

In App Router:

await req.text()

works correctly without additional body parser configuration.

What Does constructEvent Do?

stripe.webhooks.constructEvent()

This verifies that the webhook request actually came from Stripe.

Without this verification, anyone could fake webhook requests.

Important Production Tip

Stripe may send the same webhook event multiple times.

Always:

Store Stripe event IDs
Ignore duplicate events

This prevents duplicate orders or emails.

Why Webhooks Matter

Your webhook is the safest place to:

Mark orders as paid
Save payment records
Send confirmation emails
Start product fulfillment

Never trust only frontend success pages.

Why Stripe expects 200

Notice in each return statement status is mostly 200.
When Stripe sends a webhook event, it waits for your server response.

200–299 → Stripe marks event as delivered successfully
400–499 → Stripe assumes your request is invalid
500+ → Stripe assumes your server failed

If Stripe does NOT get a 2xx response, it retries the webhook multiple times automatically.

Testing Stripe Payments

Use these test cards.

Successful Payment

4242 4242 4242 4242

Declined Card

4000 0000 0000 0002

3D Secure

4000 0025 0000 3155

Production Best Practices

Best Practice	Why It Matters
Use Webhooks	Never trust client-side payment success
Validate Metadata	Prevent invalid purchases
Store Event IDs	Avoid duplicate processing
Use HTTPS	Required for secure payments
Keep Secret Keys Server Side	Prevent security leaks

Final Thoughts

Stripe Payment Element is one of the best ways to build modern checkout flows according to your website theme in Next.js applications.

You now know how to:

Create Payment Intents
Use Stripe Payment Element
Handle payments
Use Server Actions
Verify Stripe webhooks
Build a production-ready checkout flow

This setup works great for:

SaaS products
Digital products
Agencies
AI tools
Membership websites

I hope this guide helps you build your own Stripe integration successfully.

Useful Resources

React useActionState Docs: https://react.dev/reference/react/useActionState
Next.js Server Actions Docs: https://nextjs.org/docs/app/getting-started/mutating-data
Stripe Payment Element Docs: https://docs.stripe.com/payments/payment-element

Continue Learning

If you'd like to learn more about stripe, check out these tutorials:

How to Integrate Stripe Checkout with Next.js 16 (2026 Edition)

Fri, 17 Jul 2026 04:44:30 +0000

If you're building a SaaS product with Next.js, one of the fastest and most reliable ways to accept payments is by using Stripe Checkout.

In this guide, you'll learn how to integrate Stripe Checkout with Next.js 16 using:

App Router
Server Actions
TypeScript
Stripe Webhooks
Hosted Checkout Pages

By the end, you'll have a fully working Stripe payment flow with webhook handling and order verification.

What We’re Building

In this tutorial, we’ll build a simple SaaS pricing flow where users can purchase one of two packages:

Harmony
Legacy

When a user clicks a checkout button:

A Stripe Checkout Session will be created
The user will be redirected to Stripe’s hosted checkout page
After payment, Stripe redirects the user back to your website
Stripe sends a webhook event to your Next.js application
Your app verifies the payment and creates an order

This guide focuses mainly on Stripe + Next.js integration rather than UI design.

Two Ways to Integrate Stripe Checkout

1. Hosted Stripe Checkout

In this method:

Users are redirected to a secure checkout page hosted by Stripe
Stripe handles payment security and PCI compliance
After payment, users are redirected back to your website

This is the easiest and safest option for most SaaS applications.

2. Embedded Stripe Checkout

In this approach:

Stripe Checkout is embedded directly inside your website
You can customize the UI more deeply
No external redirect is required

This guide focuses on the hosted checkout approach but I've full guide covering this second method please visit How to Integrate Stripe Payment Element with Nextjs 16

Create a Next.js 16 Project

Create a new Next.js application:

npx create-next-app@latest myapp

Choose the options that fit your setup.

Recommended:

TypeScript
App Router
src/ directory
React Compiler

Install Stripe

Install the official Stripe SDK:

npm install stripe

Configure Stripe Server SDK

Create the following file:

src/lib/stripe/server.ts

Add this code:

import Stripe from 'stripe';

export const stripe = new Stripe(
  process.env.STRIPE_SECRET_KEY!,
  {
    apiVersion: '2026-04-22.dahlia'
  }
);

This initializes the Stripe SDK using your secret API key.

Get Your Stripe API Keys

Go to:

https://dashboard.stripe.com

Enable Test Mode from the dashboard.

Copy your:

sk_test_... secret key
pk_test_... publishable key

Configure Environment Variables

Create a .env.local file in your project root:

STRIPE_SECRET_KEY=sk_test_****
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_****
NEXT_PUBLIC_APP_URL=http://localhost:3000

Important Notes

STRIPE_SECRET_KEY should only be used on the server
NEXT_PUBLIC_ variables are exposed to the client
Always switch to live keys before production deployment

Create Products in Stripe

Inside the Stripe dashboard:

Go to Product Catalog
Click Create Product
Enter:
- Product name
- Pricing
- Currency
- Billing type

If users pay once:

Select One-off

If users subscribe monthly/yearly:

Select Recurring

Copy Stripe Price IDs

After creating products:

Open the product
Click the three-dot menu
Click Copy Price ID

Add them to .env.local:

NEXT_PUBLIC_STRIPE_HARMONY_PRICE_ID=price_xxx
NEXT_PUBLIC_STRIPE_LEGACY_PRICE_ID=price_xxx

Create Package Constants

Create:

src/lib/constants/package-tier.ts

Add:

export const PKG_TIER = {
  HARMONY: 'harmony',
  LEGACY: 'legacy'
} as const;

export const PACKAGES = {
  harmony: {
    id: 'harmony',
    name: 'Harmony',
    description: 'The complete memorial song',
    price: 399,
    turnaroundHours: 72,
    maxRevisions: 2,
    stripePriceId: process.env.NEXT_PUBLIC_STRIPE_HARMONY_PRICE_ID!,
    features: [
      'Custom AI-generated memorial song',
      'Two rounds of lyric revisions',
      'Single-photo video with scrolling lyrics',
      'Social media versions'
    ]
  },

  legacy: {
    id: 'legacy',
    name: 'Legacy',
    description: 'Their full story, beautifully told',
    price: 599,
    turnaroundHours: 96,
    maxRevisions: 3,
    stripePriceId: process.env.NEXT_PUBLIC_STRIPE_LEGACY_PRICE_ID!,
    features: [
      'Everything in Harmony',
      'Multi-photo slideshow video',
      'Video revisions',
      'Social media versions'
    ]
  }
};

export type PkgTierType = keyof typeof PACKAGES;

Why Use Constants Instead of Hardcoded Strings?

Avoid writing values like "harmony" everywhere in your app.

Using constants:

reduces bugs
improves autocomplete
makes refactoring easier
keeps your app scalable

Create a Server Action

Create:

src/lib/actions/start-checkout.ts

Add:

"use server";

export async function startCheckout() {

}

What Are Server Actions?

Server Actions are asynchronous functions executed on the server in Next.js.

They are commonly used for:

form submissions
database mutations
payment processing
secure backend logic

Official docs:
https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations

Create Package UI

Create:

src/components/package-list.tsx

Add:

'use client';

import { useActionState } from "react";
import { startCheckout } from "@/lib/actions/start-checkout";
import { PACKAGES } from "@/lib/constants/package-tier";

export default function PackageList() {
  const [state, action, isPending] = useActionState(
    startCheckout,
    { error: '' }
  );

  return (
    <div>
      <form action={action}>
        {Object.values(PACKAGES).map(pkg => (
          <button
            key={pkg.id}
            type="submit"
            name="packageTier"
            value={pkg.id}
            disabled={isPending}
            className="border border-gray-300 p-3 disabled:opacity-50"
          >
            {isPending ? 'Redirecting...' : pkg.name}
          </button>
        ))}
      </form>

      {state?.error && (
        <div className="text-red-500">
          {state.error}
        </div>
      )}
    </div>
  );
}

Understanding useActionState

useActionState():

connects forms with Server Actions
manages loading state
handles server responses

It accepts:

your action function
initial state

And returns:

current state
form action
pending state

Render Packages on Home Page

Update your homepage:

import PackageList from "@/components/package-list";

export default function Page() {
  return <PackageList />;
}

Create Stripe Checkout Session

Now update:

src/lib/actions/start-checkout.ts

"use server";

import { redirect } from "next/navigation";
import { PACKAGES, PkgTierType } from "../constants/package-tier";
import { stripe } from "../stripe/server";

export async function startCheckout(
  prev: unknown,
  formData: FormData
) {
  try {
    const pkgTier = formData.get('packageTier') as PkgTierType;

    if (!pkgTier || !PACKAGES[pkgTier]) {
      return { error: 'Invalid package tier' };
    }

    const session = await stripe.checkout.sessions.create({
      mode: 'payment',

      line_items: [
        {
          price: PACKAGES[pkgTier].stripePriceId,
          quantity: 1
        }
      ],

      success_url:
        `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,

      cancel_url:
        `${process.env.NEXT_PUBLIC_APP_URL}/`,

      metadata: {
        packageTier: pkgTier
      },

      customer_creation: 'always',

      billing_address_collection: 'auto',

      phone_number_collection: {
        enabled: true
      }
    });

    if (!session.url) {
      throw new Error('Failed to create checkout session');
    }

    redirect(session.url);

  } catch (err) {
    return {
      error:
        err instanceof Error
          ? err.message
          : 'Failed to checkout'
    };
  }
}

Understanding the Checkout Session

mode

mode: 'payment'

Used for one-time payments.

For subscriptions use:

mode: 'subscription'

line_items

Defines what the user is purchasing.

success_url

Where Stripe redirects users after successful payment.

cancel_url

Where Stripe redirects users after cancellation.

metadata

Useful for attaching:

package IDs
user IDs
internal references

customer_creation

Automatically creates Stripe customers.

Important Security Note

Never trust prices coming from the frontend.

Always:

validate product IDs
validate Stripe price IDs
verify payments server-side

Create Stripe Webhook Route

Create:

src/app/api/webhook/route.ts

Configure Stripe Webhooks

Inside Stripe dashboard:

Go to Developers
Click Webhooks

Click Add Destination
Enter:

https://yourdomain.com/api/webhook

Select:
- checkout.session.completed
Copy the signing secret

Add to .env.local:

STRIPE_WEBHOOK_SECRET=whsec_xxx

Test Webhooks Locally

Install the Stripe CLI:

https://docs.stripe.com/stripe-cli

Run:

stripe listen --forward-to localhost:3000/api/webhook

Stripe will generate a webhook signing secret for local development.

Implement the Webhook Handler

Add:

import { PACKAGES } from "@/lib/constants/package-tier";
import { stripe } from "@/lib/stripe/server";
import { headers } from "next/headers";
import { NextResponse } from "next/server";
import Stripe from "stripe";

const endpointSecret =
  process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  try {
    const payload = await req.text();

    const sig =
      (await headers()).get('stripe-signature')!;

    let event: Stripe.Event;

    try {
      event = stripe.webhooks.constructEvent(
        payload,
        sig,
        endpointSecret
      );

    } catch (err) {
      const errorMessage =
        err instanceof Error
          ? err.message
          : 'Unknown error';

      return NextResponse.json(
        { message: `Webhook Error: ${errorMessage}` },
        { status: 400 }
      );
    }

    if (event.type === 'checkout.session.completed') {

      const session =
        event.data.object as Stripe.Checkout.Session;

      if (session.payment_status !== 'paid') {
        return NextResponse.json(
          { message: 'Payment not completed' },
          { status: 200 }
        );
      }

      const pkgTier =
        session.metadata?.packageTier;

      const customerDetails =
        session.customer_details;

      const customerEmail =
        customerDetails?.email;

      if (!pkgTier || !(pkgTier in PACKAGES)) {
        throw new Error('Invalid package tier');
      }

      if (!customerEmail) {
        throw new Error('Customer email required');
      }

      // Create database order here
      // Send confirmation email here
    }

    return NextResponse.json(
      { message: 'Received' },
      { status: 200 }
    );

  } catch (err) {

    const error =
      err instanceof Error
        ? err.message
        : 'Something went wrong';

    console.error(error);

    return NextResponse.json(
      { error },
      { status: 500 }
    );
  }
}

Why Use `req.text()`?

In Next.js App Router route handlers, we can safely use:

await req.text()

Unlike Pages Router, no additional body-parser configuration is required.

Prevent Duplicate Orders

Stripe automatically retries failed webhooks.

Always store:

Stripe event IDs
checkout session IDs

before processing orders.

This prevents:

duplicate emails
duplicate orders
duplicate fulfillment

Subscription Webhook Events

This guide focuses on one-time payments.

If you're using subscriptions, also listen for:

invoice.paid
customer.subscription.updated
customer.subscription.deleted

Test Your Checkout

Start your Next.js app:

npm run dev

Click one of your package buttons.

You should:

Redirect to Stripe Checkout
Complete payment
Return to your website
Receive webhook events successfully

Final Thoughts

You now have a fully working Stripe Checkout integration using:

Next.js 16
App Router
Server Actions
Stripe Webhooks
TypeScript

This setup is scalable, production-friendly, and ideal for SaaS applications.

From here you can expand into:

subscriptions
invoices
customer portals
usage billing
Stripe Connect
embedded checkout

Useful Resources

Stripe Documentation: https://docs.stripe.com
Next.js Documentation: https://nextjs.org/docs
Stripe Checkout Docs: https://docs.stripe.com/payments/checkout

Continue Learning

If you'd like to learn more about stripe, check out these tutorials:

WooCommerce Payment Gateway Integration Guide: Stripe, PayPal & More

Sat, 20 Jun 2026 17:43:23 +0000

Setting up payment gateways correctly is one of the most important steps in launching a WooCommerce store — get it wrong, and you lose sales at checkout before they ever complete. This guide covers the most common payment gateways for small-to-mid-level WooCommerce stores, how they compare, and what to watch out for during setup.

What Payment Gateways Work Best with WooCommerce?

WooCommerce supports dozens of payment gateways, but for most small and mid-sized stores, three options cover almost every use case: Stripe, PayPal, and WooCommerce Payments (built directly into WooCommerce). Each has different fee structures, checkout experiences, and country availability, so the right choice depends on where your customers are and how you want checkout to feel.

How Do You Set Up Stripe with WooCommerce?

Stripe integrates with WooCommerce through the official WooCommerce Stripe Gateway plugin. After installing it, you connect your Stripe account via API keys (found in your Stripe dashboard under Developers > API Keys), enable the payment methods you want to accept (cards, Apple Pay, Google Pay), and configure your checkout to either redirect or use Stripe's embedded card fields for a smoother on-site experience.

The biggest advantage of Stripe is that customers never leave your site to pay — this typically improves conversion rates compared to gateways that redirect to an external page.

How Do You Set Up PayPal with WooCommerce?

PayPal offers a few integration options, but the most reliable for WooCommerce is the official WooCommerce PayPal Payments plugin. It supports both PayPal account payments and direct card payments without requiring the buyer to have a PayPal account, which removes a common checkout friction point.

PayPal is worth keeping even alongside Stripe, since some customers specifically prefer or trust PayPal more, especially for higher-value B2B purchases.

Stripe vs PayPal: Which Should You Use?

Factor	Stripe	PayPal
Checkout experience	Stays on your site	Can redirect (or use card fields)
Transaction fees	~2.9% + $0.30 (varies by country)	~2.9% + $0.30 (varies by country)
Buyer trust	Strong, especially for cards	Very strong, especially internationally
Setup complexity	Plugin + API keys	Plugin + business account
Best for	Card-first, fast checkout	International buyers, B2B trust

For most stores, running both side by side gives customers a choice without adding much setup overhead — and it's a pattern we recommend for small-to-mid-level WooCommerce stores serving US, UK, and international customers.

What Are Common Payment Gateway Integration Mistakes?

The most common issues we see on WooCommerce stores are: leaving test/sandbox API keys live in production, not enabling SSL before processing live payments (which breaks PCI compliance), and not testing the full checkout flow on mobile before launch. Always run a full test transaction with each gateway before going live, and double-check your SSL certificate is active across the entire checkout flow.

Does Hosting Affect Payment Gateway Performance?

Yes — checkout speed and reliability depend heavily on server response time, especially during payment processing redirects and webhook callbacks. Slow or unreliable hosting can cause failed transactions or timeout errors at the worst possible moment: checkout. We recommend OceanWebHosting Dedicated Servers for WooCommerce stores that need consistent uptime and fast response times during checkout.

Frequently Asked Questions

Can I use both Stripe and PayPal on the same WooCommerce store?
Yes, and it's generally recommended. Offering both gives customers a choice and can reduce checkout abandonment from buyers who prefer one method over the other.

Do I need an SSL certificate for WooCommerce payment gateways?
Yes, SSL is required for PCI compliance and most payment gateways won't process live transactions without it.

How much does it cost to set up payment gateway integration on WooCommerce?
For most small-to-mid-level stores, professional payment gateway integration (Stripe, PayPal, or both) typically starts from $400, depending on complexity and any custom checkout requirements.

Can a developer help if my payment gateway isn't working correctly?
Yes — common issues like failed webhooks, incorrect API key setup, or checkout errors are usually quick to diagnose and fix. See our guide on hiring a WooCommerce developer for help.

Originally published on amanurrahman.com

How to Create a One-Time Payment Link and Secure Webhook Integration with Stripe

Mon, 27 Oct 2025 12:06:28 +0000

Introduction

Stripe is an online payment platform for securely accepting credit cards, bank transfers, and more.
This guide demonstrates an end-to-end integration using Stripe Checkout Sessions for one-time payments and a tamper-proof server webhook to confirm transactions.

Terminology: "Payment Link" here refers to the URL returned by a Stripe Checkout Session (not Stripe's no-code "Payment Links" product).

Payment Flow Overview

Client clicks "Pay Now".
Backend creates a unique Checkout Session and returns the session URL.
Client is redirected to Stripe, completes payment, and is redirected to your success URL.
Stripe sends an asynchronous webhook (server-to-server) to your backend.
Backend verifies the webhook signature, updates the database, and fulfills the order.
Client gains access to the purchased resource.

Textual Diagram (ASCII)

Client (browser)
    |
    | Click "Pay Now"
    v
Backend (your server)
    - create Checkout Session -> returns session.url
    |
    | Redirect to Stripe Checkout
    v
Stripe Checkout (Hosted)
    - collects payment
    |                       \
    | Redirect to success_url   POST webhook -> /api/webhook
    v                       /
Client (success_url)       /
                          v
Backend Webhook Handler <-- verifies signature, idempotency, updates DB
    |
    v
Fulfillment / Grant access to client

Quick Setup

1. Install packages

npm install stripe dotenv

2. .env (example)

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
CLIENT_URL=http://localhost:5173

3. Initialize Stripe

// src/utils/stripe.ts
import Stripe from 'stripe';
import 'dotenv/config';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string,);

export default stripe;

Create Checkout Session (Backend Route)

Create a route that makes a Checkout Session and returns session.url:

// routes/payment.ts
import { Request, Response } from 'express';
import stripe from '../utils/stripe';

export const createCheckoutSession = async (req: Request, res: Response) => {
  const { id } = req.body;
  const existingProduct = { id, price: 4000, name: "Hamza's Coffee" };

  try {
    const session = await stripe.checkout.sessions.create({
      mode: 'payment',
      payment_method_types: ['card', 'link'],
      line_items: [{
        price_data: {
          currency: 'usd',
          product_data: { name: existingProduct.name, description: 'Payment for services rendered' },
          unit_amount: existingProduct.price,
        },
        quantity: 1,
      }],
      success_url: `${process.env.CLIENT_URL}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.CLIENT_URL}/payment/cancel`,
      metadata: { product_id: existingProduct.id }
    });

    res.status(201).json({ message: 'Payment Initialized Successfully', data: { url: session.url } });
  } catch (error) {
    res.status(500).json({ message: 'Error initializing payment.' });
  }
};

Webhook: Raw Body & Signature Verification

Define the webhook route before express.json() so the raw body can be used for signature verification.

Server Example

// server.ts
import express from 'express';
import bodyParser from 'body-parser';
import { webhookHandler } from './routes/webhook';
import { createCheckoutSession } from './routes/payment';

const app = express();

// Raw parser for webhook route only
app.post('/api/webhook', bodyParser.raw({ type: 'application/json' }), webhookHandler);

// Then JSON parser for all other routes
app.use(express.json());
app.post('/api/create-payment-link', createCheckoutSession);

app.listen(4000, () => console.log('Server running on port 4000'));

Webhook Handler

// routes/webhook.ts
import { Request, Response } from 'express';
import Stripe from 'stripe';
import stripe from '../utils/stripe';
import dotenv from 'dotenv';
dotenv.config();

export const webhookHandler = async (req: Request, res: Response) => {
  const sig = req.headers['stripe-signature'] as string;
  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch (err: any) {
    console.error('Webhook signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    const productId = session.metadata?.product_id;

    if (productId && session.payment_status === 'paid') {
      // IDEMPOTENCY: ensure session.id hasn't been processed already
      // Example: if (!db.processed(session.id)) { db.markProcessed(session.id); grantAccess(productId); }
      console.log(`Payment confirmed for product ID: ${productId}`);
    }
  }

  res.status(200).json({ received: true });
};

Local Testing with Stripe CLI

Forward events:

stripe listen --forward-to localhost:4000/api/webhook

Copy the whsec_... key from the CLI output into .env as STRIPE_WEBHOOK_SECRET.
Trigger event:

stripe trigger checkout.session.completed

Deployment Checklist

Deploy backend to production.
Register your live webhook URL in Stripe Dashboard (Developers → Webhooks) and subscribe to checkout.session.completed.
Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in your production environment.
Ensure idempotency checks on webhook processing.

Rationale / Key Decisions

Raw body required so Stripe signature can be verified.
Signature verification prevents forged events.
Idempotency avoids duplicate fulfillment on retries.
Stripe CLI simplifies local testing.

pawaPay PHP SDK v4.4.0 adds dual V1/V2 support

Tue, 12 Aug 2025 19:24:36 +0000

pawaPay PHP SDK v4.4.0, Dual Version Support [V1 + V2], Seamless Migration

pawaPay helps teams accept and move money across African markets with a clean API surface. In v4.4.0 of the pawaPay PHP SDK, we introduced dual version support so V1 and V2 can live together in one codebase. Think of it as two gears turning in sync, V1 for stability, V2 for velocity.

This design gives you the freedom to adopt V2 where it shines, while keeping proven V1 flows earning in production.

Why dual version support
What changed in v4.4.0
Environment setup and configuration
Full runnable examples, V1 and V2
Hosted Payment Page, end to end
Verification flow, returnUrl and verify without cURL
Testing and safety nets with PHPUnit
Migration playbook, step by step
Edge cases, country notes, and logging
Troubleshooting guide
Security notes and hardening tips
Where to get it

1) Why dual version support

Upgrading payments is risky. Teams struggle with three realities:

All or nothing switches increase outage risk.
Two SDKs mean duplicate configs and twice the drift.
Testing in production is scary without a clean rollback.

Our approach: keep V1 as the default, allow V2 to be toggled by environment or per call. You get gradual rollouts, quick comparisons, and instant fallback.

2) What changed in v4.4.0

Version aware client. Pass v1 or v2.
Hosted Payment Page usable from both versions.
Split config files for clarity: active_conf_v1.json, active_conf_v2.json, plus versioned MNO availability JSONs.
Better failure mapping via an improved FailureCodeHelper.
Cleaner errors that mention the version expectation.

3) Environment setup and configuration

Create a .env with clear tokens per environment.

# .env
ENVIRONMENT=sandbox
PAWAPAY_SANDBOX_API_TOKEN=your_sandbox_api_token_here
PAWAPAY_PRODUCTION_API_TOKEN=your_production_api_token_here

# Choose default API version across your app
PAWAPAY_API_VERSION=v1

Composer install:

composer require katorymnd/pawa-pay-integration

4) Full runnable examples, V1 and V2

A) Minimal V1 example, server side initiation

<?php
/**
 * Example: Minimal V1 deposit initiation
 * Goal, show a working flow with V1 as default.
 * Notes, reads ENV, builds a V1 client, initiates a classic deposit call.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$client = new ApiClient($apiToken, $environment, $sslVerify, 'v1');

// Payload shape may differ per version, keep V1 fields here
$resp = $client->initiateDeposit([
    'amount'      => '15000',
    'currency'    => 'UGX',
    'phoneNumber' => '256753456789',
    'mno'         => 'MTN',
    'reason'      => 'Order #1234',
]);

header('Content-Type: application/json');
echo json_encode($resp, JSON_PRETTY_PRINT);

B) Minimal V2 example, auto flow

<?php
/**
 * Example: Minimal V2 deposit initiation (auto)
 * Goal, exercise the new V2 route without touching V1 code.
 * Notes, just switch the version to v2.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$client = new ApiClient($apiToken, $environment, $sslVerify, 'v2');

// V2 supports initiateDepositAuto which may return a redirect, or a ready status
$resp = $client->initiateDepositAuto([
    'amount'      => '15000',
    'currency'    => 'UGX',
    'phoneNumber' => '256753456789',
    'mno'         => 'MTN',
    'returnUrl'   => 'https://example.com/paymentProcessed',
]);

header('Content-Type: application/json');
echo json_encode($resp, JSON_PRETTY_PRINT);

Why both examples matter
You can test V2 side by side, compare payloads and responses, and fall back to V1 with a single parameter change.

5) Hosted Payment Page, end to end

The hosted page is the fastest way to collect a payment with one redirect.

<?php
/**
 * Example: Hosted Payment Page, works with V1 or V2
 * Goal, show a clean redirect based on initiateDepositAuto.
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Katorymnd\PawaPayIntegration\Api\ApiClient;
use Katorymnd\PawaPayIntegration\Utils\Helpers;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v1';
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

if (!$apiToken) {
    http_response_code(500);
    echo 'Missing API token';
    exit;
}

$log = new Logger('pawaPay');
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_success.log', \Monolog\Level::Info));
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_failed.log',  \Monolog\Level::Error));

$client = new ApiClient($apiToken, $environment, $sslVerify, $apiVersion);

// Inputs, in real apps take these from your form
$depositId            = Helpers::generateUniqueId();
$amount               = '15000';
$currency             = 'UGX';
$msisdn               = '256753456789';
$mno                  = 'MTN';
$returnUrl            = 'https://your-app.example/returnUrl.php';
$statementDescription = 'Order 1234';

// V2 will typically return a redirect URL for the hosted page
try {
    $resp = $client->initiateDepositAuto([
        'amount'      => $amount,
        'currency'    => $currency,
        'phoneNumber' => $msisdn,
        'mno'         => $mno,
        'returnUrl'   => $returnUrl,
        'reason'      => $statementDescription,
        'metadata'    => ['depositId' => $depositId],
    ]);

    if (!empty($resp['redirectUrl'])) {
        header('Location: ' . $resp['redirectUrl']);
        exit;
    }

    // If no redirect is required, log and show the result
    $log->info('Hosted page not required', ['resp' => $resp]);
    header('Content-Type: application/json');
    echo json_encode($resp, JSON_PRETTY_PRINT);
} catch (\Throwable $e) {
    $log->error('Hosted page error', ['ex' => $e->getMessage()]);
    http_response_code(500);
    echo 'Payment initiation failed';
}

6) Verification flow, returnUrl and verify without cURL

Many teams prefer not to make HTTP calls to a sibling script. You can include the verifier directly.

verify.php

<?php
/**
 * verify.php
 * Purpose, encapsulate verification logic that can be included from returnUrl.php
 * Input, expects $client and $transactionId to be in scope when included
 * Output, returns associative array $verification
 */

if (!isset($client) || !isset($transactionId)) {
    throw new \RuntimeException('verify.php expects $client and $transactionId');
}

$verification = $client->checkTransactionStatus([
    'transactionId' => $transactionId,
]);

// The parent script will read $verification

returnUrl.php

<?php
/**
 * returnUrl.php
 * Purpose, handle redirected users after payment, then verify internally
 */

require_once __DIR__ . '/../vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

$dotenv = Dotenv::createImmutable(__DIR__ . '/..');
$dotenv->load();

$environment = getenv('ENVIRONMENT') ?: 'sandbox';
$sslVerify   = ($environment === 'production');
$apiVersion  = getenv('PAWAPAY_API_VERSION') ?: 'v2';
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';
$apiToken    = $_ENV[$apiTokenKey] ?? null;

$client = new ApiClient($apiToken, $environment, $sslVerify, $apiVersion);

// Transaction id from provider redirect or your metadata
$transactionId = $_GET['txId'] ?? $_POST['txId'] ?? null;

if (!$transactionId) {
    http_response_code(400);
    echo 'Missing transactionId';
    exit;
}

// Include verifier in-process, no cURL required
$verification = [];
require __DIR__ . '/verify.php';

// Persist result, show receipt, or redirect to success page
header('Content-Type: application/json');
echo json_encode(['verified' => true, 'result' => $verification], JSON_PRETTY_PRINT);

Why this is safe and simple
You keep the verification logic pure PHP, no extra HTTP hops, fewer moving parts, clearer stack traces.

7) Testing and safety nets with PHPUnit

A tiny guard to ensure your app respects the chosen version.

<?php
/**
 * tests/VersionSelectionTest.php
 * Purpose, assert the client honors PAWAPAY_API_VERSION, prevent regressions.
 */

use PHPUnit\Framework\TestCase;
use Katorymnd\PawaPayIntegration\Api\ApiClient;

final class VersionSelectionTest extends TestCase
{
    public function testChoosesV2WhenEnvSaysV2(): void
    {
        $client = new ApiClient('fake', 'sandbox', false, 'v2');
        $this->assertTrue(method_exists($client, 'initiateDepositAuto'), 'V2 method should exist');
    }

    public function testChoosesV1WhenEnvSaysV1(): void
    {
        $client = new ApiClient('fake', 'sandbox', false, 'v1');
        $this->assertTrue(method_exists($client, 'initiateDeposit'), 'V1 method should exist');
    }
}

Add more tests for response shape, error handling, and idempotency.

8) Migration playbook, step by step

Inventory your live flows, deposit, payout, refund, reconciliation.
Enable dual version globally with PAWAPAY_API_VERSION=v1.
Stand up V2 in sandbox, run the minimal V2 example.
Mirror payloads and compare responses, store both logs.
Dark launch V2 for a small traffic slice, or specific markets.
Monitor failure codes with FailureCodeHelper, alert on deltas.
Flip a single product line to V2, observe for one full billing cycle.
Rollback rule documented, set the env back to v1 if anything spikes.
Expand V2 to more flows after two stable weeks.
Retire V1 only when every flow is stable in V2.

Alternative to env flags
Use a feature flag service or a per request switch. Env is simple, flags give you finer control per tenant, market, or route.

9) Edge cases, country notes, and logging

MNO requirements differ. Some providers are strict on MSISDN formatting, always sanitize to digits and include country code.
Currencies vary. Lock your currency per market in config, do not trust form inputs.
Retrials. Use idempotent keys where available, or your own depositId.
Logs by version. Write to payment_v1.log and payment_v2.log so comparisons are easy.
Metadata discipline. Pass your order or cart reference to simplify reconciliation.

10) Troubleshooting guide

Missing API token, check .env names and ENVIRONMENT.
Method not found when calling V2, confirm you constructed the client with v2.
Unexpected currency error, confirm ISO code and market pairing.
Callback not firing, verify your returnUrl is public and uses HTTPS in production.
Random declines, try a different MNO in sandbox, then compare failure codes with FailureCodeHelper.

11) Security notes and hardening tips

Keep tokens outside your repo, use .env and secret managers.
Verify all incoming callbacks, do not rely only on query params, call checkTransactionStatus.
Store only what you need, mask MSISDN in logs, rotate tokens on schedule.
Enforce TLS, set sslVerify=true in production.

12) Where to get it

GitHub, https://github.com/katorymnd/pawa-pay-integration
Composer,

composer require katorymnd/pawa-pay-integration

Closing note

Dual version support is a calm bridge, not a cliff. Start with V1, test V2 where it counts, and move forward with confidence. If you want a diagram of the V1 to V2 rollout path, say the word and I will add a crisp visual.

pawaPay SDK offers secure, user-friendly mobile money integration for PHP, ideal for African e-commerce.

Mon, 25 Nov 2024 22:51:21 +0000

pawaPay Payment SDK: Streamline Your Payment Processes in PHP

In the fast-paced world of e-commerce and online transactions, efficiency, security, and simplicity are paramount. Integrating payment solutions can often be a complex and time-consuming process, especially when dealing with multiple payment methods across different regions. The pawaPay Payment SDK emerges as a robust solution, specially tailored for PHP applications, aiming to streamline the integration of pawaPay's Mobile Money payment solutions. This lightweight, easy-to-use SDK encapsulates powerful functionalities into a developer-friendly package, enabling seamless payment processes within your applications.

What is pawaPay?

pawaPay is a mobile money payment platform designed to empower businesses to seamlessly send and receive payments across various African countries using mobile wallets. With over 300 million mobile money users in Africa, pawaPay taps into this expansive ecosystem, providing rapid settlements, eliminating chargebacks, and ensuring secure transaction processing—all accessible from a unified dashboard. pawaPay offers integrations with all major mobile money operators, delivering a scalable and efficient solution for businesses aiming to leverage the burgeoning mobile money market in Africa.

Why Mobile Money in Africa?

Mobile money has revolutionized financial transactions in Africa, where traditional banking infrastructure is limited. It allows users to perform financial transactions using their mobile phones, without needing a bank account. This has significantly increased financial inclusion and has become the preferred method of payment for many Africans. By integrating mobile money into your applications, you open your business to a vast and growing market.

Introducing the pawaPay Payment SDK

The pawaPay Payment SDK is a secure and straightforward way to integrate pawaPay's mobile money payment services into PHP applications. By handling the complexities of direct API calls and providing a set of easy-to-implement methods, this SDK allows developers to efficiently process payments without needing deep expertise in payment systems.

Key Benefits

Simplified Integration: Reduce development time with an SDK that abstracts complex API interactions.
Enhanced Security: Leverage built-in security features adhering to the latest standards.
Comprehensive Functionality: Access a wide range of payment operations through simple methods.

Key Features of the pawaPay Payment SDK

Easy to Use

With comprehensive documentation and ready-to-use code snippets, integrating the pawaPay SDK into your existing PHP projects is straightforward. The SDK reduces the complexity involved in coding for mobile money payment systems, allowing you to focus on other critical aspects of your application.

Security at Its Core

Built with security as a priority, the SDK adheres to the latest standards in data encryption, validations, and other security protocols to ensure that all transactions are protected against fraud and breaches.

Comprehensive Payment Functions

Whether you're looking to initiate deposits, manage payouts, process refunds, or check transaction statuses, the SDK covers all bases, providing you with the tools you need to manage various mobile money payment operations efficiently.

Cross-Network Compatibility

The SDK supports integration with all major mobile money operators in Africa, ensuring that your application can process payments regardless of the user's mobile money provider.

System Requirements

Before you begin, ensure that your environment meets the following system requirements:

PHP Version: 8.0 or higher
Composer: PHP dependency manager installed
cURL: Required for making HTTP requests
OpenSSL: For secure HTTPS connections
JSON Extension: Enabled in PHP for working with JSON data
SSL Certification: A valid SSL certificate on your server
Web Server: Apache 2.4, LiteSpeed V8.1, or any modern server capable of running PHP

Installation and Setup

Step 1: Install the SDK via Composer

Begin by installing the SDK using Composer:

composer require katorymnd/pawa-pay-integration

Step 2: Configure Your API Keys

After installation, you need to configure your API keys provided by pawaPay. You can set them in your application's environment variables.

require_once 'vendor/autoload.php';

use Dotenv\Dotenv;
use Katorymnd\PawaPayIntegration\Api\ApiClient;
use Katorymnd\PawaPayIntegration\Utils\Helpers;
use Katorymnd\PawaPayIntegration\Utils\Validator;
use Katorymnd\PawaPayIntegration\Utils\FailureCodeHelper;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Whoops\Run;
use Whoops\Handler\PrettyPageHandler;

// Initialize Whoops error handler for development
$whoops = new Run();
$whoops->pushHandler(new PrettyPageHandler());
$whoops->register();

// Load the environment variables from the .env file
$dotenv = Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();


// Set the environment and SSL verification based on the production status
$environment = getenv('ENVIRONMENT') ?: 'sandbox'; // Default to sandbox if not specified
$sslVerify = $environment === 'production';  // SSL verification true in production

// Dynamically construct the API token key
$apiTokenKey = 'PAWAPAY_' . strtoupper($environment) . '_API_TOKEN';

// Get the API token based on the environment
$apiToken = $_ENV[$apiTokenKey] ?? null;


if (!$apiToken) {
    echo json_encode([
        'success' => false,
        'errorMessage' => 'API token not found for the selected environment.'
    ]);
    exit;
}

// Initialize Monolog for logging
$log = new Logger('pawaPayLogger');
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_success.log', \Monolog\Level::Info));
$log->pushHandler(new StreamHandler(__DIR__ . '/../logs/payment_failed.log', \Monolog\Level::Error));

// Create a new instance of the API client with SSL verification control
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

Replace 'YOUR_PAWAPAY_API_KEY' with your actual API key provided by pawaPay in your '.env file.

Using the SDK

Initiating a Payment

To initiate a payment, you can use the initiateDeposit method. Here's how:





// Initialize the API client
$pawaPayClient = new ApiClient($apiToken, $environment, $sslVerify);

// Generate a unique transaction ID (UUID v4)
$transactionId = Helpers::generateUniqueId();

// Define payment details
$amount = '1000'; // Payment amount in KES (Kenyan Shilling)
$currency = 'KES'; // Currency code
$correspondent = 'MPESA_KEN'; // Correspondent ID for the MPESA network
$recipientMsisdn = '254712345678'; // Recipient's phone number

// Custom transaction description
$description = 'Payment for invoice -1234';

// Optional metadata for the transaction
$metadata = [
    'order_id' => '1234',
    'customer_id' => '5678',
];

// Step 1: Validate the amount
$validatedAmount = Validator::symfonyValidateAmount($amount);

// Step 2: Validate the description
$validatedDescription = Validator::validateStatementDescription($description);

// Step 3: Validate metadata if provided
if (!empty($metadata)) {
    Validator::validateMetadataItemCount($metadata);
}

// Step 4: Initiate the payment
$response = $pawaPayClient->initiatePayment(
    $transactionId,
    $validatedAmount,
    $currency,
    $correspondent,
    $recipientMsisdn,
    $validatedDescription,
    $metadata
);

// Step 5: Check if the response is successful
if ($response['status'] === 200) {
    // Payment was initiated successfully
    $log->info('Payment initiated successfully', [
        'transactionId' => $transactionId,
        'response' => $response['response'],
    ]);
    echo "Payment initiation successful. Transaction ID: $transactionId";
} else {
    // Payment initiation failed; handle the error
    $log->error('Payment initiation failed', [
        'transactionId' => $transactionId,
        'error' => $response->getErrorMessage(),
    ]);
    echo "Payment initiation failed. Error: " . $response->getErrorMessage();
}

In this example, we initiate a payment of 1000 KES to a recipient on the MPESA network. We check if the response is successful and handle it accordingly.

Checking Transaction Status

To check the status of a transaction:


 // Proceed to check the transaction status
        $statusResponse = $pawaPayClient->checkTransactionStatus($transactionId, 'deposit');

        if ($statusResponse['status'] === 200) {
            $depositInfo = $statusResponse['response'][0]; // Get the deposit info
            $depositStatus = $depositInfo['status'];

Replace 'TRANSACTION_ID_RECEIVED' with the transaction ID you received when initiating the payment.

Handling Errors

The SDK is designed to handle errors gracefully. Here's how you might handle exceptions:

try {
     $response = $pawaPayClient->initiateDeposit(
        $depositId,
        $validatedAmount,
        $currency,
        $mno,
        $payerMsisdn,
        $validatedDescription,
        $metadata
    );

    // Process response
} catch (Exception $e) {
    // Log error details
    error_log('Payment initiation error: ' . $e->getMessage());
    // Inform the user
    echo "An error occurred while processing your payment. Please try again.";
}

Using try-catch blocks allows you to catch exceptions thrown by the SDK and handle them appropriately.

Best Practices

Secure API Keys: Never expose your API keys in your code repositories. Use environment variables or secure configuration files.
Validate User Input: Always validate and sanitize user input to prevent injection attacks.
Error Logging: Implement robust error logging to aid in troubleshooting.
Transaction Monitoring: Regularly monitor transactions to detect any suspicious activity.

Use Cases

E-commerce Platforms

Integrate seamless payment solutions that cater to both sellers and buyers. With pawaPay, customers can pay using their preferred mobile money provider, increasing conversion rates.

Marketplaces

Facilitate secure and reliable transactions between multiple parties with ease. The SDK supports splitting payments and managing payouts to different vendors.

Donation Platforms

Allow donors to contribute easily via mobile money, broadening your reach to users without traditional banking services.

Conclusion

The pawaPay Payment SDK for PHP simplifies the integration of mobile money payment solutions, enabling businesses to tap into the vast African market easily. By abstracting the complexities of payment processing and providing robust security features, the SDK allows developers to focus on building great applications while ensuring seamless and secure transactions.

Whether you're an e-commerce platform, a subscription service, or a marketplace, integrating pawaPay can significantly enhance your payment processing capabilities, reduce development time, and provide a better user experience.

Get Started Today

Visit the pawaPay Payment SDK GitHub Repository to access the SDK, documentation, and examples. Start integrating and unlock new opportunities in the African mobile money ecosystem.