---
title: "Generate a link_id"
method: POST
path: "/payment-links"
tags: ["Hosted Checkout"]
---

# Generate a link_id

`POST /payment-links`

Generate a payment-link which contains detail of the order or payment. This link_id can then be appended to the required environment and shared with the customer like this `https://test-pay.acquired.com/v1/{link_id}`. In production, remove the test prefix.

## Headers

- `Company-Id` string, uuid
- `Mid` string, uuid

## Request body

- object
  - `transaction` object
    - `order_id` string, required — Unique reference assigned by you for the payment request.
    - `amount` number, float, required — The total amount you want to charge.
    - `currency` 'aed' | 'aud' | 'cad' | 'chf' | 'cny' | 'dkk' | 'eur' | 'gbp' | 'hkd' | 'jpy' | 'mxn' | 'sek' | 'usd' | 'zar', required — ISO 4217 currency code in lower case.
    - `moto` boolean — Set to true if processing a payment over the phone.
    - `capture` boolean — Set to false if you want to just authorise and request a funds transfer later. If capture is set to true, the `transaction_type` will be `sale`.
    - `custom_data` string — Base64 encoded string detailing custom data passed in the request.
    - `custom1` string — Send additional data relating to the customer or another internal reference.
    - `custom2` string — Send additional data relating to the customer or another internal reference.
  - `payment` object
    - `reference` string — Where supported by the acquiring bank, set the reference to appear on the card holders bank statement. Avoid consecutive special characters (e.g. --) which may result in rejection.
    - `card_id` string, uuid — Unique ID assigned by Acquired.com for the card. This allows the customer to select a previously created card.
  - `customer` object
    - `customer_id` string, uuid — Unique ID assigned by Acquired.com to the customer when it is created.
    - `first_name` string — The customer's first name.
    - `last_name` string — The customer's last name. **Required for MCC 6012 merchants.**
    - `dob` string, date — The customer's date of birth. **Required for MCC 6012 merchants.**
    - `custom_data` string — Base64 encoded string detailing custom data passed in the request.
    - `billing` object
      - `address` Address
        - `line_1` string — The first line of the customer's address. **Recommended when processing EMV 3DS transactions and for AVS checks.**
        - `line_2` string — The second line of the customer's address.
        - `city` string — The city of the customer's address.
        - `state` string — The 3 letter ISO 3166-2 3-character state code of the customer's address. This should only be sent when processing in the US.
        - `postcode` string — The postcode of the customer's address. **Recommended for MCC 6012 merchants. Required when processing EMV 3DS transactions and for AVS checks.**
        - `country_code` 'al' | 'al' | 'dz' | 'as' | 'ad' | 'ao' | 'ai' | 'aq' | 'ag' | 'ar' | 'am' | 'aw' | 'au' | 'at' | 'az' | 'bs' | 'bh' | 'bd' | 'bb' | 'by' | 'be' | 'bz' | 'bj' | 'bm' | 'bt' | 'bo' | 'ba' | 'bw' | 'br' | 'io' | 'bn' | 'bg' | 'bf' | 'bi' | 'cv' | 'kh' | 'cm' | 'ca' | 'ky' | 'cf' | 'td' | 'cl' | 'cn' | 'co' | 'km' | 'cg' | 'cd' | 'cr' | 'hr' | 'cu' | 'cy' | 'cz' | 'dk' | 'dj' | 'dm' | 'do' | 'ec' | 'eg' | 'sv' | 'gq' | 'er' | 'ee' | 'sz' | 'et' | 'fk' | 'fo' | 'fj' | 'fi' | 'fr' | 'gf' | 'pf' | 'ga' | 'gm' | 'ge' | 'de' | 'gh' | 'gi' | 'gr' | 'gl' | 'gd' | 'gu' | 'gt' | 'gg' | 'gn' | 'gw' | 'gy' | 'ht' | 'hn' | 'hk' | 'hu' | 'is' | 'in' | 'id' | 'ir' | 'iq' | 'ie' | 'im' | 'il' | 'it' | 'jm' | 'jp' | 'je' | 'jo' | 'kz' | 'ke' | 'ki' | 'kp' | 'kr' | 'kw' | 'kg' | 'la' | 'lv' | 'lb' | 'ls' | 'lr' | 'ly' | 'li' | 'lt' | 'lu' | 'mo' | 'mk' | 'mg' | 'mw' | 'my' | 'mv' | 'ml' | 'mt' | 'mh' | 'mq' | 'mr' | 'mu' | 'yt' | 'mx' | 'fm' | 'md' | 'mc' | 'mn' | 'me' | 'ms' | 'ma' | 'mz' | 'mm' | 'na' | 'nr' | 'np' | 'nl' | 'nc' | 'nz' | 'ni' | 'ne' | 'ng' | 'nu' | 'nf' | 'mp' | 'no' | 'om' | 'pk' | 'pw' | 'ps' | 'pa' | 'pg' | 'py' | 'pe' | 'ph' | 'pl' | 'pt' | 'pr' | 'qa' | 'ro' | 'ru' | 'rw' | 're' | 'bl' | 'sh' | 'kn' | 'lc' | 'mf' | 'pm' | 'vc' | 'ws' | 'sm' | 'st' | 'sa' | 'sn' | 'rs' | 'sc' | 'sl' | 'sg' | 'sx' | 'sk' | 'si' | 'sb' | 'so' | 'za' | 'gs' | 'ss' | 'es' | 'lk' | 'sd' | 'sr' | 'se' | 'ch' | 'sx' | 'sy' | 'tw' | 'tj' | 'tz' | 'th' | 'tg' | 'tk' | 'to' | 'tt' | 'tn' | 'tr' | 'tm' | 'tc' | 'tv' | 'ug' | 'ua' | 'ae' | 'gb' | 'us' | 'uy' | 'uz' | 'vu' | 've' | 'vn' | 'vg' | 'vi' | 'wf' | 'eh' | 'ye' | 'zm' | 'zw' — The ISO 3166 2-character code of the customer's address. **Recommended when processing EMV 3DS transactions.**
    - `shipping` object
      - `address_match` boolean — Set to true if the customer's billing and shipping address are the same to auto populate.
    - `email` string, email — The customer's email address. **Recommended for processing EMV 3DS transactions.**
    - `phone` Phone
      - `country_code` string — The international dialling code of the customer's phone number.
      - `number` string — The customer's phone number.
  - `tds` object
    - `is_active` boolean — Enables the use of EMV 3-D Secure to authenticate the cardholder.
    - `challenge_preference` 'challenge_mandated' | 'challenge_preferred' | 'no_challenge_requested' | 'no_preference' — Indicates your preference to the issuing bank on if the cardholder should be challenged or not.
    - `contact_url` string, uri — Link to the contact us / support page of your website. Required when tds is_active is true.
  - `is_recurring` boolean — Set to true if you want to ensure card details are saved at checkout, allowing for further recurring payments.
  - `recurring` object — Used to define the validity window (term) for a recurring agreement, such as a Variable Recurring Payment (VRP) mandate. Only applies when is_recurring is true.
    - `term` object — The validity window for the recurring agreement.
      - `start_date` string, date — The date the recurring agreement is active from, in YYYY-MM-DD format. Defaults to the date the agreement is created if omitted.
      - `end_date` string, date — The date the recurring agreement is active until, in YYYY-MM-DD format. Must be later than start_date. If omitted, the agreement continues until cancelled.
  - `count_retry` integer — Number of times that a payment can be attempted using the payment link before the link becomes inactive. The default is 3 and the maximum is 10.
  - `expires_in` integer — Time for which the payment link is valid, in seconds. Default is 259200 and the maximum is 2678400.
  - `template_id` string, uuid — Unique ID assigned by Acquired.com which can be updated to change the template displayed to the user when the page is loaded.
  - `redirect_url` string, uri — Where the user should be redirected to once the authorisation process has been completed.
  - `webhook_url` string, uri — Where we should send webhook notifications throughout the authorisation process.
  - `payment_methods` string[] — Used to specify which payment methods should be displayed on the Checkout page. If the 'Enable Custom Payment Method Order' toggle is set to 'On' in the Hosted Checkout settings, the order of payment methods on the Checkout page will match the sequence defined in this array.
  - `submit_type` 'pay' | 'buy' | 'checkout' | 'donate' | 'register' | 'subscribe' — Describes the type of transaction and customises the text displayed to Checkout user, such as the submit button. Enum values accepted only. If blank, `pay` is used.
  - `configuration` object — Used to pass additional configuration options to the Hosted Checkout.
    - `variable_recurring_payment` object — Used to configure Variable Recurring Payments (VRP) on the Hosted Checkout.
      - `type` 'sweeping' — The type of VRP agreement to be created.
      - `periodic_limit` object
        - `per_payment` object — The maximum amount that can be charged in a single payment.
          - `maximum_amount` number — The amount for the per payment limit.
        - `day` object — The limits set over the course of 1 day.
          - `maximum_amount` number — The maximum amount that can be charged within a single day.
          - `alignment` 'calendar' | 'consent' — The alignment for the daily limits.
        - `week` object — The limits set over the course of 1 week.
          - `maximum_amount` number — The maximum amount that can be charged within a single week.
          - `alignment` 'calendar' | 'consent' — The alignment for the weekly limits.
        - `fortnight` object — The limits set over the course of 1 fortnight.
          - `maximum_amount` number — The maximum amount that can be charged within a single fortnight.
        - `month` object — The limits set over the course of 1 month.
          - `maximum_amount` number — The maximum amount that can be charged within a single month.
          - `alignment` 'calendar' | 'consent' — The alignment for the monthly limits.
        - `half_year` object — The limits set over the course of 6 months.
          - `maximum_amount` number — The maximum amount that can be charged within a 6 month period.
          - `alignment` 'calendar' | 'consent' — The alignment for the half-yearly limits.
        - `year` object — The limits set over the course of 1 year.
          - `maximum_amount` number — The maximum amount that can be charged within a single year.
          - `alignment` 'calendar' | 'consent' — The alignment for the yearly limits.

## Response `201`

Created

- object
  - `status` 'success'
  - `link_id` string, uuid — Unique ID assigned by Acquired.com which should be appended to the known base URL and used to load the hosted checkout.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `500` — Internal Server error

---

[API](https://skmtc.dev/acquired/apis/acquired-api.md) · [All operations](https://skmtc.dev/acquired/apis/acquired-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/acquired/acquired-api/revisions/7ae178a046f2/schema)