# Create payment link

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

Create a link to the payment window, where the payer pays for one order. The link can be paid once, for the items' total, until it expires.

## Request

**POST** `https://api.gjold.com/v2/{shopid}:pay/new`

The key needs the `payid` [permission](https://docs.gjold.com/v2/authentication#permissions). The request takes no `Idempotency-Key`: see [Retrying](https://docs.gjold.com/v2/payment-links/create#retrying).

### Headers

- `Authorization`

  **Required.** Your API key, after `Basic` and base64-encoded. See [Authentication](https://docs.gjold.com/v2/authentication).
- `Content-Type`

  `application/json`. We don't check it.

### Fields

- `orderid` (string, **required**)

  Your ID for the order. Seq returns it with the transaction, and the acquirer passes it to the payer's bank as the payment's reference. We take any length, but the acquirer sees at most the first 20 letters, digits, and spaces of it with Nets, or 30 characters with Clearhaus, so make those unique.
- `items` (array, **required**)

  What the payer pays for: one or more items, whose totals add up to the amount to pay. All in one currency, and together more than 0.
- `items[].total` (amount, **required**)

  The price of the item, its whole quantity together. At least 0, and with no more decimals than the currency has. See [Amounts](https://docs.gjold.com/v2/amounts).
- `items[].quantity` (integer)

  How many, a positive integer. The default is `1`. It is for your records and the dashboard: the `"total"` is already for all of them.
- `items[].name` (string)

  The name of the product or service, for your records and the dashboard. The payment window does not show it.
- `items[].sku` (string)

  Your [SKU](https://en.wikipedia.org/wiki/Stock_keeping_unit) for the product.
- `billing` (object)

  The payer's billing address, which seq returns with the transaction. See [Addresses](https://docs.gjold.com/v2/payment-links/create#addresses) for its fields.
- `shipping` (object)

  The address to ship to, which seq returns with the transaction. See [Addresses](https://docs.gjold.com/v2/payment-links/create#addresses) for its fields.
- `autocapture` (boolean)

  Capture the payment as soon as it is authorized. By default, `false`, it is only authorized, and you [capture](https://docs.gjold.com/v2/transactions/capture) it later. With `true`, a capture that fails voids the authorization, and the payer sees the payment declined. Use it only when you deliver at once, as the knowledge base's [Captures and refunds](https://docs.gjold.com/learn/captures-and-refunds#when-to-capture) explains.
- `successurl` (string)

  Where the payment window sends the payer when they have paid, with a `GET` and nothing added to the URL. Without it, the window shows a confirmation of its own. We don't check it, so make it an absolute `https` URL that works, and put in it what the page needs, such as your order ID. It is no proof of payment: see [Orders and payment links](https://docs.gjold.com/notes/orders#the-success-page-is-no-proof).
- `language` (string)

  The payment window's language: `"da"`, `"en"`, `"no"`, or `"sv"`. A code with a region, such as `"en-GB"`, counts as its language. Without one, or with another, the window takes the language from the payer's browser, and else uses English.
- `lifetime` (string)

  How long the link can be paid: a whole number and a unit, `d`, `h`, `m`, or `s`, as in `"90m"` or `"7d"`. The default is `"1h"`, and it can be from `"5m"` to `"30d"`. The payer must be done, 3-D Secure included, before it ends. The longer the lifetime, the longer the link's ID: see [The link's ID](https://docs.gjold.com/v2/payment-links/create#the-links-id).

The amount to pay is the sum of the items' totals, and is the amount that the payer's bank must authorize in whole: a payment that the bank approves only in part is declined. See the knowledge base's [Partial authorizations](https://docs.gjold.com/learn/authorizations#partial-authorizations).

### Addresses

`"billing"` and `"shipping"` have these fields:

| Field | Type | Description |
|---|---|---|
| `name` | string | The person's name. |
| `company` | string | The company's name. |
| `vatin` | string | The company's VAT number, as `"DK14915508"`. Billing only. |
| `gln` | string | The company's [GLN](https://en.wikipedia.org/wiki/Global_Location_Number), for electronic invoices. Billing only. |
| `email` | string | An email address. |
| `phone` | string | A phone number. In the international form, as `"+4545571057"`, it also fills in the payer's number in MobilePay. |
| `address` | array of strings | The street address, one line per string, without the city and the postcode. |
| `city` | string | The city. |
| `zip` | string | The postcode. |
| `state` | string | The state or region, where the country has them. |
| `country` | string | The country, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code such as `"DK"`. |

Every field is optional, and free text that we store and return as it is, after [cleaning up](https://docs.gjold.com/v2/requests#request-bodies) its white space.

### Example

A link for two items, which sends the payer back to your shop once they have paid:

```sh
curl https://api.gjold.com/v2/{shopid}:pay/new \
    -u {apikey} \
    -H 'Content-Type: application/json' \
    -d @request.json
```

```json
{
    "orderid": "1234zx",
    "items": [
        {
            "name": "Danmarkskort plakat",
            "quantity": 2,
            "total": "199.90 DKK",
            "sku": "182932000-MAP-DK"
        },
        {
            "name": "Fragt - PostNord",
            "total": "45 DKK"
        }
    ],
    "billing": {
        "name": "Peter Nielsen",
        "email": "pn@nielsenas.dk",
        "address": ["Pederstrupvej 14"],
        "city": "Teststrup",
        "zip": "8320",
        "country": "DK"
    },
    "successurl": "https://shop.example/thanks?order=1234zx",
    "language": "da",
    "lifetime": "2h"
}
```

## Response

We answer `200 OK` with the link:

- `url` (string)

  The link: the payment window's address, to send the payer to.
- `id` (string)

  The link's ID, the `{payid}` by which you can [delete](https://docs.gjold.com/v2/payment-links/delete) it. Store it with the order.

```json
{
    "url": "https://pay.gjold.com/q3z3amhrkmyrgk6i",
    "id": "q3z3amhrkmyrgk6i"
}
```

No transaction exists yet. We create one when the payer's bank has authorized the payment, and [seq](https://docs.gjold.com/v2/synchronization/seq) returns it then, with your `"orderid"`. Seq returns nothing for a payment that is declined, or a link that expires unpaid.

### The link's ID

An ID is random, and is 12 to 48 characters from `0` to `9` and `a` to `z` but `1`, `l`, `n`, and `o`. The longer a link can be paid, the longer its ID, so that it can't be guessed in that time:

| Lifetime | Length of the ID |
|---|---|
| 1 hour or less | 12 to 16 |
| 6 hours | 13 to 16 |
| 12 hours | 13 to 18 |
| 1 day | 16 to 21 |
| 2 days | 20 to 24 |
| 7 days | 29 to 34 |
| 14 days | 36 to 40 |
| 30 days | 44 to 48 |

Treat it as an opaque string of up to 48 characters. We read an ID without regard to case, and as if `o` were `0`, `l` and `1` were `i`, and `n` were `m`, so that a link that a person types in still works.

### Link parameters

The payment window offers the payer every payment method that you have. To take them to one, add a parameter to the link's URL:

| Link parameter | What it does |
|---|---|
| `?go=mobilepay` | Sends the payer straight on to MobilePay, without showing the payment window, as when they chose MobilePay in your checkout. |
| `?go=applepay` | Opens the payment window with Apple Pay in focus, as when they chose Apple Pay in your checkout. |

If you don't have the method, or the payer's device can't use it, the parameter does nothing, and the payer sees the payment window as without it.

## Errors

Besides the errors that any request can give, such as `401` and `413`, which [Errors](https://docs.gjold.com/v2/errors) lists:

| Status and message | Description |
|---|---|
| `400 invalid json in {where}: {why}` | The body is not a JSON object, or a field is not as the table says, as in `invalid json in items[1].total: missing currency`. See [Invalid JSON](https://docs.gjold.com/v2/errors#invalid-json). |
| `400 missing orderid` | There is no `"orderid"`, or it is empty. |
| `400 missing items` | There are no `"items"`, or the array is empty. |
| `400 total must be more than 0` | The items' totals add up to 0. |
| `400 invalid item total currency` | An item's total is in a currency that is not in the [ISO 4217 table](https://docs.gjold.com/v2/amounts#currencies). |
| `400 invalid lifetime` | The `"lifetime"` can't be read, or is under `"5m"` or over `"30d"`. |
| `500 {why}` | We could not create the link just now. Try again. |

### Retrying

A declined card is not an error of this request: the payer sees the decline in the payment window, and can try again there until the link expires. The request takes no `Idempotency-Key`, so a retry after a broken connection can create a second link. That does no harm, as no one has the first link's URL, and it expires unpaid.

## See also

[Payment links](https://docs.gjold.com/v2/payment-links), [Delete payment link](https://docs.gjold.com/v2/payment-links/delete), [Orders and payment links](https://docs.gjold.com/notes/orders), [Websites and apps](https://docs.gjold.com/notes/payment-window), and in the knowledge base, [The payment window](https://docs.gjold.com/learn/payment-window).