Integration Guide

This guide explains how to integrate the Shuttle Payment Link Generator into any call center or software platform.

Overview

Embed our payment link generator in an iframe and communicate with it using the postMessage API. This allows you to pre-populate forms with customer data and receive generated payment links for sharing.

How it works:

Embed our payment link generator in an iframe
The iframe detects your platform and asks what features you support
Optionally, provide customer data to pre-populate forms
Receive generated payment links for sharing through your platform

Setup

Embed the payment link generator in your platform using an iframe:

<iframe 
  id="shuttle-payment-iframe"
  src="https://app.shuttleglobal.com/[LINK-ID]"
  width="100%" 
  height="700">
</iframe>

Replace [LINK-ID] with your actual link generator ID.

Message Handling

1. Capability Check

The iframe will send this message to detect your platform and available features.

Message you'll receive:

{
  type: 'SHUTTLE_LINK_GENERATOR',
  request_id: 'unique-id-123'
}

Your response:

{
  type: 'SHUTTLE_LINK_GENERATOR_RESPONSE',
  request_id: 'unique-id-123',
  success: true,
  error: undefined, // or string where applicable
  payload: {
    platform: 'Your Platform Name',
    features: ['GET_DATA', 'SHARE_LINK']
  }
}

Where:

type - Response type: SHUTTLE_LINK_GENERATOR_RESPONSE
request_id - Must match the request_id from the message you received
success - Boolean indicating if the response is successful
error - Error message (only include if success is false)
platform - Your platform name for identification
features - Array of features you support:
- GET_DATA - Your platform can provide customer data to pre-populate forms
- SHARE_LINK - Your platform can receive generated payment links for sharing

Example:

window.addEventListener('message', function(event) {
  // Security check - only accept messages from Shuttle domain
  if (event.origin !== 'https://app.shuttleglobal.com') {
    return;
  }

  // Check if this is the capability check message
  if (event.data.type === 'SHUTTLE_LINK_GENERATOR') {
    // Respond with your platform capabilities
    event.source.postMessage({
      type: 'SHUTTLE_LINK_GENERATOR_RESPONSE',
      request_id: event.data.request_id,
      success: true,
      payload: {
        platform: 'Your Platform Name',
        features: ['GET_DATA', 'SHARE_LINK']
      }
    }, event.origin);
  }
});

2. Data Request (Optional)

If you indicated GET_DATA support, the iframe will request customer data to pre-populate the form. Depending on your system, you might know just customer information, or you might also know payment details like the amount. Simply populate whatever information you have available - all fields are optional.

Message you'll receive:

{
  type: 'SHUTTLE_LINK_GENERATOR_GET_DATA',
  request_id: 'unique-id-456'
}

Your response:

{
  type: 'SHUTTLE_LINK_GENERATOR_GET_DATA_RESPONSE',
  request_id: 'unique-id-456',
  success: true,
  error: undefined, // or string where applicable
  payload: {
    // Payment fields
    link_title: 'Payment Request',
    page_intro: 'Welcome! Please complete your payment below.',
    currency: 'USD',
    amount: '100.00',
    alt_key: 'REF123',
    description: 'Payment for services',
    expires: '2025-10-08T16:44:18.920Z',

    // Customer fields (all prefixed with account_)
    account_crm_key: 'CUSTOMER_ID_789',
    account_first_name: 'John',
    account_last_name: 'Doe',
    account_email: '[email protected]',
    account_phone: '+1234567890',

    // Custom metadata fields (prefixed with metadata_)
    metadata_order_number: 'ORD-2024-001',
    metadata_department: 'Sales',
    metadata_priority: 'High'
  }
}

Where:

type - Response type: SHUTTLE_LINK_GENERATOR_GET_DATA_RESPONSE
request_id - Must match the request_id from the message you received
success - Boolean indicating if the response is successful
error - Error message (only include if success is false)
link_title - Title for the payment link
page_intro - Custom welcome message shown to the customer
amount - Payment amount in decimal format (e.g., "100.00")
currency - 3-letter ISO currency code (USD, EUR, GBP)
alt_key - Your internal reference/order ID
description - Description of what the payment is for
expires - ISO timestamp when the link should expire
account_crm_key - Your internal customer ID
account_first_name - Customer's first name
account_last_name - Customer's last name
account_email - Customer's email address
account_phone - Customer's phone number
metadata_${key} - Custom metadata fields (e.g., metadata_order_number, metadata_department). Key is case-sensitive. Only metadata fields configured for this payment link generator and marked as editable can be pre-filled.

Example:

window.addEventListener('message', function(event) {
  // Security check - only accept messages from Shuttle domain
  if (event.origin !== 'https://app.shuttleglobal.com') {
    return;
  }

  if (event.data.type === 'SHUTTLE_LINK_GENERATOR_GET_DATA') {
    // Get customer data from your platform
    const customerData = getCurrentCustomerData();
    
    event.source.postMessage({
      type: 'SHUTTLE_LINK_GENERATOR_GET_DATA_RESPONSE',
      request_id: event.data.request_id,
      success: true,
      payload: customerData
    }, event.origin);
  }
});

3. Share Link (Optional)

If you indicated SHARE_LINK support, the iframe will send generated payment links along with all the form data and customer information. This gives you everything needed to formulate an appropriate message to the customer and send it through your preferred channel (SMS, email, etc.).

Message you'll receive:

{
  type: 'SHUTTLE_LINK_GENERATOR_SHARE_LINK',
  request_id: 'unique-id-789',
  payload: {
    // Form data
    amount: '100.00',
    currency: 'USD',
    alt_key: 'REF123',
    description: 'Payment for services',

    // Customer data
    account_crm_key: 'CUSTOMER_ID_789',
    account_first_name: 'John',
    account_last_name: 'Doe',
    account_email: '[email protected]',
    account_phone: '+1234567890',

    // Custom metadata fields
    metadata_order_number: 'ORD-2024-001',
    metadata_department: 'Sales',
    metadata_priority: 'High',

    // Generated payment link
    link: 'https://app.shuttleglobal.com/pay/abc123',
    expires: '2024-12-31T23:59:59Z'
  }
}

Your response:

{
  type: 'SHUTTLE_LINK_GENERATOR_SHARE_LINK_RESPONSE',
  request_id: 'unique-id-789',
  success: true,
  error: undefined // or string where applicable
}

Where:

type - Response type: SHUTTLE_LINK_GENERATOR_SHARE_LINK_RESPONSE
request_id - Must match the request_id from the message you received
success - Boolean indicating if the sharing was successful
error - Error message (only include if success is false)
link - The generated payment link to share with the customer
expires - ISO timestamp when the link expires
amount - Payment amount in decimal format
currency - 3-letter ISO currency code
alt_key - Your internal reference/order ID
description - Description of what the payment is for
account_crm_key - Your internal customer ID
account_first_name - Customer's first name
account_last_name - Customer's last name
account_email - Customer's email address
account_phone - Customer's phone number
metadata_${key} - Custom metadata fields (e.g., metadata_order_number, metadata_department). Key is case-sensitive. Only metadata fields configured for this payment link generator and marked as editable can be pre-filled.

Example:

window.addEventListener('message', function(event) {
  // Security check - only accept messages from Shuttle domain
  if (event.origin !== 'https://app.shuttleglobal.com') {
    return;
  }

  if (event.data.type === 'SHUTTLE_LINK_GENERATOR_SHARE_LINK') {
    try {
      // Share the payment link through your platform
      // e.g., send SMS, email, copy to clipboard, etc.
      shareWithCustomer(event.data.payload.link, event.data.payload);
      
      event.source.postMessage({
        type: 'SHUTTLE_LINK_GENERATOR_SHARE_LINK_RESPONSE',
        request_id: event.data.request_id,
        success: true
      }, event.origin);
    } catch (error) {
      event.source.postMessage({
        type: 'SHUTTLE_LINK_GENERATOR_SHARE_LINK_RESPONSE',
        request_id: event.data.request_id,
        success: false,
        error: error.message
      }, event.origin);
    }
  }
});