## Add a payment link

Create a new payment link that can be shared with customers to collect payments.
A payment link is a unique URL that redirects customers to a hosted checkout page.

If no `installation_*` attributes are provided, the merchant's default link installation will be used.
If any `installation_*` attributes (like `installation_email_capture`) are provided,
a new one-off installation will be created for this payment link,
based on the merchant's default link installation attributes and the provided attributes.

## Endpoint signature

```http
POST https://api.reservepay.com/merchants/add-payment-link HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>

{
  amount: number,
  currency: string,
  description: string,
  external_id: string?,
  expires_at: number?,
  single_use: boolean?,
  installation_name: string?,
  installation_payment_methods: string?,
  installation_email_capture: string?,
  installation_mobile_capture: string?,
  installation_address_capture: string?,
}
```

Returns: object

## Request arguments

### `amount` (number)

**Required**. The amount to collect in subunits according to ISO 4217. E.g., 1000 for 10.00 THB. Or 500 for 500 JPY.

### `currency` (string)

**Required**. The 3-letter ISO 4217 currency code (e.g., 'USD'). Must be a supported currency.

### `description` (string)

**Required**. A description of the product or service being paid for.

### `external_id` (string)

_Optional_. Your internal reference for this payment link.

### `expires_at` (number)

_Optional_. Optional Unix timestamp when the link should expire.

### `single_use` (boolean)

_Optional_. If true, the link will be disabled after the first successful payment. Defaults to false.

Allowed values:

- `true`
- `false`

### `installation_name` (string)

_Optional_. The name for a new custom installation.

### `installation_payment_methods` (string)

_Optional_. Comma-separated list of payment methods for a new custom installation.

### `installation_email_capture` (string)

_Optional_. Email capture configuration for a new custom installation.

Allowed values:

- `disabled`
- `optional`
- `required`

### `installation_mobile_capture` (string)

_Optional_. Mobile phone capture configuration for a new custom installation.

Allowed values:

- `disabled`
- `optional`
- `required`

### `installation_address_capture` (string)

_Optional_. Billing address capture configuration for a new custom installation.

Allowed values:

- `disabled`
- `optional`
- `required`

## Response attributes

### `payment_link_id` (string)

**Always present**. The ID of the payment link.

### `payment_link_url` (string)

**Always present**. The URL of the payment link.

### `status` (string)

**Always present**. The current status of the payment link.

Possible values:

- `active`
- `disabled`
- `expired`
- `paid`

### `amount` (number)

**Always present**. The amount of the payment link in subunits.

### `currency` (string)

**Always present**. The 3-letter ISO currency code.

### `description` (string)

**Always present**. The description of the payment link.

### `external_id` (string)

_Nullable_. The merchant's internal reference for this link.

### `expires_at` (number)

_Nullable_. When the link becomes invalid (Unix timestamp).

### `single_use` (boolean)

**Always present**. If true, the link expires after one successful payment.

### `installation` (object)

**Always present**. The installation associated with this payment link.

### `created_at` (number)

**Always present**. The creation timestamp (Unix timestamp).

### `deletable` (boolean)

**Always present**. If true, the payment link has no associated payments and can be removed.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

This error occurs when the server encounters an unexpected internal error that
it cannot handle gracefully. This typically happens due to bugs, infrastructure
issues, or edge cases that weren't anticipated during development.

### `INVALID_ARGUMENTS`

This error occurs when the request contains invalid or missing parameters.
Common cases include missing required fields, or values that don't match the
expected format or type.

### `BAD_VERSION`

This error occurs when making requests to an API version that does not exist.
This commonly happens when using an outdated SDK or when the API version
specified in the request URL is incorrect.