Carrier Billing API

Introduction #

This API is used by specifically authorised and trusted third parties to apply a charge or credit to mobile phone accounts. It is organized around REST.

Connection #

All calls to and from the Fonix Direct Billing Gateway are made through HTTPS POST.

Authentication #

Authentication is made by providing the API key as a header in your request. The header name is X-API-KEY. We provide you with a TEST and a LIVE key.

You can have multiple API keys active at any one time for multiple services with us. Your API keys carry many privileges, so be sure to keep them secret!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

FONIX API Endpoints

# https://sonar.fonix.io/v2/ 
# NOTE: The underlying destination IP address of these destinations changes over time.
#  Please don't use fixed destination IPs with this domain.

#Example API Keys
# Test Key: test_BYZNk5YUBMLfowSOQTUuqq3t
# Live Key: live_WrxOqXQYwEPWVJDGgdfirZrk

#Example Request including the API key
  curl -i https://sonar.fonix.io/v2/chargemobile
    -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t
    -d NUMBERS=447987654321
    -d AMOUNT=100

Versioning #

This functionality is included in V2 of Sonar.

The API version is visible in the Charge Report call made to your application:
V2 API: IFVERSION=2xxxxx

Message Referencing #

We support client-provided references for requests to us. This allows you to pass us up to 80 character of data in a field (REQUESTID) which we will provide back to you in the corresponding Charge Report. More detail can be found in the parameters section under REQUESTID.

#Example including requestid
  curl -i https://sonar.fonix.io/v2/chargemobile
    -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t
    -d NUMBERS=447987654321
    -d AMOUNT=100
    -d CURRENCY=GBP
    -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C
    -d BODY=This%20message%20is%20charged%20%C2%A31.

Success and Errors #

An API call sent by you to us is successful if and only if you receive a 200 OK HTTP response code in return.

Any other values in the HTTP response code indicate a failure and the request was rejected. Please do not retry the same request, as it would fail again if unchanged.

If the parameters in your request fail validation, you receive a 400 Bad Request error in response. Please check the result code in the JSON response for details of the failure.

If the key used in your request is incorrect or unauthorised, you receive a 401 Unauthorized error in response.

For all 400 BAD_REQUEST the failure reasons are included in the JSON response:

CHARGE MOBILE #

Request #

This method call charges the mobile phone account of one or many phone numbers.

The charge is only ever attempted once. If unsuccessful we do not re-attempt to charge in the same request unless you specify smsfallback=yes, in which case the charge is attempted again through premium SMS.

#CHARGE MOBILE request

 curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=eetmo-uk.440200000017 
  -d AMOUNT=100 
  -d CURRENCY=GBP 
  -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C 
  -d CHARGEDESCRIPTION=Mobile%20Games%20Service 
  -d TIMETOLIVE=10 
  -d CHARGESILENT=no 
  -d BODY=Thanks%20for%20playing%20lucky%20roulette.%20This%20message%20is%20charged%20%C2%A31.

Response #

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found.

# CHARGE MOBILE response (success)
 {
     "success": {
         "txguid": "r-4-F21B992E9257936E3D2F7CDEB38F217C",
         "numbers": "1",
         "encoding": "gsm"
     }
 }

# CHARGE MOBILE response (failure)
 {
     "failure": {
         "parameter": "numbers",
         "failcode": "INVALID_NUMBER"
     }
 }

CHARGE REPORT #

Request #

Charge Reports for previously submitted Charge Mobile requests are sent in an HTTPS POST request to your web server. They indicate whether the requested charge was successful or failed. If the charge was unsuccessful, details about the failure reason are provided in the STATUSCODE and STATUSTEXT.

# CHARGE REPORT HTTPS POST example (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440200000017&OPERATOR=eetmo-uk
# &GUID=r-4-F21B992E9257936E3D2F7CDEB38F217C&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged
# &STATUSTIME=20160302145201&REQUESTID=F21B992E9257936E3D2F7CDEB38F217C
# &DURATION=0&CHARGEMETHOD=direct
#

Response #

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200 OK, we will retry to deliver the Charge Report to your platform for up to 24 hours.

Parameters #

The following parameters are in use throughout the API:

• NUMBERS: Contains the destination mobile numbers to which the charge will be made. All numbers must include the country prefix, e.g. 44 for the UK.The mobile operator code can be prefixed, i.e. NUMBERS=eeora-uk.447123456789. This is a good idea for all use cases where we don’t receive any MO SMS messages from the consumer first, e.g. where we can only guess the mobile network based on the mobile number prefix.To charge the same amount to multiple numbers you can separate them with commas: NUMBERS=447111122222,447333344444
  The maximum numbers of MSISDN allowed in a batch is 100.
• ENCRYPTEDNUMBER: Can contain one and only one encrypted mobile number. This is a long hash value you may receive from us via Fpay where the mobile number has to remain anonyous but you still require to bill the consumer. Please note: The entire hash value should be used, including any %2F and %3D characters contained in the string.

Example ENCRYPTEDMSISDN:
  pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

• AMOUNT: An amount you wish to charge in pence. For example £1.50 would be set as AMOUNT=150. Not all mobile networks offer the same range of possible charging amounts or support billing in penny increments. If a charging amount can’t be fulfilled because it is not supported by the mobile network, you receive a failed Charge Report with "statuscode": "INVALID_REQUEST".
• CURRENCY: Optional field to specify the currency to charge in. The only allowed value currently is CURRENCY=GBP
• REQUESTID: An optional field for you to store a unique string of up to 80 characters (0-9, a-z, A-Z) along with your request. If you use this field you must ensure that the value is eternally unique for your service.If you send us a new request with a previously used REQUESTID we will not process it again, but reply with the same information we used in our previous response.The REQUESTID will also be passed back to you in the matching Charge Report.
• CHARGEDESCRIPTION: The bill descriptor of the charge is a mandatory field, although it does not appear on all operator phone bills (yet). The maximum allowed length is 30 characters
• TIMETOLIVE: Optionally sets the expiry period of the Charge Mobile request in minutes. If this period expires before a bill attempt was made, then a ‘failed Charge Report’ will be returned to you. Minimum value: 10 minutes, Maximum value: 4320 minutes, Default value: 90 minutes.
• BODY: The optional body text of a message accompanying the charge. If you don’t specify it and you requested CHARGESILENT=no, we will use the following:
  • Default BODY: “You have been charged £nn.nn for your selected product or service.”
• CHARGESILENT: If CHARGESILENT=no is requested, then the BODY will be visible to the user. Default is CHARGESILENT=yes. NOTE: The message will only be received by the end-user if the charge was successful.
• SMSFALLBACK: If SMSFALLBACK=yes is requested, then we will automatically attempt to charge the user through a premium SMS message (default is SMSFALLBACK=no). SMS fallback only works if all of the following criteria are met:
  • The attempt to charge through direct billing failed
  • The mobile operator allows SMS fallback
  • A shared premium MT shortcode with the same charge ‘AMOUNT’ exists
• NORETRY: If NORETRY=yes is requested in combination with SMSFALLBACK=yes, then we will only attempt to charge the user through a premium SMS message ONCE. This is useful where you require a quick turn-around of your billing requests, but still want to use SMS fallback. Default is NORETRY=no, meaning we retry to bill the customer thorugh SMS for a period of time.
• NETWORKRETRY: Default is NETWORKRETRY=yes. If set to NO, please make sure that the operator is specified in the request i.e. NUMBERS=eeora-uk.447123456789.
  When you send a request to us, we first check if we had successful premium transaction from the Msisdn that you are trying to bill and if we do, we’ll first try to bill the msisdn through the Operator on which we had the successful transaction and than, if that Operator doesn’t recognise the Msisdn, through the other Operators.
  If you are sure about to which Operator the Msisdn belongs to (i.e. you get the operator from header enrichment or from an MO to a shortcode), you should submit NETWORKRETRY=NO to have a quicker response.

Incoming parameters #

The following information parameters appear in CHARGE RESPONSE:

• IFVERSION: The API version in use.
• MONUMBER: The mobile number of the user who was charged. The format is MONUMBER=447111122222.
• OPERATOR: The mobile operator code of the user who was charged.
• CHARGEMETHOD: The method of charging that was used. Possible values: direct or psms.
• GUID: The unique identifier assigned by us for this charge.
• DURATION: The duration in seconds it took to apply the charge or the duration it took to find out that it failed.
• RETRYCOUNT: This parameter appears if a request is retried to be sent to you. It increases with every retry.
• STATUSCODE: A code used to advise success or failure of your Charge Mobile request.
• STATUSTEXT: A description to provide more information about the status code.

• STATUSTIME: Timestamp when the Charge Report was created
• REQUESTID: If you submitted your Charge Mobile request with a unique request id, this field will contain it in return to help you identify the charge.
• Special Requirement for O2 customers: If operator=o2-uk and statuscode is one in the following table then the related error message must be displayed through the payment interface.

• Special Requirement for EE customers: If operator=eeora-uk or operator=eetmo-uk and statuscode is one in the following table then the related error message must be displayed through the payment interface.

#

Mobile Operator Codes #

The following list of mobile operator codes are used in this API version (V2) and all future versions:

Character Types #

The following data types are in use throughout the API:

• Numeric: Characters 0-9
• Alphanumeric: Any character of UTF-8
• Mobile number: Characters 0-9, first character may be ‘+’
• Time: Timestamp as YYYYMMDDHHMMSS
• Version: Version as MNNBBB
• GUID: Characters 0-9 and a-f and A-F and ‘-‘

# Examples
# 
# 
# 
#  ORIGINATOR=84588
# 
#  BODY=Test+message
# 
#  NUMBERS=447111222333
# 
#  RECEIVETIME=20130202102030
# 
#  IFVERSION=201001
# 
#  GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Example Request #

Requests sent with a TEST API Key (i.e. an API Key starting with test_) or with the parameter DUMMY=YES are DUMMY requests and are not sent to network operators.

Our system generates internally a CHARGE REPORT depending on the MSISDN submitted in the CHARGE MOBILE request.

OPERATOR will be set basing on the first 4 digit of the MSISDN according to the following table:

For any other msisdn prefix it will be set basing on a number ranges lookup.

STATUSCODE, STATUSTEXT and CHARGEMETHOD are set based on the last 8 digit of the MSISDN according to the following table:

Charge Mobile example #

#Your charge mobile request made to an O2 number 440000000017:

curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=440000000017 
  -d AMOUNT=100 
  -d CURRENCY=GBP 
  -d REQUESTID=F21B992E9257936E3D2F7CDEB38F217C 
  -d CHARGEDESCRIPTION=Mobile%20Games%20Service 
  -d TIMETOLIVE=10 
  -d CHARGESILENT=no 
  -d BODY=Thanks%20for%20playing%20lucky%20roulette.%20This%20message%20is%20charged%20%C2%A31.

# Our ack for your request:
#
# {
#  "success": {
#     "txguid":"r-4-F21B992E9257936E3D2F7CDEB38F217C",
#     "numbers":"1",
#     "encoding":"gsm"
#   }
# }

# Our charge report request made to you:
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440000000017&OPERATOR=o2-uk
# &GUID=r-4-F21B992E9257936E3D2F7CDEB38F217C&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged&STATUSTIME=20160302123716
# &REQUESTID=F21B992E9257936E3D2F7CDEB38F217C&DURATION=0&CHARGEMETHOD=direct
#
# Your ack for our request:
#
# HTTP 200 OK

Charge Mobile example with SMS fallback #

# Your charge mobile request made to 440100000001:

curl -i https://sonar.fonix.io/v2/chargemobile 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d NUMBERS=voda-uk.440100000001 
  -d AMOUNT=100
  -d CURRENCY=GBP
  -d REQUESTID=C1E82726F1423AC298971B37265F8ED2
  -d CHARGEDESCRIPTION=Top%20Up%20Service
  -d TIMETOLIVE=10
  -d SMSFALLBACK=yes
  -d NORETRY=yes
  -d BODY=Thanks%20for%20playing%20topping%20up.%20This%20message%20is%20charged%20%C2%A31.

# Our ack for your request:
#
# {
#  "success": {
#     "txguid":"r-4-C1E82726F1423AC298971B37265F8ED2",
#     "numbers":"1",
#     "encoding":"gsm"
#   }
# }

# Our charge report request made to you:
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=440100000001&OPERATOR=voda-uk
# &GUID=r-4-C1E82726F1423AC298971B37265F8ED2&RETRYCOUNT=0
# &STATUSCODE=DELIVERED&STATUSTEXT=charged&STATUSTIME=20160302124250
# &REQUESTID=C1E82726F1423AC298971B37265F8ED2&DURATION=0&CHARGEMETHOD=psms

# Your ack for our request:
#
# HTTP 200 OK

REFUND API #

Introduction #

The Fonix REFUND API allows merchants to reverse CHARGE MOBILE charges made in the last 90 days.

# REQUEST:
curl -i https://refund.fonix.io/v2/refund 
-H X-API-KEY:SERVICE_API_KEY  
-d REQUESTID=requestid1 
-d NUMBERS=o2-uk.447400000000 
-d CHARGE_GUID=chargeguid1 
-d DUMMY=YES

# RESPONSE 
{
   "success":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully Refunded",
       "guid":"r-1-requestid1",
       "requestid":"requestid1",
       "charge_guid":"chargeguid1",
       "refund_time":"20210803153118",
       "refunded_amount_in_pence":150
   }
 }

Call Details #

Request Parameters #

All the parameters except DUMMY are mandatory.

• REQUESTID: string of up to 80 characters (0-9, a-z, A-Z) used to identfy a request that must be eternally unique for your service.
• NUMBERS: Contains one and only one mobile number for which the information is requested. The mobile operator code must be prefixed i.e. NUMBERS=eeora-uk.447123456789
• CHARGE_ORIGINATOR: Optional. Used to specify the Originator used in the PSMS charge request.
  Possible values:
  direct if the original charge was done through Direct Billing (this is the default value);
  ORIGINATOR used in the PSMS request;
  psms if the charge was done through PSMS but the PSMS originator is not known.
• CHARGE_GUID: The value returned in the GUID parameter in the CHARGE REPORT to refund.

• DUMMY: Optional, values YES/NO, default value NO.

Response #

The REFUND response is in JSON format.
If any of the parameters fail the validation, a failure response with the offending parameter and a failcode is returned.
I.e. {"failure":{"parameter":"NUMBERS","failcode":"INVALID_NUMBER"}}

If the request to the Mobile Network fails, a failure response with the statuscode and statustext related to the failure is returned.
I.e. {"failure":{"ifversion":"201001","statuscode":"MNO_TX_NOT_FOUND","statustext":"Charge Transaction Not Found","guid":"r-1-requestid1","requestid":"requestid1","charge_guid":"chargeguid1","refund_time":"20210714155121"}}

If more than MAX CONCURRENT REQUESTS are sent at the same time a failure response with status code WINDOW_EXCEEDED is returned.
I.e. {"failure":{"ifversion":"201001","statuscode":"WINDOW_EXCEEDED","statustext":"Too many requests made to the server in parallel"}}

If the request takes more than 120 seconds to be processed a pending response is returned.
I.e. {"pending":{"ifversion":"201001","statuscode":"PENDING","statustext":"The request is still processing","guid":"r-1-requestid1","requestid":"requestid1"}}

If the transaction identified by CHARGE_GUID and MOBILE NUMBER is refunded, a success response is returned.
I.e. {"success":{"ifversion":"201001","statuscode":"OK","statustext":"Successfully Refunded","guid":"r-1-requestid1","requestid":"requestid1","charge_guid":"chargeguid1","refund_time":"20210714155511","refunded_amount_in_pence":299}}

Response Parameters #

Responses can be of type failure, pending or success. Examples of the possible response types can be found in the previous paragraph.

• ifversion : Fonix API VERSION.
• parameter : Parameter for wich a validation is failing.
• failcode : Reason of validation failure.
• statuscode : Code used to report the status of the request.
• statustext : A short description associated to the statuscode.
• guid : Unique identifier at Fonix’s side build from the REQUESTID
• requestid : The REQUESTID sent in the request
• charge_guid : The CHARGE_GUID sent in the request
• refund_time : Date and time when the request reached the final status (YYYYMMDDHHMMSS).
• refunded_amount_in_pence : amount refunded.

Parameters Validation Failures #

When one or more parameters don’t pass the validation Fonix REFUND API returns a failure response in the format {"failure":{"parameter":"NUMBERS","failcode":"INVALID_NUMBER"}}.
The parameter field will specify the name of the passed parameter that didn’t pass the validation.
The failcode field will be set to one of the following codes:

Statuscodes #

Document Version #

v1.3