# Personalised links

> Personalised payment links are unique URLs for a customer to complete a specific payment. This is ideal for:

Personalised payment links are unique URLs for a customer to complete a specific payment. This is ideal for:

* **Staff-initiated customer payments**: for example, a customer service agent creates a payment link for a customer to complete, without the customer sharing their payment details with the agent
* **Workflow automation**: for example, a Zapier or Make.com workflow that sends a payment link when an invoice is created
* **Programmatic creation**: through the API, either sent to the customer or linked to from a button

Personalised payment links offer the features of multi-use links, with several additions:

* **Customer Information**: Attach customer data to the payment link to streamline checkout.
* **Custom State**: Attach up to 10kb of custom data to the payment link to facilitate workflow automation.
* **Personalised Completion Messages**: Share a user specific message after a successful payment, for example an access code. 
* **Personalised Completion Redirects**: Send the user to a URL after a successful payment, for example a resource behind a paywall
* **Receipt Skip**: Use your own bespoke receipt page after payment
* **Payment Action**: You can specify various types of payment actions like payment, auth only, or tokenise
* **Link Expiry**: Control how long the payment link is available for. 

## Customer information

You can include the following information about a customer:

* `crm_key`: Customer's identifier - this must be passed if you want to display saved cards from previous payment sessions. A single `account` will exist in Shuttle for each `crm_key`, meaning updates in email / phone will apply to previous payment sessions, and known data from previous payment sessions will auto populate if not passed.
* `email`: Customer's email address
* `phone`: Customer's phone number (international format preferred) eg `441234567890` for `+44 12345 56789`
* `first_name`: Customer's first name
* `last_name`: Customer's last name
* `company`: Customer's company name
* `address`: Customer's address, used to prepopulate card AVS fields where required
    * `line1`: Street address
    * `line2`: Address line 2
    * `line3`: Address line 3
    * `line4`: City/Town
    * `line5`: Post code/ZIP code
    * `line6`: State/Province (using ISO 3166-2 subdivision codes, e.g., 'CA' for California)
    * `country`: Country ISO code (e.g., 'US' for United States)

All fields are optional, however:

* `crm_key`: is highly recommended if you have a customer identifier to ensure data is linked together - this can be any string, such as a database ID
* `email`: is recommended if you are using Shuttle's receipting
* Some cards require 3D secure, which requires `phone` or `email` be available 
* If your payment processor uses AVS (address verification), passing `address` will pre-populate the address fields, making checkout much quicker
* `first_name`, `last_name`, `phone` and `email` are passed to the payment processor where available to assist viewing payment data in the processor's dashboard / reporting 

## Custom state

You can attach up to 10kb of custom data to the payment link to facilitate workflow automation. For example you could include order / contact information for how the payment link was generated, so once it's paid (or expired) you can automate order fulfilment or customer notification.

Through the API, it's a single field, `state`, which is a JSON object. In workflow automation tools it's presented as nine text fields (`state1` to `state9`), so you don't need steps to build or split it.

We recommend you use these as such:
* `state1`: Workflow identifier, eg `INVOICE_PAYMENT`, `INVOICE_CHASER`, `EVENT_PAYMENT` - this allows you to filter payment link webhooks to just those for a specific workflow.
* `state2` - `state9`: Workflow-specific data, eg incoming slack channel / message id, or order / contact information. 


## Personalised completion messages

You can attach a personalised completion message to the payment link to display after a successful payment. This can include sensitive information, as it is securely held on the server side until payment success or payment pending.

A payment can complete in two statuses:

* **Success**: The payment was successful and the transaction was completed - `page_success_message` will be displayed
* **Pending**: The payment is still pending and the transaction has not been completed - `page_pending_message` will be displayed.

Completion messages are shown on the receipt page and in the payment receipt. Please note, using `skip_receipt` and disabling customer email receipts will prevent the customer from seeing the message.

## Personalised completion redirects

You can attach a personalised completion redirect to the payment link to redirect to after a successful payment. This can include sensitive information, as it is securely held on the server side until payment success or payment pending.

A payment can complete in two statuses:

* **Success**: The payment was successful and the transaction was completed - `success_url` will be displayed
* **Pending**: The payment is still pending and the transaction has not been completed - `pending_url` will be displayed.

Completion redirects are shown as a "Next" button on the receipt page, unless `skip_receipt` is set to `true` in which case the redirect will be shown after payment processing.

## Receipt skip

A payment link will show a receipt page on successful submission, unless `skip_receipt` is set to `true` in which case the receipt will be skipped allowing you to customise the page after payment. This is only applicable where a `success_url` or `pending_url` is set.

## Payment action: PAYMENT / AUTH / TOKENISE

Shuttle Payment Links allow the following actions:

* **PAYMENT**: Process payment immediately
* **AUTH**: Reserve funds without immediate capture, you can capture funds later via the "Activity" view or via API
* **TOKENISE**: Capture card details, without taking payment

In addition, you can store payment details while performing PAYMENT / AUTH, by setting `save_card: true`

Please note: Only payment methods that can perform the requested option will be displayed. For example, ACH doesn't support `AUTH` only, Apple Pay doesn't support `TOKENISE` / `save_card: true`.

## Link expiry

You can set when a payment link expires with the `expires` parameter, an ISO 8601 date and time. The Zapier and Make.com connectors also accept a duration, **Expires In** (in seconds), and work out `expires` for you. After the expiry, the payment link won't open, and payments through it fail.

Typical use cases include:

* Matching your session expiry: for example, if you only hold goods in a basket for 15 minutes, set `expires` to 15 minutes from now (or **Expires In** to `900` in a connector)
* Time-sensitive events: for example, for a ticket sale, set `expires: "2025-06-20T12:00:00Z"` (the time you want ticket sales to stop)