Create a Payment Link

Overview

Create a new Payment Link resource and a unique URL for a buyer to submit a payment. Payment Links provide a simple, hosted payment page that you can share with customers via email, SMS, or embedded on your website.

Resource Access

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

Arguments

Parameter	Type	Required	Description
merchant_id	string	Yes	The ID of the Merchant who will receive the payment
application_id	string	Yes	The Application ID
payment_frequency	string	Yes	How often payment occurs (ONE_TIME, RECURRING)
nickname	string	Yes	Internal name for the payment link
allowed_payment_methods	array	Yes	Payment methods accepted (PAYMENT_CARD, BANK_ACCOUNT)
amount_details	object	Yes	Amount configuration (type, total, breakdown)
amount_details.amount_type	string	Yes	FIXED or MIN_MAX
amount_details.total_amount	integer	Yes	Total amount in cents
amount_details.currency	string	Yes	Currency code (e.g., USD)
amount_details.amount_breakdown	object	No	Itemized breakdown (subtotal, shipping, tax, etc.)
is_multiple_use	boolean	No	If true, link can be used multiple times (default: false)
items	array	No	Items included in the payment
additional_details	object	No	Collection and redirection settings
additional_details.collect_name	boolean	No	Collect customer name
additional_details.collect_email	boolean	No	Collect customer email
additional_details.collect_billing_address	boolean	No	Collect billing address
additional_details.success_return_url	string	No	URL to redirect after successful payment
additional_details.send_receipt	boolean	No	Send receipt to customer
branding	object	No	Customize the payment page appearance
split_transfers	array	No	Split payment among multiple merchants
tags	object	No	Custom metadata

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/payment_links' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant_id": "MUmerchantExample123",
    "application_id": "APapplicationExample123",
    "payment_frequency": "ONE_TIME",
    "nickname": "Invoice #12345",
    "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,
        "description": "High-quality widget with lifetime warranty",
        "price_details": {
          "sale_amount": 22500,
          "currency": "USD"
        },
        "image_details": {
          "primary_image_url": "https://example.com/images/widget.jpg"
        }
      }
    ],
    "additional_details": {
      "collect_name": true,
      "collect_email": true,
      "collect_billing_address": true,
      "success_return_url": "https://yourstore.com/thank-you",
      "send_receipt": true,
      "receipt_requested_delivery_methods": [
        {
          "type": "EMAIL",
          "destinations": ["customer@example.com"]
        }
      ]
    },
    "branding": {
      "brand_color": "#111823",
      "accent_color": "#f3eeee",
      "logo": "https://yourstore.com/logo.png",
      "logo_alternative_text": "Your Store Logo",
      "button_font_color": "#ffffff"
    },
    "tags": {
      "invoice_number": "12345",
      "customer_id": "CUST-789"
    }
  }'

Example Response

{
  "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,
      "description": "High-quality widget with lifetime warranty",
      "price_details": {
        "sale_amount": 22500,
        "currency": "USD"
      },
      "image_details": {
        "primary_image_url": "https://example.com/images/widget.jpg"
      }
    }
  ],
  "additional_details": {
    "collect_name": true,
    "collect_email": true,
    "collect_billing_address": true,
    "success_return_url": "https://yourstore.com/thank-you",
    "send_receipt": true,
    "receipt_requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": ["customer@example.com"]
      }
    ]
  },
  "branding": {
    "brand_color": "#111823",
    "accent_color": "#f3eeee",
    "logo": "https://yourstore.com/logo.png",
    "logo_alternative_text": "Your Store Logo",
    "button_font_color": "#ffffff"
  },
  "tags": {
    "invoice_number": "12345",
    "customer_id": "CUST-789"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/payment_links/PLpaymentLinkExample456"
    }
  }
}

Additional Information

Link States:
- ACTIVE: Link is live and can accept 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
Payment Frequency:
- ONE_TIME: Link is for a single payment
- RECURRING: Link is for recurring subscription payments (future feature)
Multiple Use: Set is_multiple_use to true if you want the link to remain active after the first payment (useful for donation pages, generic payment pages)
Amount Types:
- FIXED: Exact amount must be paid
- MIN_MAX: Customer can choose amount within a range (future feature)
Amount Breakdown: Optionally itemize the total into:
- subtotal_amount: Base amount before additions
- shipping_amount: Shipping/delivery fees
- estimated_tax_amount: Sales tax
- discount_amount: Discount applied
- tip_amount: Gratuity
- additional_buyer_charges: Convenience fees, surcharges, etc.
Items: Display line items on the payment page with images and descriptions for better customer experience
Data Collection: Choose which customer information to collect:
- Name and email for receipts and customer records
- Billing address for AVS verification
Branding: Customize the payment page to match your brand with colors, logo, and button styling
Split Transfers: Automatically split payments among multiple merchants (useful for marketplace platforms)
Receipt Delivery: Automatically send receipts via email or SMS after successful payment
Link Expiration: Links expire after 6 months by default. Deactivate manually if needed sooner
Webhook Events: Subscribe to payment_link.completed webhook to be notified when payment is received

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​