Update a Payment Link

Overview

Update metadata (nickname, tags), state, allowed payment methods, or buyer details for a Payment Link. This endpoint allows you to modify payment link settings and control its availability.

Resource Access

• User Permissions: All users can access this endpoint
• Endpoint: PUT /payment_links/\{payment_link_id}

Arguments

Parameter	Type	Required	Description
payment_link_id	string	Yes	The unique ID of the Payment Link to update
nickname	string	No	Update the internal name for the payment link
state	string	No	Toggle link availability (ACTIVE, DEACTIVATED)
allowed_payment_methods	array	No	Update accepted payment methods (PAYMENT_CARD, BANK_ACCOUNT)
buyer_details	object	No	Pre-populate buyer details for a single-use link
tags	object	No	Update custom metadata

Example Request (Deactivate Link)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "DEACTIVATED"
  }'

Example Request (Update Nickname and Tags)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "nickname": "Invoice #12345 - PAID",
    "tags": {
      "invoice_number": "12345",
      "customer_id": "CUST-789",
      "status": "paid",
      "payment_date": "2023-06-20"
    }
  }'

Example Request (Update Payment Methods)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "allowed_payment_methods": ["PAYMENT_CARD"]
  }'

Example Request (Pre-populate Buyer Details)

curl -X PUT \
  'https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "buyer_details": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "555-123-4567",
      "billing_address": {
        "line1": "123 Main Street",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94105",
        "country": "USA"
      }
    }
  }'

Example Response

{
  "id": "PLpaymentLinkExample456",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-20T14:45:30Z",
  "link_url": "https://forms.finix.com/payment-links/PLpaymentLinkExample456",
  "link_expires_at": "2023-12-15T10:30:00Z",
  "merchant_id": "MUmerchantExample123",
  "application_id": "APapplicationExample123",
  "nickname": "Invoice #12345 - PAID",
  "payment_frequency": "ONE_TIME",
  "is_multiple_use": false,
  "state": "COMPLETED",
  "allowed_payment_methods": ["PAYMENT_CARD"],
  "amount_details": {
    "amount_type": "FIXED",
    "total_amount": 50000,
    "currency": "USD"
  },
  "tags": {
    "invoice_number": "12345",
    "customer_id": "CUST-789",
    "status": "paid",
    "payment_date": "2023-06-20"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456"
    }
  }
}

Additional Information

• State Management:
  • ACTIVE: Link is live and can accept payments
  • DEACTIVATED: Link is manually disabled and cannot accept payments
  • Note: You cannot manually set state to COMPLETED or EXPIRED (these are system-managed)
• Deactivating Links: Set state to DEACTIVATED to:
  • Prevent further payments on the link
  • Disable access to the payment page
  • Keep the link record for historical tracking
• Reactivating Links: Set state back to ACTIVE to re-enable a deactivated link
• Nickname Updates: Update the nickname for better organization and tracking:
  • Add payment status (e.g., "Invoice #123 - PAID")
  • Include customer information
  • Track internal references
• Payment Methods:
  • Restrict to ["PAYMENT_CARD"] for card-only payments
  • Restrict to ["BANK_ACCOUNT"] for ACH-only payments
  • Allow both with ["PAYMENT_CARD", "BANK_ACCOUNT"]
• Buyer Details Pre-population:
  • Only available for single-use links (is_multiple_use = false)
  • Pre-fills customer information on the payment page
  • Reduces friction for known customers
  • Fields can still be edited by the customer during payment
• Tags: Use tags for:
  • Tracking invoice numbers and customer IDs
  • Recording payment status and dates
  • Organizing links by campaign or category
  • Adding custom metadata for reporting
• Immutable Fields: You cannot update:
  • Amount details (total_amount, amount_type, amount_breakdown)
  • Items and line items
  • Payment frequency
  • Multiple use flag
  • Merchant or Application IDs
  • Link expiration date
  • Create a new Payment Link if these need to be changed
• State Transitions:
  • ACTIVE ↔ DEACTIVATED: Manual control
  • ACTIVE → COMPLETED: Automatic when single-use link is paid
  • ACTIVE → EXPIRED: Automatic when link expires
  • COMPLETED and EXPIRED states are permanent
• Use Cases:
  • Disable a link that was sent in error
  • Update tracking information after payment
  • Change payment methods accepted
  • Pre-fill customer information for personalized links