Xendit’s updated payment integration guidance in 2026 identifies Payment Sessions as the recommended migration path for legacy Payment Links created through the /v2/invoices API. The newer /sessions API supports different payment flows and provides a more structured way to manage checkout sessions, customer information, and payment status. Although older integrations remain functional, businesses should understand the differences before planning new payment integrations or migrating existing systems.
This guide compares Xendit Payment Sessions with legacy Payment Links, including their API endpoints, supported payment flows, transaction statuses, webhook notifications, and integration requirements. Businesses planning a migration can also consult Xendit’s official migration guide for detailed information about replacing the older API.
What Legacy Invoices Were Built to Do?
In Xendit’s older payment infrastructure, the term legacy invoice commonly refers to a Payment Link created through the /v2/invoices API. This allows a business to generate a payment request and share a checkout link with a customer. It supports one-time payment collection and can be useful when customers receive payment links through email, messaging platforms, or other communication channels.
However, a legacy Payment Link should not automatically be treated as the same thing as a formal accounting invoice. Businesses may still need separate billing records, customer references, and financial reporting systems. To understand how payment links work when shared through messaging channels, readers can also explore our guide explaining SMS payments.
What Payment Sessions are Built to Do?
Xendit Payment Sessions provide a structured way to manage payment-related checkout flows through the /sessions API. Developers can create sessions for one-time payments, saving supported payment methods, or subscription registration. The API supports different integration modes, including Xendit-hosted payment links and supported embedded checkout components.
Each session can include relevant transaction information such as payment amount, currency, customer details, permitted payment channels, and expiration settings. Developers can review the available fields and integration requirements in Xendit’s official Create a Session API reference. Applications must still maintain their own order records and confirm the final payment outcome before delivering goods or services.
Key Changes Introduced in 2026
The biggest change is the mindset shift from sending a bill to orchestrating a checkout. Payment Sessions support tighter control over the lifecycle of a payment attempt, which makes it easier to manage retries, partial failures, and customer drop-offs.
Another change is improved consistency across payment methods. When payment method availability depends on amount, customer location, channel, or risk signals, a session approach is simpler to reason about than multiple invoice templates and workarounds.
- Checkout Flow Control: Payment Sessions focus on a guided payment journey, while legacy invoices focus on payment collection after an invoice is issued.
- Context Preservation: Sessions are built to carry customer and cart context through completion, which reduces mismatches in fulfillment and reconciliation.
- Operational Visibility: Sessions tend to provide cleaner event tracking for payment start, method selection, and completion, which helps analytics and support teams.
These changes matter most when you are optimizing conversion, automating fulfillment, and reducing manual exception handling.
Payment Lifecycle and Expiration Behavior
Legacy Payment Links and Payment Sessions both have expiration behavior, but their configuration and lifecycle models differ. Legacy Payment Links use invoice-based expiration settings, while Payment Sessions use an expires_at timestamp. According to Xendit’s session API documentation, a Payment Session expires after 30 minutes by default unless another permitted expiration time is configured.
Businesses should manage inventory reservations, changing prices, and abandoned orders within their own application systems. A Payment Session does not automatically guarantee an inventory hold or successful payment. Developers should check session and payment statuses, handle expiration correctly, and create a new session when an expired checkout needs to be restarted.
Customer Experience and Payment Method Selection
Invoice flows can feel like a handoff – the user receives a link, opens it, and pays. That is fine for B2B billing, school fees, and many pay-later scenarios where the payer expects an invoice artifact.
Payment Sessions support different checkout experiences depending on the selected integration mode. Businesses can use Xendit’s hosted checkout page or supported embedded components to connect payments with their applications. However, payment method availability depends on factors such as country, currency, merchant activation, and channel configuration. Developers should review Xendit’s available payment methods before designing a checkout flow and measure actual payment completion rates rather than assuming that a new integration automatically improves conversion.
- Hosted Checkout: Businesses can redirect customers to a Xendit-hosted payment page using the supported Payment Link mode.
- Embedded Components: Supported integrations can collect payment information through Xendit Components within the merchant’s checkout experience.
- Payment Confirmation: Applications should use verified session and payment updates to confirm transactions rather than relying only on a customer returning to a success page.
This is also where product analytics improves, since session stages are easier to instrument than invoice link opens.
Reconciliation and Accounting Impacts
Finance teams often prefer invoices because they align with accounts receivable language and invoice numbering practices. That said, invoice-centric checkout can create edge cases when the invoice is used as both a payment object and a billing document.
Payment Sessions can reduce reconciliation noise by keeping checkout attempts distinct from final settlement records. When implemented well, this makes it easier to map events to orders, refunds, and chargebacks with fewer manual lookups.
| Comparison Area | Payment Sessions | Legacy Payment Links (Invoices) |
|---|---|---|
| API Endpoint | POST /sessions |
POST /v2/invoices |
| Primary Purpose | Manage checkout and supported payment-related sessions | Generate one-time payment links |
| Core Identifier | payment_session_id |
Invoice id |
| Payment Flows | PAY, SAVE, and SUBSCRIPTION |
One-time payment collection |
| Checkout Experience | Hosted Payment Link or supported Components mode | Hosted payment link |
| Expiration Configuration | expires_at timestamp |
invoice_duration |
| Payment Status | Session status and related payment status | Invoice status such as PENDING, PAID, or EXPIRED |
| Failed Payment Visibility | Can receive payment failure events through the newer payment infrastructure | More limited visibility into individual failed attempts |
| Payment Method Support | Newer supported payment channels and regions | Older supported channels and regions |
| Migration Position | Recommended newer integration | Legacy integration with an official migration path |
Whichever model you pick, the real goal is consistent mapping between an order record, a payment record, and a payout settlement record. That is what keeps finance and operations aligned.
Risk Management and Payment Integrity
Secure payment processing requires more than fraud prevention. Businesses must protect API credentials, validate incoming requests, maintain consistent order references, and prevent repeated processing of the same payment event. Our guide to API security basics explains important security practices for connected applications, including authentication, access controls, and secure webhook handling.
Payment Sessions provide structured status information, but they do not eliminate the need for merchant-side security controls. Developers should authenticate incoming webhooks, handle duplicate notifications safely, and confirm payment status before delivering goods or services. Xendit’s official webhook handling guidance explains these practices and the importance of secure server-side processing.
Developer Integration and Maintenance
Legacy invoices are often easier to start with because they can be created and sent with minimal frontend work. That speed can be valuable for pilots, manual sales flows, and finance-led collections where a hosted invoice page is enough.
A reliable payment integration should keep checkout operations, order processing, and fulfillment responsibilities clearly defined. Applications must maintain consistent transaction references, protect API endpoints, and process payment notifications correctly. Development teams building distributed applications can also explore how API gateways and load balancers support request routing, service availability, and access controls. Any reduction in maintenance work should be measured after migration rather than assumed in advance.
- Frontend Complexity: Sessions often require tighter integration but provide a smoother checkout journey once implemented.
- Backend State Handling: Sessions encourage clearer state machines for started, pending, completed, and expired outcomes.
- Testing Coverage: Session flows are easier to test end-to-end because stages are explicit and measurable.
Teams that treat payments as a product surface rather than a back-office tool tend to prefer session-based design.
When to Use Payment Sessions
Payment Sessions are a strong fit when the payment action is part of an app journey and speed matters. They also help when you need a consistent multi-method checkout that adapts to customer context.
They are commonly chosen for ecommerce, digital services, subscriptions with immediate access, and any flow where you need reliable confirmation before fulfillment.
- Instant Fulfillment: You unlock content, ship goods, or provision access only after a confirmed payment.
- Multiple Payment Methods: You want one checkout that can support cards, transfers, e-wallets, and other rails as available.
- Conversion Optimization: You need better visibility into drop-offs and friction points inside the payment journey.
This approach aligns with product-led teams that measure checkout performance closely.
When Legacy Payment Links May Still Be Used
Legacy Payment Links may remain in existing business applications while companies prepare to migrate to Payment Sessions. Xendit continues to support its older integration stack, although new features and payment channels are being developed for the newer APIs.
Businesses should evaluate their existing integrations before changing payment flows that already support important operations.
- Existing Integrations: Businesses may need to maintain currently functioning legacy payment links while testing a replacement.
- Migration Planning: Development teams should review endpoint changes, customer information requirements, webhook events, and payment status mapping.
- Operational Continuity: Existing payment processes should remain reliable during a controlled migration, with appropriate monitoring and fallback procedures.
A traditional accounting invoice can still be created and managed separately from the payment API. Businesses should avoid assuming that the older Payment Link API is required simply because their finance teams use invoices.
Practical Migration Checklist for Development Teams
Moving from legacy Payment Links to Payment Sessions requires careful planning because API fields, payment statuses, and webhook notifications do not always have direct one-to-one replacements.
Before making the transition, development teams should review the following requirements:
- ย Identify Existing Endpoints: Check where the application currently uses /v2/invoices and which business processes depend on those requests.
- ย Map API Fields: Review changes involving customer information, transaction references, expiration settings, and permitted payment channels.
- Update Webhook Processing: Configure the required session and payment notifications, including appropriate security checks and duplicate-event handling.
- Test Payment Outcomes: Verify successful, failed, expired, and canceled checkout scenarios before enabling the new integration for customers.
- Monitor the Migration: Compare payment completion rates, error logs, reconciliation accuracy, and support issues during a controlled rollout.
A successful migration should preserve reliable payment processing while making the newer integration easier to operate and maintain.
Conclusion
The change in 2026 is that Xendit Payment Sessions align better with how modern products run checkout, track intent, and automate fulfillment. Legacy invoices still work well for invoice-first billing and pay-later collections, but they are not always the best foundation for high-conversion checkout.
Choose sessions when you need lifecycle control and analytics, and keep invoices where a billing document is central to the workflow. When both coexist, define clear boundaries between checkout payments and accounts receivable billing to keep teams aligned.
Frequently Asked Questions
Do Payment Sessions Replace Legacy Invoices Completely?
Xendit recommends Payment Sessions as the migration path for its legacy Payment Link API. Existing legacy integrations may continue operating during migration, but businesses should evaluate the newer API for future payment integrations. Traditional accounting invoices are separate business documents and may still be required regardless of the payment technology used.
What Should A Team Migrate First When Adopting Payment Sessions?
Start with pay-now flows tied to immediate fulfillment, since they benefit most from session lifecycle control. Ensure your order state model, webhook handling, and reconciliation mapping are defined before switching critical revenue paths.
Can A Business Use Both Sessions and Invoices Without Confusing Reporting?
Yes, but you need consistent identifiers that tie orders, payments, refunds, and payouts together. Establish clear rules for when an order uses a session checkout versus when it is billed through an invoice workflow.
