Best practices

Use these recommendations to reduce payment issues, improve reconciliation, and prepare each payment channel for a reliable go-live. These guidelines apply across PayMongo products, with additional notes for specific channels where needed.

Cross-product guidance

Unlock the payment methods you need before going live

Before launching a payment flow, check which payment methods are already available on your account and request access to any additional methods you plan to offer. Review available payment methods in Settings → Payment Methods and request enablement for any method your production flow requires. Validate the enabled methods in test mode before rollout.

Associate each payment with an internal record

Create a clear link between your internal order, invoice, or customer record and the Payment Link or Checkout Session you generate. Store the PayMongo payment object reference with the matching order, invoice, or customer record. Use a consistent internal reference format and check for an existing active request before creating another one for the same order.

Expire unused payment requests

Unused Payment Links or Checkout Sessions can create confusion if customers open or pay an old request later. Set an expiration policy for requests that are no longer needed. Expire them when an order is cancelled, replaced, or already paid through another channel so customers only receive valid checkout options.

Enable payment methods before configuring checkout

A payment method must be enabled on your account before it can be used in production. Verify payment method capability in Settings → Payment Methods before integration. Configure checkout only after the required payment methods are available for your account.

Hosted Checkout

Do not embed Checkout Page inside your website

Don't embed the PayMongo Hosted Checkout page inside an iframe or embed element. Hosted Checkout blocks rendering inside embedded environments to prevent UI-redress and clickjacking attacks.

Use a fully qualified success_url and cancel_url

When configuring Hosted Checkout, always use a complete success and cancel URL. Use fully qualified URLs, such as https://example.com/success, for both success_url and cancel_url. Avoid domain-only or incomplete paths, and test the redirect flow before enabling live payments.

Payment Links

Use Payment Links instead of Legacy Links

Legacy Links do not support newer payment methods. Use Payment Links for all new payment collection flows. Use Payment Links from the start for new payment collection flows. Use the Legacy endpoint /v1/links only when backward compatibility is required.

Payment Pages

Use order details to improve payment tracking

If you track orders or inventory, include a reference that your team can search later. Use a custom field when creating checkout to store an order reference ID. Keep the format consistent so your team can find payments in the Payments menu and reconcile them with your system.

Storefront

Request storefront enablement before launch

Storefront setup is still managed manually by the PayMongo team and is currently available through a limited beta. Submit a request through the Storefront Initial Set-up Form before planning your rollout. Confirm your setup scope and available prompt credits before generating storefronts.

Write specific prompts before using credits

Prompt credits can be consumed quickly when prompts are too broad, vague, or missing key storefront details. Prepare a detailed prompt before submitting it. Include brand colors, font style, target audience, product examples, and the sections you want the storefront to include. Avoid unclear instructions such as "make it look nice" or "create a modern store" without describing the style, layout, or audience.

Set up your product catalog first before publishing

Storefront depends on complete product data to publish a useful storefront.

Set up your product catalog in the /products menu before publishing the storefront. Confirm that all product names, descriptions, and prices are complete so products can be pulled correctly.

E-commerce Plugins

Validate the integration in the development environment first

For plugin-based integrations, use the development dashboard before enabling live payments. Simulate the integration flow in the development dashboard and confirm that the payment behavior matches your expected customer journey. Verify the plugin configuration before switching to live mode.