Create payment link

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/v1/new

The URL names no shop: the request is for the shop whose API key it has. The key needs the payid permission. The request takes no Idempotency-Key: see Retrying.

Headers

HTTP header	Description
`Authorization`	Required. Your API key, after `Basic` and base64-encoded. See Authentication.
`Content-Type`	`application/json`. We don't check it.
`X-Cardholder-IP`	Ignored. Older versions of these docs asked for the payer's IP address here, and a request that has it still works.

Fields

Field	Type	Description
`orderid`	string	Your ID for the order. Seq returns it with the transaction, which is how you match the transaction to the order, and the acquirer passes it to the payer's bank as the payment's reference. Optional, but give it. 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, as a string with its currency, as `"199.90 DKK"`. At least 0. Decimals beyond the currency's minor unit are cut off: `"10.999 DKK"` is 10.99 DKK. See 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 for the product. We accept it, but don't store it, so seq does not return it.
`billing`	object	The payer's billing address, which seq returns with the transaction. See Addresses for its fields.
`shipping`	object	The address to ship to, which seq returns with the transaction. See 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 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 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.
`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"`, or several, as in `"1d 12h"`. The default is `"1h"`, and it can be from 15 minutes to 30 days: a shorter lifetime is made 15 minutes, and a longer one 30 days. One we can't read is not an error, but gives the link the default or the shortest lifetime, so check yours. 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.

A field we don't know is ignored. Send each field with the type that the table gives: a known field of another type, as a "billing" that is a string, or null, may be ignored rather than refused, so a mistake can go unreported.

Partial authorizations

The amount to pay is the sum of the items' totals. The payer's bank may approve only part of it, as some debit and prepaid cards do. Then:

Without "autocapture", the payment goes through for what the bank approved, and seq returns the transaction with that in totals.authorized. Compare it with what the order costs before you deliver.
With "autocapture", the payment is declined, and the payer can try again in the window.

See the knowledge base's 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, 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 code such as `"DK"`.

Every field is optional, and free text that we store and return as it is, after cleaning up its white space.

Example

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

curl https://api.gjold.com/v1/new \
    -u {apikey} \
    -H 'Content-Type: application/json' \
    -d @request.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:

Field	Type	Description
`url`	string	The link: the payment window's address, to send the payer to. Its last part is the link's ID: see The link's ID.

{
    "url": "https://pay.gjold.com/q3z3amhrkmyrgk6i"
}

No transaction exists yet. We create one when the payer's bank has authorized the payment, and seq returns it then, with your "orderid", which is how you match it to the order, as the answer has no ID to store. Seq returns nothing for a payment that is declined, or a link that expires unpaid.

The link's ID

The ID is the last part of the link's URL, after the host. It 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 the URL as an opaque string, and the ID as 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.

Use it only if you have MobilePay: without it, the payer sees the error mobilepay not supported in place of the payment window.

Errors

Besides the errors that any request can give, such as 401 and 413, which Errors lists:

Status and message	Description
`400 invalid json in {where}: {why}`	The body is not JSON, or an item's total can't be read, has no currency, or is in another currency than the items before it, as in `invalid json in items[1].total: missing currency`. See Invalid JSON.
`400 total must be more than 0`	The items' totals add up to 0.
`500 missing items`	There are no `"items"`, or the array is empty. Fix the request: a retry fails the same way.
`500 invalid item total currency`	An item's total is in a currency that is not in the ISO 4217 table. Fix the request.
`500 {why}`	Any other failure: we could not create the link just now. Try again.

A "lifetime" that can't be read, or is out of bounds, is not an error: see the field.

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.