Actions and events
This document provides comprehensive implementation requirements for building workflow integrations (such as Zapier and Make.com) 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
Section titled “Understanding this document”Document structure
Section titled “Document structure”Each endpoint section is organized into three parts:
- Endpoint Overview - Basic information about the endpoint including the HTTP method and API path
- Input Fields - Fields that users configure in the workflow platform
- Output Fields - Data returned to users after the API call
Interpreting input fields
Section titled “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
Section titled “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
Section titled “Implementation guidelines”Expiry date handling
Section titled “Expiry date handling”The API takes one expiry field, expires, an ISO 8601 date and time. Offer your users two ways to set it:
- Expires At: a date and time, sent as
expires - Expires In: seconds from now. The API has no
expires_infield, so convert it toexpiresbefore you call the API:
const expiresDate = new Date(Date.now() + (expires_in * 1000)).toISOString();State fields
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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)
Endpoints and authentication
Section titled “Endpoints and authentication”You call the API with the OAuth access token for the merchant’s account, at https://app.shuttleglobal.com/c/api/.... The token identifies the account, so the path has no instance key: for example POST /c/api/payment_links. See Calling the API with an access token.
Action: Create Payment Link
Section titled “Action: Create Payment Link”Endpoint: POST /c/api/payment_links
Creates a new shareable payment link that customers can use to make payments.
Input fields
Section titled “Input fields”| Display Name | Field ID | Type | API Mapping | Description |
|---|---|---|---|---|
| Currency | payment_link__currency |
string | payment_link.options.currency |
(Required) 3-letter currency code. Must be valid ISO code (USD, EUR, GBP, etc.) matching gateway-supported currency |
| Amount | payment_link__amount |
string | payment_link.options.amount |
Payment amount in decimal format (e.g., “29.99”, “1000.00”), not cents |
| Reference | payment_link__alt_key |
string | payment_link.options.alt_key |
Your reference to track payment in your system (e.g., ORDER_1234, INV_567) |
| Customer CRM Key | payment_link__account_crm_key |
string | payment_link.options.account.crm_key |
Your unique CRM identifier to link payment to existing customer |
| Customer First Name | payment_link__account_first_name |
string | payment_link.options.account.first_name |
Customer first name |
| Customer Last Name | payment_link__account_last_name |
string | payment_link.options.account.last_name |
Customer last name |
| Customer Email | payment_link__account_email |
string | payment_link.options.account.email |
Customer email address. Must be valid email format |
| Customer Phone | payment_link__account_phone |
string | payment_link.options.account.phone |
Customer phone number |
| Save Card | payment_link__save_card |
boolean | payment_link.options.save_card |
Save payment method. true = always save, false = never save, unset = user choice |
| Skip Receipt | payment_link__skip_receipt |
boolean | payment_link.options.skip_receipt |
Skip receipt page and redirect immediately if true. Default: false |
| Page Success Message | payment_link__page_success_message |
string | payment_link.options.page_success_message |
Message shown when payment succeeds and no success_url provided |
| Page Pending Message | payment_link__page_pending_message |
string | payment_link.options.page_pending_message |
Message shown when payment pending and no pending_url provided |
| Success URL | payment_link__success_url |
string | payment_link.options.success_url |
Success redirect URL. HTTPS required. Query params added: payment_link, status, contract, charge, transaction, payment_method, account |
| Pending URL | payment_link__pending_url |
string | payment_link.options.pending_url |
Pending redirect URL. HTTPS required. Used when payment needs authorization |
| Page Name | payment_link__name |
string | payment_link.options.name |
Name of the page to display in the payment link |
| Page Intro | payment_link__page_intro |
string | payment_link.options.page_intro |
Introductory text to display on the payment page |
| Expires At | payment_link__expires |
string | payment_link.expires |
Expiry datetime in ISO 8601 format. Must be future date/time |
| Expires In | payment_link__expires_in |
number | Convert to payment_link.expires |
Seconds until expiry. Convert to ISO datetime: new Date(Date.now() + (expires_in * 1000)).toISOString() |
| State 1 | state1 |
string | payment_link.state.state1 |
Custom state field 1 - data returned unchanged in webhooks/redirects |
| State 2 | state2 |
string | payment_link.state.state2 |
Custom state field 2 - data returned unchanged in webhooks/redirects |
| State 3 | state3 |
string | payment_link.state.state3 |
Custom state field 3 - data returned unchanged in webhooks/redirects |
| State 4 | state4 |
string | payment_link.state.state4 |
Custom state field 4 - data returned unchanged in webhooks/redirects |
| State 5 | state5 |
string | payment_link.state.state5 |
Custom state field 5 - data returned unchanged in webhooks/redirects |
| State 6 | state6 |
string | payment_link.state.state6 |
Custom state field 6 - data returned unchanged in webhooks/redirects |
| State 7 | state7 |
string | payment_link.state.state7 |
Custom state field 7 - data returned unchanged in webhooks/redirects |
| State 8 | state8 |
string | payment_link.state.state8 |
Custom state field 8 - data returned unchanged in webhooks/redirects |
| State 9 | state9 |
string | payment_link.state.state9 |
Custom state field 9 - data returned unchanged in webhooks/redirects |
Output fields
Section titled “Output fields”| Display Name | Field ID | Source Path | Type | Description |
|---|---|---|---|---|
| Payment Link ID | payment_link__id |
payment_link.id |
string | Unique payment link identifier (format: pl_1234_abcdef) |
| Payment Link URL | payment_link__url |
payment_link.url |
string | Shareable payment link URL to send to customers |
| Expires At | payment_link__expires |
payment_link.expires |
string | ISO 8601 expiry datetime when link becomes invalid |
Action: Update Payment Link
Section titled “Action: Update Payment Link”Endpoint: PUT /c/api/payment_links/{payment_link_id}
Updates an existing payment link. All fields are optional. How the fields you send are applied depends on mode:
REPLACE(the default): each top-level field you send replaces the stored one whole.optionsandstateare replaced as complete objects, so sending onlyoptions.amountremoves every other option, such as the currency. Send the completeoptionsandstateobjects in this mode.PATCH: the fields you send are merged into the stored payment link, so you can change a single field, such asoptions.amount, and keep the rest.
Input fields
Section titled “Input fields”| Display Name | Field ID | Type | API Mapping | Description |
|---|---|---|---|---|
| Payment Link ID | payment_link__id |
string | URL parameter | (Required) ID of payment link to update (format: pl_1234_abcdef) |
| Mode | mode |
string | mode |
Update mode: REPLACE (default) or PATCH. REPLACE replaces each top-level field sent, including the whole options and state objects; PATCH changes only the fields sent |
| Currency | payment_link__currency |
string | payment_link.options.currency |
3-letter currency code. Cannot change after payments made |
| Amount | payment_link__amount |
string | payment_link.options.amount |
Payment amount in decimal format (e.g., “29.99”, “1000.00”) |
| Reference | payment_link__alt_key |
string | payment_link.options.alt_key |
Your reference to track this payment |
| Customer CRM Key | payment_link__account_crm_key |
string | payment_link.options.account.crm_key |
Your CRM identifier for customer |
| Customer First Name | payment_link__account_first_name |
string | payment_link.options.account.first_name |
Customer’s first name |
| Customer Last Name | payment_link__account_last_name |
string | payment_link.options.account.last_name |
Customer’s last name |
| Customer Email | payment_link__account_email |
string | payment_link.options.account.email |
Customer’s email address. Must be valid email format |
| Customer Phone | payment_link__account_phone |
string | payment_link.options.account.phone |
Customer’s phone number |
| Save Card | payment_link__save_card |
boolean | payment_link.options.save_card |
Control payment method saving |
| Skip Receipt | payment_link__skip_receipt |
boolean | payment_link.options.skip_receipt |
Skip receipt page and redirect immediately |
| Page Success Message | payment_link__page_success_message |
string | payment_link.options.page_success_message |
Message shown when payment succeeds |
| Page Pending Message | payment_link__page_pending_message |
string | payment_link.options.page_pending_message |
Message shown when payment is pending |
| Success URL | payment_link__success_url |
string | payment_link.options.success_url |
URL for successful payment redirect. Must be HTTPS |
| Pending URL | payment_link__pending_url |
string | payment_link.options.pending_url |
URL for pending payment redirect. Must be HTTPS |
| Page Name | payment_link__name |
string | payment_link.options.name |
Name of the page to display in the payment link |
| Page Intro | payment_link__page_intro |
string | payment_link.options.page_intro |
Introductory text to display on the payment page |
| Expires At | payment_link__expires |
string | payment_link.expires |
ISO 8601 datetime when link expires. Must be future date/time |
| Expires In | payment_link__expires_in |
number | Convert to payment_link.expires |
Seconds until link expires. Convert: new Date(Date.now() + (expires_in * 1000)).toISOString() |
| State 1 | state1 |
string | payment_link.state.state1 |
Custom state field 1 for workflow tracking |
| State 2 | state2 |
string | payment_link.state.state2 |
Custom state field 2 for workflow tracking |
| State 3 | state3 |
string | payment_link.state.state3 |
Custom state field 3 for workflow tracking |
| State 4 | state4 |
string | payment_link.state.state4 |
Custom state field 4 for workflow tracking |
| State 5 | state5 |
string | payment_link.state.state5 |
Custom state field 5 for workflow tracking |
| State 6 | state6 |
string | payment_link.state.state6 |
Custom state field 6 for workflow tracking |
| State 7 | state7 |
string | payment_link.state.state7 |
Custom state field 7 for workflow tracking |
| State 8 | state8 |
string | payment_link.state.state8 |
Custom state field 8 for workflow tracking |
| State 9 | state9 |
string | payment_link.state.state9 |
Custom state field 9 for workflow tracking |
Output fields
Section titled “Output fields”| Display Name | Field ID | Source Path | Type | Description |
|---|---|---|---|---|
| Payment Link ID | payment_link__id |
payment_link.id |
string | Unique payment link identifier |
| Payment Link URL | payment_link__url |
payment_link.url |
string | Shareable payment link URL |
| Expires At | payment_link__expires |
payment_link.expires |
string | ISO 8601 expiry datetime |
Action: Get Payment Link
Section titled “Action: Get Payment Link”Endpoint: GET /c/api/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
Section titled “Input fields”| Display Name | Field ID | Type | API Mapping | Description |
|---|---|---|---|---|
| Payment Link ID | payment_link__id |
string | URL parameter | (Required) ID of payment link to retrieve (format: pl_1234_abcdef) |
Output fields
Section titled “Output fields”| Display Name | Field ID | Source Path | Type | Description |
|---|---|---|---|---|
| Payment Link ID | payment_link__id |
payment_link.id |
string | Payment Link ID |
| Payment Link URL | payment_link__url |
payment_link.url |
string | Payment Link URL |
| Status | payment_link__status |
payment_link.status |
string | Current status (ACTIVE, PENDING, COMPLETED, EXPIRED, ARCHIVE) |
| Created Date | payment_link__created |
payment_link.created |
string | Created timestamp (ISO 8601 datetime) |
| Updated Date | payment_link__updated |
payment_link.updated |
string | Last updated timestamp (ISO 8601 datetime) |
| Expiry Date | payment_link__expires |
payment_link.expires |
string | Expiry timestamp (ISO 8601 datetime) |
| Currency | payment_link__currency |
payment_link.options.currency |
string | Currency code |
| Amount | payment_link__amount |
payment_link.options.amount |
string | Payment amount |
| Reference | payment_link__alt_key |
payment_link.options.alt_key |
string | Reference key |
| Customer CRM Key | payment_link__account_crm_key |
payment_link.options.account.crm_key |
string | Customer CRM key |
| Customer First Name | payment_link__account_first_name |
payment_link.options.account.first_name |
string | Customer first name |
| Customer Last Name | payment_link__account_last_name |
payment_link.options.account.last_name |
string | Customer last name |
| Customer Email | payment_link__account_email |
payment_link.options.account.email |
string | Customer email |
| Customer Phone | payment_link__account_phone |
payment_link.options.account.phone |
string | Customer phone |
| Save Card | payment_link__save_card |
payment_link.options.save_card |
boolean | Save card setting |
| Skip Receipt | payment_link__skip_receipt |
payment_link.options.skip_receipt |
boolean | Skip receipt setting |
| Page Success Message | payment_link__page_success_message |
payment_link.options.page_success_message |
string | Success message |
| Page Pending Message | payment_link__page_pending_message |
payment_link.options.page_pending_message |
string | Pending message |
| Success URL | payment_link__success_url |
payment_link.options.success_url |
string | Success redirect URL |
| Pending URL | payment_link__pending_url |
payment_link.options.pending_url |
string | Pending redirect URL |
| Page Name | payment_link__name |
payment_link.options.name |
string | Name of the page to display in the payment link |
| Page Intro | payment_link__page_intro |
payment_link.options.page_intro |
string | Introductory text to display on the payment page |
| Account ID | account__id |
payment_link.account.id |
string | Shuttle Account ID (format: acc_1234_abcdef) |
| Account Name | account__name |
payment_link.account.name |
string | Full account name |
| Account Email | account__email |
payment_link.account.email |
string | Account email |
| Account Phone | account__phone |
payment_link.account.phone |
string | Account phone |
| Account Status | account__status |
payment_link.account.status |
string | Account status (ACTIVE, TEMP) |
| Contract ID | contract__id |
payment_link.contract.id |
string | Contract ID (format: co_1234_abcdef) |
| Contract Reference | contract__alt_key |
payment_link.contract.alt_key |
string | Contract reference |
| Contract Amount | contract__amount |
payment_link.contract.amount |
string | Contract amount, in decimal format (e.g., “29.99”) |
| Contract Currency | contract__currency |
payment_link.contract.currency |
string | Contract currency |
| Contract Status | contract__status |
payment_link.contract.status |
string | Contract status (SETUP, ACTIVE, FAILING, PENDING, SUSPENDED, UNRESOLVED, COMPLETED, CANCELLED, CANCELLING) |
| Charge ID | charge__id |
payment_link.charge.id |
string | Charge ID (format: cg_1234_abcdef) |
| Charge Amount | charge__amount |
payment_link.charge.amount |
string | Charge amount, in decimal format |
| Charge Status | charge__status |
payment_link.charge.status |
string | Charge status (ACTIVE, PENDING, COMPLETED, WRITTENOFF) |
| Transaction ID | transaction__id |
payment_link.transaction.id |
string | Transaction ID (format: tr_1234_abcdef) |
| Transaction Amount | transaction__amount |
payment_link.transaction.amount |
string | Transaction amount, in decimal format |
| Transaction Currency | transaction__currency |
payment_link.transaction.currency |
string | Transaction currency |
| Transaction Status | transaction__status |
payment_link.transaction.status |
string | Transaction status (SUCCESS, PENDING, DECLINED, REQAUTH, INVALID_PAYMENT_METHOD, UNRESOLVED, UNATTRIBUTED) |
| Transaction Gateway Status | transaction__gateway_status |
payment_link.transaction.gateway_status |
string | The category or error message received from the payment provider |
| Transaction Gateway Message | transaction__gateway_message |
payment_link.transaction.gateway_message |
string | Gateway response message |
| Transaction Gateway Reference | transaction__gateway_reference |
payment_link.transaction.gateway_reference |
string | Gateway reference eg ID in Adyen / Stripe |
| Transaction Reference | transaction__reference |
payment_link.transaction.reference |
string | Transaction reference, REF-000162622 |
| Transaction Processed | transaction__processed |
payment_link.transaction.processed |
string | When the transaction was processed (ISO 8601 datetime) |
| Payment Method ID | payment_method__id |
payment_link.payment_method.id |
string | Payment method ID (format: pm_1234_abcdef) |
| Payment Method Type | payment_method__type |
payment_link.payment_method.type |
string | Payment method type |
| Payment Method Status | payment_method__status |
payment_link.payment_method.status |
string | Payment method status |
| Payment Method BIN | payment_method__bin |
payment_link.payment_method.bin |
string | Payment method BIN |
| Payment Method Last 4 | payment_method__last4 |
payment_link.payment_method.last4 |
string | Payment method last 4 |
| Payment Method Expiry | payment_method__expiry |
payment_link.payment_method.expiry |
string | Payment method expiry |
| Payment Method Name | payment_method__name |
payment_link.payment_method.name |
string | Payment method name |
| Payment Method Source | payment_method__source |
payment_link.payment_method.source |
string | Payment method source |
| Payment Method Gateway Reference | payment_method__token |
payment_link.payment_method.token |
string | Payment method token gateway reference eg ID in Adyen / Stripe |
| State 1 | state1 |
state.state1 |
string | Custom state field 1 |
| State 2 | state2 |
state.state2 |
string | Custom state field 2 |
| State 3 | state3 |
state.state3 |
string | Custom state field 3 |
| State 4 | state4 |
state.state4 |
string | Custom state field 4 |
| State 5 | state5 |
state.state5 |
string | Custom state field 5 |
| State 6 | state6 |
state.state6 |
string | Custom state field 6 |
| State 7 | state7 |
state.state7 |
string | Custom state field 7 |
| State 8 | state8 |
state.state8 |
string | Custom state field 8 |
| State 9 | state9 |
state.state9 |
string | Custom state field 9 |
Action: Cancel Payment Link
Section titled “Action: Cancel Payment Link”Endpoint: DELETE /c/api/payment_links/{payment_link_id}
Cancels/archives a payment link, preventing any future payments.
Input fields
Section titled “Input fields”| Field ID | Type | API Mapping | Description |
|---|---|---|---|
payment_link__id |
string | URL parameter | (Required) ID of payment link to cancel (format: pl_1234_abcdef) |
Output fields
Section titled “Output fields”This endpoint returns an empty response (HTTP 204) on success.
Event: Payment Link Notification
Section titled “Event: Payment Link Notification”This is a trigger that receives webhook notifications when payment link events occur.
Input fields (webhook payload)
Section titled “Input fields (webhook payload)”| Field ID | Type | Source Path | Description |
|---|---|---|---|
action |
string | action |
Event type that triggered the webhook: PAYMENT_LINK.CREATED, PAYMENT_LINK.UPDATE, PAYMENT_LINK.PENDING, PAYMENT_LINK.FAILED, PAYMENT_LINK.COMPLETE, PAYMENT_LINK.EXPIRED or PAYMENT_LINK.ARCHIVE. See Webhook events |
payment_link |
string | payment_link |
Payment link ID (format: pl_1234_abcdef) |
account |
string | account |
Account ID (format: acc_1234_abcdef) |
contract |
string | contract |
Contract ID (format: co_1234_abcdef) |
charge |
string | charge |
Charge ID (format: cg_1234_abcdef) |
transaction |
string | transaction |
Transaction ID (format: tr_1234_abcdef) |
payment_method |
string | payment_method |
Payment method ID (format: pm_1234_abcdef) |
state |
object | state |
Custom state object containing state1-state9 fields |
Output fields (transformed for workflow)
Section titled “Output fields (transformed for workflow)”| Display Name | Field ID | Transformation | Type | Description |
|---|---|---|---|---|
| Action | action |
Direct map from action |
string | Event type |
| Payment Link ID | payment_link__id |
Map from payment_link |
string | Payment link ID (note the double underscore) |
| State 1 | state1 |
Extract from state.state1 |
string | Custom state field 1 |
| State 2 | state2 |
Extract from state.state2 |
string | Custom state field 2 |
| State 3 | state3 |
Extract from state.state3 |
string | Custom state field 3 |
| State 4 | state4 |
Extract from state.state4 |
string | Custom state field 4 |
| State 5 | state5 |
Extract from state.state5 |
string | Custom state field 5 |
| State 6 | state6 |
Extract from state.state6 |
string | Custom state field 6 |
| State 7 | state7 |
Extract from state.state7 |
string | Custom state field 7 |
| State 8 | state8 |
Extract from state.state8 |
string | Custom state field 8 |
| State 9 | state9 |
Extract from state.state9 |
string | Custom state field 9 |
Was this page helpful?
What went wrong?
Thanks for telling us.