Payment Links

A payment link is a Flute-hosted, shareable checkout page.

Payment links are the best fit when a merchant wants to collect a payment without building or embedding a checkout flow. They work without a card-present terminal or a custom checkout integration. This is in contrast with payment sessions. Those are used inside Flute Elements or Flute Checkout, where the merchant has already built an integrated checkout experience.

Consider the following cases:

• A merchant taking a phone or mail order who has no POS terminal handy and no online checkout page can text or email a link and let the customer pay on their own.
• A business invoicing a client for a one-time amount can generate a SingleUse link tied to that specific order or reference identifier. That link naturally closes out after that one payment.
• A business may want a standing, reusable payment page, such as a general "pay us" link for a storefront, a fundraiser, or recurring informal payments from the same or different customers. That case can use a MultiUse link instead, because it keeps accepting payments rather than deactivating it after the first one.

A merchant creates a link by specifying:

• A transaction base amount (in USD). The transaction base amount can be omitted, which allows the customer to enter an amount at checkout.
• A payment method, such as a card, ACH, or both.

A payment link's use limit is specified using linkType, which identifies:

A link can optionally be tied to a specific customer. It carries its own reference identifier, name, and merchant-facing description for internal use.

A payment link moves through one of the following statuses.

Flute tracks the count and the total amount of the successful payments it has received.

The following endpoints are available to:

The following is a brief, complete workflow for using a payment link.

1) Create a payment link for a transaction.
Use: POST /v2/payment-links.
Partial request body:

   {
       "linkType": "SingleUse",
       "baseAmount": 75,
       "currencyCode": "USD",
       "paymentMethods": {
           "card": {
            "enabled": true
           }
       }
   }

Partial response body:

   {
        "paymentLinkId": "6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b", 
        "shortUrl": "https://pay.example.com/l/abc123",
        ...
   }

This returns:

• The paymentLinkId, a UUID identifier for this payment link.
• The shortUrl, a URL the customer can open to complete the payment.

2) Share the payment link with the customer so they can complete the transaction.
This may be done either:

• Calling POST /v2/payment-links/{{paymentLinkId}}/share. This endpoint sends the payment link to the customer specified in the request.
• Sending the returned shortUrl directly through another channel, such as a text or email.

3) The customer opens the shared payment link and completes the payment on Flute's hosted checkout page.

4) Verify the payment.
Poll the payment link using: GET /v2/payment-links/{{paymentLinkId}}
Partial response body:

   {
        "paymentLinkStatus": "Completed", 
        "paymentCount": 1,
        "totalCollectedAmount": 75,
        "lastPaymentOn": "",
        ...
   }

For SingleUse payments, check that the paymentLinkStatus is Completed. If so, paymentCount, totalCollectedAmount and lastPaymentOn should accurately reflect the transaction. Together, these verify the transaction completed successfully.

For MultiUse payments, the paymentLinkStatus remains Active. The paymentCount and totalCollectedAmount values continue to increase with each payment. Check lastPaymentOn for the last payment timestamp.

5) Verify with Webhooks.
In either case, a webhook can be created with the payment_session.completed event type added. The webhook returns the status and the paymentLinkId that can be linked back the original transaction.

A payment session is created each time a customer opens a payment link, whether the link's type is SingleUse or MultiUse. The customer completes the payment through that session's checkout page. Once the transaction finishes, the payment session itself closes and is marked Completed. It's this Completed status that invokes the webhook's payment_session.completed event type.

Every session follows this same lifecycle, regardless of the payment link's type. What the payment link type does affect is the payment link itself afterward.

• A SingleUse link is marked Completed once its one session finishes.
• AMultiUse link stays Active and can generate further sessions from later transactions.