Key concepts

This page covers the foundational concepts behind every payment channel. Whether you're using Hosted Checkout directly or a no-code option like Payment Links, the same primitives are at work behind the scenes.

This page is written for developers integrating Hosted Checkout, but business owners can read it to understand what's happening when a customer pays.

---

Checkout Session

A Checkout Session is the object that powers every payment channel. When a customer pays through Hosted Checkout, a Payment Link, a Payment Page, an e-commerce plugin, or a Storefront checkout, a Checkout Session is what they actually interact with.

A Checkout Session represents one customer's attempt to pay for one order. It holds the amount, the available payment methods, the customer's selection, payment attempts, and the resulting payment.

Checkout Session URL

When you create a Checkout Session, PayMongo returns a hosted URL of the form:

https://checkout.paymongo.com/<checkout_session_id>

Open the URL to send the customer to PayMongo's hosted checkout page. The page renders the payment methods you enabled, collects the customer's payment details, and handles redirects to bank or wallet apps where required.

Checkout Session lifecycle

sequenceDiagram
    participant M as Merchant backend
    participant P as PayMongo
    participant C as Customer
    participant B as Bank / Wallet

    M->>P: Create Checkout Session
    P-->>M: Returns checkout URL
    M->>C: Redirect to checkout URL
    C->>P: Selects payment method
    P->>P: Creates Payment Intent
    P->>C: Redirect to authorization
    C->>B: Authorizes payment
    alt Payment succeeds
        B-->>P: Success
        P->>C: Show success page
        P-->>M: checkout_session.payment.paid webhook
        M-->>P: Acknowledge webhook
    else Payment fails
        B-->>P: Failure
        P->>C: Show error, allow retry
        Note over P: New Payment Intent created on retry
    end

Each Checkout Session can produce multiple Payment Intents — one per attempt. If a customer's first attempt fails, they can retry with a different method, and PayMongo creates a fresh Payment Intent for that attempt. The Checkout Session stays the same throughout.

To learn more about Payment Intents, see Payment Acceptance → Key concepts.

Checkout Session status

A Checkout Session is in one of two states:

• active — The session is open and the customer can still complete payment.

• expired — The session has been explicitly closed and no longer accepts payment.

Checkout Sessions do not expire on their own. There is no default time limit — an active session stays open indefinitely until you mark it as expired. A session moves to expired only when:

• You call the Expire a Checkout Session API endpoint, or

• You archive the underlying Payment Link or Payment Page from the dashboard. Once expired, the checkout URL no longer accepts payment. If the customer still wants to pay, create a new session.

---

Hosted Checkout

Hosted Checkout uses the Checkout API: you send PayMongo the payment details, and PayMongo hosts the checkout UI. Self-hosted checkout uses the Payment API: you build the checkout UI yourself and call the Payments APIs directly.

Both flows result in a paid Payment Intent. The difference is which API you use and who owns the customer-facing experience.

Pick Hosted Checkout when you have a system that needs to accept payment but you don't want to build and maintain a payment UI. You provide the payment request and PayMongo handles the rest.

Pick Self-hosted Checkout when the checkout experience needs to live inside your own UI and you're prepared to maintain it as payment methods evolve. See Payment Acceptance for the Payment API flow.

---

Webhooks

PayMongo notifies your backend of payment outcomes through webhooks. The key event for Checkout Sessions is:

• checkout_session.payment.paid — Sent when a customer successfully completes payment. The payload includes the full Checkout Session object and the resulting payment details, so you can fulfill the order without an additional API call.
• link.payment.paid — Sent when a customer successfully completes payment from Payment Links.

Set up webhooks in your dashboard under Settings → Webhooks.

---

Pass-on Fees

By default, PayMongo's transaction fee is deducted from the amount you receive. If you'd rather pass the fee to the customer, set pass_on_fees: true when creating a Checkout Session. PayMongo automatically calculates and adds the correct fee for whichever payment method the customer selects.

For more details about how pass-on fees are calculated, see Payment Acceptance → Pass-on Fees.

---

Glossary