Checkout URL parameters
Technical reference for every parameter the checkout link accepts, with format, validation, what happens with an invalid value and how to build the links in your code.
This is the reference for anyone who generates checkout links in code, for example on a sales page, in a transactional e-mail or in a CRM. What each parameter does for the buyer, with examples for store owners, is in Payment link and URL parameters.
The base address
https://pay.vipter.com/<offer-slug-or-id>| Part | Format |
|---|---|
| Offer slug | Lowercase letters, numbers and hyphens, 3 to 61 characters, starting with a letter or number: ^[a-z0-9][a-z0-9-]{2,60}$. |
| Offer ID | ofr_ followed by letters and numbers, such as ofr_a3454b7c008d455fbc5c3fc436c1879d. It works even when the offer has a slug. |
| Host | pay.vipter.com or the store's active custom domain, with the same path. The custom domain only opens offers from its own store. |
When the link can't open, the checkout redirects to /unavailable?reason=<reason>. The reason stays in the address for troubleshooting:
reason | Cause |
|---|---|
not_found | The slug or ID doesn't exist, the offer belongs to a store other than the domain's, or the slug has an uppercase letter. |
link_disabled | The offer's payment link is turned off. |
offer_archived | The offer was archived. |
no_prices | The offer has no price. |
no_settleable_price | No price is in a currency the store can receive. |
project_unavailable | The store is not selling at the moment. |
pack_unavailable | The pack is not a pack of the offer, or the offer is a subscription. |
Parameters
All are optional and the order doesn't matter. A repeated parameter takes its first value. Unknown parameters are ignored.
| Parameter | Accepted format | If the value is invalid | Example |
|---|---|---|---|
pack | Integer from 1 to 999, digits only. It must be the quantity of one of the offer's packs. | The link unavailable page, with pack_unavailable. Empty (pack=) is ignored. | pack=3 |
code | Coupon: up to 40 characters, only letters, numbers, - and _. | An invalid format is ignored. A coupon that doesn't apply to the order shows up in the summary with the reason, and the purchase goes ahead without a discount. | code=BLACK10 |
v | Seller code: 2 to 31 characters, lowercase letters, numbers and hyphens, starting with a letter or number. Uppercase and leading or trailing spaces are normalized. | A malformed code, a code that doesn't exist or one from an inactive seller doesn't attribute the sale to anyone. | v=ana |
lang | Exactly one of pt, en, es, fr, de, it, ja, ko, ru, zh, in lowercase. | Ignored: the language comes from the buyer's previous choice, the browser or the country. | lang=en |
currency | Three-letter ISO 4217 code. Upper or lower case. | With no price in that currency, the checkout opens in the store's currency, the default price or the offer's first price, in that order. | currency=USD |
email | Text. Fills in the buyer's e-mail, which they can correct. | Not validated on opening: the form validates it on submission. | email=ana%40example.com |
name | Text. Fills in the buyer's name. | Not validated on opening. | name=Ana%20Souza |
utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id | Text, up to 500 characters. Leading and trailing spaces are removed and the rest is cut at 500. | Empty is ignored. | utm_source=instagram |
src, sck | Text, up to 500 characters. Same rule as the UTMs. | Empty is ignored. | src=bio |
fbclid, gclid, gbraid, wbraid, ttclid, epik, tblci, ob_click_id, msclkid | Click IDs, text up to 500 characters. Ad platforms add them on their own. | Empty is ignored. | gclid=Cj0KCQ… |
fbp, fbc, ttp, ga_client_id | Values of the _fbp, _fbc and _ttp cookies and of the client ID from your page's _ga. The t.js script adds them on its own. | Empty is ignored. | fbp=fb.1.1790600000000.123456789 |
Reserved: rec is the token of the abandoned checkout recovery link, which comes ready in the recovery_url of the checkout.abandoned event. ctx is for Vipter's internal use. Don't build links with them.
The checkout doesn't accept phone, document or address through the URL.
Rules for each parameter
pack
Only one-time offers have packs. On a subscription offer, any pack leads to the link unavailable page. Without the parameter, the link sells 1 unit at the offer's price. The checkout has no pack selector: one link per pack.
lang
The link's language overrides the rule for stores that sell to a single country, which hides the selector and uses that country's language. The checkout stores the choice in the pay_locale cookie for one year, and later visits without lang use that cookie. In a single-country store, the cookie is not used: only the lang in the link itself changes the language.
Campaign source: UTMs, src and sck
They work as first touch: the first link that brought utm_*, src or sck to that browser in the last 30 days sets all of these values together. A later link with another campaign doesn't replace any of them. The checkout stores this data in the checkout domain's localStorage, under the vpt_attr key, and the 30 days count from the first time something was stored.
Click IDs, cookies and v
They take the last value received: a new click on an ad replaces the stored gclid, and the last seller link opened sets v. When an fbclid arrives without fbc, the checkout builds fbc in the format fb.1.<milliseconds>.<fbclid>. The v code is checked when the checkout creates the payment session: the seller who is active at that moment counts.
email and name
The entry address that Vipter stores with the sale is saved without email, name, phone, rec and ctx. Even so, this data stays in the browser history and in the logs of whoever serves the previous page. Use email and name only in individual links, such as in an e-mail to one customer, never in ads or public pages.
Where the data goes
- The seller (
v) is stored on the order and counts toward commissions. - UTMs,
src,sckand click IDs are stored with the sale and feed the sales sources and the conversions sent to ad platforms. - The UTMs go in the
utmfield of thecheckout.abandonedevent. Order events don't include UTMs or the seller.
Build links in code
Encode each value. An unencoded +, common in e-mails such as ana+loja@example.com, turns into a space. Use your language's functions instead of concatenating text:
function checkoutLink(base, params) {
const url = new URL(base);
for (const [key, value] of Object.entries(params)) {
if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value));
}
return url.toString();
}
checkoutLink('https://pay.vipter.com/kit-cha', { pack: 3, code: 'BLACK10', v: 'ana', utm_source: 'instagram', utm_campaign: 'black-friday' });
// https://pay.vipter.com/kit-cha?pack=3&code=BLACK10&v=ana&utm_source=instagram&utm_campaign=black-friday
checkoutLink('https://pay.vipter.com/curso-fotografia', { email: 'ana+teste@example.com', name: 'Ana Souza', lang: 'pt' });
// https://pay.vipter.com/curso-fotografia?email=ana%2Bteste%40example.com&name=Ana+Souza&lang=ptIn Python, urllib.parse.urlencode generates the same query:
from urllib.parse import urlencode
"https://pay.vipter.com/curso-fotografia?" + urlencode({"email": "ana+teste@example.com", "name": "Ana Souza", "lang": "pt"})
# https://pay.vipter.com/curso-fotografia?email=ana%2Bteste%40example.com&name=Ana+Souza&lang=pt+ and %20 both count as a space in the checkout. If your sales page already has UTMs in its address, the t.js script carries these values to the link with no code.
What to do next
- See how buyers see the checkout.
- Carry the UTMs from the sales page to the checkout with the t.js script.
Retries, disabling and resending
When Vipter retries a failed delivery, when it disables the endpoint on its own, what happens to events while it is off, and how to use the test event and the resend button in the dashboard.
t.js tracking script
What the https://pay.vipter.com/t.js script does on your sales page, step by step, the data-hosts attribute, what it stores and adds to links, how to install it with and without a tag manager and what to allow in your CSP.