NAV
shell

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.

Interface
Payment partner —{Charge Mobile - HTTPS:POST}–> FONIX
Payment partner <–{Charge Report - HTTPS:POST}— FONIX

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.

HTTP CODE Description
200 OK - Everything worked as expected.
400 BAD_REQUEST - Check the response body for details.
403 NOT_AUTHORORIZED - No valid API key provided.
500 INTERNAL_SERVER_ERROR - An unexpected error occured at the FONIX platform

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

failcode Description
OUT_OF_RANGE A request parameter value can’t be accepted
IS_EMPTY A mandatory request parameter is empty
TOO_MANY_NUMBERS Too many numbers. Max 100
INVALID_NUMBER Number is incorretly formatted
TOO_MANY_CHARACTERS A request parameter is too long
INVALID_CHARACTERS A request parameter has invalid chars

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.

Your HTTP response codes Description
200 You have accepted the Charge Report.
4xx, 5xx You have not accepted the Charge Report. Fonix retries.

Parameters

The following parameters are in use throughout the API:

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.

Example ENCRYPTEDMSISDN:
  pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

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.

Incoming parameters

The following information parameters appear in CHARGE RESPONSE:

CR STATUS CODES STATUS TEXT
BARRED_MVNO Request not accepted by virtual mobile operator
DELIVERED Charge successfully delivered
DUPLICATE The request was processed twice, but only charged once
INSUFFICIENT_FUNDS User didn’t have enough money
INVALID_REQUEST The request couldn’t be accepted
INVALID_MSISDN Mobile number not accepted by operator
MAX_SPEND_MSISDN Daily user spend limit exceeded
OPERATOR_ERROR Request not accepted by operator
OPERATOR_REJECTED Request not accepted by operator
PENDING The request is still processing
PERMANENTLY_BARRED User is permanently barred from request type
TEMPORARY_BARRED User is temprorarely barred from request type
TEMPORARY_FAILURE A temporary failure prevented processing
UNKNOWN_MSISDN Mobile number not known to operator
UNREACHABLE User mobile is switched off or absent
UNROUTABLE We can’t process the request due to a missing route
UNKNOWN_ERROR Something went wrong, - the request failed
SECTOR_NOT_ALLOWED Service not allowed to bill in the specified sector
OPERATOR_SRV_DAILY_MAX_SPEND Daily Spend Limit Reached
OPERATOR_SRV_WEEKLY_MAX_SPEND Weekly Spend Limit Reached
OPERATOR_SRV_MONTHLY_MAX_SPEND Monthly Spend Limit Reached
OPERATOR_SRV_TYPE_DAILY_MAX_SPEND Daily Spend Limit Reached
OPERATOR_SRV_TYPE_WEEKLY_MAX_SPEND Weekly Spend Limit Reached
OPERATOR_SRV_TYPE_MONTHLY_MAX_SPEND Monthly Spend Limit Reached

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.

CR STATUS CODES ERROR MESSAGE
MAX_SPEND_MSISDN Sorry you’ve reached your monthly spending limit on Charge to Mobile services, which O2 have to protect their new customers. You won’t be able to charge this type of service to your O2 bill again, until next month
SECTOR_NOT_ALLOWED Service temporarily unavailable; try again later
OPERATOR_SRV_DAILY_MAX_SPEND Sorry, you’ve spent all you can today, come back tomorrow
OPERATOR_SRV_WEEKLY_MAX_SPEND Sorry, you’ve spent all you can this week, come back next week”
OPERATOR_SRV_MONTHLY_MAX_SPEND Sorry, you’ve spent all you can this month, come back next month
OPERATOR_SRV_TYPE_DAILY_MAX_SPEND Sorry, you’ve spent all you can today on these things
OPERATOR_SRV_TYPE_WEEKLY_MAX_SPEND Sorry, you’ve spent all you can this week on these things
OPERATOR_SRV_TYPE_MONTHLY_MAX_SPEND Sorry, you’ve spent all you can this month, on these things

Mobile Operator Codes

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

Operator Code Operator
three-uk Three UK
eeora-uk EE (Orange) UK
eetmo-uk EE (T-Mobile) UK
voda-uk Vodafone UK
o2-uk O2 UK
virgin-uk Virgin Media UK
unknown Operator unknown

Character Types

The following data types are in use throughout the API:

# 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:

Msisdn Prefix Operator Code
4400 o2-uk
4401 voda-uk
4402 eetmo-uk
4403 eeora-uk
4404 virgin-uk
4405 three-uk

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:

MSISDN Suffix STATUSCODE STATUSTEXT CHARGEMETHOD
00000001 DELIVERED charged psms
00000002 INVALID_MSISDN Destination Address Error psms
00000003 OPERATOR_REJECTED Invalid state or parameters psms
00000004 SMSC_ERROR Operator System Error psms
00000005 INSUFFICIENT_FUNDS Temporary Error psms
00000006 UNKNOWN_MSISDN UnknownSubscriber psms
00000007 TEMPORARY_OPERATOR_ERROR Temporary network/roaming issue psms
00000008 UNREACHABLE_MSISDN Mobile not reachable or temporary busy psms
00000009 INVALID_OPERATOR_SERVICE Service not supported from mobile or operator psms
00000010 PERMANENT_OPERATOR_ERROR Permanent Error (network/parameters) psms
00000011 TEMPORARY_BARRED Temporary Barred psms
00000012 PERMANENTLY_BARRED Permanently Barred psms
00000013 UNKNOWN_ERROR Unknown Error psms
00000014 MAX_SPEND_MSISDN Spend Limit Reached psms
00000015 OPERATOR_TIMEOUT Operator has not acknowledged. Message might have been sent psms
00000016 UNROUTABLE Unable to route the message psms
00000017 DELIVERED charged direct_bill
00000018 INVALID_MSISDN Destination Address Error direct_bill
00000019 OPERATOR_REJECTED Invalid state or parameters direct_bill
00000020 INVALID_REQUEST Invalid service, subscription, transaction or price point direct_bill
00000021 INSUFFICIENT_FUNDS Temporary Error direct_bill
00000022 UNKNOWN_MSISDN UnknownSubscriber direct_bill
00000023 OPERATOR_ERROR Operator System Error direct_bill
00000024 UNREACHABLE_MSISDN Mobile not reachable or temporary busy direct_bill
00000025 D2B_BARRED Direct billing not allowed direct_bill
00000026 DUPLICATE Transaction already processed direct_bill
00000027 TEMPORARY_BARRED Temporary Barred direct_bill
00000028 PERMANENTLY_BARRED Permanently Barred direct_bill
00000029 UNKNOWN_ERROR Unknown Error direct_bill
00000030 MAX_SPEND_MSISDN Spend Limit Reached direct_bill
00000031 OPERATOR_TIMEOUT Operator has not acknowledged. Client might have been billed direct_bill
00000032 UNROUTABLE Unable to route the message direct_bill
00000033 TEMPORARY_FAILURE Temporary failure direct_bill
00000034 SECTOR_NOT_ALLOWED Service not allowed to bill in the specified sector psms
00000035 SECTOR_NOT_ALLOWED Service not allowed to bill in the specified sector direct_bill
00000036 OPERATOR_SRV_DAILY_MAX_SPEND Daily Spend Limit Reached psms
00000037 OPERATOR_SRV_DAILY_MAX_SPEND Daily Spend Limit Reached direct_bill
00000038 OPERATOR_SRV_WEEKLY_MAX_SPEND Weekly Spend Limit Reached psms
00000039 OPERATOR_SRV_WEEKLY_MAX_SPEND Weekly Spend Limit Reached direct_bill
00000040 OPERATOR_SRV_MONTHLY_MAX_SPEND Monthly Spend Limit Reached psms
00000041 OPERATOR_SRV_MONTHLY_MAX_SPEND Monthly Spend Limit Reached direct_bill
00000042 OPERATOR_SRV_TYPE_DAILY_MAX_SPEND Daily Spend Limit Reached psms
00000043 OPERATOR_SRV_TYPE_DAILY_MAX_SPEND Daily Spend Limit Reached direct_bill
00000044 OPERATOR_SRV_TYPE_WEEKLY_MAX_SPEND Weekly Spend Limit Reached psms
00000045 OPERATOR_SRV_TYPE_WEEKLY_MAX_SPEND Weekly Spend Limit Reached direct_bill
00000046 OPERATOR_SRV_TYPE_MONTHLY_MAX_SPEND Monthly Spend Limit Reached psms
00000047 OPERATOR_SRV_TYPE_MONTHLY_MAX_SPEND Monthly Spend Limit Reached direct_bill

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

Document Version

v1.3

Fonix