convex-saligpay

Convex component for SaligPay payment integration. This package provides a self-contained Convex component with its own database tables and functions for integrating SaligPay payment processing.

Features

• OAuth Authentication - Secure token-based authentication with automatic refresh
• Checkout Sessions - Create and manage payment checkout sessions
• Payment Intents - Handle payment intents with 3D Secure support
• Subscriptions - Recurring billing with plan management
• Webhook Handling - Receive and verify webhook events from SaligPay
• Type Safety - Full TypeScript support with exported types
• Isolated Data - Component has its own database tables, isolated from your app

Installation

npm install convex-saligpay convex

Quick Start

1. Add the Component

In your app's convex/convex.config.ts:

import { defineApp } from "convex/server";
import saligpay from "convex-saligpay/convex.config.js";

const app = defineApp();
app.use(saligpay);

export default app;

2. Run Convex Dev

npx convex dev

This generates the component's API in convex/_generated/api.js.

3. Use in Your Functions

import { mutation } from "./_generated/server";
import { components } from "./_generated/api.js";

export const createPayment = mutation({
    args: {
        merchantId: v.string(),
        amount: v.number(),
        description: v.string(),
    },
    handler: async (ctx, args) => {
        await ctx.runMutation(components.saligpay.lib.authenticate, {
            merchantId: args.merchantId,
            clientId: "your-client-id",
            clientSecret: "your-client-secret",
            env: "sandbox",
        });

        const checkout = await ctx.runMutation(
            components.saligpay.lib.createCheckout,
            {
                merchantId: args.merchantId,
                externalId: `order-${Date.now()}`,
                amount: args.amount,
                description: args.description,
            },
        );

        return checkout;
    },
});

API Reference

Authentication

| Function | Type | Description | | ----------------------------- | -------- | ----------------------------------------- | | authenticate | mutation | Get OAuth tokens using client credentials | | refreshToken | mutation | Refresh expired access tokens | | getStoredTokens | query | Retrieve stored tokens for a merchant | | validateToken | query | Check if tokens are valid | | loginAndRetrieveCredentials | action | Full OAuth flow with email/password | | internalAuthentication | action | Authenticate by user ID |

Checkout

| Function | Type | Description | | ------------------ | -------- | --------------------------------------- | | createCheckout | mutation | Create a new checkout session | | getSession | query | Get checkout by externalId or sessionId | | getCheckoutByUrl | query | Get checkout by session token | | listCheckouts | query | List checkouts for a merchant | | expireSession | mutation | Mark a session as expired |

Payment Intents

| Function | Type | Description | | ------------------------ | -------- | --------------------------- | | createPaymentIntent | mutation | Create a payment intent | | confirmPaymentIntent | mutation | Confirm with payment method | | getPaymentIntentStatus | query | Get current status | | listPaymentIntents | query | List intents for a merchant | | cancelPaymentIntent | mutation | Cancel an intent |

Subscriptions

| Function | Type | Description | | --------------------------------- | -------- | ---------------------------------- | | initiateSubscription | mutation | Start a new subscription | | processSubscriptionPayment | mutation | Process a subscription payment | | pollSubscriptionIntent | query | Poll for payment intent status | | getSubscription | query | Get subscription by ID | | listSubscriptions | query | List subscriptions for a merchant | | updateSubscriptionPlan | mutation | Change subscription plan | | updateSubscriptionPaymentMethod | mutation | Update payment method | | cancelSubscription | mutation | Cancel a subscription | | reactivateSubscription | mutation | Reactivate a canceled subscription |

Webhooks

| Function | Type | Description | | ------------------------------ | -------- | -------------------------- | | receiveWebhook | mutation | Receive and verify webhook | | handleCheckoutCompleted | mutation | Handle completed checkout | | handleCheckoutFailed | mutation | Handle failed checkout | | handlePaymentIntentSucceeded | mutation | Handle successful payment | | handleRefundCreated | mutation | Handle refund creation |

Component Tables

The component creates these isolated tables:

• saligpayTokens - OAuth tokens per merchant
• saligpayCredentials - Merchant credentials
• checkoutSessions - Checkout session records
• paymentIntents - Payment intent records
• subscriptions - Subscription records
• webhookEvents - Webhook event audit log

Client Wrapper

import { SaligPayComponent } from "convex-saligpay";
import { components } from "./_generated/api.js";

const saligpay = new SaligPayComponent(components.saligpay);

// Auth
await ctx.runMutation(saligpay.auth.authenticate, { merchantId, clientId, clientSecret });
await ctx.runQuery(saligpay.auth.getStoredTokens, { merchantId });

// Checkout
await ctx.runMutation(saligpay.checkout.create, { merchantId, amount, ... });
await ctx.runQuery(saligpay.checkout.getSession, { externalId });

// Payment Intent
await ctx.runMutation(saligpay.paymentIntent.create, { merchantId, amount, ... });
await ctx.runQuery(saligpay.paymentIntent.getStatus, { intentId });

// Subscriptions
await ctx.runMutation(saligpay.subscription.initiate, { merchantId, planId, ... });
await ctx.runQuery(saligpay.subscription.get, { subscriptionId });
await ctx.runMutation(saligpay.subscription.updatePlan, { subscriptionId, newPlanId });
await ctx.runMutation(saligpay.subscription.cancel, { subscriptionId });

// Webhooks
await ctx.runMutation(saligpay.webhook.receive, { payload, signature, timestamp, signingSecret });

License

MIT