v3 SMS HTTP
Mobile Crediting enables you to offer monetary credit to pre- and post-pay end users on any United Kingdom mobile operator. The amount is added to a pre-pay end user's balance or applied to a contract end user's monthly bill.
Mobile Crediting is available through both MEP and our API operations. If you wish to use MEP rather than the API, contact your account manager to provision this and find out how to configure Crediting in MEP.
The operations supported by Crediting are:
Supported mobile operators
Mobile Crediting is supported by the major UK mobile operators: Vodafone, O2, Three, Orange and T-Mobile.
Some mobile operators require you to notify the end user when a credit has occurred via an SMS message. For more information see Confirming the credit with the end user.
Mobile operators only support certain credit values. You must ensure that any credit you wish to make is supported by your account and that you have sufficient pre-paid funds. Contact your account manager for details.
Prerequisites to using Mobile Crediting
Contact your OpenMarket account manager to become provisioned with Mobile Crediting. We will provide you with a provisioning form, asking for details about:
- The number of independent crediting services, known as Brands, that you want for your account.
- The mobile operators that you which to run services on.
- The credit values (price points) that you wish to provision, as these may need to be specifically provisioned with the mobile operators.
- Specific integration details, such as the URL to which we send Mobile Crediting notifications, as well as any IP addresses or domains that you want whitelisted for your service.
There is no specific need to have a short code associated with the Mobile Crediting itself; however, you may need one to receive crediting campaign opt-ins or opt-out texts.
Configuring price points
The range of available price points is between £0.50 and £10.00 and the price points you want to use are identified during the provisioning process. Different values may need to be provisioned separately for some mobile operators. Once your services are running, you will only be able to send credit at the price points your account has been provisioned with; if you need new price points after this point, then please contact your account manager.
Setting up a prepaid balance
In order to credit end users, you must hold sufficient pre-paid funds in an account with OpenMarket. The balance is reduced by the relevant amount whenever a credit is applied.
You can find out your current balance using the credit balance request. For information about making one of these requests, see Get Credit Balance.
Brands
A brand is a set of configuration data that relates to a specific crediting service you are supplying. Each brand identifies the following:
- The notification URL for that brand.
- Whether or not you wish an SMS message to be sent to the end user once the credit is applied. Note that some mobile operators require a message to be sent.
- The originator details sent with credit SMS messages to the end user.
- The price points that are valid for the brand.
You will need to set up at least one brand for your services. You may have multiple brands, one of which will be your default brand. Each brand linked to your account will have its own identifying value of the brand parameter, which you can specify in both apply credit and credit balance requests.
Contact OpenMarket to set up additional brands on your existing account.
Confirming the credit with the end user
Messages required by T-Mobile
T-Mobile requires your service to send an SMS message when a credit is applied. To make sure you meet these requirements and to make the process easier for you, OpenMarket automatically sends these confirmation messages to T-Mobile end users. This message is triggered once OpenMarket receives a confirmation from T-Mobile indicating that they have credited the end user's account.
The SMS message is configurable through the Apply Credit request. To set the message you wish to send an end user, use the smsContent parameter in the request. If you don't specify a message, then OpenMarket will send a default credit confirmation message to the end user.
Choosing to message end users on other mobile operators
You can use the same automatic feature to send a confirmation SMS to all of your end users, regardless of mobile operator. If you want to do this, then you will need to:
- Let OpenMarket know, as we will need to configure your account accordingly
- Always include the smsContent parameter in the request. If you do not, then OpenMarket will only send a confirmation message to T-Mobile end users, and use our default message text.
Retry strategy
OpenMarket will retry credit requests that have failed but may still succeed when retried. These fall into two categories:
- When OpenMarket cannot reach the mobile operator
- The mobile operator initially fails the request, but the failure code from the mobile operator reveals that it is due to a temporary issue
In these situations, OpenMarket will retry the request at increasing intervals up to a total of 10 attempts, representing a maximum duration of around 17 hours.
You will receive a confirmed or failed notification depending on the eventual outcome of the retries.