## Overview

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 can 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 processor.
The processor can be omitted, which then uses the merchant's default processor.


A linkType specifies:

* `SingleUse`. The payment link is intended for one customer and one payment.
* `MultiUse`. 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.

A payment link moves through an effective status of the following.

| 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.

The following endpoints are available to:

* Create a payment link (`POST /v2/payment-links`)
* List a payment link (`GET /v2/payment-links`)
* Retrieve a specified payment link (`GET /v2/payment-links/{{paymentLinkId}}`)
* 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 brief complete workflow for using a payment link.

1) Create a payment link for a transaction.
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", 
        "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:

* Using: `POST /v2/payment-links/{{paymentLinkId}}/share`.
This endpoint sends the payment link to the customer described in the endpoint.
* Send the returned `shortUrl` directly through any other 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:

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

Check that `paymentLinkStatus` is `Completed`.
If so, `paymentCount` and `totalCollectedAmount` should reflect the transaction.
Together, these verify the transaction completed successfully.