---
title: "Retrieve a payment link"
method: GET
path: "/api/v1/payment-links/{id}"
tags: ["Payment Links"]
---

# Retrieve a payment link

`GET /api/v1/payment-links/{id}`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/payment-links/{id}`
- Auth: API key in header `x-api-key`

Retrieve a payment link. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

## Path parameters

- `id` string, required

## Response `200`

Successful response

- PaymentLink
  - `id` string, required
  - `object` 'payment_link', required
  - `url` string, uri, required
  - `active` boolean, required
  - `lineItems` object[], required
    - `priceId` string, required
    - `quantity` integer, required
  - `couponId` string, nullable
  - `allowPromotionCodes` boolean
  - `paymentMethodTypes` string[], nullable: Per-link override; null uses the merchant default.
  - `collectCustomerEmail` true, required
  - `shippingAddressCollection` object, nullable: Ask the payer for a shipping address on the link page. Null turns it off.
    - `allowedCountries` string[], required: ISO 3166-1 alpha-2 codes the payer may ship to.
  - `shippingOptions` object[]: Shipping rates the payer picks from on the link page, the first preselected. Needs shippingAddressCollection; one-time links only. An empty list removes them.
    - `shippingRate` string, required: An active shipping rate in the link's currency.
  - `restrictions` object, nullable: Sales limit: the checkout that reaches `limit` turns the link off, and the page shows `inactiveMessage`. Payers checking out at the same moment can go slightly over. Raising the limit does not turn the link back on. Null removes the limit.
    - `completedSessions` object, required
      - `limit` integer, required
      - `count` integer, required: Completed checkouts so far; late payments are not counted.
  - `inactiveMessage` string, nullable: Shown on the link page once the link is off or sold out; null shows the default text.
  - `customFields` CustomField[]: Asked on the link page; `value` is always null here.
    - `key` string, required
    - `label` object, required
      - `type` 'custom', required
      - `custom` string, required
    - `type` 'dropdown' | 'text', required
    - `optional` boolean, required
    - `dropdown` object, nullable, required
      - `options` object[], required
        - `label` string, required
        - `value` string, required
      - `defaultValue` string, nullable, required
      - `value` string, nullable, required
    - `text` object, nullable, required
      - `minimumLength` integer, nullable, required
      - `maximumLength` integer, nullable, required
      - `defaultValue` string, nullable, required
      - `value` string, nullable, required
  - `submitType` 'auto' | 'pay' | 'book' | 'donate': The payment page's button label: `auto` keeps the default, the others say Pay, Book or Donate.
  - `afterCompletion` object
    - `redirectUrl` string, uri, nullable
    - `customMessage` string, nullable: Shown on the confirmation page after payment; null shows the default text. Not shown when `redirectUrl` is set.
  - `phoneNumberCollection` object: The link page asks for a phone number (6 to 20 digits, optional +); the session's `customerDetails.phone`.
    - `enabled` boolean, required
  - `nameCollection` object: The link page asks for a full name and/or a business name (optional next to the full name); the session's `customerDetails`.
    - `individual` object
      - `enabled` boolean, required
    - `business` object
      - `enabled` boolean, required
  - `consentCollection` object
    - `promotions` 'auto' | 'none': `auto`: an optional marketing checkbox; the session's `consent.promotions`.
    - `termsOfService` 'required' | 'none': `required`: a checkbox the payer must tick, linking the terms of service in Checkout → Store policies (400 when none is set).
  - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)