How to Build a Payments Integration with Unified

September 16, 2025

With Unified you can build payment products that work with your end customers payment providers. With a single API you can connect payment processors like Stripe, PayPal, GoCardless and more!

You can do all sorts of things like listing payments, generating payment links, manage payouts and even handle refunds - all without building custom connectors for each provider.

In this guide, I will show you how to create and list payments as well as some related objects. For the example we will be using Stripe, but this approach works for any of the payment integrations supported by Unified.

See the full list of supported payment integrations.

Prerequisites

• Node.js (v18+)
• Unified account with a payment integration enabled (e.g., Stripe)
• Unified API key
• Your customer's payment processor connection ID

Step 1: Setting up your project

Set up your dependencies

mkdir payments-demo
cd payments-demo
npm init -y
npm install @unified-api/typescript-sdk dotenv

Add your credentials to .env:

UNIFIED_API_KEY=your_unified_api_key
CONNECTION_STRIPE=your_customer_stripe_connection_id

Step 2: Initialize the SDK

import 'dotenv/config';
import { UnifiedTo } from '@unified-api/typescript-sdk';

const { UNIFIED_API_KEY, CONNECTION_STRIPE } = process.env;

const sdk = new UnifiedTo({
  security: { jwt: UNIFIED_API_KEY! },
});

Step 3: How to Get Your Customer's Connection ID

Before you can list payments, your customer must authorize your application to access their payment provider via Unified's embedded authorization flow.

Once authorized, you'll receive a connection ID.

Step 4: Creating a Payment

export async function createPayment(connectionId: string, amount: number, currency: string, customerId: string) {
  const paymentResult = await sdk.payment.createPayment({
    connectionId,
    payment: {
      amount,
      currency,
      customerId,
      status: "PAYMENT_STATUS_PENDING", // or "PAYMENT_STATUS_SUCCEEDED"
      description: "Test payment",
    },
  });
  return paymentResult.payment;
}

Step 5: Listing Payments

export async function listPayments(connectionId: string) {
  const paymentsResult = await sdk.payment.listPayments({
    connectionId,
    limit: 10,
  });
  return paymentsResult.payments;
}

Step 6: Creating a Payment Link

export async function createPaymentLink(connectionId: string, amount: number, currency: string) {
  const linkResult = await sdk.payment.createLink({
    connectionId,
    link: {
      amount,
      currency,
      description: "Payment for order #123",
      status: "LINK_STATUS_ACTIVE",
    },
  });
  return linkResult.link;
}

Step 7: Creating a Refund

export async function createRefund(connectionId: string, paymentId: string, amount: number) {
  const refundResult = await sdk.payment.createRefund({
    connectionId,
    refund: {
      paymentId,
      amount,
      reason: "requested_by_customer",
    },
  });
  return refundResult.refund;
}

Step 8: Creating a Payout

export async function createPayout(connectionId: string, amount: number, currency: string, destination: string) {
  const payoutResult = await sdk.payment.createPayout({
    connectionId,
    payout: {
      amount,
      currency,
      destination,
      status: "PAYOUT_STATUS_PENDING",
    },
  });
  return payoutResult.payout;
}

Step 9: Creating a Subscription

export async function createSubscription(connectionId: string, customerId: string, planId: string) {
  const subscriptionResult = await sdk.payment.createSubscription({
    connectionId,
    subscription: {
      customerId,
      planId,
      status: "SUBSCRIPTION_STATUS_ACTIVE",
    },
  });
  return subscriptionResult.subscription;
}

Step 10: Example Usage

Here's how you might use these functions in your payment workflow:

async function main() {
  // 1. Create a payment
  const payment = await createPayment(CONNECTION_STRIPE!, 1000, "USD", "cus_123");

  // 2. List payments
  const payments = await listPayments(CONNECTION_STRIPE!);

  // 3. Create a payment link
  const link = await createPaymentLink(CONNECTION_STRIPE!, 1000, "USD");

  // 4. Create a refund
  if (payment?.id) {
    const refund = await createRefund(CONNECTION_STRIPE!, payment.id, 500);
    console.log("Refund:", refund);
  }

  // 5. Create a payout
  const payout = await createPayout(CONNECTION_STRIPE!, 1000, "USD", "acct_456");

  // 6. Create a subscription
  const subscription = await createSubscription(CONNECTION_STRIPE!, "cus_123", "plan_789");

  console.log("Payment:", payment);
  console.log("Payments:", payments);
  console.log("Payment Link:", link);
  console.log("Payout:", payout);
  console.log("Subscription:", subscription);
}

main();

Happy building! 🎉