Key concepts

Overview

Every payment method in PayMongo's Payment Acceptance section is built on the same foundation: the Payment Intent. This page explains what a Payment Intent is, how it moves through its lifecycle, what each status means, which webhook events PayMongo sends, and defines the terms used across all payment method guides.

Understanding this page thoroughly will make every other guide in this section easier to follow.

What is a Payment Intent?

A Payment Intent is a server-side record that represents a single checkout transaction. It holds:

• The amount to charge (in centavos — PHP 100.00 is 10000)
• The currency (PHP or USD for USD card acceptance)
• The payment methods allowed for this transaction
• The current status of the payment

Think of a Payment Intent as a shopping cart that stays open until the customer either pays or abandons it. You create it on your server, and it persists through authentication redirects, QR code generation, and polling — until the payment is either succeeded or definitively failed.

Payment Intent is a concept, not a standalone product. It is the mechanism that powers all payment methods in this section.

The payment lifecycle

Every payment in PayMongo flows through these stages:

1. Create a Payment Intent (server-side)

Call the Create Payment Intent endpoint from your backend using your secret API key. This establishes the transaction record.

POST https://api.paymongo.com/v1/payment_intents

{
  "data": {
    "attributes": {
      "amount": 10000,
      "currency": "PHP",
      "payment_method_allowed": ["card", "gcash", "qrph"],
      "description": "Order #1234"
    }
  }
}

The response includes:

• id — the Payment Intent ID, saved on your server
• client_key — sent to your frontend for client-side operations
• status — starts as awaiting_payment_method

2. Create a Payment Method (client-side)

Call the Create Payment Method endpoint from your frontend using your public API key. This step collects the customer's payment details.

Important: Never send card numbers or sensitive payment data to your backend. Collect them client-side and create the Payment Method there. Sending card data to your server requires full PCI DSS compliance — PayMongo's client-side tokenization eliminates that requirement for merchants.

3. Attach the Payment Method (client-side)

Attach the Payment Method to the Payment Intent using the client_key from step 1. This triggers payment processing.

Depending on the payment method:

• Cards — may return an authorization URL for 3D Secure authentication
• E-wallets — return a redirect URL to the provider's app or website
• QR Ph — return a Base64-encoded QR code image

4. Handle the next action

If the payment requires customer action (3DS, redirect, QR scan), direct the customer to complete it. Monitor the Payment Intent status by polling or listening to webhooks.

5. Receive the outcome

PayMongo sends payment.paid or payment.failed webhook events when the payment resolves.

Payment Intent statuses

There is no explicit failed status on the Payment Intent itself. When a payment fails, the intent returns to awaiting_payment_method so the customer can retry with a different method. Check last_payment_error for the failure reason.

Payment method expiry windows

When a payment method is attached and the customer needs to complete an action, there is a time limit:

If the customer doesn't complete the action within the window, the payment method expires, the intent returns to awaiting_payment_method, and a qrph.expired (for QR Ph) or similar event is sent.

Webhook events

Webhooks are HTTP callbacks PayMongo sends to your server when something changes.

Glossary

Payment Intent A server-side record representing one checkout transaction. Holds the amount, currency, allowed payment methods, and current status. The core object in all Payment Acceptance integrations.

Payment Method A customer's payment details — a tokenized card, e-wallet selection, or QR Ph request — attached to a Payment Intent to trigger payment.

client_key A short-lived token returned when you create a Payment Intent. Pass it to your frontend so it can perform client-side operations (creating a Payment Method, attaching it) without exposing your secret key.

Secret API key Your private PayMongo key. Used for server-side operations — creating Payment Intents, capturing payments, creating refunds. Never expose this in client-side code.

Public API key Your frontend-safe PayMongo key. Used for client-side operations — creating Payment Methods, attaching them using a client_key.

Webhook An HTTP callback PayMongo sends to your server when a payment event occurs. More reliable than polling — use webhooks to confirm payment outcomes in production.

3D Secure (3DS) An authentication protocol for card payments. PayMongo uses 3DS 2.0. When required, the customer is redirected to their bank's verification page (OTP, biometric, etc.) before the payment completes.

Centavos PayMongo amounts are always expressed in the smallest currency unit. PHP 100.00 = 10000 centavos. USD 10.00 = 1000 cents.

MDR (Merchant Discount Rate) The percentage fee PayMongo charges per transaction. Varies by payment method. Used in the Pass on Fees calculation.

PCI DSS Payment Card Industry Data Security Standard. The compliance framework governing how card data must be handled. PayMongo is PCI Service Provider Level 1 certified. See Best Practices for the scope breakdown between PayMongo and your integration.