> ## 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. # Update a Payment Link > Apply partial changes to an existing payment link, including its amount, schedule, and status. ## OpenAPI ````yaml products/realtime-collections/api-reference/payment-links.json PATCH /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}: patch: tags: - Payment Links summary: Update a Payment Link description: >- Applies partial changes to an existing payment link. Only the fields present in the request body are changed. A body that cannot be deserialized, or that omits `reason`, returns `400` regardless of whether the id exists. Field-constraint violations are checked after the payment link is loaded, so those return `404` when the id is unknown. Unlike create, dates supplied here are not normalized to the next banking day. operationId: updatePaymentLinksById parameters: - $ref: '#/components/parameters/PaymentLinkIdPath' - $ref: '#/components/parameters/MeridianApiKeyHeader' - $ref: '#/components/parameters/MeridianTimestampHeader' requestBody: description: >- Request body to partially update a payment link. Only provided fields are changed. content: application/json: schema: $ref: '#/components/schemas/UpdatePaymentLinkRequest' examples: PaymentLinkUpdateRequestExample: $ref: '#/components/examples/PaymentLinkUpdateRequestExample' required: true responses: '200': description: Payment link updated successfully headers: {} content: application/json: schema: $ref: '#/components/schemas/PaymentLinkResponse' examples: PaymentLinkUpdated: $ref: '#/components/examples/PaymentLinkUpdated' '400': description: >- Malformed or invalid submission, including a body that cannot be deserialized or is missing `reason`. 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. Also returned when the new `referenceId` collides with another payment link for the same merchant and status. 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: UpdatePaymentLinkRequest: type: object description: >- Request body to partially update a payment link. Only provided fields are changed. properties: reason: type: string description: >- Reason the payment link is being updated, recorded on the audit trail (non-blank, max 255 characters). maxLength: 255 title: String status: description: New status of the payment link, if provided. anyOf: - $ref: '#/components/schemas/PaymentLinkStatus' - type: 'null' creditAmount: type: - string - 'null' description: >- New amount collected per charge, if provided, sent as a decimal string such as `"300.00"`. Must be greater than zero. A JSON number is also accepted on input. On a `VARIABLE` link, supplying this field also triggers the next-collection-date lead check described under `nextCollectionDate`, even when you do not send that field. title: BigDecimal example: '300.00' referenceLabel: type: - string - 'null' description: >- New human-readable label for the payment link, if provided (non-blank, max 64 characters). maxLength: 64 title: String description: type: - string - 'null' description: >- New description for the payment link, if provided (max 255 characters). maxLength: 255 title: String referenceId: type: - string - 'null' description: >- New merchant reference for the payment link, if provided (non-blank, max 255 characters). Must stay unique across the merchant's payment links with the same status; a collision currently surfaces as a `500` rather than a `409`. maxLength: 255 title: String startDate: type: - string - 'null' format: date description: New start date, if provided. Must be today or later. title: LocalDate endDate: type: - string - 'null' format: date description: >- New end date, if provided. Must be after today and after the effective start date, which is the stored `startDate` when you do not send a new one. title: LocalDate collectionCount: type: - integer - 'null' description: >- New number of installments to collect, if provided, between 1 and 500. minimum: 1 maximum: 500 title: Int nextCollectionDate: type: - string - 'null' format: date description: >- Overrides the date of the next scheduled collection. Accepted only for `VARIABLE` payment links. When either this field or `creditAmount` is supplied, the effective next collection date, which falls back to the link's stored next payment date, must be at least 3 days in the future, and must not precede the effective start date. title: LocalDate customFields: type: - object - 'null' description: >- Replacement key-value map of custom fields, if provided. The supplied map replaces the stored one rather than being merged into it. additionalProperties: type: string description: Value of the custom field, as a string. title: Map_String_String required: - reason title: UpdatePaymentLinkRequest PaymentLinkResponse: type: object description: Wrapper returned by the create and update payment link endpoints. properties: paymentLink: $ref: '#/components/schemas/PaymentLink' description: The created or updated payment link. required: - paymentLink title: PaymentLinkResponse 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 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 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 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 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 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 examples: PaymentLinkUpdateRequestExample: summary: Adjust the collection amount value: reason: Adjust collection amount creditAmount: '300.00' PaymentLinkUpdated: summary: Payment link after the amount was adjusted value: paymentLink: id: usmer-fh6vd59kdi6q4komfkygdhuf createdAt: '2026-07-02T20:32:35.000Z' updatedAt: '2026-07-02T20:32:58.000Z' linkToken: e7a94c74-a72a-463e-a1f0-d882fdfad746 userId: null status: ACTIVE statusReason: null initialAccessBy: '2026-07-03T20:32:34.000Z' merchantId: usmer-rtn86be1xb9jzb5qwib6z0i9 recurrenceType: VARIABLE referenceId: REF-VAR-1 referenceLabel: Variable Test description: null creditAmount: '300.00' creditCurrency: USD debitCurrency: USD nextPaymentDate: null lastPaymentDate: null paymentAttempts: 0 startDate: null endDate: null collectionCount: null customFields: {} 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. ````