Cyprus - Epic PIN Opt-in Subscriptions

Cyprus – Epic PIN Opt-in Subscriptions

The information provided in this document is intended for developers to integrate the subscription and charging of your customers who are registered with the Epic network in Cyprus using a PIN opt-in flow. If you have not already done so, please contact the business development team before attempting to follow this guide; business@messagecloud.com or +44 (0)330 1130 243, option 2.

Flow diagram

Explanation of flow diagram

1. You must register your application with a service keyword by contacting us.
2. Customer visits your website and enters their phone number into a form.
3. You send a request to our generate-pin API. Customer is redirected to a verify PIN form.
4. Epic sends a free SMS to the customer containing a PIN and information about the service to which they are subscribing.
5. Customer enters PIN into your website.
6. You send the PIN to our verify-pin API.
7. Once verified, the customer is sent a free SMS by Epic requiring them to reply with the text OK to complete the opt-in.
8. Customer replies to this SMS with the aforementioned message.
9. MessageCloud forwards an MO notification to you to confirm that a successful opt-in has taken place.
10. You can now send a chargeable MT to the customer via our Gateway API.
11. If customer requests an opt-out, we will send this to you as an MO notification. You can also manually invoke an opt-out by calling the stop API.

Registering your campaign

To register your campaign with Epic, please contact the support team through help@messagecloud.com. You will need to provide them with a service keyword which will represent your service and will be seen by your customers. You may also be required to provide any relevant promotional material for your campaign.

Generating a PIN

To start the opt-in process, you should obtain the MSISDN of the customer and call the API with the following parameters. Please note that all parameters are required.

Your requests should be sent to:

https://client.txtnation.com/cy/generate-pin

You are able to send either HTTP GET or HTTP POST to this API.

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/generate-pin?campaign_name=XXXX&api_key=XXXX&network=epic&service=TEST&msisdn=35700000000"
> GET /cy/generate-pin?campaign_name=XXXX&api_key=XXXX&network=epic&service=TEST&msisdn=35700000000 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 109
< Date: Mon, 16 Dec 2019 16:53:24 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"Pin Sent","requestId":"d827f300-624a-48b1-89e8-d0e19d71287b"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true. An example of this is shown below:

{"success":true,"statusCode":0,"statusMessage":"Pin Sent","requestId":"d827f300-624a-48b1-89e8-d0e19d71287b"}

From this result, it is important to store the requestId so that you can use it in the next step once the PIN has been submitted by the customer.

Failed responses will contain a non-zero status code in the statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

At this point, an SMS will be sent to the customer containing a PIN in a format similar to the below:

3753 ΚΩΔΙΚΟΣ ΕΓΓΡΑΦΗΣ ΣΤΗ ΧΡΕΩΣΙΜΗ ΣΥΝΔΡΟΜΗΤΙΚΗ ΥΠΗΡΕΣΙΑ TEST. Η ΧΡΕΩΣΗ ΑΝΑΦΕΡΕΤΑΙ ΣΤΗ ΠΙΟ ΠΑΝΩ ΣΧΕΤΙΚΗ ΙΣΤΟΣΕΛΙΔΑ. ΒΕΒΑΙΩΣΟΥ ΟΤΙ ΕΧΕΙΣ ΔΙΑΒΑΣΕΙ ΠΡΟΣΕΚΤΙΚΑ ΤΟΥΣ ΟΡΟΥΣ ΚΑΙ ΠΡΟΥΠΟΘΕΣΕΙΣ.

3753 PIN CODE FOR THE CHARGEABLE SUBSCRIPTION SERVICE TEST. THE CHARGE IS MENTIONED ON THE ABOVE RELEVANT WEBSITE. MAKE SURE THAT YOU HAVE READ CAREFULLY THE TERMS AND CONDITIONS.

Verifying a PIN

When a customer has entered their PIN code into the form on your website, the following API will verify it for you. Once sent, the customer has approximately 2-3 minutes to confirm the PIN before they receive a second message informing them that they did not opt-in quickly enough. At this point, the customer can restart the opt-in process.

Your requests should be sent to:

https://client.txtnation.com/cy/verify-pin

You are able to send either HTTP GET or HTTP POST to this API.

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/verify-pin?campaign_name=XXXX&api_key=XXXX&network=epic&id=d827f300-624a-48b1-89e8-d0e19d71287b&pin=1234"
> GET /cy/verify-pin?campaign_name=XXXX&api_key=XXXX&network=epic&id=d827f300-624a-48b1-89e8-d0e19d71287b&pin=1234 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 67
< Date: Wed, 18 Dec 2019 12:01:24 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"PIN Verified"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true. An example of this is shown below:

{"success":true,"statusCode":0,"statusMessage":"PIN Verified"}

Failed responses will contain a non-zero status code in the  statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

Notification of opt-in

Once the PIN has been verified, the customer will be sent an SMS instructing them to reply with the message OK. The SMS will be in the following format:

ΣΤΕΙΛΕ ΑΠΑΝΤΗΣΗ ΣΤΟ 6161 ΜΕ ΤΗ ΛΕΞΗ "ΟΚ"
ΚΑΙ ΕΠΙΒΕΒΑΙΩΣΕ ΤΗΝ ΕΝΤΟΛΗ ΣΟΥ ΓΙΑ ΕΓΓΡΑΦΗ
ΣΤΗ ΣΥΝΔΡΟΜΗΤΙΚΗ ΧΡΕΩΣΙΜΗ ΥΠΗΡΕΣΙΑ TEST
ΤΗΣ MESSAGECLOUD (ΤΗΛ. ΕΤΑΙΡΕΙΑΣ 004403301130243)
ΜΕ ΧΡΕΩΣΗ €2.03 ΑΝΑ SMS.

SEND REPLY "OK" TO 6161
AND CONFIRM YOUR ORDER
FOR REGISTRATION TO THE CHARGEABLE SUBSCRIPTION SERVICE TEST
OF MESSAGECLOUD (TEL. NUMBER 004403301130243)
AT A CHARGE OF €2.03 PER SMS.

After the customer replies with OK they will receive a final SMS that confirms the subscription has started:

MESSAGE CLOUD LTD
Η ΕΓΓΡΑΦΗ ΟΛΟΚΛΗΡΩΘΗΚΕ ΣΤΗ ΧΡΕΩΣΙΜΗ ΣΥΝΔΡΟΜΗΤΙΚΗ ΥΠΗΡΕΣΙΑ ΜΕ ΧΡΕΩΣΗ ΚΑΙ ΟΡΟΥΣ ΟΠΩΣ ΑΝΑΦΕΡΟΝΤΑΙ ΣΤΗΝ ΙΣΤΟΣΕΛΙΔΑ ΤΗΣ ΥΠΗΡΕΣΙΑΣ.
ΓΙΑ ΑΠΕΝΕΡΓΟΠΟΙΗΣΗ ΣΤΕΙΛΤΕ “TELOS OFF” ΣΤΟ 6161.
ΔΥΝΑΤΟΤΗΤΑ ΥΠΟΒΟΛΗΣ ΠΑΡΑΠΟΝΩΝ ΜΕΣΩ https://www.txtnation.com ΚΑΙ https://www.epic.com.cy/en/page/By9vGEaa/epic-contact-us.

THE REGISTRATION TO THE CHARGEABLE SUBSCRIPTION SERVICE WITH CHARGES AND TERMS AS PER THE SERVICE’S WEBSITE IS COMPLETED.
TO UNSUBSCRIBE SEND “TELOS OFF” TO 6161.
COMPLAINTS CAN BE FILED VIA https://www.txtnation.com/ AND https://www.epic.com.cy/en/page/By9vGEaa/epic-contact-us

We will then send a notification of the MO to your chosen MO receiver using the same format and URL as supported by Gateway. You can read more about this in the Receiving a Message part of the Gateway documentation.

Sending a chargeable MT

The billing message should be sent through the MessageCloud Gateway API. Please refer to the Sending a Message documentation for more information.

You must also send through the original id sent to you as part of the MO notification. This should be included in the id parameter to Gateway using a pipe to separate it from your own ID.

e.g. if the original ID of the request is 123456 and your ID is 98765432123, you should send this through to Gateway as:

id=123456|98765432123

This will allow us to recognise this transaction as being a part of a subscription.

If you want to send Greek text through, you should encode your characters with UTF-8 and send it to us with encoding=utf8. The text will be automatically converted to the correct character set in the background.

Opt-outs

There are two ways for the customer to opt-out of your subscription service; the customer can send TELOS OFF to 6161 or you can trigger an opt-out by calling our API.

Your requests should be sent to:

https://client.txtnation.com/cy/stop

You are able to send either HTTP GET or HTTP POST to this API.

If we called the API with an HTTP GET, the request might look as follows:

$ curl -v "https://client.txtnation.com/cy/stop?campaign_name=XXXX&api_key=XXXX&network=cyta&msisdn=35700000000"
> GET /cy/stop?campaign_name=XXXX&api_key=XXXX&network=cyta&msisdn=35700000000 HTTP/1.1
> Host: client.txtnation.com
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< X-Served-By: Eos
< Content-type: text/html; charset=UTF-8
< Content-Length: 62
< Date: Wed, 18 Dec 2019 12:04:58 GMT
< Server: txtNation HTTP Server
<
{"success":true,"statusCode":0,"statusMessage":"Unsubscribed"}

Successful requests will be responded to with a JSON-formatted object containing a boolean status value of true.

{"success":true,"statusCode":0,"statusMessage":"Unsubscribed"}

Failed responses will contain a non-zero status code in the  statusCode parameter, with a relevant message in the statusMessage parameter. For your convenience, a list of potential status codes are provided in Status Codes.

Status codes

If your API submission was not successful, a non-zero status code will be returned in JSON format. As part of this object, there will be statusCode and statusMessage parameters which can be used to determine why the request failed. It will also be accompanied by a status parameter that is set to false.