Skip to content
ShuttleShuttle Docs
Status
View as MarkdownPlain text for AI toolsOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this pageOpen in GitHub CopilotAsk questions about this page

Integration guide

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

Overview

Section titled “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:

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

Setup

Section titled “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

Section titled “Message Handling”

1. Capability Check

Section titled “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)

Section titled “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: 'john.doe@example.com',
    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);
  }
});
Section titled “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: 'john.doe@example.com',
    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);
    }
  }
});

Was this page helpful?