Migration from legacy

If you already run services on the previous platform, read this before anything else. Most of the migration is mechanical. One part is not: your DataSync receiver has to be rewritten, not re-pointed.

What changed across the whole API

	Legacy	Now
Transport	GET, parameters in the query string	POST with a JSON body
Credentials	username and password in the URL	Authorization: Bearer header
Responses	raw text you had to string-match	a JSON envelope with a stable code
Errors	ambiguous or absent	an explicit code, and whether retrying can help
Retry safety	none	spTransactionId on every write
Service identity	your legacy service id	a new number, issued by Tornet SDP

Your service id changes, and the old one may now mean something else

When your service is migrated it is issued a new serviceId, and your legacy service id stops being valid. The operator team gives you the new number at migration; it is also the serviceId in every DataSync event, so the two always agree and you can take it from either.

Do not reuse your legacy service id

The two numbering schemes are unrelated, and a legacy id can be a perfectly valid id belonging to a different service. In most cases such a call is refused, because the service will not be on your short code. But if the number happens to match another of your own services on the same short code, nothing can tell that apart from a deliberate request, and the call will act on the wrong service.

So replace the number at migration rather than mapping around it, and if you keep the old value anywhere, keep it somewhere it cannot be sent.

Credentials no longer travel in URLs. They ended up in web-server logs, proxy logs and browser history on every call. That change is not negotiable.

And you no longer parse text to find out what happened. Branch on code. See The envelope.

Call by call

Legacy	Now
sendPincode	POST dcb/subscription/pin
verifyPincode	POST dcb/subscription/verify
unsubscribeUser	POST dcb/subscription/unsubscribe
sendDCBSMS	POST dcb/sms
(no equivalent)	GET dcb/subscription/status (new)
(no equivalent)	GET dcb/antifraud/script (new, and required)

Two changes to sendDCBSMS that will fail loudly

msg is now message, and it is plain text, not hex. Sending msg is a validation failure.

alphanumeric is refused. The sender is derived from the service's short code and cannot be set per request.

Both are refused rather than ignored on purpose. Accepting msg silently would double-encode your text; accepting alphanumeric and ignoring it would drop a sender you had asked for. A clear failure at integration time beats a subtle one in production.

Anti-fraud is now part of your flow

There was nothing to do on the legacy platform. There is now, and it is the most common reason a migrated integration fails its first real call: your backend fetches a script, your page loads it, and its identifiers travel with the confirming call. See Anti-fraud.

DataSync: a rewrite, not a re-point

This is the part that is not mechanical

Changing the URL you receive on is not sufficient. The feed's shape, its vocabulary and its acknowledgement rules have all changed. A receiver that worked on the legacy platform will not work here, and it will fail in ways that look like missing events rather than like an error.

What is different:

• Numeric actionType values are gone, replaced by named eventType strings such as subscription.created. Your switch will not map across.
• Acknowledge with a 2xx HTTP status. Returning the literal text OK no longer means anything; the status is what we read.
• Every delivery is signed and you must verify it over the raw body, before parsing. See Verifying the signature.
• Deduplicate on eventId. Delivery is at-least-once and ordering is not guaranteed.
• subscription.created carries treatAsNewSubscriber: the first-time-versus-returning question that could not be answered at all on the legacy platform.

Budget real time for this. It is the one part of the migration where reading this page is not a substitute for testing against a real event.

Suggested order

1. Get one authenticated call working: Getting started.
2. Add anti-fraud to your page before touching the flows.
3. Port your flows, one at a time, checking codes rather than text.
4. Rewrite the DataSync receiver last, and test it against real events rather than by inspection.