---
title: "Retrieve Link"
method: GET
path: "/paymentlinks/retrieve"
tags: ["Payment Links"]
---

# Retrieve Link

`GET /paymentlinks/retrieve`

Used to retrieve a single link via the Payment Links system

 **Integration Methods:**
- Host Direct

See the [Integration Methods](/guides/quickstart#integration-methods) and [URLs Section](/guides/quickstart#urls) sections of the Development Quick Start guide for details regarding each processing option.

## Headers

- `InterfaceVersion` string, required
- `InterfaceName` string, required
- `CompanyName` string, required
- `AccessToken` string, uuid, required
- `PaymentLinkId` string, required

## Response `200`

Request was processed

- object
  - `result` object[]
    - `dateTime` string, ISO 8601 — Date-time when the object was created
    - `paymentLink` PaymentLinkResponse
      - `id` string — Identifier of Payment Link
      - `type` 'line_items' | 'card_verification' — The kind of flow the payment link performs. - `line_items` (default) — a standard payment flow. The customer pays for the products defined in `lineItems`. - `card_verification` — performs a $0 authorization to confirm the card is valid (a security check that a real card and cardholder are behind it) **without** charging it. The validated card is also saved to the customer. These links take **no** `lineItems`, but **require** a top-level `currency` and a defined `customer`. When omitted, the link defaults to `line_items`.
      - `status` 'active' | 'expired' | 'deactivated' | 'completed' | 'scheduled' — Status of a Payment link. It can be one of the following: Value | Description ------------|--------------- active | Payment link is active and functional expired | Payment link expired and is no longer functional deactivated | Payment link has been deactivated by merchant completed | preset number of successful transactions made with this payment link has been reached, it is no longer functional scheduled | Payment link is yet to become active In the [/paymentlinks/update](/apis/payments-platform-rest/openapi/payment-links/paymentslinkupdate) request this field can be used to deactivate and reactivate an existing payment link.
      - `lastOpened` string, ISO 8601 — The date the link was last opened. Omitted if the link has not been opened yet.
      - `lineItems` object[] — List of line items
        - `product` object — Definition of a product
          - `name` string — Name of a product
          - `description` string — Description of a product, shown to the customer on the hosted checkout page directly under the product name
          - `currencyCode` string — currency represented as a three-letter ISO currency code
          - `amount` union — Payment amount definition. A fixed-amount link returns `total`; a customer-chosen amount link returns `options`, `custom`, or both. `total` is never present alongside `options` or `custom`.
            - object
              - …
            - object
              - …
      - `currency` string — Currency for the authorization, represented as a three-letter ISO currency code. **Required only for `card_verification` links.** For `line_items` links the currency is taken from the line items and this field may be omitted.
      - `url` string — URL that can be used to process payment defined by this Payment Link
      - `returnUrl` string — Customer will be redirected to this URL after completing payment on `paymentLink.url` page. When not provided the return URL from account setting will be used. Some dynamic parameters will be appended to this URL. Example: `{returnUrl}?status=success&checkout_session_id=chse_xxxxx`
      - `collectBillingAddress` boolean — If the value is true, the customer will be asked to provide the billing address. Default: false
      - `collectShippingAddress` boolean — If the value is true, the customer will be asked to provide the shipping address. Default: false
      - `restrictions` PaymentLinkRestrictions — This object describes time boundaries and preset number of charges made with the Payment link
        - `dates` object
          - `activatesAt` string, ISO 8601 — Activation date of a payment link. By default, payment links are active at the moment of creation. Max: +1 month
          - `expiresAt` string, ISO 8601 — Expiration date of a payment link. By default, payment links do not expire.
        - `payments` object
          - `limit` integer — Maximum number of successful payments allowed to be done using this payment link. Default: 1 Range: 1–999
          - `count` integer — Number of successful payments
      - `notifications` PaymentLinkNotificationsResponse — Payment Links notifications
        - `share` object
          - `email` object — Email notification details
            - `emailAddress` string — Email address
            - `status` 'sent' | 'delivered' | 'failed' — Email delivery status.
      - `staticFields` PaymentLinkStaticFields — List of custom information (for example: hotel reservation details) in key value pair format. A maximum of 10 entries can be provided. The key contains the title of custom information and is a maximum of 55 characters. The value contains the text of custom information and is a maximum of 255 characters. Examples: `"Date of event": "12 April"` `"Invoice number": "ABC2016"`
      - `customFieldsTitle` string — Title of custom fields section
      - `customFields` object[] — Using custom fields, the merchant can request additional information from the customer. Each custom field will be displayed in the form as a new text field to fill out.
        - `key` string, required — Identifier of custom field
        - `label` string, required — Label of custom field
        - `optional` boolean — If this flag is set to `true`, then customer doesn't have to provide any value for this custom field
      - `locale` 'auto' | 'en' | 'bg' | 'cs' | 'da' | 'de' | 'el' | 'es' | 'et' | 'fi' | 'fr' | 'hr' | 'hu' | 'it' | 'lt' | 'lv' | 'nl' | 'no' | 'pl' | 'pt' | 'ro' | 'ru' | 'sk' | 'sl' | 'be' — Language that will be used on payment page. Default: `auto` = use browser language
      - `vendorReference` string — Merchant Defined Descriptor related to the Payment Link. This field is reportable on the merchant portal and settlement extract.
    - `customer` PaymentLinksCustomerResponse
      - `id` string — Identifier of the customer
      - `emailAddress` string — Email
      - `phoneCountry` string — Two-letter ISO 3166-1 alpha-2 country code of the phone number's country (e.g., `US`, `GB`, `DE`). Present when the customer was created with `phoneCountry` set.
      - `phoneNumber` string — Phone number. When `phoneCountry` was provided on creation, the number is returned with the corresponding country calling code prepended.
      - `addressLine1` string — Cardholder’s street address exactly as it appears on their billing statement. This field is used in AVS.
      - `firstName` string — Specifies a consumer’s first name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
      - `middleName` string — Specifies a consumer’s middle name.
      - `lastName` string — Specifies a consumer’s last name. This field is used in AVS. If the interface sends this field, the value specified by the interface will be returned in the response, unless the API Option [USECARDNAME](/guides/appendices/api-options#usecardname) is included in the request and a Commerce Engine or UTG-controlled PIN pad is in use. If the interface does not send the `customer` object, the consumer's name will be returned in the `customer` object if the name is present in the card's EMV or track data.
      - `postalCode` string — Cardholder’s ZIP/postal code from their billing statement. This field is used in AVS. Do not include special characters. **Note: This field only allows alphanumeric characters (a-z, A-Z, 0-9). Special characters including - are not allowed. If you are sending in zip+4 you must not include the dash so 89134-1234 would be sent as 891341234**
      - `addressCity` string — City
      - `addressRegion` string — Region or state
      - `addressCountry` string — Country
    - `metadata` PaymentLinksMetadata — Key-value object for storing additional custom data. This is never displayed to customer on the payment page. Examples: `"order_id": "12345"` `"campaign_code": "SUMMER2025"`

## Other responses

- `400` — Error
- `504` — Timeout

---

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