# Create a payment link, share it by email, track sharing events, and manage its lifecycle.

Create a payment link, share it by email, track sharing events, and manage its lifecycle.

1. Create the payment link on the processing terminal. Primary path: a reusable multiUse link where the customer enters the amount (order.charge.type = prompt). For a one-off link send type = singleUse with an order.orderId and expiresOn, and use charge.type = preset with an amount to fix the price. Save the returned paymentLinkId - every follow-on step needs it - and the assets.paymentUrl to share manually.
 [createPaymentLink](/api/create-payment-link)
2. Email the payment link to the customer. Requires the paymentLinkId from step 1. Send sharingMethod = email plus a recipients array (name and email are required); set merchantCopy = true to also send the merchant a copy. Returns a sharingEventId used to track this send.
 [sharePaymentLink](/api/share-payment-link)
3. List the sharing events for the payment link to confirm and track when and to whom it was sent. Paginated; filter by recipientName or recipientEmail. Keyed by paymentLinkId.
 [listPaymentLinkShareEvents](/api/list-payment-link-share-events)
4. The customer pays through the hosted payment link - the assets.paymentUrl created in step 1, delivered by the email share. This happens outside these API steps, on the Payroc-hosted page. For a singleUse link the link moves to `completed` after the single payment; the optional retrievePaymentLink step is how the merchant checks whether the customer has paid.

5. OPTIONAL — retrieve the current state of the payment link by paymentLinkId - for example to check whether the customer has paid (status = completed). Returns the same polymorphic link object as create.
 [retrievePaymentLink](/api/retrieve-payment-link)
6. OPTIONAL lifecycle update. Partially update the payment link with an RFC 6902 JSON Patch document - the body is an ARRAY of patch operations, not a full resource. This example replaces the expiry date. Note: updating a single-use link regenerates its payment URL, invalidating the original.
 [updatePaymentLink](/api/update-payment-link)
7. OPTIONAL — list the payment links on the processing terminal, for example to find a link when you don't have its paymentLinkId. Paginated; filter by merchantReference, linkType, chargeType, status, recipient, or dates. Keyed by processingTerminalId (not paymentLinkId).
 [listPaymentLinks](/api/list-payment-links)
8. OPTIONAL and TERMINAL — deactivate the payment link so the customer can no longer use it. Takes no idempotency key. Deactivation cannot be reversed - the link can't be reactivated. Returns the link with status = deactivated.
 [deactivatePaymentLink](/api/deactivate-payment-link)

## Workflow diagram

```mermaid
flowchart TD
  step0["1. create link request · API"]
  step1["2. share link request · API"]
  step0 --> step1
  step2["3. sharing events lookup · API"]
  step1 --> step2
  step3["4. hosted link payment · Manual"]
  step2 --> step3
  step4["5. link lookup · API"]
  step3 --> step4
  step5["6. JSON Patch update · API"]
  step4 --> step5
  step6["7. list links request · API"]
  step5 --> step6
  step7["8. deactivate request · API"]
  step6 --> step7
```