Hosted Payment Pages | Run Developers

Overview

Hosted Payment Pages (HPP) allow you to generate a branded, shareable payment link without building a custom checkout UI. Each page is pre-configured with a merchant ID, optional amount, and customer data fields — and can be sent directly to a customer for self-service payment.

For creating a new HPP, see the POST /api/v1/hpp endpoint in the API reference.

Edit a Hosted Payment Page

PUT https://javelin.runpayments.io/api/v1/hpp/{hpp_client_id}

Updates an existing hosted payment page. Existing fields are preserved unless overridden — this endpoint does not remove fields that are omitted from the request body.

Request Fields

Field	Format	Required	Editable	Description
`cc_mid`	string	Yes	No	Merchant ID associated with the hosted payment page. Cannot be changed after creation.
`name`	string	No	Yes	Display name of the hosted payment page.
`name_on_account`	string	No	Yes	Customer name to pre-populate on the payment form.
`amount`	string	No	Yes	Fixed amount for the payment.
`lock_amount`	string	No	Yes	`"true"` or `"false"`. When `"true"`, the customer cannot change the amount. Requires `amount` to be set.
`disable_after_payment`	string	No	Yes	`"true"` or `"false"`. When `"true"`, the payment page is deactivated after a single successful payment.
`min_amount`	string	No	Yes	Minimum amount the customer may enter. Only valid when `lock_amount` is `"false"`. May equal `amount`.
`max_amount`	string	No	Yes	Maximum amount the customer may enter. Only valid when `lock_amount` is `"false"`. May equal `amount`.
`hpp_options`	array	No	Yes	Array of optional form field configurations. See below.

`hpp_options` Fields

Each entry in the hpp_options array configures a form field on the payment page:

Field	Type	Description
`name`	string	Field identifier. Supported values: `address`, `phone`, `email`, `invoice_id`, `custom_01`–`custom_05`.
`value`	string	Pre-populated default value for the field.
`is_readonly`	string	`"true"` or `"false"`. When `"true"`, the customer cannot edit the field.
`is_required`	string	`"true"` or `"false"`. When `"true"`, the field must be completed before payment.

Request Example

{
  "name": "GS2 Payment Link",
  "name_on_account": "Testing Payments",
  "cc_mid": "800000001780",
  "amount": "99.99",
  "lock_amount": "false",
  "disable_after_payment": "false",
  "min_amount": "50.00",
  "max_amount": "200.00",
  "hpp_options": [
    {
      "name": "email",
      "value": "test@test.com",
      "is_readonly": "false",
      "is_required": "true"
    },
    {
      "name": "phone",
      "value": "2150462839",
      "is_readonly": "false",
      "is_required": "true"
    }
  ]
}

Response Fields

Field	Format	Description
`success`	boolean	`true` if the update was applied successfully.
`message`	string	Confirmation message.
`url`	string	The updated payment page URL.

Response Example

{
  "success": true,
  "message": "HPP updated successfully",
  "url": "https://hpp.runpayments.io/payment?client_id=2DF1A41172BA157090D8E26EC83E0CE0"
}

Redirect after payment

By default, a customer who pays on a hosted payment page ends on the Run success page (or the Run decline page). To send them back to your own site instead, set one or both of these fields on POST /api/v1/hpp or PUT /api/v1/hpp/{hpp_client_id}:

Field	Format	Description
`success_redirect_url`	string, up to 1,000 characters	Where to send the customer after an approved payment.
`failure_redirect_url`	string, up to 1,000 characters	Where to send the customer after a declined payment.

Both are optional. A field that is not set keeps the standard Run page for that outcome. Both create and edit responses return the two fields as stored, or null when unset.

URL rules

A destination must:

start with https://;
use a domain name with a top-level domain, such as shop.example.com (no IP addresses, no localhost, no xn-- punycode labels, host at most 253 characters);
have no port, or port 443;
have no username or password (https://user:pass@…);
contain no spaces, control characters or backslashes.

An invalid destination returns 400 with an error message naming the field, and nothing is saved.

A valid destination is stored in canonical form: the scheme and host are lower-cased and :443 is removed. The path, query and fragment are kept exactly as you sent them. For example, HTTPS://Shop.Example.com:443/Thanks?ref=hpp is stored as https://shop.example.com/Thanks?ref=hpp.

Include a path in your destination, for example https://shop.example.com/ rather than https://shop.example.com.

Editing and clearing

On PUT /api/v1/hpp/{hpp_client_id}, a redirect field you omit keeps its stored value. Send null or "" to clear it and return that outcome to the standard Run page.

{
  "cc_mid": "800000001780",
  "success_redirect_url": "https://shop.example.com/thanks",
  "failure_redirect_url": null
}

What your page receives

When a payment completes and a destination is set for that outcome, the customer is redirected with two query parameters added:

Parameter	Description
`transaction_id`	The transaction ID of the payment. Left out if there is none.
`result`	`approved` or `declined`.

transaction_id comes first, then result. Any query string already on your destination is kept, and the parameters are added before any #fragment. For example, https://shop.example.com/thanks?order=42#top becomes:

https://shop.example.com/thanks?order=42&transaction_id=123456789&result=approved#top

Treat these parameters as a hint for what to show the customer, not as proof of payment: anyone can type them into a URL. Confirm the transaction through the API or a webhook before fulfilling an order.

Things to know

Vault and card-on-file pages never redirect. When a page saves a card rather than charging it, the customer always lands on the standard Run page.
One-time links are still used up. If disable_after_payment is on, an approved payment that redirects disables the link just as the Run success page would. A declined payment does not.