Payment Intents

Payment Intents Overview

Copy page

Payment Intents in SaligPay

Payment Intents are objects that represent a payment attempt from a customer. They are designed to handle complex payment flows including authentication, confirmation, and status tracking. Unlike simple payment sessions, Payment Intents provide more granular control over the payment process.

What is a Payment Intent?

A Payment Intent tracks the process of collecting payment from your customer. It handles the complexities of payment confirmation, authentication (like 3D Secure), and provides ways to handle different payment outcomes.

Key Benefits

1. Flexible Payment Flows: Support for various payment methods and authentication requirements
2. Secure Handling: Proper handling of sensitive payment information
3. Status Tracking: Comprehensive status tracking throughout the payment lifecycle
4. Retry Logic: Built-in mechanisms to handle payment failures appropriately
5. Multi-step Authentication: Support for 3D Secure and other authentication methods

Payment Intent Lifecycle

The typical lifecycle of a Payment Intent involves several stages:

1. Creation: A Payment Intent is created with an initial amount and payment method
2. Confirmation: The Payment Intent is confirmed, potentially triggering customer authentication
3. Processing: The payment is processed by the payment provider
4. Completion: The payment either succeeds or fails, with appropriate status updates

When to Use Payment Intents

Payment Intents are ideal for:

• Complex payment flows requiring authentication
• Mobile applications with custom payment UI
• Scenarios where you need fine-grained control over the payment process
• Integrations where you collect payment details directly

For simpler checkout flows, consider using the standard checkout sessions instead.

Statuses

Payment Intents transition through various statuses:

Status	Description
requires_payment_method	Payment method needs to be attached
requires_confirmation	Ready to be confirmed
requires_action	Additional action required (e.g., 3D Secure authentication)
processing	Payment is being processed
succeeded	Payment completed successfully
canceled	Payment was canceled

API Endpoints

The following API endpoints are available for Payment Intents:

• POST /api/payment-intent - Create a payment intent
• POST /api/payment-intent/{intentId}/confirm - Confirm a payment intent
• GET /api/payment-intent/{intentId}/status - Get payment intent status

SDK Integration

The SaligPay SDK provides convenient methods for working with Payment Intents:

Code
 
import { SaligPay } from "saligpay-node";

const saligpay = new SaligPay({
    clientId: process.env.SALIGPAY_CLIENT_ID!,
    clientSecret: process.env.SALIGPAY_CLIENT_SECRET!,
    env: "sandbox",
});

const intent = await saligpay.paymentIntents.create({
    amount: 10000,
    description: "One-time purchase",
    externalId: "order-456",
    contact: {
        name: "Jane Smith",
        email: "jane@example.com",
        phone: "+639123456789",
    },
    metadata: { item: "premium_upgrade" },
    returnUrl: "https://yourapp.com/payment/success",
    webhookUrl: "https://yourapp.com/webhooks/saligpay",
});

For more details on specific operations, see the other guides in this section.