Create Payment Link

Create shareable payment links with custom amounts, expiry, quantity limits, and customer details.

Create Payment Link

Version: 3.0.0

Generate an API Key for the Payment Link channel before making requests.

Payment links let you create shareable URLs that customers can use to make one-time payments. Configure the amount, expiry, quantity limits, and customer details to tailor each link to your use case — whether it's for donations, product sales, or service payments.

Payment links are one-time use by default. Each link generates a unique URL you can share via email, SMS, chat, or embed in your website.

Endpoint

Method	URL
POST	`https://api.payorc.com/payment-links/v1/add`

Please use the test credentials for sandbox testing.

Authentication

Header	Type	Description
`merchant-key`	String	Your merchant key
`merchant-secret`	String	Your merchant secret

Request Body

Field	Type	Required	Description
`amount`	Object	Yes	Amount details
`amount.currency`	String	Yes	ISO 4217 currency code (3 characters, e.g., `USD`, `AED`)
`amount.value`	Number	Yes	Payment amount (1 – 99999999)
`description`	String	Yes	Description shown to the customer (max 100 characters)
`error_msg`	String	Yes	Custom error message shown on validation failure (max 100 characters). Send an empty string if not needed
`no_quantity_per_transaction`	Number	Yes	Maximum quantity per transaction (1 – 9999999)
`shipping_fee`	Number	Yes	Shipping fee (0 – 99999). Send an empty string for none
`convenience_fee`	Number	Yes	Convenience fee (0 – 99999). Send an empty string for none
`no_of_transactions_per_user`	Object	Yes	Transaction limits per user
`no_of_transactions_per_user.no_limit`	String	Yes	`yes` for unlimited transactions per user, `no` to enforce a limit
`no_of_transactions_per_user.quantity`	Number	Conditional	Required when `no_limit` is `no` (1 – 9999999)
`no_of_transactions_per_user.frequency`	String	Yes	Frequency: `per_day`, `per_month`, or `till_expiry`
`total_quantity_allowed`	Object	Yes	Total quantity limits across all users
`total_quantity_allowed.no_limit`	String	Yes	`yes` for unlimited total quantity, `no` to enforce a limit
`total_quantity_allowed.quantity`	Number	Conditional	Required when `no_limit` is `no` (1 – 9999999)
`total_quantity_allowed.frequency`	String	Yes	Frequency: `per_day`, `per_month`, or `till_expiry`
`link_expiry`	Object	Yes	Expiry configuration
`link_expiry.is_expiry`	String	Yes	`yes` to enable expiry, `no` to disable
`link_expiry.end_date`	String	Conditional	Required when `is_expiry` is `yes`. Format `YYYY-MM-DD`, today or later
`customer_name`	String	Yes	Customer name in `Firstname Lastname` format (max 50 characters). Send an empty string if not needed
`customer_email`	String	Yes	Customer email (max 50 characters). Send an empty string if not needed
`product_details`	String	Yes	Product or service details (max 200 characters). Send an empty string if not needed
`split_bill`	String	Yes	`0` to disable split bill, `1` to enable
`tip`	String	Yes	`0` to disable tip, `1` to enable
`m_order_id`	String	No	Order ID provided by merchant (max 50 characters)
`m_customer_id`	String	No	Merchant's customer ID (max 50 characters)
`customer_mobile`	String	No	Customer mobile number (digits only, optional leading `+`). When `customer_mobile_code` is supplied, the number length must match the digit length configured for that country code.
`customer_mobile_code`	String	No	Mobile country dialing code (1-9 chars, e.g. `91`). Must be a valid dialing code supported by PayOrc.
`urls`	Object	No	Optional redirect and webhook URLs — see URLs
`urls.success`	String	No	URL to redirect after successful payment
`urls.failure`	String	No	URL to redirect if payment fails
`urls.cancel`	String	No	URL to redirect if customer cancels
`urls.webhook_url`	String	No	Per-order webhook URL (HTTPS). Used when a customer pays via this link

Fields marked Yes must be present in the request body. Where noted, you may send an empty string ("") to leave the value blank.

URLs

The urls object is optional. Omit it entirely if you do not need custom redirect or webhook URLs.

Field	Type	Required	Description
`success`	String	No	URL to redirect after successful payment
`failure`	String	No	URL to redirect if payment fails
`cancel`	String	No	URL to redirect if customer cancels
`webhook_url`	String	No	Per-order webhook URL (HTTPS). Overrides dashboard webhook for orders created from this link

When a customer opens the payment link and pays, these URLs are copied to the order. Redirect URLs fall back to MID defaults when empty. webhook_url must use HTTPS (localhost is allowed for testing).

Response (200 OK)

Field	Type	Description
`data_id`	String	Data ID of the payment link, used for update, details, activate, and deactivate
`link_id`	String	Human-readable link reference number
`qr_code`	String	QR code as a base64 image
`link`	String	Payment link URL
`message`	String	Response message
`status`	String	Response status
`code`	String	Response code (`00` on success)

Code Examples

curl -X POST https://api.payorc.com/payment-links/v1/add \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "amount": {
      "currency": "USD",
      "value": 4999
    },
    "description": "Wireless Headphones",
    "shipping_fee": 500,
    "convenience_fee": 100,
    "no_quantity_per_transaction": "5",
    "no_of_transactions_per_user": {
      "no_limit": "no",
      "quantity": 3,
      "frequency": "per_month"
    },
    "total_quantity_allowed": {
      "no_limit": "no",
      "quantity": 500,
      "frequency": "till_expiry"
    },
    "link_expiry": {
      "end_date": "2026-12-31",
      "is_expiry": "yes"
    },
    "customer_name": "Jane Doe",
    "customer_email": "[email protected]",
    "product_details": "Wireless Bluetooth Headphones",
    "m_order_id": "ORD-2026-001",
    "m_customer_id": "CUST-123",
    "customer_mobile": "9876543210",
    "customer_mobile_code": "91",
    "split_bill": "1",
    "tip": "1",
    "urls": {
      "success": "https://merchant.example.com/success",
      "failure": "https://merchant.example.com/failure",
      "cancel": "https://merchant.example.com/cancel",
      "webhook_url": "https://merchant.example.com/webhook"
    },
    "error_msg": "Invalid request"
  }'

Example Response

{
  "data_id": "6a1d4f160b1b43999539e9ad1cc9565d",
  "link_id": "0000002058",
  "qr_code": "data:image/png;base64,...",
  "link": "https://checkout.payorc.com/checkout/qr/6a1d4f160b1b43999539e9ad1cc9565d",
  "message": "Payment link generated successfully",
  "status": "success",
  "code": "00"
}

Expired payment links cannot be reactivated. Create a new link if the previous one has expired.

Payment Link Statuses

The list endpoint returns a final_status field that reflects the link's overall lifecycle state:

Status	Description
`Active`	Link is live and can accept payments
`Expired`	Link has passed its expiry date
`Deactivated`	Link was manually deactivated

The list response also includes status (Active / Deactivated) and expiry_status (Expired / Not Expired / No expiry date). The details response returns status as Activated or Deactivated.

Create Payment Link

On this page