Skip to main content

The redirect contract

The subscriber's browser reaches us, we decide, and we redirect them back to you. This page is what arrives.

Where they land is configured, not requested​

We redirect only to the success and failure URLs registered against your service by the operator team. Nothing in the query string can change the destination.

This is deliberate and not negotiable: an endpoint that redirects wherever a caller asks is an open redirector, and this one takes a subscriber's identity from the network. If you need a different destination, that is a configuration change.

On success​

https://your-success-url.example?msisdn=…&success=1&ti=…&ts=…&servicename=…&merchantname=…

ti and ts come back exactly as they arrived, so you can match the return against the journey you started.

On failure​

The subscriber goes to your failure URL with a reason telling you what happened. The distinction that matters most: whether it is worth trying again.

  • The check ran and declined: a fresh attempt will be declined too. Offer the PIN flow instead.
  • The check could not run: transient. Retrying is reasonable.
  • We had no record of the transaction identifier: your page did not fetch the anti-fraud script for this ti. This is not a decline, and no amount of retrying fixes it; the fix is in your page. See Anti-fraud.

Show something useful. A subscriber sent to an undifferentiated "something went wrong" page has no idea whether to wait, retry, or use a different method, and you do.

Already subscribed​

If the number already has a live subscription, that is not a failure. You are redirected to success with an already marker, so you can send them to their content rather than a welcome flow.

Attribution: your own parameters come back​

Any extra parameter you add to the enrichment URL is echoed back on the redirect, unchanged. That is how you attribute a conversion to a campaign, a placement or an ad:

GET /he/v1/subscribe?serviceId=…&ti=…&ts=…&campaign=spring&placement=banner-3
        ↓
https://your-success-url.example?…&campaign=spring&placement=banner-3

Use it. Without it, an HE conversion arrives with no idea where it came from, and this is the hook that exists precisely so you do not have to guess.

Two limits, and they are bounds rather than decoration: there is a cap on how many extra parameters you may add and how long each value may be, and values are restricted to characters that cannot alter the structure of the resulting URL rather than its content.

Some parameter names are reserved: those the contract itself uses, and those your page addresses to us. Reserved names are not echoed, so do not name your attribution parameters after them. Prefix your own and you will never collide.

Nothing is charged in the redirect​

The redirect means the subscription is open, not that money has moved. The first charge happens on the platform's own schedule. A subscriber who returns to your page has not yet paid, and any messaging that implies otherwise will be wrong for a short window.