Recurring Payments (Subscriptions)

Subscription payments are currently supported on the following EVM-compatible chains:

Note: Currently, only USDC is supported as the payment currency for subscriptions. You can use "POL" or "MATIC" interchangeably for Polygon.

Complete Subscription Flow

import axios from 'axios';

const BASE_URL = 'https://beprod.dashx.xyz';
const API_KEY = 'your_api_key';
const MERCHANT_ID = 'your_merchant_id';

// Step 1: Merchant creates a subscription payment link
async function createSubscriptionLink() {
  const response = await axios.post(
    `${BASE_URL}/payment-link/`,
    {
      link_type: 'SUBSCRIPTION',
      token: 'USDC',
      accepted_chain_symbols: ['POL', 'ARB', 'ETH'],
      amount: '10.00',
      title: 'Premium Membership',
      description: 'Monthly premium subscription',
      merchant: MERCHANT_ID,
      subscription_frequency: 'MONTHLY',
      subscription_interval: 1,
      subscription_duration: 12,
      collect_email: true
    },
    {
      headers: {
        'X-API-KEY': API_KEY,
        'X-MERCHANT-ID': MERCHANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

// Step 2: Customer visits gateway and subscribes
// The customer visits: https://gateway.dashx.xyz/gateway?slug={paymentLink.slug}
// They connect their wallet and approve the token allowance through the UI
// The subscription is automatically created when they approve the allowance

// Step 3: Merchant checks payment status
async function checkPaymentStatus(slug, walletAddress, subscriptionId) {
  const response = await axios.post(
    `${BASE_URL}/subscriptions/check-payment-status/`,
    {
      slug: slug,
      wallet_address: walletAddress,
      subscription_id: subscriptionId
    }
  );
  
  return response.data;
}

// Step 4: Merchant lists customer subscriptions
async function listCustomerSubscriptions(customerWallet) {
  const response = await axios.get(
    `${BASE_URL}/subscriptions/?customer_wallet=${customerWallet}`,
    {
      headers: {
        'X-API-KEY': API_KEY,
        'X-MERCHANT-ID': MERCHANT_ID
      }
    }
  );
  
  return response.data;
}

// Step 5: Merchant cancels subscription (if needed)
async function cancelSubscription(subscriptionId) {
  const response = await axios.post(
    `${BASE_URL}/subscriptions/${subscriptionId}/cancel/`,
    {},
    {
      headers: {
        'X-API-KEY': API_KEY,
        'X-MERCHANT-ID': MERCHANT_ID,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

// Example usage
async function main() {
  // Merchant creates payment link
  const paymentLink = await createSubscriptionLink();
  console.log('Payment link created:', paymentLink.slug);
  console.log('Share this link with customers:', paymentLink.link);
  
  // Customer visits the gateway link and subscribes (happens in browser UI)
  // After customer subscribes, merchant can list their subscriptions
  const customerWallet = '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb';
  const subscriptions = await listCustomerSubscriptions(customerWallet);
  console.log('Customer subscriptions:', subscriptions);
  
  // If merchant needs to cancel a subscription
  if (subscriptions.length > 0) {
    const result = await cancelSubscription(subscriptions[0].id);
    console.log('Cancellation result:', result);
  }
}

main();

DashX sends webhook events to your configured endpoint for subscription-related events. Each webhook includes an HMAC signature for verification.

Event Types

Webhook Payload Format

{
  "id": "evt_1a2b3c4d5e6f",
  "apiVersion": "2023-01-11",
  "created": 1697234567000,
  "object": "checkoutSession",
  "type": "checkout_session.completed",
  "data": {
    "object": {
      "id": "pay_abc123def456",
      "createdAt": "2024-10-14T12:05:30Z",
      "amountTotal": "10.00",
      "status": "SUCCESS",
      "currency": "USDC",
      "customer_id": "customer_123",
      "payment_link_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "payment_link_title": "Premium Membership",
      "payment_link_slug": "premium-membership-xyz123",
      "transaction_hash": "0x9876543210fedcba9876543210fedcba98765432...",
      "from_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "payment_address": "0xd0dd2d1f25b3efdb24bdb224be2d65cd98b5a975",
      "chain_symbol": "ARB",
      "payment_amount": "10.00",
      "payment_processing_fee": "0.00",
      "updatedAt": "2024-10-14T12:05:35Z"
    }
  }
}

Webhook Headers

{
  "Content-Type": "application/json",
  "X-DashX-Signature": "t=1697234567000,v1=abc123def456..."
}

Verifying Webhook Signatures

Always verify the webhook signature to ensure the request is from DashX:

import hmac
import hashlib

def verify_webhook_signature(payload, signature_header, webhook_secret):
    # Extract timestamp and signature from header
    parts = signature_header.split(',')
    timestamp = parts[0].split('=')[1]
    signature = parts[1].split('=')[1]
    
    # Create HMAC signature
    expected_signature = hmac.new(
        webhook_secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Compare signatures
    return hmac.compare_digest(signature, expected_signature)

# Usage in your webhook endpoint
@app.post('/webhook')
def handle_webhook(request):
    payload = request.body.decode('utf-8')
    signature = request.headers.get('X-DashX-Signature')
    webhook_secret = 'your_webhook_secret'
    
    if not verify_webhook_signature(payload, signature, webhook_secret):
        return {'error': 'Invalid signature'}, 401
    
    event = json.loads(payload)
    
    if event['type'] == 'checkout_session.completed':
        # Handle successful subscription payment
        payment_data = event['data']['object']
        print(f"Payment {payment_data['id']} completed for {payment_data['amountTotal']} {payment_data['currency']}")
    
    elif event['type'] == 'checkout_session.canceled':
        # Handle failed subscription payment
        payment_data = event['data']['object']
        print(f"Payment {payment_data['id']} failed after max retries")
    
    return {'received': True}, 200