# Create a new payment link

`POST https://app.shuttleglobal.com/c/api/instances/{instance_key}/payment_links`

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Request body (`application/json`), required

- `payment_link` (object, required)
  - `expires` (string (date-time)): Expiry date for the payment link. Must be a future date - cannot set expiry to a past date.
  - `options` (object): Configuration options for the payment link experience
    - `account` (one of)
    - `allow_description` (boolean): Whether to allow the payer to add a comment
    - `alt_key` (string): Fixed reference for the payment (if specified, user cannot modify)
    - `amount` (string): Fixed amount for the payment in major currency units, as a decimal string without commas, using '.' as the decimal separator (e.g. "18.18" for £18.18). If specified, the payer cannot modify it.
    - `description` (string): Fixed comment to show with payment
    - `currency` (string): Three-letter ISO currency code
    - `default_alt_key` (string): Default reference that user can modify
    - `default_amount` (string): Default amount in major currency units, as a decimal string without commas, using '.' as the decimal separator (e.g. "100.00"). The payer can modify it.
    - `default_description` (string): Default comment to show (can be changed by payer if allow_description is true)
    - `name` (string): Custom name for the payment link (defaults to instance name)
    - `page_intro` (string): Custom introduction message for the payment page
    - `page_pending_message` (string): Message to display to the user when their payment is pending authorization. Only shown on the receipt page when skip_receipt is false and no pending_url is provided.
    - `page_success_message` (string): Message to display to the user when their payment is successful. Only shown on the receipt page when skip_receipt is false and no success_url is provided.
    - `pending_url` (string (uri)): URL to redirect to when a payment requires authorization (pending state). If skip_receipt is true, redirect happens immediately after payment submission. If skip_receipt is false, URL is presented as a button on the receipt page. Query parameters will be appended to this URL - see RedirectUrlParameters schema. Parameters include: payment_link, status, contract, charge, transaction, payment_method, account. Example: https://shop.example.com/pending?payment_link=pl_1234_abcdef&status=PENDING... Use these parameters to verify payment status and retrieve additional details via API.
    - `save_card` (boolean): Controls whether the payment method will be saved: - If true: Payment method will be saved with the payment - If false: Payment method won't be saved and user won't be given the option - If not set: User will be given the option to save their payment method Note that `save_card: false` also withdraws any payment method that can only be used by storing a token first - GoCardless Direct Debit and Instant Bank Pay, for example - since those cannot be offered under a hard "never save" instruction. To take a payment that saves nothing while still offering them, leave `save_card` unset and use `default_save_card` with `hide_save_card_toggle` instead.
    - `default_save_card` (boolean): Initial state of the "save payment method" checkbox. The payer can still change it, and it is ignored when `save_card` is set. Unlike `save_card`, it does not restrict which payment methods are offered.
    - `hide_save_card_toggle` (boolean): Hides the "save payment method" checkbox from the payer, leaving whatever `default_save_card` set in force. Pair the two to express a preference rather than an instruction: do not save, but stay available to methods that need a token.
    - `skip_receipt` (boolean): Controls redirect behavior after payment submission: * true - Immediately redirect to success_url/pending_url * false - Show receipt page with messages before redirect - If true: Immediately redirect to success_url (successful payment) or pending_url (pending authorization) - If false: Show receipt page with a button to proceed to the appropriate URL
    - `source` (string): Source of the payment link One of: `ECOMMERCE`.
    - `channel` (string): Channel identifier to process the payment through
    - `force_add` (boolean): Only allow new payment methods, do not show saved payment methods
    - `timezone` (string): IANA timezone name for date/time display (e.g., America/New_York)
    - `success_url` (string (uri)): URL to redirect users after successful payment completion. Query parameters included in redirect: * payment_link - Payment link ID * status - Will be 'COMPLETED' * contract - Contract ID if created * charge - Charge ID if created * transaction - Transaction ID if created * payment_method - Payment method ID if created * account - Account ID if created If skip_receipt is true, redirect happens immediately after successful authorization. If skip_receipt is false, URL is presented as a button on the receipt page. Query parameters will be appended to this URL - see RedirectUrlParameters schema. Parameters include: payment_link, status, contract, charge, transaction, payment_method, account. Example: https://shop.example.com/success?payment_link=pl_1234_abcdef&status=COMPLETED... Use these parameters to verify payment status and retrieve additional details via API.
  - `state` (one of): Custom state data for link creator. Can be an object, string, or array. Maximum size when stringified is 10KB.

## Responses

### 200: Payment link created successfully

```json
{
  "payment_link": {
    "id": "string",
    "account": "string",
    "charge": "string",
    "client": "string",
    "contract": "string",
    "expires": "2026-01-01T12:00:00Z",
    "nonce": "string",
    "options": {
      "account": "string",
      "action": "PAYMENT",
      "allow_comment": true,
      "amount": "18.18",
      "comment": "string",
      "currency": "USD",
      "default_amount": "100.00",
      "default_comment": "string",
      "default_reference": "string",
      "name": "string",
      "page_intro": "string",
      "page_pending_message": "string",
      "page_success_message": "string",
      "pending_url": "https://example.com",
      "reference": "string",
      "source": "ECOMMERCE",
      "channel": "string",
      "force_add": true,
      "timezone": "string",
      "success_url": "https://example.com"
    },
    "payment_method": "string",
    "payment": "string",
    "state": {},
    "status": "ACTIVE",
    "transaction": "string",
    "url": "https://app.shuttleglobal.com/cp/link/{id}",
    "v": 1
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Authentication required

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

### 404: Instance not found (only checked after successful authentication)

```json
{
  "code": "string",
  "message": "string"
}
```

### 500: Internal server error

```json
{
  "error": {
    "type": "string",
    "message": "string"
  }
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/payment_links \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_link": {
    "options": {
      "amount": "18.18",
      "default_amount": "100.00",
      "skip_receipt": false,
      "source": "ECOMMERCE"
    }
  }
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/createpaymentlink/