# Payment links

Create payment links with Moov to send or accept from cards, bank accounts, or Apple Pay.

Create a payment link from the [API](/api/money-movement/payment-links/) or the [Dashboard](https://dashboard.moov.io/signin) that you can send to merchants through your chosen form of communication, such as email or SMS. Use the generated payment link code to create a QR code for in-person payments. You can use payment links to disburse or accept a payment.

The payment link flow authenticates a session that lets your customers securely create a Moov account and link payment methods before submitting payment through the link or QR code.

Successfully submitted payment links will use the `transferID` and the `email`/`emailAccountID` to automatically create and send a [receipt](/api/money-movement/receipts/) via email.

We suggest using the Dashboard’s payment link process to create payment links. Visit our [Dashboard](/guides/dashboard/payment-links/) guide for more information.

Before you send your first payment link, you have the option to set up brand colors. Moov offers light and dark mode brand settings, which you can set in the Dashboard or with the [API](/api/enrichment/branding/). Colors you select for light and dark modes will be used as accent colors throughout the customer's user experience, including the payment link UI.

## [Payment methods](#payment-methods)

To **accept a payment**, you can choose any or all of the following payment methods:

- Apple Pay
- Google Pay
- Card
- ACH debit collect

To **send a payment**, you can choose any or all of the following payment methods:

- Push to card
- RTP credit
- ACH credit same day
- ACH credit standard

## [Payment link options](#payment-link-options)

When creating a payment link, you're required to provide the merchant account ID in the path and the partner account ID in the request. Note that sometimes a partner can be acting as a merchant and therefore the ID is the same account ID for both. Additionally, you must send the merchant's payment method ID and the payment amount.

You can optionally require other data such as customer address or phone number, metadata, and a custom dynamic descriptor for the statement. You can also set an expiration date and limit on the amount of times a payment link can be used.

Additionally, you can set line items, tax, surcharge fees, and tipping options. The sections below describe these options.

Once a payment link is created, you'll receive a sharable URL and QR code. The URL will be in the following format: `https://moov.link/p/{unique-payment-link}`. URLs and QR codes can be retrieved again using the `GET` [payment link](/api/money-movement/payment-links/get/) or [QR code](/api/money-movement/payment-links/get-qrcode/) endpoints, or in the Dashboard by navigating to **Transfers > Payment links**.

### [Line items](#line-items)

When you create a payment link you have the option of creating a line item. Line items allow you to list items within the transaction, each with their own distinct name, description, image, and price modifier. For tracking purposes, you can give each item a unique identifier using the `productID` field.

When using line items, the total `amount` of the payment link needs to include all additional costs and price modifiers associated with each item.

```json
{
  "lineItems": {
    "item": {
      "basePrice": {
        "currency": "USD",
        "valueDecimal": "14.95"
      },
      "name": "Lunch combo 1",
      "productID": "5afv22245-7095-24ba-b21a-5c4dc993737",
      "quantity": 1
    }
  }
}
```

### [Tax & surcharge fees](#tax--surcharge-fees)

In Moov API `v2026.07.00` and later, within `amountDetails`, you can set sales tax and/or a surcharge fee (for credit card transactions).

Surcharging is optional for credit card transactions, but if enabled, the account must follow card brand caps, as well as additional card network rules and state and federal regulations. See the main [surcharge](/guides/money-movement/accept-payments/card-acceptance/surcharges/) guide for details on compliance, disclosures, and regulations.

```json
{
  "amountDetails": {
    "surcharge": {
      "currency": "USD",
      "valueDecimal": "2.00"
    },
    "tax": {
      "currency": "USD",
      "valueDecimal": "6.00"
    }
  }
}
```

Tax and surcharge fees are not available for payment links with user defined amounts.

### [Tipping](#tipping)

Tipping presets must be configured via the `POST` transfer config [endpoint](/api/money-movement/transfers/create-transfer-config/). Presets can either be a percentage of the total, or a fixed amount, such as 10%, 15%, and 20%, or $1.00, $1.50, and $2.00. Preset percentages must also be set to calculate on either the pre-tax or post-tax amount. Fixed amount presets must also set the currency.

See the [tipping](/guides/money-movement/tipping/) guide for more information on preset configuration. If you enable tipping without any presets, the customer will be prompted to enter a custom amount in a free-form field.

By default, tipping is disabled. To enable tipping, set `tippingEnabled: true` when you create a payment link.

```json
{
  "customer": {
    "requirePhone": true,
    "tippingEnabled": true
  }
}
```

Tipping is not available for payment links with user defined amounts.

### [User defined amounts](#user-defined-amounts)

With Moov API `2026.07.00` and higher, you can allow a user to enter their own amount. Instead of choosing a product or entering an amount, you can let the end-user choose the amount to pay or receive.

With this option, you can set a minimum and maximum range, as well as select up to five suggested amounts. If either minimum or maximum is omitted, the limit for that end is **open**. If suggested amounts are set, they must use USD and fall within the `amountRange`.

```json
{
  "customAmountPayment": {
    "allowedMethods": [
      "apple-pay",
      "card-payment",
      "google-pay"
    ],
    "amountRange": {
      "minimum": {
        "currency": "USD",
        "valueDecimal": "10.00"
      },
      "maximum": {
        "currency": "USD",
        "valueDecimal": "100.00"
      }
    },
    "suggestedAmounts": [
      {
        "currency": "USD",
        "valueDecimal": "25.00"
      },
      {
        "currency": "USD",
        "valueDecimal": "50.00"
      },
      {
        "currency": "USD",
        "valueDecimal": "100.00"
      }
    ]
  }
}
```

The user will see the options in their checkout process.

### [Full example](#full-example)

Use the payment links `POST` [endpoint](/api/money-movement/payment-links/create/) to send either a `payment`, `payout`, or `customAmountPayment`.

You can limit the amount of times a payment link can be used with the `maxUses` field. By setting `maxUses` to 0, there is no limit on the amount of times the link can be used. For payouts, `maxUses` is always `1`. The response will include a `paymentLinkCode`, which you can use to retrieve a specific payment link later on.

Only the account that creates the payment link can update it. The `ownerAccountID` is returned in the response for reference. This ID will correspond to the `partnerAccountID` or `merchantAccountID` of the account that created the payment link.

The examples below show one payment link with line items and one payment link with a user defined amount.

[Line item](#tab-487269135-4-0) [User defined amount](#tab-487269135-4-1)

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/payment-links" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00" \
  --data-raw '{
    "accountID": "c197cd40-7745-4413-8f3b-ec962d1b5225",
    "merchantPaymentMethodID": "3afc7533-7095-43bb-b21a-5c4dc5568451",
    "partnerAccountID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "amount": {
      "currency": "USD",
      "value": 1645
    },
    "amountDetails": {
      "surcharge": {
        "currency": "USD",
        "valueDecimal": "0.45"
      },
      "tax": {
        "currency": "USD",
        "valueDecimal": "1.05"
      }
    },
    "lineItems": {
      "item": {
        "basePrice": {
          "currency": "USD",
          "valueDecimal": "14.95"
        },
        "name": "Lunch combo 1",
        "productID": "5afv22245-7095-24ba-b21a-5c4dc993737",
        "quantity": 1
      }
    },
    "maxUses": 0,
    "expiresOn": "2026-08-24T14:15:22Z",
    "display": {
      "title": "string",
      "description": "string",
      "callToAction": "pay"
    },
    "customer": {
      "requirePhone": true,
      "tippingEnabled": true
    },
    "payment": {
      "allowedMethods": [
        "apple-pay",
        "card-payment",
        "google-pay"
      ]
    }
  }'
```

```zsh
curl -X POST "https://api.moov.io/accounts/{accountID}/payment-links" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2026.07.00" \
  --data-raw '{
    "accountID": "c197cd40-7745-4413-8f3b-ec962d1b5225",
    "merchantPaymentMethodID": "3afc7533-7095-43bb-b21a-5c4dc5568451",
    "partnerAccountID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "maxUses": 0,
    "expiresOn": "2026-08-24T14:15:22Z",
    "display": {
      "title": "string",
      "description": "string",
      "callToAction": "pay"
    },
    "customer": {
      "requirePhone": true,
      "tippingEnabled": false
    },
    "customAmountPayment": {
      "allowedMethods": [
        "apple-pay",
        "card-payment",
        "google-pay"
      ],
      "amountRange": {
        "minimum": {
          "currency": "USD",
          "valueDecimal": "10.00"
        },
        "maximum": {
          "currency": "USD",
          "valueDecimal": "100.00"
        }
      },
      "suggestedAmounts": [
        {
          "currency": "USD",
          "valueDecimal": "25.00"
        },
        {
          "currency": "USD",
          "valueDecimal": "50.00"
        },
        {
          "currency": "USD",
          "valueDecimal": "100.00"
        }
      ]
    }
  }'
```

## [Get generated QR code](#get-generated-qr-code)

To facilitate in-person payments, you have the ability to generate a QR code for a customer to use with the payment links QR `GET` [endpoint](/api/money-movement/payment-links/get-qrcode/).

To generate a QR code, pass the `accountID` and `paymentLinkCode`.

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/payment-links/{paymentLinkCode}/qrcode" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
```

## [Manage payment links](#manage-payment-links)

Once a payment link is created, you can manage it through the API or the Dashboard. You can list all created payment links, find a specific one, update it, or disable it.

### [Retrieve](#retrieve)

View a list of all payment links with the list payment links `GET` [endpoint](/api/money-movement/payment-links/list/), or view an individual payment link with the retrieve payment links `GET` [endpoint](/api/money-movement/payment-links/get/).

[List all links](#tab-174269538-6-0) [Retrieve a link](#tab-174269538-6-1)

To list all payment links for an account, pass the `accountID`.

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/payment-links" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
```

To retrieve a specific payment link for an account, pass the `accountID` and `paymentLinkCode`. The payment link code is provided in the initial `POST` response when created a payment link. You can use the list payment link endpoint to retrieve all payment links and their payment link codes.

```zsh
curl -X GET "https://api.moov.io/accounts/{accountID}/payment-links/{paymentLinkCode}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
```

### [Update](#update)

You have the ability to update certain properties of payment links with the payment links `PATCH` [endpoint](/api/money-movement/payment-links/update/). You can update the amount, expiration date, display options, customer data, as well as payment and payout options.

Only the account that created the payment link can update the payment link. The `ownerAccountID` is returned in the create payment link response if needed for reference.

To update a payment link, pass the `accountID` and `paymentLinkCode`.

```zsh
curl -X PATCH "https://api.moov.io/accounts/{accountID}/payment-links/{paymentLinkCode}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
  --data-raw '{
    "amount": {
      "currency": "USD",
      "value": 1204
    },
    "expiresOn": "2025-08-24T14:15:22Z",
    "display": {
      "title": "string",
      "description": "string",
      "callToAction": "pay"
    },
    "customer": {
      "requireAddress": true,
      "requirePhone": true,
      "metadata": {
        "property1": "string",
        "property2": "string"
      }
    },
    "payment": {
      "allowedMethods": [
        "apple-pay"
      ],
      "cardDetails": {
        "dynamicDescriptor": "WhlBdy *Yoga 11-12"
      },
      "achDetails": {
        "companyEntryDescription": "Gym Dues",
        "originatingCompanyName": "Whole Body Fit"
      }
    }
  }'\
```

### [Disable](#disable)

You can disable a payment link at any time. Customers will receive an error page if they try and access a disabled payment link. Use the payment links `DEL` [endpoint](/api/money-movement/payment-links/delete/) to disable the link.

To delete (disable) a payment link, pass the `accountID` and `paymentLinkCode`.

```zsh
curl -X DELETE "https://api.moov.io/accounts/{accountID}/payment-links/{paymentLinkCode}" \
  -H "Authorization: Bearer {token}" \
  -H "x-moov-version: v2024.01.00" \
```