Advanced Features

Enhance your integration with advanced features like KYC import, external order tracking, and comprehensive user data pre-filling for improved conversion rates and user experience.

Overview

Advanced features allow you to:

Import existing KYC data to skip verification steps
Track orders with your internal identifiers
Pre-fill user information to reduce friction
Implement custom business logic before order creation

KYC Import with SumSub

Import existing KYC verification data using SumSub share tokens to streamline the user experience for returning customers.

If you have existing KYC data in SumSub, generate a share token for the user:

// Your SumSub integration
const shareToken = await sumSubClient.generateShareToken(userId);

async function createOrderWithKYC(
  secretKey,
  {
    amount,
    fromCurrency,
    toCurrency,
    targetAddress,
    userEmail,
    userPhone,
    shareToken, // SumSub share token
    externalId,
  },
) {
  const response = await fetch(
    "https://api.swipelux.com/api/orders/createPrepared",
    {
      method: "POST",
      headers: {
        Authorization: secretKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amounts: {
          from: { amount, currency: fromCurrency },
          to: { currency: toCurrency },
        },
        user: { email: userEmail, phone: userPhone },
        targetAddress,
        shareToken, // This imports the KYC data
        externalId,
      }),
    },
  );
 
  return await response.json();
}

Handle KYC-Enabled Response

Users with valid KYC data will skip verification steps:

{
  "orderId": "ord_abc123def456",
  "orderToken": "ord_token_abc123def456",
  "acsUrl": "https://track.swipelux.com?specificSettings={...}",
  "externalId": "user_purchase_123",
  "kycStatus": "VERIFIED"
}

External Order Tracking

Link orders to your internal systems using external identifiers for seamless tracking and reconciliation.

Implementation

const orderData = {
  amounts: {
    from: { amount: 100, currency: "USD" },
    to: { currency: "USDC" },
  },
  user: {
    email: "user@example.com",
    phone: "+1234567890"
  },
  targetAddress: "0x1234...",
  externalId: `${userId}_purchase_${Date.now()}`, // Your unique identifier
};
 
const response = await fetch(
  "https://api.swipelux.com/api/orders/createPrepared",
  {
    method: "POST", 
    headers: {
      Authorization: "YOUR_SECRET_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderData),
  },
);

Webhook Integration

Receive webhooks with your external ID for easy matching:

{
  "type": "order.completed",
  "data": {
    "orderId": "ord_abc123",
    "externalId": "user456_purchase_1642781776000", // Your ID
    "status": "SUCCESS",
    "amounts": {
      "from": { "amount": 100, "currency": "USD" },
      "to": { "amount": 99.2, "currency": "USDC" }
    }
  }
}

Complete User Data Pre-filling

Maximize conversion rates by pre-filling all available user information.

Full Integration Example

async function createAdvancedOrder({
  // Required parameters
  amount,
  fromCurrency,
  toCurrency, 
  targetAddress,
  userEmail,
  userPhone,
  
  // Advanced parameters
  paymentChannel = null,
  shareToken = null,
  externalId = null,
  
  // Additional user data
  userName = null,
  userCountry = null,
}) {
  const orderData = {
    amounts: {
      from: { amount, currency: fromCurrency },
      to: { currency: toCurrency },
    },
    user: {
      email: userEmail,
      phone: userPhone,
    },
    targetAddress,
  };
 
  // Add optional parameters
  if (paymentChannel) orderData.paymentChannel = paymentChannel;
  if (shareToken) orderData.shareToken = shareToken;  
  if (externalId) orderData.externalId = externalId;
  
  // Add extended user data if available
  if (userName) orderData.user.name = userName;
  if (userCountry) orderData.user.country = userCountry;
 
  const response = await fetch(
    "https://api.swipelux.com/api/orders/createPrepared",
    {
      method: "POST",
      headers: {
        Authorization: "YOUR_SECRET_KEY",
        "Content-Type": "application/json", 
      },
      body: JSON.stringify(orderData),
    },
  );
 
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Order creation failed: ${error.message}`);
  }
 
  return await response.json();
}

Usage Example

try {
  // Create order with comprehensive user data
  const order = await createAdvancedOrder({
    // Transaction details
    amount: 250,
    fromCurrency: "EUR",
    toCurrency: "ETH",
    targetAddress: "0x742d35Cc6609A338B7d1f8ABE7D3A8CBDDB22b13",
    
    // User information
    userEmail: "premium.user@company.com",
    userPhone: "+49123456789",
    userName: "John Doe",
    userCountry: "DE",
    
    // Advanced features
    paymentChannel: "OPEN_BANKING", // EU-optimized
    shareToken: "sumsub_share_token_xyz789", // Import KYC
    externalId: `premium_${userId}_${new Date().toISOString()}`,
  });
 
  console.log("Advanced order created:", {
    orderId: order.orderId,
    orderToken: order.orderToken,
    externalId: order.externalId,
  });
  
  // Redirect user to complete payment
  window.location.href = order.acsUrl;
  
} catch (error) {
  console.error("Order creation failed:", error.message);
  // Handle error appropriately
}

Business Intelligence Integration

Track order creation with comprehensive metadata:

function createOrderWithAnalytics(userSession, transactionData) {
  const externalId = `${userSession.userId}_${transactionData.type}_${Date.now()}`;
  
  const orderData = {
    ...transactionData,
    externalId,
    user: {
      email: userSession.email,
      phone: userSession.phone,
      // Add analytics context
      referrer: document.referrer,
      userAgent: navigator.userAgent,
      sessionId: userSession.id,
    },
  };
 
  return fetch("https://api.swipelux.com/api/orders/createPrepared", {
    method: "POST",
    headers: {
      Authorization: "YOUR_SECRET_KEY", 
      "Content-Type": "application/json",
    },
    body: JSON.stringify(orderData),
  });
}

Error Handling and Validation

Implement robust error handling for production environments:

class SwipeluxOrderService {
  constructor(secretKey) {
    this.secretKey = secretKey;
    this.baseUrl = "https://api.swipelux.com/api/orders";
  }
 
  async createOrder(orderData) {
    // Validate required fields
    this.validateOrderData(orderData);
 
    try {
      const response = await fetch(`${this.baseUrl}/createPrepared`, {
        method: "POST",
        headers: {
          Authorization: this.secretKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(orderData),
      });
 
      if (!response.ok) {
        const error = await response.json();
        throw new SwipeluxApiError(error.message, error.code, response.status);
      }
 
      const result = await response.json();
      
      // Log successful order creation
      this.logOrderCreation(result);
      
      return result;
      
    } catch (error) {
      this.handleOrderError(error, orderData);
      throw error;
    }
  }
 
  validateOrderData(data) {
    const required = ['amounts', 'user', 'targetAddress'];
    for (const field of required) {
      if (!data[field]) {
        throw new ValidationError(`Missing required field: ${field}`);
      }
    }
 
    if (!data.amounts.from?.amount || !data.amounts.from?.currency) {
      throw new ValidationError('Invalid amounts.from structure');
    }
 
    if (!data.amounts.to?.currency) {
      throw new ValidationError('Missing amounts.to.currency');
    }
  }
 
  logOrderCreation(result) {
    console.log('Order created successfully:', {
      orderId: result.orderId,
      externalId: result.externalId,
      timestamp: new Date().toISOString(),
    });
  }
 
  handleOrderError(error, orderData) {
    console.error('Order creation failed:', {
      error: error.message,
      orderData: { ...orderData, user: '***' }, // Don't log sensitive data
      timestamp: new Date().toISOString(),
    });
  }
}
 
class SwipeluxApiError extends Error {
  constructor(message, code, status) {
    super(message);
    this.name = 'SwipeluxApiError';
    this.code = code;
    this.status = status;
  }
}
 
class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'ValidationError';
  }
}

Complete API Reference

Request Parameters

Prop	Type	Default
`externalId?`	`string`	-
`shareToken?`	`string`	-
`paymentChannel?`	`string`	-
`targetAddress`	`string`	-
`user`	`object`	-
`amounts`	`object`	-

For complete parameter specifications, see the Basic Integration reference section.

Next Steps

After implementing advanced features:

Monitor performance: Track conversion rates with different feature combinations
Optimize UX: A/B test KYC import vs. standard flow for returning users
Scale operations: Use external IDs for automated reconciliation and reporting
Handle events: Set up webhooks to process order completion events
Track orders: Monitor status with GET order API

On this page