Three Ireland DCB (Direct Carrier Billing)

Three Ireland DCB (Direct Carrier Billing)

The information provided in this document is intended for developers to integrate the subscription and charging of customers registered with Three Ireland using our direct carrier billing platform. If you have not done so, please get in touch with the business development team before following this guide; business@messagecloud.com or +44 (0)330 1130 243, option 2.

Flow Diagram

Flow Diagram Explained

1. The customer wants to opt into your subscription service.
2. You request a new Checkout window from MessageCloud. A redirect URL is returned, to which you should forward the customer.
3. The customer uses the generated window to complete the opt-in. There are several methods available for confirmation, including header enrichment, PIN flow and MO. At launch, we will be limited to the PIN flow.
4. When the PIN is confirmed in the generated window, the customer will be redirected to your completion URL with a status and a token. This token will be used to refer to the customer in all future notifications. Also, if you wish to manage the customer's subscription via our API, you will need to use this token in your API calls in place of the MSISDN. It is important to note that the customer has not yet opted into your subscription service.
5. Using the token, you should call the Create Subscription API to start the subscription. It is at this point that you could call other subscription-starting methods, such as Create Trial Subscription or Create Inactive Subscription, but these methods will not be available at launch.
6. You should also send a welcome message to the customer with information about the service and the subscription details. This will help to avoid any confusion and reduce possible complaints.
7. In the response to Create Subscription, we will confirm that the API call was successful. If successful, the customer is now subscribed to your service and charging will happen at the pre-determined interval. If your service does not start with a trial period then the customer will also be charged their initial subscription fee at this point.
8. When charging happens, we will notify your delivery report URL with a standard delivery report, using standard status notation. We will also provide you with a subscription_id parameter which uniquely identifies the customer and a subscription_period_id which identifies the period for which the customer is being charged.
9. If the customer wishes to opt-out of the subscription, we will send you an MO notification with the message STOP. In this notification, we will also send the subscription_id to help you identify exactly which customer has stopped their subscription. You can also opt out on their behalf by calling the Stop Subscription API.

Generating a Checkout Window

To generate a Checkout window, you should send an HTTP GET request to the following URL:

https://client.txtnation.com/ie/checkout/generate

The parameters that control this API endpoint are as follows:

Upon a successful call to the Generate API, we will return a JSON response that includes a window URL to which the customer should be redirected. An example of this can be seen below:

{
    "success": true,
    "statusCode": 0,
    "statusMessage": "Window generated",
    "redirectUrl": "http://checkout.sla-alacrity.com/purchase?service=campaign%3Axxxxxx&merchant=partner%3Ayyyyyy&redirect_url=https%3A%2F%client.txtnation.com%2Fie%2Fcheckout%2Fredirect&correlator=c3ede597-7c9a-40a1-b979-d8c35beac791",
    "requestId": "c3ede597-7c9a-40a1-b979-d8c35beac791"
}

If the request is not successful, the success parameter will be set to false and an accompanying statusCode and statusMessage will be able to provide you with more details about the reason. A table showing the possible reasons is shown under the Error Codes section.

Receiving the Redirect

As previously mentioned, your redirect_url should be ready to receive the customer when the Checkout process has concluded. We will append three parameters onto the end of your redirect URL when redirecting: callback_id, status and token. The status parameter will tell you if the Checkout process was a success, with either success upon success or failed upon failure. The token represents the unique ID for the customer. This token should be used for all interactions between you and the customer in future API calls, such as Create Subscription or Stop Subscription. Finally, the callback_id parameter will be the same ID as the requestId you received in response to your original window generation request. Extra callback parameters on your callback_url are possible but please do not use the status, callback_id and token keys.

Once the redirection is completed, it is important to note that the subscription has not yet been created. You must call the Create Subscription API to start it.

Create Subscription

To start a subscription for your customer, you should now call the following API using an HTTP GET request:

https://client.txtnation.com/ie/subscriptions/create

The following parameters should be sent to this API:

Upon a successful call to the Create Subscription API, we will return a JSON response that includes a subscriptionId. This is the unique ID of the customer in your subscription service. An example response can be seen below:

{
    "success": true,
    "statusCode": 0,
    "statusMessage": "Subscription created",
    "requestId": "c3ede597-7c9a-40a1-b979-d8c35beac791",
    "subscriptionId": "757bda2e-6287-4c32-bf40-a45241beffd6",
    "msisdn": "353xxxxxxxxxx"
}

If the initial Create Subscription API call is successful and you do not have a trial period, then the customer will also be charged their initial subscription fee at this point. No separate delivery report will be sent to your notification URL — you should use the successful result here to indicate a successful payment. Any failures here will not charge the customer.

If the request is not successful, the success parameter will be set to false and an accompanying statusCode and statusMessage will be able to provide you with more details about the reason. A table showing the possible reasons is shown under the Error Codes section.

The JSON response contains a subscriptionId and a msisdn property. These fields can be used to identify and correlate the customer upon receipt of renewal notifications. See Receiving Start, Trial or Renewal Notifications for more information.

Stop Subscription

To stop a subscription on behalf of your customer, you should call the following API using an HTTP GET request:

https://client.txtnation.com/ie/subscriptions/stop

The following parameters should be sent to this API:

Upon a successful call to the Stop Subscription API, we will return a JSON response. If the status of the request is true then the customer has been removed from your subscription. An example of a successful opt-out is shown below:

{
    "success": true,
    "statusCode": 0,
    "statusMessage": "Subscription deleted",
    "requestId": "c3ede597-7c9a-40a2-b979-d8c35beac791"
}

Sending an SMS

As part of your subscription, you may want to send an SMS to the customer in several situations, for example, delivering content, welcoming a new customer or confirming the opt-out of an existing customer.

In order to send an SMS, you should use the following API with an HTTP GET request:

https://client.txtnation.com/ie/send/sms

The following parameters should be sent to this API:

Unfortunately, it is not possible to customise the sender ID for these messages as this is beyond our control. These messages will always be free for the customer as premium SMS is no longer supported.

Upon a successful call to the Send SMS API, we will return a JSON response. If the status of the request is true then the customer has received the SMS. An example of a successful send is shown below:

{
    "success": true,
    "statusCode": 0,
    "statusMessage": "SMS sent",
    "requestId": "d3ede597-7c9a-40a2-b979-d8c35beac792"
}

Error Codes

The following possible error codes can be returned from the API:

Migrating from PSMS to DCB

Unlike Premium SMS through our standard Gateway API, DCB requires a different integration with your system and there are different methods for handling opt-ins, opt-outs and notifications.

However, it also simplifies the payment process. If you have experience integrating PSMS, then integrating DCB should not be a significant challenge.

Your focus should be on handling related notifications which we will forward to your system via the present Three Ireland DCB API. For example, this will prevent you from sending content to a customer that has opted out and will inform you when a customer is successfully charged or not.

You should ensure that you honour these notifications, handling them as appropriate in accordance with Irish telecommunications regulations.

Our Compliance Team can assist you with any questions you may have about local regulations and it is vital that your campaigns are compliant in all respects before you promote and monetise your campaigns for the first time.

Migration Checklist

1. Stop your active promotions to prevent new opt-ins.
2. Stop your subscription charger to prevent any further charges from being made.
3. Export your active subscriber base, including MSISDNs, dates of original opt-in, dates of next charges, networks, subscription intervals and subscription values. Send this to our Compliance Team.
4. Update your systems to no longer send subscription billing requests and to accept delivery report notifications with a subscription_id and subscription_period_id. Any callback IDs used in the id/message_id parameters will no longer be valid. Be ready for the SUBSCRIBED delivery report status, which indicates that a customer has only subscribed to your service and has not yet paid.
5. Optionally, update your systems to use the subscription_id parameter that will now be sent to you in any opt-out notifications. You may be able to continue to rely on the number parameter but this will depend on your existing solution.
6. Update your promotions with the new details of your subscription service, including intervals, values and opt-in methods. It is important that these details are updated to prevent customer complaints.
7. Integrate the new Checkout payment window flow to obtain new subscribers. The exact integration details, including the flow and API calls, are above on the current page.

Receiving Start, Trial or Renewal Notifications

When a customer opts into a premium subscription to receive your content, MessageCloud handles the repeat billing to the pre-agreed schedule and we will handle opt-outs and other changes of state in the customer's subscription.

With PSMS, you would in most cases handle the scheduling of repeat charges. With DCB, this is handled by us. This should greatly simplify the integration and ongoing management of your DCB campaigns.

The notification for this type of message will be sent in the format of a delivery report to your callback URL. This should ensure a level of backwards-compatibility with any existing Gateway integration.

In addition to the standard delivery report parameters, we will also send extra parameters to identify the subscriber and subscription period more accurately.

An example notification could look like this:

https://your-notification-url.com/?action=mp_report&id=1269115137&message_id=1269115137&number=35377777777&report=DELIVERED&subscription_id=c537bf6b-8603-466c-9eaa-bf6d3faed28c&subscription_period_id=6ab07b272683N

Stop Notifications

Stop notifications are very similar to those sent for Gateway transactions. In fact, these notifications should be backwards-compatible with any existing integration with Gateway.

In addition to the standard Gateway stop notifications, we will also send a subscription_id parameter to identify the subscriber more accurately. This is the same subscription_id that uniquely identifies a customer to you as part of the start and renewal notifications.

An example notification could look like this:

https://your-notification-url.com/?action=mpush_ir_message&id=1269114791&message_id=1269114791&number=35377777777&network=THREE-DOB-IE&message=ask+puregaming+stop&subscription_id=c537bf6b-8603-466c-9eaa-bf6d3faed28c

More details can be found on the Stop Requests page.

Delivery Report Statuses

The possible statuses we could send to your platform in these notifications are detailed on the Receiving a Delivery Report page. In addition to these standard statuses, you may also receive the following for DCB transactions depending on the type of service you offer: