List Payment Links

Overview

Retrieve a list of previously created Payment Links. Use this endpoint to view all payment links associated with your account, with optional filtering by state, merchant, and other criteria.

Resource Access

• User Permissions: All users can access this endpoint
• Endpoint: GET /payment_links

Arguments

Parameter	Type	Required	Description
limit	integer	No	The maximum number of results to return (default: 5)
state	string	No	Filter by link state (ACTIVE, DEACTIVATED, COMPLETED, EXPIRED)
merchant_id	string	No	Filter by Merchant ID
after_cursor	string	No	Return every resource created after the cursor value for pagination

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/payment_links?limit=20&state=ACTIVE' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "payment_links": [
      {
        "id": "PLpaymentLinkExample456",
        "created_at": "2023-06-15T10:30:00Z",
        "updated_at": "2023-06-15T10:30:00Z",
        "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",
        "payment_frequency": "ONE_TIME",
        "is_multiple_use": false,
        "state": "ACTIVE",
        "allowed_payment_methods": ["PAYMENT_CARD", "BANK_ACCOUNT"],
        "amount_details": {
          "amount_type": "FIXED",
          "total_amount": 50000,
          "currency": "USD",
          "amount_breakdown": {
            "subtotal_amount": 45000,
            "shipping_amount": 3000,
            "estimated_tax_amount": 2000
          }
        },
        "items": [
          {
            "name": "Premium Widget",
            "quantity": 2,
            "price_details": {
              "sale_amount": 22500,
              "currency": "USD"
            }
          }
        ],
        "tags": {
          "invoice_number": "12345"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456"
          }
        }
      },
      {
        "id": "PLdonationPage789",
        "created_at": "2023-06-10T14:20:00Z",
        "updated_at": "2023-06-10T14:20:00Z",
        "link_url": "https://forms.finix.com/payment-links/PLdonationPage789",
        "link_expires_at": "2023-12-10T14:20:00Z",
        "merchant_id": "MUmerchantExample123",
        "application_id": "APapplicationExample123",
        "nickname": "General Donations",
        "payment_frequency": "ONE_TIME",
        "is_multiple_use": true,
        "state": "ACTIVE",
        "allowed_payment_methods": ["PAYMENT_CARD"],
        "amount_details": {
          "amount_type": "FIXED",
          "total_amount": 10000,
          "currency": "USD"
        },
        "tags": {
          "campaign": "annual_fund"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/payment_links/PLdonationPage789"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 2
  }
}

Additional Information

• Link States:
  • ACTIVE: Link is live and accepting payments
  • DEACTIVATED: Link has been manually deactivated
  • COMPLETED: Single-use link has been paid (is_multiple_use = false)
  • EXPIRED: Link has passed its expiration date
• Filtering by State: Use the state parameter to find links in a specific state:
  • state=ACTIVE: Find all active payment links
  • state=COMPLETED: Find all paid single-use links
  • state=EXPIRED: Find all expired links
• Filtering by Merchant: Use merchant_id to retrieve links for a specific merchant
• Pagination: Use the after_cursor parameter to paginate through large result sets
• Payment Frequency:
  • ONE_TIME: Link for a single payment
  • RECURRING: Link for recurring subscription payments
• Multiple Use Links: When is_multiple_use is true, the link remains ACTIVE after payment and can be used multiple times
• Amount Details:
  • amount_type: FIXED (exact amount) or MIN_MAX (range)
  • total_amount: Total in cents
  • amount_breakdown: Optional itemization of subtotal, tax, shipping, etc.
• Items: Line items displayed on the payment page
• Link Expiration: Links expire 6 months after creation by default
• Use Cases:
  • Invoicing: Create unique links for each invoice
  • Donations: Use multiple-use links for donation pages
  • E-commerce: Share payment links via email or SMS
  • Service payments: Send links to customers for service fees
• Monitoring: Regularly review EXPIRED and COMPLETED links to track payment status