Create Payment Link

Create a shareable payment link.

POST /payment_link

Profile defaults, per-order overrides. return_url and webhook details default to the business profile and are not set on this create-link request. When the customer completes the link, you can send per-order return_url, order_details, metadata, merchant_order_reference_id, billing, and shipping on the resulting payment. See Create a payment from a link.

Body Parameters

Parameter	Type	Required	Description
`currency`	string	Yes	Three-letter ISO 4217 currency code (e.g. `USD`, `EUR`).
`amount`	integer	No	Amount in the smallest currency unit (e.g. 6540 for $65.40). Optional for `donation` links where the customer chooses the amount; required for `one_time` and `recurring`.
`description`	string	No	Description shown on the payment page.
`expiry`	string	No	Expiration date in ISO 8601 format (e.g. `2024-12-31T23:59:59Z`). After this time the link returns a sold-out response.
`link_type`	string	No	Type of link. One of `one_time` (default), `recurring`, or `donation`.
`customer_id`	string	No	Pre-fill the link with a known customer ID so the resulting payment is associated with that customer.
`send_email`	boolean	No	When `true`, the platform delivers the link to the customer's email. Requires `email` to be set. Defaults to `false`.
`email`	string	No	Customer email used when `send_email` is `true`.
`send_sms`	boolean	No	When `true`, the platform delivers the link to the customer over SMS. Defaults to `false`.
`usage_limit`	integer	No	Maximum number of successful payments the link accepts. Once reached, further attempts see `sold_out_message`.
`sold_out_message`	string	No	Message rendered on the link page once `usage_limit` is reached.
`capture_method`	string	No	One of `automatic` (default) or `manual`. Determines whether captured funds are settled immediately or held for a manual capture call.
`authentication_type`	string	No	One of `three_ds` (default) or `no_three_ds`. Controls whether 3D Secure is forced for card payments.
`require_customer_info`	boolean	No	When `true`, the link form collects customer name/email/phone before allowing payment. Defaults to `false`.
`setup_future_usage`	string	No	Stores the payment method for future merchant-initiated transactions. One of `on_session` or `off_session`.
`payment_link_config`	object	No	Per-link branding overrides (logo, colors, button labels, allowed payment methods). See Payment link configuration.

Payment link configuration

The payment_link_config object lets a single payment link override the merchant's default branding without touching the profile-level theme. Common fields:

Field	Type	Description
`theme`	string	Hex color used as the primary accent on the link page.
`logo`	string	URL of the logo rendered above the form.
`seller_name`	string	Business name displayed on the link page and on the customer's statement copy.
`sdk_layout`	string	Controls the SDK rendering mode. One of `tabs`, `accordion`, `spaced_accordion`.
`display_sdk_only`	boolean	When `true`, the link renders only the SDK (no header/footer). Useful for embedding.
`enabled_saved_payment_method`	boolean	Allow saved payment methods on the link form when the customer is recognised.
`allowed_payment_method_types`	array of strings	Restricts which payment method types appear (e.g. `["card", "google_pay"]`).

Request Example

curl -X POST 'https://api.uprails.com/payment_link' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -d '{
  "amount": 5000,
  "currency": "USD",
  "description": "Invoice #1234",
  "link_type": "one_time",
  "expiry": "2024-12-31T23:59:59Z",
  "customer_id": "cus_xyz789",
  "send_email": true,
  "email": "customer@example.com",
  "capture_method": "automatic",
  "authentication_type": "three_ds",
  "require_customer_info": true,
  "payment_link_config": {
    "theme": "#5B1166",
    "seller_name": "Acme Inc.",
    "sdk_layout": "tabs"
  }
}'

Response

{
"payment_link_id": "plink_1234567890",
"amount": 5000,
"currency": "USD",
"description": "Invoice #1234",
"url": "https://buy.uprails.com/plink_1234567890",
"status": "active",
"created": "2024-01-22T10:00:00Z"
}

Next steps

Business profiles — learn how return_url and webhook_details are configured at the profile level.