> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a Payment Link

> Retrieve a payment link and its current state by Meridian id.



## OpenAPI

````yaml products/realtime-collections/api-reference/payment-links.json GET /v1/payment-links/{id}
openapi: 3.1.0
info:
  title: Realtime Collections API
  description: >-
    Partner API for Meridian Realtime Collections: operator sessions, and
    creating, updating, and retrieving payment links used to collect funds from
    customers.
  version: 1.0.0
servers:
  - url: https://us-merchant.sandbox.api-us.meridianapps.dev
    description: Sandbox
  - url: https://us-merchant.api-us.payments.meridianpay.com
    description: Production
security: []
tags: []
externalDocs:
  url: /
paths:
  /v1/payment-links/{id}:
    get:
      tags:
        - Payment Links
      summary: Retrieve a Payment Link
      description: >-
        Retrieves a payment link by its Meridian id.


        Unlike the create and update endpoints, this endpoint returns the
        payment link object directly rather than wrapping it in a `paymentLink`
        property.
      operationId: listPaymentLinksById
      parameters:
        - $ref: '#/components/parameters/PaymentLinkIdPath'
        - $ref: '#/components/parameters/MeridianApiKeyHeader'
        - $ref: '#/components/parameters/MeridianTimestampHeader'
      responses:
        '200':
          description: Retrieved data
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
              examples:
                PaymentLinkGet:
                  $ref: '#/components/examples/PaymentLinkGet'
        '400':
          description: >-
            Malformed or invalid submission. Also returned when the API key is
            valid but does not belong to a merchant.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '401':
          description: >-
            Missing, unknown, or incorrectly signed API key. The response body
            is empty.
          headers: {}
        '404':
          description: >-
            Payment link not found. Also returned when the payment link belongs
            to another merchant.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
      deprecated: false
      security:
        - MeridianHmacAuth: []
components:
  parameters:
    PaymentLinkIdPath:
      name: id
      in: path
      required: true
      description: Meridian id of the payment link.
      schema:
        type: string
      example: usmer-kiqt7rz1qvwqnryhvbqf463q
    MeridianApiKeyHeader:
      name: X-Meridian-Api-Key
      in: header
      required: true
      description: API key issued by Meridian during provisioning.
      schema:
        type: string
      example: your-api-key
    MeridianTimestampHeader:
      name: X-Meridian-Timestamp
      in: header
      required: true
      description: >-
        Current time in milliseconds since the Unix epoch. Must be within 10
        seconds of the request.
      schema:
        type: string
      example: '1749566400000'
  schemas:
    PaymentLink:
      type: object
      description: A payment link and its current state.
      properties:
        id:
          type: string
          description: Unique id of the payment link.
          title: String
        createdAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp (UTC) when the payment link was created.
          title: Instant
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp (UTC) when the payment link was last updated.
          title: Instant
        linkToken:
          type: string
          description: >-
            Non-guessable, URL-safe token that uniquely identifies the payment
            link and is exposed in payment URLs.
          title: String
        userId:
          type:
            - string
            - 'null'
          description: >-
            Meridian user id of the payer who attempted payment on this link,
            when one has.
          title: String
        status:
          $ref: '#/components/schemas/PaymentLinkStatus'
          description: Current status of the payment link.
        statusReason:
          type:
            - string
            - 'null'
          description: Optional detail about the current status of the payment link.
          title: String
        initialAccessBy:
          type: string
          format: date-time
          description: >-
            ISO-8601 timestamp (UTC) by which the payment link must first be
            accessed. If it is not accessed by this time it expires and becomes
            invalid. The expiry window is set in the merchant configuration.
          title: Instant
        merchantId:
          type: string
          description: Unique identifier of the merchant that owns the payment link.
          title: String
        recurrenceType:
          $ref: '#/components/schemas/PaymentLinkRecurrenceType'
          description: How the payment link handles recurrence.
        referenceId:
          type:
            - string
            - 'null'
          description: >-
            Unique reference defined by the merchant to identify the payment
            link. Not shown to customers on single payment links.
          title: String
        referenceLabel:
          type: string
          description: Human-readable label for the payment link.
          title: String
        description:
          type:
            - string
            - 'null'
          description: Optional human-readable description for the payment link.
          title: String
        creditAmount:
          type:
            - string
            - 'null'
          description: >-
            Amount collected per charge, returned as a decimal string such as
            `"100.50"`. Null for `VARIABLE` links whose amount has not been set
            yet.
          title: BigDecimal
        creditCurrency:
          $ref: '#/components/schemas/MeridianCurrency'
          description: ISO-4217 currency code the merchant is paid out in.
        debitCurrency:
          $ref: '#/components/schemas/MeridianCurrency'
          description: ISO-4217 currency code debited from the payer.
        nextPaymentDate:
          type:
            - string
            - 'null'
          format: date
          description: Pre-calculated date of the next scheduled payment.
          title: LocalDate
        lastPaymentDate:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Date the most recent payment attempt was initiated for the payment
            link.
          title: LocalDate
        paymentAttempts:
          type: integer
          description: Number of payment attempts initiated for the payment link.
          title: Int
        startDate:
          type:
            - string
            - 'null'
          format: date
          description: >-
            Start date from which the payment link can be paid. Payments are not
            allowed before this date.
          title: LocalDate
        endDate:
          type:
            - string
            - 'null'
          format: date
          description: End date after which the payment link can no longer be paid.
          title: LocalDate
        collectionCount:
          type:
            - integer
            - 'null'
          description: Number of installments the payer will be charged.
          title: Int
        customFields:
          type:
            - object
            - 'null'
          description: Key-value map of custom fields defined by the merchant.
          additionalProperties:
            type: string
            description: Value of the custom field, as a string.
          title: Map_String_String
        autopays:
          type: array
          description: >-
            Auto pays set up by the payer to automatically collect payments on
            recurring links. Empty when none are configured.
          items:
            $ref: '#/components/schemas/Autopay'
          title: Array_Autopay
      required:
        - id
        - createdAt
        - updatedAt
        - linkToken
        - status
        - initialAccessBy
        - merchantId
        - recurrenceType
        - referenceLabel
        - creditCurrency
        - debitCurrency
        - paymentAttempts
      title: PaymentLink
    MeridianError:
      type: object
      description: >-
        Standard error response returned when a request cannot be completed.
        Includes a human-readable message and, for validation failures, a list
        of field-level errors.
      properties:
        validationErrors:
          type: array
          description: >-
            List of field-level validation errors, empty when the failure is not
            validation-related.
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Array_ValidationError
        message:
          type: string
          description: Human-readable description of the error.
          title: String
        errorCode:
          type: string
          description: >-
            Machine-readable error code identifying the failure. Omitted when no
            specific code applies.
          title: String
      required:
        - validationErrors
        - message
      title: MeridianError
    PaymentLinkStatus:
      type: string
      description: >-
        Status of a payment link.


        - `ACTIVE`: available for payment.

        - `PROCESSING`: a payment attempt is being processed; new attempts are
        temporarily blocked.

        - `FAILED`: the payment attempt failed.

        - `INACTIVE`: manually deactivated and no longer valid for payments.

        - `EXPIRED`: expired and no longer valid for payments.

        - `LOCKED`: temporarily locked and cannot be paid until its status
        changes.

        - `ARCHIVED`: archived and no longer valid for payments.

        - `COMPLETED`: successfully paid.
      enum:
        - ACTIVE
        - PROCESSING
        - FAILED
        - INACTIVE
        - EXPIRED
        - LOCKED
        - ARCHIVED
        - COMPLETED
      title: PaymentLinkStatus
    PaymentLinkRecurrenceType:
      type: string
      description: >-
        How a payment link handles recurrence.


        - `SINGLE`: can be paid only once; the link becomes invalid after a
        successful payment.

        - `VARIABLE`: recurring payments whose amount and next collection date
        can vary between charges. The amount may be left blank at creation and
        set later, together with the next collection date, via the update
        endpoint.

        - `RECURRING`: recurring payments allowing multiple charges over time
        according to the recurrence configuration.
      enum:
        - SINGLE
        - RECURRING
        - VARIABLE
      title: PaymentLinkRecurrenceType
    MeridianCurrency:
      type: string
      description: >-
        ISO-4217 currency code, or a stablecoin asset identifier. Which values
        are accepted depends on the merchant configuration.
      enum:
        - EUR
        - USD
        - GBP
        - PHP
        - MXN
        - ZAR
        - USDC_ETH
        - USDC_SOL
        - USDT_ETH
        - USDT_SOL
      title: MeridianCurrency
    Autopay:
      type: object
      description: >-
        An auto pay configured to automatically collect payments for a recurring
        payment link.
      properties:
        id:
          type: string
          description: Unique id of the auto pay.
          title: String
        createdAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp (UTC) when the auto pay was created.
          title: Instant
        updatedAt:
          type: string
          format: date-time
          description: ISO-8601 timestamp (UTC) when the auto pay was last updated.
          title: Instant
        status:
          $ref: '#/components/schemas/AutopayStatus'
          description: Current status of the auto pay.
        statusReason:
          type:
            - string
            - 'null'
          description: Optional detail about the current status of the auto pay.
          title: String
        scheduleDay:
          type:
            - integer
            - 'null'
          description: >-
            Day of the month on which the payment is scheduled to occur, as
            configured by the payer. Set for recurring payment links.
          title: Int
      required:
        - id
        - createdAt
        - updatedAt
        - status
      title: Autopay
    ValidationError:
      description: >-
        A single validation error describing why a specific field or parameter
        was rejected. The `type` property identifies which variant it is.
      oneOf:
        - $ref: '#/components/schemas/InvalidFormat'
        - $ref: '#/components/schemas/InvalidValue'
        - $ref: '#/components/schemas/MissingPathParameter'
        - $ref: '#/components/schemas/MissingQueryParameter'
        - $ref: '#/components/schemas/MissingRequestBody'
        - $ref: '#/components/schemas/MissingValue'
        - $ref: '#/components/schemas/NotFound'
        - $ref: '#/components/schemas/UnexpectedVerificationError'
        - $ref: '#/components/schemas/UnprocessableValue'
        - $ref: '#/components/schemas/Unknown'
      discriminator:
        propertyName: type
        mapping:
          InvalidFormat:
            $ref: '#/components/schemas/InvalidFormat'
          InvalidValue:
            $ref: '#/components/schemas/InvalidValue'
          MissingPathParameter:
            $ref: '#/components/schemas/MissingPathParameter'
          MissingQueryParameter:
            $ref: '#/components/schemas/MissingQueryParameter'
          MissingRequestBody:
            $ref: '#/components/schemas/MissingRequestBody'
          MissingValue:
            $ref: '#/components/schemas/MissingValue'
          NotFound:
            $ref: '#/components/schemas/NotFound'
          UnexpectedVerificationError:
            $ref: '#/components/schemas/UnexpectedVerificationError'
          UnprocessableValue:
            $ref: '#/components/schemas/UnprocessableValue'
          Unknown:
            $ref: '#/components/schemas/Unknown'
      title: ValidationError
    AutopayStatus:
      type: string
      description: |-
        Status of an auto pay.

        - `ACTIVE`: active and available to collect payment on the schedule day.
        - `INACTIVE`: inactive and no longer valid to collect payment.
        - `EXPIRED`: expired and no longer valid to collect payment.
      enum:
        - ACTIVE
        - INACTIVE
        - EXPIRED
      title: AutopayStatus
    InvalidFormat:
      type: object
      description: A field was supplied in a format the API could not interpret.
      properties:
        type:
          type: string
          enum:
            - InvalidFormat
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: InvalidFormat
    InvalidValue:
      type: object
      description: A field was well-formed but its value is not allowed.
      properties:
        type:
          type: string
          enum:
            - InvalidValue
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Reference to the request field that caused the validation error.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: InvalidValue
    MissingPathParameter:
      type: object
      description: A required path parameter was missing from the request URL.
      properties:
        type:
          type: string
          enum:
            - MissingPathParameter
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Name of the path parameter that was missing.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the parameter failed validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: MissingPathParameter
    MissingQueryParameter:
      type: object
      description: A required query parameter was missing from the request URL.
      properties:
        type:
          type: string
          enum:
            - MissingQueryParameter
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Name of the query parameter that was missing.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the parameter failed validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: MissingQueryParameter
    MissingRequestBody:
      type: object
      description: The request body was absent, or was missing fields that may not be null.
      properties:
        type:
          type: string
          enum:
            - MissingRequestBody
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Always `requestBody` for this error type.
          title: String
        message:
          type: string
          description: >-
            Human-readable explanation of why the request body failed
            validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: MissingRequestBody
    MissingValue:
      type: object
      description: A required field was missing from the request body.
      properties:
        type:
          type: string
          enum:
            - MissingValue
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Reference to the request field that was missing.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field failed validation.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: MissingValue
    NotFound:
      type: object
      description: A referenced resource could not be found.
      properties:
        type:
          type: string
          enum:
            - NotFound
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: >-
            Reference to the request field naming the resource that was not
            found.
          title: String
        message:
          type: string
          description: Human-readable explanation of what could not be found.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: NotFound
    UnexpectedVerificationError:
      type: object
      description: An unexpected error occurred while verifying the value of a field.
      properties:
        type:
          type: string
          enum:
            - UnexpectedVerificationError
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Reference to the request field that could not be verified.
          title: String
        message:
          type: string
          description: Human-readable explanation of the verification failure.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: UnexpectedVerificationError
    UnprocessableValue:
      type: object
      description: >-
        A field was valid in isolation but cannot be processed in the context of
        this request.
      properties:
        type:
          type: string
          enum:
            - UnprocessableValue
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Reference to the request field that could not be processed.
          title: String
        message:
          type: string
          description: Human-readable explanation of why the field could not be processed.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: UnprocessableValue
    Unknown:
      type: object
      description: >-
        The request was rejected but the specific field at fault could not be
        determined.
      properties:
        type:
          type: string
          enum:
            - Unknown
          description: Validation error type discriminator.
        fieldRef:
          type: string
          description: Always `unknown` for this error type.
          title: String
        message:
          type: string
          description: Human-readable explanation of the failure.
          title: String
      required:
        - type
        - fieldRef
        - message
      title: Unknown
  examples:
    PaymentLinkGet:
      summary: Payment link retrieved by id
      value:
        id: usmer-kiqt7rz1qvwqnryhvbqf463q
        createdAt: '2026-07-02T20:31:25.000Z'
        updatedAt: '2026-07-02T20:31:25.000Z'
        linkToken: de4261dd-548a-4cbc-9f48-9d13924e3d7d
        userId: null
        status: ACTIVE
        statusReason: null
        initialAccessBy: '2026-07-03T20:31:20.000Z'
        merchantId: usmer-rtn86be1xb9jzb5qwib6z0i9
        recurrenceType: SINGLE
        referenceId: REF-ONEOFF-2
        referenceLabel: One-off USD
        description: null
        creditAmount: '100.50'
        creditCurrency: USD
        debitCurrency: USD
        nextPaymentDate: null
        lastPaymentDate: null
        paymentAttempts: 0
        startDate: null
        endDate: '2027-01-31'
        collectionCount: null
        customFields:
          name: John Doe
          email: john@example.com
        autopays: []
  securitySchemes:
    MeridianHmacAuth:
      type: apiKey
      in: header
      name: X-Meridian-Signature
      description: >-
        Meridian HMAC header authentication.


        Required headers:
          - X-Meridian-Api-Key
          - X-Meridian-Timestamp
          - X-Meridian-Signature

        X-Meridian-Signature is the HMAC SHA-256 signature of the canonical
        request string, computed per request as HMAC-SHA256(apiKey + timestamp +
        method + request URI including any query string + body). See
        [Authentication](/products/realtime-collections/authentication) for how
        to construct it.

````