--- updatedAt: 2026-09-02T04:24:52.000Z agentTools: projectIndex: https://docs.paymongo.com/llms.txt --- # Key concepts This page covers the foundational concepts behind every payment channel. Whether you're using Hosted Checkout, a no-code option like Payment Links, or Invoicing, this is the mental model that underpins how payments flow through PayMongo. 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/ ``` 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 ```mermaid 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. | | **Hosted Checkout** | **Self-hosted Checkout** | | --------------------------------- | ----------------------- | ------------------------ | | API used | Checkout API | Payment API | | Who builds the payment experience | PayMongo | Merchant | | New payment methods support | Available automatically | Need manual integration | | PCI DSS scope | Minimal | Higher | | Branding control | Limited | Full control | 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. ### Enable pass-on fees from the dashboard No-code channels come with a **Pass on Fees** toggle, no integration needed. It is available on Payment Pages, Invoices, Order & Pay, and Storefront. On a Payment Page, open the page and turn on **Pass on Fees**. ![Pass on Fees toggle on a Payment Page](https://files.readme.io/b02ad2471ab7ec8fc407ea213acd5aa9e1ab95357ebaa0ff9d815ece7c15fb9e-pass-on-fees-pages.png) On an Invoice, turn on **Pass on Fees** while creating the invoice. ![Pass on Fees toggle when creating an Invoice](https://files.readme.io/3fb8a83ade9dc788394a8dff7a644e411ef8f893b96fbcbda0fdc751541bd0af-pass-on-fees-invoices.png) On a Storefront, open **Settings** and turn on **Pass on fees** under Payments. ![Pass on fees toggle in Storefront settings](https://files.readme.io/7454be15e93601638354996f1bc5e4f7b287c55f2b240426c221fc68a73594dd-pass-on-fees-storefront.png) *** ## Glossary | Term | Definition | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Payment Channel | A PayMongo-hosted way to accept payments without building your own checkout UI. | | Hosted Checkout | A low-code payment flow where your backend creates a Checkout Session and redirects the customer to PayMongo's hosted checkout page. | | Payment Link | A no-code payment request you create from the dashboard and share with a customer. | | Checkout Session | The object that represents one customer's attempt to pay for one order through a PayMongo payment channel. | | Payment Page | A reusable, brandable payment page with a persistent URL and QR code. | | E-commerce plugin | A drop-in integration that connects PayMongo payments to supported e-commerce platforms. | | Storefront | A PayMongo-generated storefront with payments built in. | | Invoice | A payment request created from the PayMongo Dashboard. An invoice includes customer details, a breakdown of line items, and a due date. | | Payment method | A payment option shown to the customer at checkout, such as card, bank, or wallet-based payment methods enabled on your account. | | Closed-loop wallet / Default wallet | A PayMongo Wallet type shown in the dashboard that can accept QR Ph payments, top up, and send funds to other PayMongo Wallets; for wallet limits and upgrade steps, see Wallets. | | Payment Intent | An object created for each payment attempt made inside a Checkout Session. | | Webhook | A notification PayMongo sends to your backend when a payment event happens. | | Pass-on fees | A Checkout Session setting that adds PayMongo's transaction fee to the customer’s total instead of deducting it from the amount you receive. |