How to Build a Fintech Application with Unified's Payments API

October 11, 2025

Introduction

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

You can do various things such as creating payments, generating payment links, manage payouts and even handle refunds - all without building custom connectors for each payment provider.

In this guide, we will show you how to create and list payments as well as some related data. 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 app to access their payment provider via Unified's embedded auth flow.

Once authorized, you'll receive a connection ID for each integrations.

Step 4: Listing Payments

export async function listPayments(connectionId: string) {
  const payments = await sdk.payment.listPaymentPayments({
    connectionId,
    limit: 10,
  });
  return payments; // PaymentPayment[]
}

Step 5: Creating a Payment Link

export async function createPaymentLink(connectionId: string, amount: number, currency: string) {
  const link = await sdk.link.createPaymentLink({
    connectionId,
    paymentLink: {
      amount,
      currency,
      isActive: true,
      successUrl: "<https://example.com/success>",
      // Stripe typically requires line items on links
      lineitems: [
        {
          itemName: "Order #123",
          unitAmount: amount,
          unitQuantity: 1,
          itemSku: "SKU-123",
        },
      ],
    },
  });
  return link; // PaymentLink
}

Step 6: Listing Refunds

export async function listRefunds(connectionId: string) {
  const refunds = await sdk.refund.listPaymentRefunds({
    connectionId,
    limit: 10,
  });
  return refunds; // PaymentRefund[]
}

Step 7: Listing Payouts

export async function listPayouts(connectionId: string) {
  const payouts = await sdk.payout.listPaymentPayouts({
    connectionId,
    limit: 10,
  });
  return payouts; // PaymentPayout[]
}

Step 8: Listing Subscriptions

export async function listSubscriptions(connectionId: string) {
  const subs = await sdk.subscription.listPaymentSubscriptions({
    connectionId,
    limit: 10,
  });
  return subs; // PaymentSubscription[]
}

Step 9: 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");

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

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

  // 4. List links
  const links = await sdk.link.listPaymentLinks({ connectionId: CONNECTION_STRIPE!, limit: 10 });

  // 5. List refunds
  const refunds = await listRefunds(CONNECTION_STRIPE!);

  // 6. List payouts
  const payouts = await listPayouts(CONNECTION_STRIPE!);

  // 7. List subscriptions (creation may not be implemented for some providers)
  const subscriptions = await listSubscriptions(CONNECTION_STRIPE!);

  console.log("Payment:", payment);
  console.log("Payments count:", payments.length);
  console.log("Payment Link URL:", link.url);
  console.log("Links count:", links.length);
  console.log("Refunds count:", refunds.length);
  console.log("Payouts count:", payouts.length);
  console.log("Subscriptions count:", subscriptions.length);
}

main();

Happy building! 🎉