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.

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

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.

baseAmountnumber or null, (double)

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

Example:25

currencyCodestring or null

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

Example: 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. This value is not allowed when linkType is MultiUse.

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

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

referenceIdstring or null

Specifies a reference identifier provided by the merchant, up to 200 characters.

Example: ORDER-1042

Example:"ORDER-1042"

namestring or null

Specifies the merchant-facing label for the payment link, up to 80 characters.

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

Example: Spring campaign

Example:"Spring campaign"

descriptionstring or null

Specifies merchant-internal notes for the payment link, up to 500 characters.

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' \
  -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"

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.

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 the customer-facing shortened URL of the payment link.

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: 2026-09-15T00:00:00.000Z

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

paymentCountinteger, (int32)

Indicates the number of successful payments received.

Example: 3

Example:3

totalCollectedAmountnumber, (double)

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

Example: 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"
}