Payment Methods

Managing Payment Methods

Copy page

Managing Payment Methods

Effective management of payment methods is crucial for providing a smooth customer experience while maintaining security and compliance.

Payment Method Storage

Payment methods are stored securely using tokenization to protect sensitive information.

Tokenization Process

When a payment method is created, SaligPay replaces sensitive data with a unique identifier called a token:

Code
 
Raw Card Data: 4111111111111111 -> Token: pm_card_abc123

The raw data is never stored in your systems, only the token which can be securely stored for future use.

Payment Method Object

A complete payment method object contains:

Code
 
{
    "id": "pm_card_abc123",
    "type": "card",
    "card": {
        "brand": "visa",
        "last4": "1111",
        "exp_month": 12,
        "exp_year": 2027,
        "fingerprint": "unique-fingerprint"
    },
    "billing_details": {
        "name": "Juan Dela Cruz",
        "email": "juan@example.com"
    },
    "created": "2025-05-03T12:00:00Z",
    "livemode": false
}

Creating Payment Methods

Payment methods are typically created during checkout or payment intent processes:

Code
 
const intent = await saligpay.paymentIntents.create({
    amount: 10000,
    description: "Payment with saved card",
    externalId: "order-789",
    contact: {
        name: "Juan Dela Cruz",
        email: "juan@example.com",
    },
});

console.log("Available payment methods:", intent.paymentMethods);

Updating Payment Methods

Payment methods can be updated when information changes:

Expiration Updates

For cards approaching expiration:

Code
 
try {
    await saligpay.paymentIntents.confirm(intentId, {
        paymentMethod: "pm_card_old",
    });
} catch (error) {
    if (error.message.includes("expired")) {
        console.log("Card has expired. Please update card details.");
    }
}

Using Saved Payment Methods

Using previously stored payment methods streamlines the checkout experience:

Code
 
async function getCustomerPaymentMethods(customerId: string) {
    return await getStoredPaymentMethods(customerId);
}

const paymentMethods = await getCustomerPaymentMethods("cust_abc123");

const confirmation = await saligpay.paymentIntents.confirm("intent_xyz", {
    paymentMethod: paymentMethods[0].id,
});

Payment Method Validation

Always validate payment methods before attempting charges:

Code
 
function validatePaymentMethod(paymentMethod: any) {
    if (paymentMethod.type === "card") {
        const currentDate = new Date();
        const expiryDate = new Date(
            paymentMethod.card.exp_year,
            paymentMethod.card.exp_month - 1
        );

        if (currentDate > expiryDate) {
            return { valid: false, reason: "Card is expired" };
        }
    }

    if (paymentMethod.status !== "active") {
        return { valid: false, reason: "Payment method is not active" };
    }

    return { valid: true };
}

Security Best Practices

PCI Compliance

• Never store card numbers, CVV, or other sensitive authentication data
• Use only tokens provided by SaligPay
• Follow PCI DSS requirements for your system

Data Protection

• Encrypt stored payment method tokens
• Limit access to payment method data
• Implement audit trails for payment method operations
• Use secure connections (HTTPS) for all operations

Access Control

• Restrict who can view or modify payment methods
• Implement role-based access controls
• Log all payment method access and changes
• Regular security audits of payment method handling

Handling Payment Method Failures

Code
 
async function handlePaymentFailure(error: any, paymentMethodId: string) {
    switch (error.code) {
        case "card_declined":
            console.log("Card was declined. Customer should try another payment method.");
            break;
        case "expired_card":
            console.log("Card has expired. Customer needs to update card details.");
            break;
        case "insufficient_funds":
            console.log("Insufficient funds. Customer should try another payment method.");
            break;
        default:
            console.log("Payment failed:", error.message);
    }

    await updatePaymentMethodStatus(paymentMethodId, "failed");
}

Error Recovery

Implement robust error recovery:

Code
 
async function processPaymentWithFallback(order: any, customer: any) {
    const paymentMethods = await getCustomerPaymentMethods(customer.id);

    for (const method of paymentMethods) {
        try {
            const result = await saligpay.paymentIntents.confirm(order.intentId, {
                paymentMethod: method.id,
            });

            if (result.status === "succeeded") {
                return result;
            }
        } catch (error) {
            console.log(`Payment failed with method ${method.id}:`, error.message);
        }
    }

    throw new Error(
        "All payment methods failed. Customer must provide new payment method."
    );
}

Testing Payment Method Management

For comprehensive testing:

1. Test with various payment method types
2. Simulate expired card scenarios
3. Test with insufficient funds
4. Verify tokenization works correctly
5. Test error handling and recovery