# Payment links

Source: <https://docs.gjold.com/v1/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 /v1/new` | [Create](https://docs.gjold.com/v1/payment-links/create) a link for an order. |

The same request, with a `"subscriber"`, creates a link where the payer saves their card: see [Create subscriber](https://docs.gjold.com/v1/subscribers/create).

## From link to transaction

1. When the payer clicks Pay in your checkout, your server [creates a link](https://docs.gjold.com/v1/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/v1/synchronization/ping) you, and [seq](https://docs.gjold.com/v1/synchronization/seq) returns the [transaction](https://docs.gjold.com/v1/transactions#the-transaction-object), with your `"orderid"`. This, not the redirect, is when the order is paid.
6. You [capture](https://docs.gjold.com/v1/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. |

A link can't be changed, and v1 can't delete one: it can be paid until it expires. To change the order, create a new link, and keep lifetimes short. If a link you replaced is paid after all, seq returns its transaction like any other: don't capture it, and the bank releases the amount when the authorization runs out. Only a paid link leaves a trace in seq, as a transaction; a decline or an expiry 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. Without `"autocapture"`, a bank that approves only part of the sum leaves a transaction for that part: see [Partial authorizations](https://docs.gjold.com/v1/payment-links/create#partial-authorizations).
- 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 15 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/v1/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/v1/subscribers/create) and [Renew subscriber](https://docs.gjold.com/v1/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.

## See also

[Create payment link](https://docs.gjold.com/v1/payment-links/create), 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).