Payment Providers API

Direct integration endpoints for each supported payment provider. Use these when you need granular control over the payment flow.

For most use cases, use the unified /api/checkout/initialize endpoint which automatically routes to the correct provider.

Stripe

Create Payment Intent

Create a Stripe PaymentIntent for client-side payment collection.

POST /api/providers/stripe/create-intent
Content-Type: application/json

Request Body

interface CreateIntentRequest {
  amount: number;           // Amount in cents (9999 = $99.99)
  currency: string;         // ISO 4217 code (e.g., "USD")
  orderId: string;          // Your order identifier
  customer?: {
    email: string;
    name?: string;
    firstName?: string;
    lastName?: string;
  };
  metadata?: Record<string, string>;
  shippingAddress?: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
}

Example Request

{
  "amount": 9999,
  "currency": "USD",
  "orderId": "order_123",
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "metadata": {
    "source": "api"
  }
}

Response

{
  "success": true,
  "paymentIntentId": "pi_3ABC123DEF456",
  "clientSecret": "pi_3ABC123DEF456_secret_xyz789"
}

Use the clientSecret with Stripe.js on the frontend to complete payment.

Confirm Payment

Confirm a PaymentIntent after frontend payment completion.

POST /api/providers/stripe/confirm
Content-Type: application/json

Request Body

{
  "paymentIntentId": "pi_3ABC123DEF456"
}

Response

{
  "success": true,
  "status": "succeeded",
  "paymentIntentId": "pi_3ABC123DEF456",
  "orderId": "order_123",
  "paymentMethodId": "pm_1ABC123"
}

Statuses:

succeeded - Payment complete
processing - Payment in progress
requires_action - Additional authentication needed (3D Secure)
failed - Payment failed

NMI

Process Payment

Process a payment directly through NMI gateway.

POST /api/providers/nmi/process-payment
Content-Type: application/json

Request Body

interface NmiPaymentRequest {
  orderId: string;
  cardNumber: string;
  cardExpMonth: string;
  cardExpYear: string;
  cardCvv: string;
  amount: number;           // In cents
  currency: string;
  customer?: {
    email: string;
    firstName: string;
    lastName: string;
  };
  billingAddress?: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
}

Response

{
  "success": true,
  "transactionId": "txn_nmi_123456",
  "orderId": "order_123",
  "paymentMethodToken": "vault_123|txn_nmi_123456",
  "demo": false
}

The paymentMethodToken format is customerVaultId|transactionId for use in upsell charges.

Process Upsell

Process a 1-click upsell using a saved payment method.

POST /api/providers/nmi/process-upsell
Content-Type: application/json

Request Body

{
  "paymentMethodToken": "vault_123|txn_nmi_123456",
  "amount": 1999,
  "orderId": "upsell_order_123",
  "originalOrderId": "order_123"
}

Sticky.io

Create Order

Create a Sticky.io order without processing payment.

POST /api/providers/sticky/create-order
Content-Type: application/json

Request Body

interface StickyCreateOrderRequest {
  orderId: string;
  customer: {
    email: string;
    firstName: string;
    lastName: string;
    phone?: string;
  };
  shippingAddress: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  billingAddress: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  lineItems: Array<{
    productId: string;
    quantity: number;
    price: number;
  }>;
  total: number;
  currency: string;
  campaignId?: string;
}

Response

{
  "success": true,
  "stickyOrderId": "sticky_12345678",
  "demo": false
}

Process Payment

Process payment on an existing Sticky.io order.

POST /api/providers/sticky/process-payment
Content-Type: application/json

Request Body

{
  "stickyOrderId": "sticky_12345678",
  "cardNumber": "4111111111111111",
  "cardExpMonth": "12",
  "cardExpYear": "2025",
  "cardCvv": "123",
  "orderId": "order_123"
}

Response

{
  "success": true,
  "transactionId": "txn_sticky_123",
  "stickyOrderId": "sticky_12345678"
}

Confirm Order

Confirm a Sticky.io order after payment.

POST /api/providers/sticky/confirm-order
Content-Type: application/json

Konnektive

Process Payment

Process payment through Konnektive CRM.

POST /api/providers/konnektive/process-payment
Content-Type: application/json

Request Body

interface KonnektivePaymentRequest {
  orderId: string;
  campaignId: string;
  customer: {
    email: string;
    firstName: string;
    lastName: string;
    phone?: string;
  };
  billingAddress: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  shippingAddress?: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  lineItems: Array<{
    productId: string;
    quantity: number;
    price: number;
  }>;
  cardNumber: string;
  cardExpMonth: string;
  cardExpYear: string;
  cardCvv: string;
}

Shopify

Create Checkout

Create a Shopify checkout session (draft order).

POST /api/providers/shopify/create-checkout
Content-Type: application/json

Request Body

{
  "orderId": "order_123",
  "lineItems": [
    {
      "variantId": "gid://shopify/ProductVariant/123",
      "quantity": 1
    }
  ],
  "customer": {
    "email": "customer@example.com"
  }
}

Returns a checkoutUrl for redirecting customers to Shopify's hosted checkout.

Complete Checkout

Complete a Shopify checkout after payment.

POST /api/providers/shopify/complete-checkout
Content-Type: application/json

Request Body

{
  "shopifyOrderId": "gid://shopify/DraftOrder/123456",
  "orderId": "order_123"
}

Confirm Order

Confirm a Shopify order.

POST /api/providers/shopify/confirm-order
Content-Type: application/json

UltraCart

Create Cart

Create an UltraCart cart for checkout.

POST /api/providers/ultracart/create-cart
Content-Type: application/json

Request Body

{
  "orderId": "order_123",
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "shippingAddress": {
    "line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  },
  "lineItems": [
    {
      "itemId": "ITEM-001",
      "quantity": 1,
      "price": 9999
    }
  ]
}

Response

{
  "success": true,
  "ultraCartOrderId": "UC-12345678",
  "demo": false
}

Process Payment

Process payment on an existing UltraCart cart.

POST /api/providers/ultracart/process-payment
Content-Type: application/json

Request Body

{
  "ultraCartOrderId": "UC-12345678",
  "cardNumber": "4111111111111111",
  "cardExpMonth": "12",
  "cardExpYear": "25",
  "cardCvv": "123",
  "orderId": "order_123"
}

Response

{
  "success": true,
  "transactionId": "UC-FINAL-12345678",
  "ultraCartOrderId": "UC-FINAL-12345678",
  "demo": false
}

EPD (Easy Pay Direct)

Process Payment

Process a payment through the EPD gateway.

POST /api/providers/epd/process-payment
Content-Type: application/json

Request Body

interface EpdPaymentRequest {
  orderId: string;
  cardNumber: string;
  cardExpMonth: string;
  cardExpYear: string;
  cardCvv: string;
  amount: number;           // In cents
  currency?: string;        // Default: "USD"
  customer?: {
    email: string;
    firstName: string;
    lastName: string;
    phone?: string;
  };
  billingAddress?: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  shippingAddress?: {
    line1: string;
    line2?: string;
    city: string;
    state: string;
    postalCode: string;
    country: string;
  };
  lineItems?: Array<{
    productId: string;
    quantity: number;
    price: number;
  }>;
}

Example Request

{
  "orderId": "order_123",
  "cardNumber": "4111111111111111",
  "cardExpMonth": "12",
  "cardExpYear": "25",
  "cardCvv": "123",
  "amount": 9999,
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Response

{
  "success": true,
  "transactionId": "epd_txn_123456",
  "orderId": "order_123",
  "paymentMethodToken": "vault_abc|epd_txn_123456",
  "demo": false
}

The paymentMethodToken format is customerVaultId|transactionId for use in upsell charges.

Demo Mode

All payment providers run in demo mode when credentials are not configured. Demo mode:

Returns mock successful responses
Generates realistic-looking transaction IDs
Allows full integration testing without real credentials
Includes "demo": true in responses

Example demo response:

{
  "success": true,
  "paymentIntentId": "pi_demo_1704067200_abc123",
  "clientSecret": "pi_demo_1704067200_abc123_secret_xyz",
  "demo": true
}

Payment Method Tokens

Each provider returns payment method tokens in different formats for use in upsell charges:

Provider	Token Format	Usage
Stripe	`paymentMethodId\|customerId`	PaymentIntent with saved method
NMI	`customerVaultId\|transactionId`	Customer vault charge
Sticky.io	`stickyOrderId`	Add-to-order upsell
Konnektive	`orderId`	Add-to-order upsell
Shopify	`orderId`	Draft order modification
UltraCart	`ultraCartOrderId`	Order modification
EPD	`customerVaultId\|transactionId`	Customer vault charge

Environment Variables

Configure credentials for each provider:

# Stripe
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

# NMI
NMI_SECURITY_KEY=your-nmi-key

# Sticky.io
STICKY_API_URL=https://api.sticky.io
STICKY_API_KEY=your-sticky-key

# Konnektive
KONNEKTIVE_API_URL=https://api.konnektive.com
KONNEKTIVE_USERNAME=your-username
KONNEKTIVE_PASSWORD=your-password

# Shopify
SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_STOREFRONT_TOKEN=your-storefront-token
SHOPIFY_ADMIN_TOKEN=your-admin-token

# UltraCart
ULTRACART_API_KEY=your-ultracart-key
ULTRACART_MERCHANT_ID=your-merchant-id

# EPD
EPD_GATEWAY_URL=https://secure.easypaydirect.com
EPD_USERNAME=your-username
EPD_PASSWORD=your-password

Payment Providers

On this page