{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Payment Links","siteUrl":"https://developer.flute.com","description":"Documentation and API reference for integrating Flute payment processing.","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-links","__idx":0},"children":["Payment Links"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment link is a Flute-hosted, shareable checkout page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consider the following cases:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A business invoicing a client for a one-time amount can generate a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SingleUse"]}," link tied to that specific order or reference identifier."," ","That link naturally closes out after that one payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MultiUse"]}," link instead, because it keeps accepting payments rather than deactivating it after the first one."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A merchant creates a link by specifying:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A transaction base amount (in USD)."," ","The transaction base amount can be omitted, which allows the customer to enter an amount at checkout."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A payment method, such as a card, ACH, or both."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment link's use limit is specified using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["linkType"]},", which identifies:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"linkType"},"children":["linkType"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SingleUse"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specifies the payment link is intended for one customer and one payment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MultiUse"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specifies the payment link is intended for more than one payment and may be used by more than one customer."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A link can optionally be tied to a specific customer."," ","It carries its own reference identifier, name, and merchant-facing description for internal use."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment link moves through one of the following statuses."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Active"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The link is open and can accept a payment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Completed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A single use link has received its one payment."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The link has expired."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inactive"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The link was deactivated and cannot accept a payment."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flute tracks the count and the total amount of the successful payments it has received."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-link-endpoints","__idx":1},"children":["Payment Link Endpoints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following endpoints are available to:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List a payment link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/payment-links"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve a specified payment link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/payment-links/{{paymentLinkId}}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a payment link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payment-links"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update a specified payment link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /v2/payment-links/{{paymentLinkId}}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete a specified payment link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v2/payment-links/{{paymentLinkId}}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Share an active link with a customer by SMS or email"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payment-links/{{paymentLinkId}}/share"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":2},"children":["Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is a brief, complete workflow for using a payment link."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["1) Create a payment link for a transaction.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Use: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payment-links"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Partial request body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"   {\n       \"linkType\": \"SingleUse\",\n       \"baseAmount\": 75,\n       \"currencyCode\": \"USD\",\n       \"paymentMethods\": {\n           \"card\": {\n            \"enabled\": true\n           }\n       }\n   }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partial response body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"   {\n        \"paymentLinkId\": \"6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b\", \n        \"shortUrl\": \"https://pay.example.com/l/abc123\",\n        ...\n   }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This returns:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLinkId"]},", a UUID identifier for this payment link."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shortUrl"]},", a URL the customer can open to complete the payment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["2) Share the payment link with the customer so they can complete the transaction.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","This may be done either:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payment-links/{{paymentLinkId}}/share"]},"."," ","This endpoint sends the payment link to the customer specified in the request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sending the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shortUrl"]}," directly through another channel, such as a text or email."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["3) The customer opens the shared payment link and completes the payment on Flute's hosted checkout page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["4) Verify the payment.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Poll the payment link using: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/payment-links/{{paymentLinkId}}"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Partial response body:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"   {\n        \"paymentLinkStatus\": \"Completed\", \n        \"paymentCount\": 1,\n        \"totalCollectedAmount\": 75,\n        \"lastPaymentOn\": \"\",\n        ...\n   }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SingleUse"]}," payments, check that the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLinkStatus"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]},"."," ","If so, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentCount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCollectedAmount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastPaymentOn"]}," should accurately reflect the transaction."," ","Together, these verify the transaction completed successfully."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MultiUse"]}," payments, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLinkStatus"]}," remains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]},"."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentCount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCollectedAmount"]}," values continue to increase with each payment."," ","Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastPaymentOn"]}," for the last payment timestamp."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["5) Verify with Webhooks.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","In either case, a webhook can be created with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_session.completed"]}," event type added."," ","The webhook returns the status and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentLinkId"]}," that can be linked back the original transaction."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment session is created each time a customer opens a payment link, whether the link's type is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SingleUse"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MultiUse"]},"."," ","The customer completes the payment through that session's checkout page."," ","Once the transaction finishes, the payment session itself closes and is marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]},"."," ","It's this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]}," status that invokes the webhook's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_session.completed"]}," event type."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SingleUse"]}," link is marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Completed"]}," once its one session finishes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MultiUse"]}," link stays ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Active"]}," and can generate further sessions from later transactions."]}]}]},"headings":[{"value":"Payment Links","id":"payment-links","depth":1},{"value":"Payment Link Endpoints","id":"payment-link-endpoints","depth":2},{"value":"Example","id":"example","depth":2}],"frontmatter":{"title":"Payment Links","description":"A payment link is a Flute-hosted, shareable checkout page.","seo":{"title":"Payment Links"}},"lastModified":"2026-08-24T20:43:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/online-payments/payment-links","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}