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