Actions / Events

This document provides comprehensive implementation requirements for building workflow integrations (Zapier, Make.com, n8n, etc.) with Shuttle Payment Links. It details the exact fields that need to be exposed to users and how they map to our API.

Understanding This Document

Document Structure

Each endpoint section is organized into three parts:

1. Endpoint Overview - Basic information about the endpoint including the HTTP method and API path
2. Input Fields - Fields that users configure in the workflow platform
3. Output Fields - Data returned to users after the API call

Interpreting Input Fields

Input fields represent the user-facing interface in your workflow platform. Each input field entry contains:

• Display Name: The name of the field as it should appear in the workflow platform
• Field ID: The exact field name to expose in your UI (e.g., payment_link__amount)
• Type: The data type (string, boolean, number, etc.)
• Required: Whether the field must be provided
• API Mapping: How this field maps to the Shuttle API request structure
• Description: User-friendly description for the field including any special handling instructions, validation rules, or conversion requirements

Interpreting Output Fields

Output fields represent the data returned from the API that should be made available to subsequent workflow steps. Each output field entry contains:

• Display Name: The field name as it should appear in the workflow platform
• Field ID: The exact field name to expose in your UI (e.g., payment_link__amount)
• Source Path: The JSON path in the API response where this data comes from
• Type: The data type of the field
• Description: What this field represents including any transformation or special handling required

Implementation Guidelines

Auto-fill Text Feature

The auto_fill_text field allows natural language input that automatically populates other fields. Fields containing the word "auto" (except state parameters) will be filled based on this text. Use auto:default_value syntax to set defaults.

Expiry Date Handling

Payment links support two methods for setting expiration:

• Direct datetime: expires field accepts ISO 8601 datetime
• Relative seconds: expires_in field accepts seconds from now

When implementing expires_in, convert to ISO datetime:

const expiresDate = new Date(Date.now() + (expires_in * 1000)).toISOString();

State Fields

State fields (state1 through state9) allow users to attach custom data to payment links. This data is returned unchanged in webhooks and redirect URLs, enabling workflow tracking and correlation.

Field Validation

• Currency must be a valid 3-letter ISO code (USD, EUR, GBP, etc.)
• Amounts must be in decimal format (e.g., "29.99", not "2999" cents)
• URLs must be valid and use HTTPS protocol
• Email addresses must be properly formatted

Data Type Conversion

Ensure proper type conversion throughout your implementation:

• Boolean fields: Use true/false values, not string representations
• Decimal amounts: Use string format (e.g., "29.99"), not integers in cents
• Datetime fields: Use ISO 8601 format for all date/time values

Field Naming Convention

The double underscore (__) convention helps users understand the data hierarchy and prevents naming conflicts in workflow platforms. If your platform does not support double underscores, single underscores are acceptable.

Error Handling

All endpoints should properly handle and expose error responses including:

• Validation errors (400)
• Authentication failures (401)
• Resource not found errors (404)
• Server errors (500)

Action: Create Payment Link

Endpoint: POST /c/api/instances/{instance_key}/payment_links

Creates a new shareable payment link that customers can use to make payments.

Input Fields

Output Fields

Action: Update Payment Link

Endpoint: PUT /c/api/instances/{instance_key}/payment_links/{payment_link_id}

Updates an existing payment link. All fields are optional - only provided fields will be updated.

Input Fields

Output Fields

Action: Get Payment Link

Endpoint: GET /c/api/instances/{instance_key}/payment_links/{payment_link_id}?expand=account,contract,charge,transaction,payment_method

Retrieves detailed information about a payment link including all related data.

TIP!: The Get Payment Link endpoint must include the expand parameter to retrieve all related data in a single API call.

Input Fields

Output Fields

Action: Cancel Payment Link

Endpoint: DELETE /c/api/instances/{instance_key}/payment_links/{payment_link_id}

Cancels/archives a payment link, preventing any future payments.

Input Fields

Output Fields

This endpoint returns an empty response (HTTP 204) on success.

Event: Payment Link Notification

This is a trigger that receives webhook notifications when payment link events occur.

Input Fields (Webhook Payload)

Output Fields (Transformed for Workflow)