Payment Intents

Checking Payment Intent Status

Copy page

Checking Payment Intent Status

After creating and confirming a Payment Intent, it is essential to monitor its status to determine if the payment was successful or if further action is required.

API Endpoint

GET /api/payment-intent/{intentId}/status

Request Parameters

Parameter	Location	Type	Description
intentId	Path	string	The ID of the Payment Intent to check

Example Request (REST API)

Code
 
GET /api/payment-intent/pi_abc123/status
Authorization: Bearer <access_token>

Example Response

Code
 
{
    "success": true,
    "data": {
        "id": "pi_abc123",
        "transactionId": "txn_xyz789",
        "amount": 10000,
        "status": "succeeded",
        "paymentMethod": {
            "id": "pm_abc123",
            "type": "gcash"
        },
        "createdAt": "2025-05-03T12:00:00Z",
        "updatedAt": "2025-05-03T12:01:00Z"
    }
}

Using the SDK

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

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

try {
    const intent = await saligpay.paymentIntents.getStatus("pi_abc123");

    console.log("Payment Intent Status:", intent.status);
    console.log("Transaction ID:", intent.transactionId);
    console.log("Amount:", intent.amount);
    console.log("Payment Method:", intent.paymentMethod?.type);

    switch (intent.status) {
        case "succeeded":
            console.log("Payment successful!");
            break;
        case "failed":
            console.log("Payment failed!");
            break;
        case "processing":
            console.log("Payment is still processing...");
            break;
        case "requires_action":
            console.log("Additional action required!");
            break;
        default:
            console.log("Current status:", intent.status);
    }
} catch (error) {
    console.error("Error getting payment intent status:", error);
}

Payment Intent Statuses

Status	Description	Action Required
requires_payment_method	Payment method needs to be attached	Attach a payment method
requires_confirmation	Ready to be confirmed	Confirm the intent
requires_action	Additional action required (e.g., 3D Secure)	Complete authentication
processing	Payment is being processed	Wait for final status
succeeded	Payment completed successfully	Process successful payment
canceled	Payment was canceled	Handle canceled payment

Polling Strategies

For payment flows that require waiting for completion, implement polling with appropriate delays:

Code
 
async function pollPaymentStatus(intentId: string, maxAttempts = 10) {
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
        try {
            const status = await saligpay.paymentIntents.getStatus(intentId);

            switch (status.status) {
                case "succeeded":
                    return { success: true, status };
                case "failed":
                    return { success: false, status };
                case "canceled":
                    return { success: false, status };
                default:
                    await new Promise((resolve) =>
                        setTimeout(resolve, Math.min(1000 * (attempt + 1), 5000))
                    );
            }
        } catch (error) {
            console.error(`Error polling payment status (attempt ${attempt + 1}):`, error);
            if (attempt === maxAttempts - 1) throw error;
            await new Promise((resolve) => setTimeout(resolve, 1000));
        }
    }

    throw new Error("Max polling attempts reached");
}

const result = await pollPaymentStatus("pi_abc123");
if (result.success) {
    console.log("Payment succeeded!");
} else {
    console.log("Payment failed or was canceled.");
}

Webhook Handling

Instead of polling, implement webhook handlers to receive real-time status updates:

Code
 
app.post("/webhooks/saligpay", async (req, res) => {
    try {
        const payload = req.body;

        if (payload.type && payload.type.startsWith("payment_intent.")) {
            const intentId = payload.data?.id;
            const status = payload.data?.attributes?.status;

            console.log(`Payment Intent ${intentId} changed to status: ${status}`);

            switch (status) {
                case "succeeded":
                    break;
                case "failed":
                    break;
                default:
                    break;
            }
        }

        res.status(200).json({ received: true });
    } catch (error) {
        console.error("Webhook processing error:", error);
        res.status(500).json({ error: "Webhook processing failed" });
    }
});

Status Transition Patterns

Successful Payment: requires_payment_method -> requires_confirmation -> processing -> succeeded

Payment Requiring Authentication: requires_payment_method -> requires_confirmation -> requires_action -> processing -> succeeded

Failed Payment: requires_payment_method -> requires_confirmation -> processing -> failed

Error Handling

Common errors when checking status:

Error Code	Description	Solution
INTENT_NOT_FOUND	Payment Intent does not exist	Verify intent ID is correct
UNAUTHORIZED	Invalid or expired access token	Refresh authentication token
INTERNAL_ERROR	Server-side error	Retry request or contact support

Best Practices

1. Do not rely solely on polling; implement webhooks for real-time updates
2. Handle all status types in your application
3. Implement exponential backoff when polling
4. Store status changes for audit trails
5. Validate webhook signatures
6. Set reasonable timeouts