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.

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:

  • 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.
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
  • 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.
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
  • 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.
CR STATUS CODES ERROR MESSAGE
OPERATOR_SRV_MONTHLY_MAX_SPEND You have reached your charge to bill limit. Further attempts to add charges to your bill will fail. The limit will reset on your next bill date.
TEMPORARY_BARRED (with CHARGEMETHOD parameter set to direct) You are unable to use this service; you have a 3rd party bar. To remove the bar text UNBAR to 150.
TEMPORARY_BARRED (with CHARGEMETHOD=psms) You are unable to use this service, please contact your mobile provider.
INSUFFICIENT_FUNDS You do not have enough credit to make this purchase. Please top up your phone credit via your usual method.
PAYM_MNO_SPEND_LIMIT You have reached your limit and are unable to add further charges to your bill. You need to wait until your next billing cycle or please call 150 for further help and support.

#

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:

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

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

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 #

URL https://refund.fonix.io/v2/refund
METHOD POST
TYPE Synchronous
MAX Concurrent Requests 5
MAX Response Time 120 seconds

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:

FAILCODE DESCRIPTION
INVALID generic format check failure
INVALID_CHARACTERS one or more characters in the parameter value are not accepted
IS_EMPTY a mandatory parameter has not been sent or sent as empty
TOO_MANY_CHARACTERS string over the maximum allowed length
OUT_OF_RANGE unexpected value for multi value field
INVALID_OPERATOR when the operator the msisdn belongs to is not supported

Statuscodes #

STATUSCODE STATUSTEXT Note
OK Successfully Refunded The transaction was successfully refunded
ALREADY_REFUNDED Refund Already Processed The transaction was successfully refunded previously
WINDOW_EXCEEDED Too many requests made to the server in parallel
PENDING The request is still processing
PERMANENT_REQUEST_FAILURE Operator Error The request was rejected by the operator and the request can’t be retried
TEMPORARY_REQUEST_FAILURE Operator Error The request was rejected by the operator and the request can be retried
UNEXPECTED_RESPONSE Transaction might be refunded Unexpected Response Format from the Operator
UNKNOWN_ERROR Unknown Error Unexpected Error from the Operator
REFUND_FAILED Transaction Not Refunded
MNO_TX_NOT_FOUND Charge Transaction Not Found Charge Transaction Not Found at Operator Side

Document Version #

v1.3

Powered by BetterDocs

How we work with brands