# Payment links

Source: <https://docs.gjold.com/v2/payment-links>

A payment link is a URL to our payment window, where the payer pays for one order. It can be paid once, for its whole amount, until it expires; when it is, it becomes a transaction.

## Requests

| Request | What it does |
|---|---|
| `POST {shopid}:pay/new` | [Create](https://docs.gjold.com/v2/payment-links/create) a link for an order. |
| `DELETE {shopid}:pay:{payid}` | [Delete](https://docs.gjold.com/v2/payment-links/delete) a link before it expires. |

## From link to transaction

1. When the payer clicks Pay in your checkout, your server [creates a link](https://docs.gjold.com/v2/payment-links/create), with your `"orderid"` and the items.
2. You redirect the payer to the link's `"url"`.
3. The payer pays in the payment window, with 3-D Secure if their bank asks for it. A declined payment stays in the window, where the payer can try again.
4. When the bank has authorized the payment, we create a transaction, and the window sends the payer to your `"successurl"`.
5. We [ping](https://docs.gjold.com/v2/synchronization/ping) you, and [seq](https://docs.gjold.com/v2/synchronization/seq) returns the [transaction](https://docs.gjold.com/v2/transactions#the-transaction-object), with your `"orderid"`. This, not the redirect, is when the order is paid.
6. You [capture](https://docs.gjold.com/v2/transactions/capture) the transaction when you deliver, unless the link had `"autocapture"`.

What the payer sees, from the payment methods to 3-D Secure, is in the knowledge base's [The payment window](https://docs.gjold.com/learn/payment-window).

## A link's states

| State | What it means | Opening the link |
|---|---|---|
| Open | Created, not yet paid, and not expired. | Shows the payment window. |
| Paid | The bank authorized a payment, and there is a transaction. | Shows a confirmation for 10 minutes, then `404`. |
| Expired | Its `"lifetime"` ran out unpaid. | `404`, with a page that says it expired. |
| Deleted | You [deleted](https://docs.gjold.com/v2/payment-links/delete) it. | As for an expired link. |

A link can't be changed: to change the order, delete its link and create a new one. Only a paid link leaves a trace in seq, as a transaction; a decline, an expiry, or a delete does not.

## Rules

- A link is paid once, for the sum of its items. A second payment of it is not possible, from the same window or another.
- It can be open in several windows or devices at once, and keeps its state on our servers, so the payer can reload, go back, or switch device. While one window is paying, another that tries gets an error, and can try again once the first is done.
- It expires after its `"lifetime"`: 1 hour by default, and from 5 minutes to 30 days. The payer must be done before then, 3-D Secure included, so use long lifetimes only for links sent by email or SMS.
- Its ID is random, and longer the longer it lives, so that a link can't be guessed while it can be paid. See [The link's ID](https://docs.gjold.com/v2/payment-links/create#the-links-id).
- Anyone with the URL can pay the link, and see your shop's name and the amount, but nothing of the payer.

## Subscribers

[Create subscriber](https://docs.gjold.com/v2/subscribers/create) and [Renew subscriber](https://docs.gjold.com/v2/subscribers/renew) answer with links of the same kind, which open the same window, where the payer saves their card rather than only pays. They follow the same rules, and are deleted the same way.

## See also

[Create payment link](https://docs.gjold.com/v2/payment-links/create), [Delete payment link](https://docs.gjold.com/v2/payment-links/delete), and the implementation notes [Orders and payment links](https://docs.gjold.com/notes/orders) and [Websites and apps](https://docs.gjold.com/notes/payment-window). In the knowledge base: [The payment window](https://docs.gjold.com/learn/payment-window), [3-D Secure](https://docs.gjold.com/learn/3-d-secure), and [PCI DSS](https://docs.gjold.com/learn/pci-dss).