Payment Link API

Overview

A payment link API creates and manages shareable URLs that direct payers to a hosted payment page for a defined amount or payment request. Possession of the link may reveal payment context or permit payment, so links should not contain secrets or unnecessary personal data. Link creation also does not mean payment has occurred. Expired, reused, altered, or forwarded links can create customer confusion. The Payment Link API contract should define identifiers, validation, authorization, status semantics, errors, limits, and version behavior at the same boundary. Changes to Payment Link API should be checked against older clients, stored payloads, enum growth, default behavior, and retry assumptions.

Clients should use unique order references, validate amounts, protect creation credentials, and store both link and provider identifiers. The API accepts commercial details such as amount, pricing currency, description, order reference, expiration, callback destination, and available methods, then returns a URL the merchant can distribute through email, messaging, invoices, or another channel. Final order updates should rely on authenticated callbacks or authoritative API status rather than link visits. For Payment Link API, the application should preserve a correlation path from request construction through response, asynchronous completion, and final business state.

Observability for Payment Link API should record operation, version, principal, request ID, latency, retry count, error code, and final state without exposing secrets.

Testing Payment Link API should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

The Payment Link API owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.