Creates a payment link

Request

POST {{baseURL}}/v2/payment-links

This endpoint creates a new payment link.

A paymentMethods entry without processorId is pinned to the merchant's default active processor of that type at creation time.

This endpoint is Idempotent. See the idempotency-key header entry. For more information, see Idempotency.

This endpoint requires a merchant API token. A partner API token will result in a permissions error including possibly a 403 response.

See Also:
To list payment links, see GET /v2/payment-links.
To retrieve a payment link by identifier, see GET /v2/payment-links/{{paymentLinkId}}.
To update a payment link, see PATCH /v2/payment-links/{{paymentLinkId}}.
To delete a payment link, see DELETE /v2/payment-links/{{paymentLinkId}}.
To share a payment link, see POST /v2/payment-links/{{paymentLinkId}}/share.

Security

Bearer

Headers

idempotency-keystring, (uuid), <= 255 characters

Specifies the client-generated idempotency-key.

This key is optional. We recommend using the key to prevent multiple invocations of the operation. This key makes this request safely retryable, or idempotent. If the idempotency key is not included, the call will not have idempotency protection.

A retry with the same key, made within the retention window, returns the original response verbatim. The operation is not repeated. The retention window, also called the TTL (time to live) is 1440 minutes (24 hours) by default but this setting may be changed.

A retry with the same key while the original request is still processing returns 409 Conflict (IdempotencyKeyInProgress). Retry again after a short delay.

Reusing the same key with a different request body returns 422 Unprocessable Content (IdempotencyKeyConflict). Generate a new key for each distinct operation.

A 500 series server error is not stored against the key. A retry with the same key after a 500 series response processes the request again.

Example:6a1f7e2c-4b3d-4e5a-8f9c-1d2e3f4a5b6c

Bodyapplication/json

Payment link configuration.

paymentMethodsobjectrequired

Identifies the payment methods a payment link accepts. It is keyed by method so each one carries only the configuration that applies to it.

At least one payment method must be enabled, card or ACH. Both may be specified.

taxModestring

Specifies how taxRate and taxAmount is applied to amount.

Name	Description
Exclusive	Adds the tax on top of `amount`. The payer is charged `amount` plus the tax.
Inclusive	Treats `amount` as already including the tax. No extra amount is added.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

Example: Exclusive

Enum:"Exclusive""Inclusive"

Example:"Exclusive"

taxRatenumber or null, (double)

Specifies the tax rate percentage to apply to the base amount.

Valid values range from 0 to 100, with up to three decimal places.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

Example: 8.25 (for 8.25%)

Example:8.25

taxAmountnumber or null, (double), decimal places <= 2, >= 0

Specifies a fixed tax amount (in USD) to apply to the base amount.

This value has up to two decimal places and cannot be negative. This value requires a fixed baseAmount.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

A response carries this value only when the tax was configured as an amount. Otherwise, it is null.

Examples:
3.75 (for $3.75)
null

Example:3.75

baseAmountnumber or null, (double), decimal places <= 2

Specifies the payment amount (in USD).

This value must be greater than zero when provided. Omit this value for a flexible amount, where the customer enters the amount at checkout.

Example: 25 (for $25)

Example:25

currencyCodestring or null, <= 3 characters

Specifies the transaction's currency code (in uppercase ISO 4217 currency code).

Example: USD

Value:"USD"

Example:"USD"

linkTypestring

Identifies the payment link type.

Valid values are:

Type	Description
MultiUse	The link can be shared with, and paid by, more than one customer.
SingleUse	The link is intended for a single customer and a single payment.

Example: SingleUse

Default:"SingleUse"

Enum:"MultiUse""SingleUse"

Example:"SingleUse"

customerIdstring or null, (uuid)

Specifies the customer the link is issued for.

Omit this value for an anonymous link. On a MultiUse link, its payments, and any payment method a payer saves there, are recorded under this customer. For additional security, a payment page with MultiUse links and a customerId never shows the customer's details or saved methods.

Example: 3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e

Example:"3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e"

modestring, (enum)

Specifies whether payers are offered to save their payment method.

Valid values are:

Name	Description
Payment	Takes a one-off payment.
PaymentAndSave	Takes the payment and also offers the payer to save their payment method. When the link has no customer, a customer is created for a payer who saves. A `customerId` alone does not turn saving on.

This value cannot be changed through the API after the link is created. A merchant who adds a customer to the link in the merchant portal turns saving on, and removing the customer there turns it off.

Example: Payment

Default:"Payment"

Enum:"Payment""PaymentAndSave"

Example:"Payment"

metadataobject or null

Specifies arbitrary key-value pairs to attach to the payment link.

These pairs are copied into every payment session the link opens and are returned with that session. A key with a null value is not stored.

The limits are 50 keys, 100 characters per key, 500 characters per value, and 8 KB in total.

Example: {"orderId": "9921"}

Example:

{
  "orderId": "9921",
  "Guest notes": "Member of The World of Hyatt Credit Card."
}

referenceIdstring or null, <= 200 characters

Specifies a reference identifier provided by the merchant.

Example: ORDER-1042

Example:"ORDER-1042"

namestring or null, <= 80 characters

Specifies the merchant-facing label for the payment link.

This value is auto-generated from the amount when omitted.

Example: Spring campaign

Example:"Spring campaign"

descriptionstring or null, <= 500 characters

Specifies merchant-internal notes for the payment link.

This value is never shown to customers.

Example: Bulk prices due for spring season sales

Example:"Bulk prices due for spring season sales"

expiresOnstring or null, (date-time)

Specifies the UTC expiration date-time (in an ISO 8601 UTC date-time format).

This value must not be in the past. Omit this value for a link that never expires.

Example: 2026-07-07T14:09:31.264Z

Example:"2026-07-07T14:09:31.264Z"

curl -i -X POST \
  https://sandbox.api.flute.com/v2/payment-links \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'idempotency-key: 6a1f7e2c-4b3d-4e5a-8f9c-1d2e3f4a5b6c' \
  -d '{
    "paymentMethods": {
      "card": {
        "enabled": true,
        "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e"
      }
    },
    "baseAmount": 25,
    "currencyCode": "USD",
    "linkType": "SingleUse",
    "customerId": "3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e",
    "referenceId": "ORDER-1042",
    "name": "Spring campaign",
    "description": null,
    "expiresOn": "2026-09-15T00:00:00.000Z"
  }'

Responses

Bodyapplication/json

paymentLinkIdstring, (uuid)

Indicates the payment link identifier.

Example: 6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b

Example:"6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b"

linkTypestring

Identifies the payment link type.

Valid values are:

Type	Description
MultiUse	The link can be shared with, and paid by, more than one customer.
SingleUse	The link is intended for a single customer and a single payment.

Example: SingleUse

Default:"SingleUse"

Enum:"MultiUse""SingleUse"

Example:"SingleUse"

modestring or null, (enum)

Indicates whether payers are offered to save their payment method.

Valid values are:

Name	Description
Payment	Takes a one-off payment.
PaymentAndSave	Takes the payment and also offers the payer to save their payment method. When the link has no customer, a customer is created for a payer who saves. A `customerId` alone does not turn saving on.

This value is null when no mode is recorded for the link. This value cannot be changed through the API after the link is created. A merchant who adds a customer to the link in the merchant portal turns saving on, and removing the customer there turns it off.

Example: Payment

Default:"Payment"

Enum:"Payment""PaymentAndSave"

Example:"Payment"

metadataobject or null

Indicates the key-value pairs attached to the payment link.

These pairs are copied into every payment session the link opens. This value is null when the link has none.

Example: {"orderId": "9921"}

Example:

{
  "orderId": "9921",
  "Guest notes": "Member of The World of Hyatt Credit Card."
}

paymentMethodsobject

Identifies the payment methods a payment link accepts. It is keyed by method so each one carries only the configuration that applies to it.

At least one payment method must be enabled, card or ACH. Both may be specified.

taxModestring

Specifies how taxRate and taxAmount is applied to amount.

Name	Description
Exclusive	Adds the tax on top of `amount`. The payer is charged `amount` plus the tax.
Inclusive	Treats `amount` as already including the tax. No extra amount is added.

A taxMode value must be used with exactly one of taxRate or taxAmount, or none of the three. When all three are omitted, the payment session has no tax configured.

Example: Exclusive

Enum:"Exclusive""Inclusive"

Example:"Exclusive"

taxRatenumber or null, (double)

Indicates the tax rate percentage to apply to the base amount.

Example: 8.25 (for 8.25%)

Example:8.25

taxAmountnumber or null, (double), decimal places <= 2, >= 0

Indicates a fixed tax amount (in USD) to apply to the base amount.

A response carries this value only when the tax was configured as an amount. Otherwise, it is null.

Examples:
3.75 (for $3.75)
null

Example:3.75

baseAmountnumber or null, (double)

Indicates the payment amount.

If omitted or null, indicates the customer can enter the amount at checkout.

Example: 25

Example:25

currencyCodestring or null

Indicates the transaction's currency code (in uppercase ISO 4217 currency code).

Example: USD

Example:"USD"

paymentLinkStatusstring

Indicates the status of the payment link.

Valid values are:

Status	Description
Active	The link is open and can accept a payment.
Completed	A SingleUse link that has received its one payment.
Expired	The link's `expiresOn` date has passed.
Inactive	The link was deactivated and cannot accept a payment.

Example: Active

Enum:"Active""Completed""Expired""Inactive"

Example:"Active"

namestring or null, <= 80 characters

Indicates the merchant-facing label for the payment link.

Example: Spring campaign

Example:"Spring campaign"

descriptionstring or null

Indicates the merchant-internal notes for the payment link.

This value is never shown to customers.

Example: Shared with returning customers only

Example:"Shared with returning customers only"

shortUrlstring or null

Indicates a shortened version of the URL to the invoice's public payment page.

These are generated by Flute and are the hosted page the customer opens to pay. This is the compact form. It is better suited for SMS messages, printed materials, anywhere character count or a tidy appearance matters.

Example: https://pay.example.com/l/abc123

Example:"https://pay.example.com/l/abc123"

customerIdstring or null, (uuid)

Indicates the customer the link is issued for.

If omitted or null, this value is for an anonymous link.

Example: a3b37f26-3b4c-4d5e-6f7a-8b9c0d1e2f58

Example:"a3b37f26-3b4c-4d5e-6f7a-8b9c0d1e2f58"

customerFirstNamestring or null

Indicates the first name of the attached customer, when any.

Example: Alexandro

Example:"Alexandro"

customerLastNamestring or null

Indicates the last name of the attached customer, when any.

Example: Peppared

Example:"Peppared"

referenceIdstring or null

Indicates the reference identifier provided by the merchant.

Example: ORDER-1042

Example:"ORDER-1042"

expiresOnstring or null, (date-time)

Indicates the UTC expiration date-time (in an ISO 8601 UTC date-time format).

This value is null when the link never expires.

Example: 2029-09-15T00:00:00.000Z

Example:"2029-09-15T00:00:00.000Z"

paymentCountinteger, (int32)

Indicates the number of successful payments received.

Example: 3

Example:3

totalCollectedAmountnumber, (double), decimal places <= 2

Indicates the sum of all successful payment amounts (in USD).

Example: 75 (for $75)

Example:75

createdOnstring, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) the payment link was created on.

Example: 2026-01-15T10:30:56.264Z

Example:"2026-01-15T10:30:56.264Z"

lastPaymentOnstring or null, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) of the newest successful payment.

This value is null when no payments exist.

Example: 2026-03-10T18:42:11.264Z

Example:"2026-03-10T18:42:11.264Z"

modifiedOnstring, (date-time)

Indicates the date-time (in an ISO 8601 UTC date-time format) the payment link was last modified on.

Example: 2026-07-07T14:09:31.264Z

Example:"2026-07-07T14:09:31.264Z"

Response

{
  "paymentLinkId": "6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b",
  "linkType": "SingleUse",
  "paymentMethods": {
    "card": {
      "enabled": true,
      "processorId": "d529945e-8d10-4cb4-9dc3-718e57f3f14e"
    }
  },
  "baseAmount": 25,
  "currencyCode": "USD",
  "paymentLinkStatus": "Active",
  "name": "Spring campaign",
  "description": null,
  "shortUrl": "https://pay.example.com/l/abc123",
  "customerId": "3c4d5e6f-7a8b-49c0-8d1e-2f3a4b5c6d7e",
  "customerFirstName": "Alexandro",
  "customerLastName": "Peppared",
  "referenceId": "ORDER-1042",
  "expiresOn": "2026-09-15T00:00:00.000Z",
  "paymentCount": 0,
  "totalCollectedAmount": 0,
  "lastPaymentOn": null,
  "createdOn": "2026-08-12T09:15:22.100Z",
  "modifiedOn": "2026-08-12T09:15:22.100Z"
}