# Payment Links

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

This payment link directs customers to a checkout page where they complete the payment.
The merchant does not need to build the checkout user interface, its dialog, or having to embed any checkout flow.
No POS terminal and no custom integration are required.
A payment link can be texted or emailed to a customer directly.

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.

The following are common use 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:

| linkType | Description |
|  --- | --- |
| SingleUse | Specifies the payment link is intended for one customer and one payment. |
| MultiUse | Specifies the payment link is intended for more than one payment and may be used by more than one customer. |


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

A payment link can be one of the following statuses.

| Status | Description |
|  --- | --- |
| Active | The link is open and can accept a payment. |
| Completed | A single use link has received its one payment. |
| Expired | The link has expired. |
| Inactive | The link was deactivated and cannot accept a payment. |


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

## Payment Link Endpoints

The following endpoints are available to:

| Action | Endpoint |
|  --- | --- |
| List a payment link | `GET /v2/payment-links` |
| Retrieve a payment link by ID | `GET /v2/payment-links/{{paymentLinkId}}` |
| Create a payment link | `POST /v2/payment-links` |
| Update a specified payment link | `PATCH /v2/payment-links/{{paymentLinkId}}` |
| Delete a specified payment link | `DELETE /v2/payment-links/{{paymentLinkId}}` |
| Share an active link with a customer by SMS or email | `POST /v2/payment-links/{{paymentLinkId}}/share` |


## Example

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

* Creating a payment link
* Sharing the payment link
* Opening the payment link
* Confirming the payment
* Verifying the payment with webhooks


### Creating a payment link

This creates a new payment link.

Use: `POST /v2/payment-links`.
Partial request body:

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

Partial response body:

```json
   {
        "paymentLinkId": "6f2a8b3c-9d4e-4f1a-8b7c-3e5d6a9f0c1b",
        "fullUrl": "https://pay.flute.com/invoices/39a95e35-6d50-45ec-884b-c2417edf005d",
        "shortUrl": "https://pay.flute.com/l/abc123",
        ...
   }
```

This returns:

* The `paymentLinkId`, a UUID identifier for this payment link.
* The `fullUrl` and `shortUrl`, are URLs the customer can open to complete the payment.


### Sharing the payment link

The payment link must be shared with the customer so they can complete the transaction.
This may be done either by:

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


### Opening the payment link

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

### Confirming the payment

After the customer completes the transaction, you can confirm the status.

Poll the payment link using: `GET /v2/payment-links/{{paymentLinkId}}` 
Partial response body:

```json
   {
        "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.

### Verifying the payment with webhooks

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` after a successful payment.
* A`MultiUse` link stays `Active` and can generate further sessions from later transactions.