What is fpay? #
fPay is Fonix’s direct billing solution, offering a quick and easy way to integrate mobile billing into your website.
How it works #
To use fPay you must have a registered merchant account with Fonix, if you are not an existing client please contact clientservices@fonix.com.
Once an account has been created you will be able to access the Fonix Dashboard at accounts.fonix.io. In the dashboard area of the platform, you can check stats, create new services, and amend existing services. When a service is live you can present users with the option to pay for products or services using carrier billing. When the user is ready to proceed to checkout we will require you to create a payment session through our APIs. Fonix will handle the payment processes on your behalf and notify you of any successful or failed transactions.
Payment flows (UK) #
Fonix provide a range of payment flows, the screens presented to an individual end user vary based on the service configuration and whether the end user is using a Mobile Data or WiFi Connection.
Wifi Flow (Pin Verification) #
When the user clicks the Continue button a free to end user SMS messageis triggered to the handset, containing a unique pin which is required for the second step of the authentication process. The user is then presented with the second Fonix screen, inviting them to enter the unique pin number previously sent to the handset. Once a valid pin is entered and verified by Fonix, a billing request is triggered to the Mobile Network Operator, and upon a successful confirmation from the Mobile Network Operator, is shown the success screen and a SMS receipt is sent to the user’s handset.
Mobile Data Flow(3G/4G/5G) #
This flow is only allowed for Single Purchases and for Subscription servicesthat are behind a secure login with a username and password.
The Three network does not allow this flow for any service types.
Hybrid flow #
The Hybrid flow is used as an alternative to the mobile data flow and the same conditions apply. This flow is only allowed on EE and Vodafone, with approval from the Mobile Network Operator.
WiFi Flow (Pin Verification) Default Message Wording #
Below is an overview of the current default SMS message wording for the WiFi Flow (Pin Verification) for all service types within fpay. Please note the message body is set as standard, but subject to change based on Mobile Network Operator or PSA guidance.
Single Payment Service
The first example shows the verification message sent to the handset containing the unique pin in order to confirm the user is in possession of the handset. The second message is the receipt message, confirming the purchase, this is triggered once the user has competed the pin verification on the payment screen.
Donation Service
The first example shows the verification message sent to the handset containing the unique pin in order to confirm the user is in possession of the handset. The second message is the receipt message, confirming the purchase, this is triggered once the user has competed the pin verification on the payment screen.
Subscription Service Without A Trial Period
The below example messages detail the free to consumer SMS messages a user will receive throughout the duration of a subscription service.
The first example shows the verification message sent to the handset containing the unique pin in order to confirm the user is in possession of the handset. The second message is the receipt message confirming the purchase, this is triggered once the user has completed the pin verification on the payment screen. This message also confirms the subscription has been started and provides details as to how the user can unsubscribe from the service. The third message is the receipt message for a successfully charged re-bill. This message will be sent out for every billing event for the duration of the subscription. The final message is the confirmation message sent to a user who has unsubscribed from the service.
Subscription Service With A Free Trial Period
The below example messages detail the free to consumer SMS messages a user will receive throughout the duration of a subscription service. The first example shows the verification message sent to the handset containing the unique pin in order to confirm the user is in possession of the handset. This message also details the length of the free trial period based on the service configuration.The second message is the receipt message confirming the purchase, this is triggered once the user has completed the pin verification on the payment screen. This message confirms the subscription has been startedand the end date of the free trial and details as to how the user can unsubscribe from the service. The third message is the receipt message for a successfully charged re-bill. This message will be sent out for every billing event for the duration of the subscription. The final message is the confirmation message sent to a user who has unsubscribed from the service.
Subscription Service With A Paid Trial Period
The below example messages detail the free to consumer SMS messages a user will receive throughout the duration of a subscription service.
The first example shows the verification message sent to the handset containing the unique pin in order to confirm the user is in possession of the handset. This message also details the length and cost of the paid trial period based on the service configuration.
The second message is the receipt message confirming the purchase, thisis triggered once the user has completed the pin verification on the payment screen. This message confirms the subscription has been startedand the end date of the paid trial and details as to how the user can unsubscribe from the service.
The third message is the receipt message for a successfully charged re-bill. This message will be sent out for every billing event for the duration of the subscription.
The final message is the confirmation message sent to a user who has unsubscribed from the service.
Security and connectivity #
Example API KEY:
x-api-key:live_123456789abcdefg
On account creation and / or for each new service created, Fonix will provide you with a unique API Key that must be included in all API calls to fpay.fonix.io.
The API key must be added as an HTTP header to all API requests. The key:value pair for the header is X-API-KEY:your_api_key_here.
Creating a new service #
Before you start using the Fonix APIs, a valid service must be created and a number of parameters configured. A unique service id (often titled “sid”) is generated in the process in order to identify the relevant product or service.
Service fields #
Below is a list of required and optional fields available to use when creating a service. Some parameters can also be dynamically customised when you create a new payment session through our API. For more information about customisable fields please refer to the Create a payment session section of this documentation.
- *Service Name ()**: This is the name of your service within fPay. This will appear on the payment flow, reporting and the receipt SMS’s.
- *Service Type ()**: This field will determine the type of service that a user is going to go through. There are 5 types of services you can choose from: One-Off payment (for example top up credit or buy a service with a one-off transaction), Donation (same as one-off payment but specificly designed for donations), Subscriptions (Recurring billing every of a defined amount over a set billing frequency), Subscription with free trial and Subscription with paid trial (the trial period can be of different length and amount).
- *Merchant name ()**: This is the name of the merchant as it is displayed throughout the payment flow.
- *Customer care number()**: Your customer care number. It will be displayed to the end-users throughout the payment flow.
- API key: The API key used to identify you in the fPay APIs (subscription re-bills, create sessions, subscriptions stop, etc). This is automatically generated and it will be visible after your service has been approved.
- Promotional Text: This is extra wording to be displayed on top of the standard wording on the payment screens
- Amount: The amount to be charged. This has different behaviours depending on the type of your service. For Single payment and Donation services this is the amount charged for each transaction. For Subscription and Subscription donation this is the amount used for both the first transaction and all subsequent re-bills. For Subscription with free trial this is the amount used for re-bills (as the first transaction is free). For Subscription with paid trial this is the amount used for re-bills – the amount of the first transaction is the one set in the trial amount field.
- Billing frequency (* Subscription only): This is the billing frequency we will display to a user that comes to the payment screen. This will be displayed to the user throughout the payment flow. We don’t run re-bills automatically, you will have to make an API call to our re-bill endpoint at every billing frequency period. More information in the subscription section.
- Trial duration (* Subscription with paid or free trial only): This is the period of the trial (either free or paid). This will be shown to end-users throughout the payment flow and you can start re-bills for a subscription after its trial period expired.
- Trial amount (* Subscription with paid trial only): This is the amount charged for the trial period of a subscription (the first transaction that starts the subscription). The service amount is used for re-bills.
- Site URL: The URL for your main site. This will be used to whitelist your domain in case you want to embed the payment screen into your website. Format should be
(https:// + domain only)
, e.g.https://example.com
- Success URL: This string is absolute URL that the end user will be redirected to upon a successful transaction.
- Failure URL: This string is absolute URL user will be redirected to when transaction fails or when user presses “Exit” on one of our screens
- Background notification URL: String representing absolute URL to which fpay will invoke a POST request to send notifications of the status of a transaction.
- *Unsubscribe URL ( subscription only)**: String representing absolute URL we will post stop subscription notifications if user texts STOP to a shortcode. Mandatory for Subscription type services
- STOP Shortcode: (optional, leave blank to use default 62442) This will replace the shortcode shown on the payment flow and receipt SMS’s. It must be provided by Fonix.
- GA Tracking ID: Goole Analytics tracking Id. Tracks clicks on Cancel/Exit button, Resend Token, landing and confirmation screen continue/confirm button clicks, success/retry buttons
- Upload image first screen: The image to display on the landing payment screen.
- Upload image second screen: The image displayed on the confirmation payment screen. If left blank we will use the first one for both.
- *Upload T&C ()**: A text file with the terms and conditions for the service to be linked to on the payment screen.
(*) Mandatory fields
After you create your service it will be in a Pending Approval state. Client Services will be contacted automatically to perform checks and final configurations. This is a manual process and may take 1 day (during normal UK working hours).
Configuration by Client Services #
There are some optional features that can be requested based on approval by the Fonix Client Services team
- Skip Success Page: Client services can configure a service to skip the success page in the payment flow and redirect the user straight to the ‘Success URL’ provided.
- Age verification: A service can be configured to only be accessiblefor users over 18 years
- Billing Amount Above £10: A service can be configured to chargeup to £10 without any approval required. If the service is configured to charge more than £10, Fonix need to seek approval from the Mobile Network Operators. A service cannot go live until permission is granted, please contact clientservices@fonix.com
Test and Live mode #
When a service is configured it will default to sandbox mode. Whilst in sandbox mode, any transactions made will simulate success and failures without actually billing the mobile handset. The payment flow will behave in exactly the same way as a live service, however, all SMS messages will include Sandbox Mode at the beginning to indicate it is a test service and that the handset will not be billed. Once all testing is completed, you can click on the Test/Live switch which will trigger a notification to Fonix to approve the service for the live environment.
Integration with fPay #
Integrating with fPay is easy, below you can find examples of the typical interaction between the end-user, your website and fPay. The following example are valid for all service types and payment flows.
In order to start using fpay, the configuration required involves:
- Creating a payment session through the API;
- Creating an endpoint to receive charge reports for each transaction and/or querying the status of the transaction;
- Being able to handle users redirected back to your website after a payment has been completed.
If the service is a subscription service, you need to:
- Notify us when a user unsubscribes from the service through your platform;
- Make an API call to re-bill existing subscriptions (trial ended and every billing frequency period, for example every month);
- Create an endpoint that is able to receive requests to unsubscribe an end-user. Fonix will send a notification to the configured url every time a user sends STOP to unsubscribe from the service or when we close stale subscriptions automatically.
For more information about subscription services please check the subscription section.
Charge reports #
You can create a payment session by sending a server-to-server request to the create payment session API. Fonix will process the request and return a redirect url in order to redirect the user to the payment flow. For each transaction created, you will receive a charge notification (or receipt) containing all the information related to the transaction and the status. When an end-user completes a purchase (either successfully or not) Fonix redirect the user back to you with the information regarding the status of the payment, enabling to you to identify the user and allow them access to the purchased content. For more information about the redirection process, please click here.
The charge notification is asynchronous, this means that in some cases the notification may arrive after the the end-user is redirected to your success/failure page or, in case of network issues, it may not reach you. This scenario is shown in the diagram below:
The charge notification is the primary method that should be utilised in order to obtain information regarding the status of a transaction. If for an reason the charge notification fails, you must still grant access to the content the user paid for. fPay provides secondary methods to access information about a specific transaction:
- Use the secret_success_token or secret_failure_token returned by the session creation API and cross-check it with thes_tokenreturned by the redirected user. This can provide an easy way to give access to users by checking if the s_token is equal to the secret_success_token.
- Query the transaction status API to retrieve the same information that would have been provided within the charge report.
Querying the status of a transaction. #
Some merchants would prefer to take an active approach and request the status of a transaction removing the requirement for the charge report notification. When a user returns to the website, you can request the status of the transaction utilising the transaction status API. If utilising this API you can ignore the charge report notification or alternatively do not configure a background notify URL for the service.
A payment session will still be initiated by sending a server-to-server request to the create payment session API, however, when the user is directed back to the website, either by user redirect or any other method, you can query fPay through the transaction status API and retrieve the transactional information associated to the user.
In the diagram above we show the call to the transaction status API being made synchronously to the request made by the end user to show your success page. Users may not be able to view the success page after a successful payment (they may lose internet connection or fail to click on the final continue button that redirects them back to you). In this scenario you should check the status of the transaction in an alternative way e.g when the user attempts to access the content.
Handling subscriptions #
Subscription services can be configured within the fpay platform to include an optional trial period. The trial period can be either free to the end user or a different offer amount to the fixed recurring billing amount.
In this section we are going to detail how subscription services work and the operations that can be performed.
Every subscription is triggered through the fPay payment screens. When auser initiates a subscription to the service, you need to create a payment session on fPay and redirect the user to Fonix.
This is an example of the lifespan of a typical subscription, with a trial period, and an explanation of the various date fields we pass back to you through different endpoints.
This is an example of the lifespan of a typical subscription without a trial period.
Please note, the first transaction is processed when the user completes the purchase through the Fonix payment screens. Subsquent subscription re-bills need to triggered by the merchant at each end_validity_date.
While the following is an example of the lifespan of a typical subscription without trial period.
Please notice that the first transaction is processed when the user goes through the payment page. you will only need to trigger re-bills at each end_validity_date.
Re-billing an active subscription #
The Fonix platform does not support automatic re-bills (or managed subscriptions) this needs to be handled by the merchant. The below rules need to be reviewed before implementing any re-billing logic:
- Rebills should be triggered between 8AM and 8PM of the target country;
- Rebills should be triggered on the same day of the subscription’s end date (the period of time for which the subscription is considered active);
- If the rebill fails, you can only trigger a rebill the day after the failed rebill;
Please refer to rebill subscription API for further integration details regarding this API.
Stopping a subscription #
There are 4 main ways a user can end a subscription:
- Users who are provided an option to unsubscribe from the service within an account environment or profile page. If the user unsubscribes from the service in this way, you need to trigger a call to the unsubscribe subscription endpoint. This will allow Fonix to handle users correctly should they attempt to re-subscribe to the service in the future;
- Through the customer care page in the reporting suite of fPay;
- The user sends a STOP message to the fpay stop shortcode;
- Automatic subscription expiry after 60 days at the end of validity of the subscription (subscription hasn’t been successfully rebilled for 60 days after the end of the validity period).
Every time a user is unsubscribed from our platform, using any of the methods described, you will receive a background notification from fPay notifying you of the successful operation. The user will also receive a SMS message to the subscribed handset notifying them of the successful operation.
Reactivating an existing subscription #
The below section details the scenario where a user has subscribed to a service, unsubscribes from the service and then wishes to re-join the service at a later date.
This can happen when the subscription is in 2 different states:
- Subscription is UNSUBSCRIBED and the end_validity_date is in the past.
- Subscription is UNSUBSCRIBED and the end_validity_date is in the future.
For the first case the subscription is after the validity period. This means the user should be redirected back to the Fonix payment screens as if they were a new user. The user will be required to go through the payment flow and a new subscription to the service will be created along with a new subscription ID.
For the second case the subscription is still within the validity period. In this scenario the user will still have to complete the payment process, however, the user will not be charged. Fonix will generate a successful status code (SUBSCRIPTION_REACTIVATED) and the existing subscription will re-enabled rather than creating a new subscription ID.
APIs #
The below section details the request and response information for the complete range of Fonix APIs.
Create a payment session #
This is the main entry point to create a payment session. When a user initiates a payment for either a one off transaction or a subscription service, you create a payment session using the below endpoint. If the transaction is successful, we return a redirect url which should be used to redirect the user to Fonix to complete the transaction process.
Target URL: https://fpay.fonix.io/rest/sessions/create?sid={service_id}&{other_params}={other_values}
Method: GET
Request values: url encoded
curl -v 'https://fpay.fonix.io/rest/sessions/create?sid=123456&mobile=47123456789&amount=300' --header 'X-API-KEY:live_1234abcdefg'
Name | Type | Mandatory | Value |
---|---|---|---|
sid | Param | true | The service id of the service. |
amount | Param | false | This is available if a custom amount has been enabled in the service rather than a fixed price. You can specify the amount in the fraction of the currency, for example £5.00 is 500. |
successUrl | Param | false | The url to be used when we redirect the user back to you for a successful transaction (CHARGED, ALREADY_SUBSCRIBED, SUBSCRIPTION_REACTIVATED). This will override the configuration in your service configuration. |
failureUrl | Param | false | The url to use when we redirect the user back to you in case of failed or cancelled transaction. This will override the configuration in your service configuration. |
notifyUrl | Param | false | The url to use for the server-to-server receipt notification. This will override the configuration in your service configuration. |
cssUrl | Param | false | The custom css url to use to customise your payment pages. You can upload the custom css in your domain during development, so you can test it live. Conditions for this to work is that your service should be in sandbox (test) mode and your domain should be specified in the site url field in the service configuration. |
imageUrlFirstButton | Param | false | You can host images to use as a banner logo in the payment pages in your own domain. If you do so you can specify the url to the image to show in the first payment page in this parameter. Make sure the domain hosting your image is also specified in the site url field in the service configuration. |
imageUrlSecondButton | Param | false | You can host images to use as a banner logo in the payment pages in your own domain. If you do so you can specify the url to the image to show in the confirmation page in this parameter. Make sure the domain hosting your image is also specified in the site url field in the service configuration. |
mobile | Param | false | This field can be used to pre-populate the mobile phone field in the payment page. The user can change this value. |
billing-frequency | Param | false | (Subscription only) The billing frequency. |
account_ref | Param | false | (Austria only) Enduser’s id as defined by the merchant. E.g. username, email, SSN, member-id, … required for iGaming. |
X-API-KEY | Header | true | The api key associated to this service. |
Response
{
"code":0,
"session":{
"secret_failure_token":"b5cdab4f-6fc7-4fa7-8d38-b2c9d81eed3d",
"secret_success_token":"2a0769c7-382b-4769-b1d1-757e2a196146",
"payment_url":"http://fpay.co/newpayment.jsp?rsid=0459V2CHK0P6N6JTO8C32QCFY3TRWH0T6225",
"redirectUrl":"newpayment.jsp?rsid=0459V2CHK0P6N6JTO8C32QCFY3TRWH0T6225",
"guid":"be32c9c7-6647-43fa-a8ee-9c4371ea7f66"
},
"sessionId":"ZLYV2LAP6PGNEP2H5Y5FS21Z83CO735H",
"message":"ok"
}
Name | Type | Mandatory | Value |
---|---|---|---|
code | numeric | true | 0 or an error code from the error codes table |
message | String | true | ok or an error message from the error codes table |
sessionId | String | true | Deprecated Please ignore this value. |
session | session json | false | the session information you can use to redirect your user to us. Present only for status code 0 |
session
Name | Type | Mandatory | Value |
---|---|---|---|
secret_failure_token | String | true | A token used to identify a failed transaction when the user is redirected back to the merchant before the receipt callback has reached them. Please read user redirection for more information. |
secret_success_token | String | true | A token used to identify a successful transaction when the user is redirected back to the merchant before the receipt callback has reached them. Please read user redirection for more information. |
payment_url | String | true | The url to use to redirect the merchant to our payment flow. |
redirectUrl | String | true | Deprecated Please ignore this value. |
guid | String | true | The unique transaction id that you can use for APIs or to match the user for callbacks and redirects. |
Transaction status #
The transaction status API allows you to retrieve the current status of the transaction.
Target URL: https://fpay.fonix.io/rest/v2/transactions/status/{transaction_id}
Method: GET
Request values:
curl -v 'https://fpay.fonix.io/rest/v2/transactions/status/123456-123456-123456-123456' --header 'X-API-KEY:live_1234abcdefg'
Name | Type | Mandatory | Value |
---|---|---|---|
transaction_id | Request parameter | true | The unique fPay transaction id (or GUID) |
X-API-KEY | Header | true | The api key of the service associated to the transaction. |
Response
{
"subscription":{
"billing_frequency":{
"time_unit":"DAY",
"time_amount":20
},
"end_validity_date":"2020-04-12 11:54:21.123",
"id":1363635,
"creation_date":"2020-03-23 11:53:21.007",
"rebill_amount":{
"amount":500,
"currency":"GBP",
},
"start_date":"2020-03-23 11:53:21.123",
"status":"SUBSCRIBED"
},
"transaction":{
"user_ip":"78.33.71.182",
"sandbox_mode":true,
"status_code":"CHARGED",
"service_id":150494,
"track_user_flow":[
{
"tracking_action":"PAYMENT_LANDING_PAGE",
"tracking_time":"2020-03-23 11:54:06.123"
},
{
"tracking_action":"PAYMENT_CONFIRMATION_PAGE",
"tracking_time":"2020-03-23 11:54:11.123"
},
{
"tracking_action":"PROCESSING_BILLING_REQUEST",
"tracking_time":"2020-03-23 11:54:21.123"
},
{
"tracking_action":"PAYMENT_PROCESSING_PAGE",
"tracking_time":"2020-03-23 11:54:21.123"
},
{
"tracking_action":"PAYMENT_SUCCESS_PAGE.123",
"tracking_time":"2020-03-23 11:54:23"
},
{
"tracking_action":"PREPROCESSING_BILLING_REQUEST",
"tracking_time":"2020-03-23 11:54:21.087"
}
],
"guid":"200e4cd9-3b16-4feb-bd0b-a69751f2a4c8",
"creation_date":"2020-03-23 11:54:06.020",
"charge_method":"direct",
"msisdn":{
"mobile_number":"447400000001",
"moid":14319293,
"operator":"o2-uk"
},
"merchant_params":{
"tag":"product-1",
"requestid":"xyz123",
"x_my_request_id":"abcdef0123456789"
},
"flow":"3g",
"billing":{
"amount":500,
"currency":"GBP"
}
},
"status":"OK"
}
Name | Type | Mandatory | Value |
---|---|---|---|
status | String | true | OK for success or the error codename in the error codes table |
message | String | false | Only present if status is not OK. It’s a human readable description of the error |
transaction | transaction json | false | only present if the status is OK |
subscription | subscription json | false | only present if the status is OK and there is a subscription associated to the transaction. Always for re-bill and successful payment flow transactions (CHARGED, ALREADY_SUBSCRIBED and SUBSCRIPTION_REACTIVATED) of subscription services – not guaranteed for other status codes. |
subscription json
Name | Type | Mandatory | Value |
---|---|---|---|
id | numeric | true | The subscription id to be used for all subscription APIs. |
billing_frequency | billing frequency json | true | The billing frequency of the transaction, for example monthly will be 1 Month. |
end_validity_date | datetime | false | The end of the validity of the subscription. This is the period of time the user paid for, so if the starting day of a subscription is 01/01/2020 00:00:01 with a free trial of 1 week and 1 month billing frequency, the initial end_validity_date will be 08/01/2020 00:00:01 and after the first successful rebill the next end_validity_date will be 07/02/2020 08:00:01 (30 days after the successful re-bill, not from the previous end_validity_date). Only present if start_date is present. |
creation_date | datetime | true | The creation time of the subscription. Does not indicate when a subscription started. |
rebill_amount | rebill amount json | true | The amount taken from the user every time a re-bill is successfully processed. |
start_date | datetime | false | Indicates when a subscription was successfully activated by the initial successful transaction. This value is only present if the initial transaction that created the subscription was successful. |
status | subscription status enum | true | Indicates the current status of the subscription. |
transaction json
Name | Type | Mandatory | Value |
---|---|---|---|
guid | String | true | The unique transaction id you used to call this API |
user_ip | String | true | The end-user’s IP, this is present only for successful transactons. |
sandbox_mode | boolean | true | False if the service is live, true if is in test mode |
status_code | String | true | The status of the transaction. Check the status code column in the status codes table |
service_id | numeric | true | The service id associated to the transaction. |
track_user_flow | user flow json array | true | The list of operations performed by users and the pages they’ve been to. |
creation_date | datetime | true | The date time this transaction was created. |
charge_method | String | false | The charging method used for this transaction, can be PSMS (premium sms) or DIRECT (direct billing). Guaranteed present for CHARGED transactions (no free trial transaction for subscriptions). Could be present for other status codes. |
msisdn | msisdn json | true | The end-user’s mobile phone information. |
merchant_params | merchant params json | true | It contains all the custom parameters passed when creating the payment session. |
billing | billing json | true | the amount paid for this transaction. |
flow | String | true | The payment flow for this transaction. Can either be 3g, wifi, hybrid, not_yet_available, rebill. Every flow except for rebill is related to the payment flow users go through. |
msisdn json
Name | Type | Mandatory | Value |
---|---|---|---|
moid | numeric | false | The end-user’s phone number unique id. This is always present for processed transactions. It’s not present only if we don’t know the end-user’s phone number. |
mobile_number | String | false | The end-user’s mobile phone number used for billing. Only present for CHARGED transactions. |
operator | String | false | One of the operator aliases in the operator table. Only present if the mobile_number field is present. |
merchant params json
Name | Type | Mandatory | Value |
---|---|---|---|
tag | String | false | Same value passed to the tag parameter when creating the payment session for this transaction. |
requestid | String | false | Same value passed to the requestid parameter when creating the payment session for this transaction. |
x_* | String | false | All parameters starting with x_ that you passed when creating the payment session for this transaction. |
subscription status enum
Name | Meaning |
---|---|
PENDING_PAYMENT | This status is only present during the initial transaction to subscribe a new user until we know the status of the transaction. |
SUBSCRIBED | The subscription is currently active. This status will persist until the user unsubscribes from the service, even if the subscription hasn’t been successfully rebilled after the end_validity_date. |
FAILED | This status is only present if the initial transaction to subscribe a new user fails. |
UNSUBSCRIBED | The end-user unsubscribed. This value is present from the moment the user unsubscribes from your service. The subscription may still be valid if the current date is before the end_validity_date. Up until that point the user could reactivate the same subscription if they want to. |
billing frequency json
Name | Type | Mandatory | Value |
---|---|---|---|
time_amount | numeric | true | The numeric part of the duration of the subscription. For example for a monthly subscription this value will be 1. |
time_unit | String (DAY, WEEK, MONTH, YEAR) | true | The unit associated to the numeric value of time. For example for a monthly subscription this value will be MONTH. |
billing and rebill_amount
Name | Type | Mandatory | Value |
---|---|---|---|
amount | numeric | true | The amount paid/to be paid in smallest fraction of the currency, for example pence for GBP. 5.00£ will be 500. |
currency | String | true | ISO 4217 currency code. Currenctly supporting only GBP and ZAR and EUR. |
Stop subscription #
This API must be called when a user unsubscribes from the service. This will allow users to reactivate a subscription without being blocked.
Target URL: https://fpay.fonix.io/rest/subscriptions/{subscription_id}/stop
Method: POST
Request values:
curl -v 'https://fpay.fonix.io/rest/subscriptions/{subscription_id}/stop' --header 'x-api-key:xxxxxxxxxxxxx' --data ''
Name | Type | Mandatory | Value |
---|---|---|---|
subscription_id | URL Param | true | The unique subscription identifier of the subscription you want to stop |
X-API-KEY | Header | true | The API key of the service associated to this subscription |
Response type: JSON
{
"code":0,
"sessionId":"MJA73J0VOSO05MR8JR2320H3KNI45OJH",
"message":"ok"
}
Response
Name | Type | Mandatory | Value |
---|---|---|---|
code | numeric | true | 0 in case of success or error code in the error codes table |
message | string | true | ok in case of success or message in the error codes table |
sessionId | string | true | Deprecated Please ignore this value |
Re-bill subscription #
This endpoint is used to re-bill active subscriptions. Rules about re-billing a subscription can be found here; When you trigger a re-bill successfully, the response contains transactional information related to the newly created transaction. The status of this transaction will initially show as PENDING, whilst you wait for a callback receipt detailing the status of the transaction or you can query the status of the transaction using the transaction status API.
Target URL: https://fpay.fonix.io/rest/subscriptions/{subscription_id}
Method: POST
Request values:
curl -v 'https://fpay.fonix.io/rest/subscriptions/{subscription_id}' --header 'x-api-key:xxxxxxxxxxxxx' --data ''
Name | Type | Mandatory | Value |
---|---|---|---|
subscription_id | Url param | true | The unique subscription id returned by either the receipt callback or the transaction status api. |
requestid | param | false | used to identfy a request that must be eternally unique for your service. |
X-API-KEY | Header | true | The api key associated to this service. |
Response
For successful transactions it’s likely that you will receive a pending transaction as result. You will receive a callback receipt when the transaction has been processed.
{
"code":0,
"sessionId":"63HDB7ZW760WX2B9XM4GGRP83DJRJ1TE",
"message":"ok",
"transaction":{
"amount":100,
"sandboxmode":true,
"support_message":"",
"monumber":"447429482354",
"MerchantNotificationAttemptsCount":"1",
"statustext":"Successful transaction",
"statustime":"20200325171412",
"CHARGEMETHOD":"direct",
"moid":14000008,
"statuscode":"CHARGED",
"subscription_id":1,
"MerchantNotificationStatus":"Exception - INVALID_SSL",
"guid":"ccf0ce18-5c86-4d5e-91ba-db64793dda0f",
"userResponse":"Successful transaction. Mobile number billed"
}
}
Name | Type | Mandatory | Value |
---|---|---|---|
code | numeric | true | 0 in case of success or error code in the error codes table |
message | string | true | ok in case of success or message in the error codes table |
sessionId | string | true | Deprecated Please ignore this value |
transaction | transaction json | false | The new transaction associated to this re-bill request. |
transaction
Name | Type | Mandatory | Value |
---|---|---|---|
amount | numeric | true | The amount to be charged. |
sandboxmode | boolean | true | True for test or sandbox mode, false for live services |
support_message | String | true | Deprecated Please ignore this value |
monumber | String | true | The mobile number to bill for this transaction |
MerchantNotificationAttemptsCount | String | true | Deprecated Please ignore this value |
statustext | String | true | The human readable description of the current status of the transaction. Please check the status codes table. |
statustime | datetime | true | The creation datetime of this transaction. |
CHARGEMETHOD | String | false | The method used for the charge. Either PSMS or Direct billing (psms, direct). |
moid | numeric | true | The unique identifier associated to the mobile number used for billing. |
statuscode | String | true | The current status of the transaction. Please check the status codes table. |
subscription_id | String | true | The subscription id associated to the transaction (same as the one used to call this api) |
MerchantNotificationStatus | String | true | Deprecated Please ignore this value |
guid | String | true | The unique identifier for this transaction |
userResponse | String | true | Deprecated Please ignore this value |
Subscription status #
This API can be called at any time to retrieve the current status of a subscription.
Target URL: https://fpay.fonix.io/rest/subscriptions/status/{subscription_id}
Method: GET
Request values:
curl -v 'https://fpay.fonix.io/rest/subscriptions/status/1350512' --header 'x-api-key:xxxxxxxxxxxxx'
Name | Type | Mandatory | Value |
---|---|---|---|
subscription_id | URL Param | true | The unique subscription identifier of the subscription you want to retrieve |
X-API-KEY | Header | true | The API key of the service associated to this subscription |
Response type: JSON
{
"status":"OK",
"subscription":
{
"id":1350512,
"status":"INACTIVE",
"start_date":"2019-10-10 08:12:55",
"end_date":"2019-11-09 08:13:55",
"amount":999,
"currency":"GBP",
"billing_frequency":"1.MONTH"
}
}
Response
Name | Type | Mandatory | Value |
---|---|---|---|
status | string | true | OK or error codename |
message | string | false | Present only for errors – see messages in the error codes table |
subscription | JsonObject | see table below |
subscription
Name | Type | Mandatory | Value |
---|---|---|---|
id | numeric | true | The same subscription_id passed as parameter |
status | string | true | Status of the transaction in our side – it can be ACTIVE, INACTIVE or DELETED |
start_date | datetime | true | |
end_date | datetime | true | |
amount | numeric | true | The recurring amount of this subscription. This is the amount that will be taken from the end-user mobile credit for each re-bill request. |
currency | string | true | ISO 4217 currency code to be used for the subscription re-bill. Currently supporting ZAR and GBP and EUR. |
billing_frequency | string (numeric.string) | true | Number of units and time unit, for example 1.MONTH |
REFUND API #
Refund transaction #
The Fonix REFUND API allows merchants to refund a successful transaction made within the last 90 days.
If the refunded transaction is a subscription, the merchant can also expire the subscription by passing the expire-subscription parameter within the same request.
curl -X POST -i https://fpay.fonix.io/rest/transactions/{transaction-ext-id}/refund
-H X-API-KEY:live_1234abcdefg
-d expire-subscription=expire
Target URL: https://fpay.fonix.io/rest/transactions/{transaction-ext-id}/refund
Method: POST
Request Parameters:
Name | Type | Mandatory | Value |
---|---|---|---|
transaction-ext-id | Url param | true | The unique external transaction id. |
expire-subscription | param | false | expire |
X-API-KEY | Header | true | The api key associated to this service. |
Response
{
"transaction_external_id":"123abc",
"subscription_id":"123",
"subscription_status":"UNSUBSCRIBED",
"msisdn":"447400000000",
"status_code":"OK",
"message":"Successfully Refunded",
"amount_refunded":"150"
}
Name | Type | Mandatory | Value |
---|---|---|---|
transaction_external_id | string | false | The unique external transaction id |
subscription_id | string | false | The unique external subscription id |
subscription_status | string | false | UNSUBSCRIBED if subscription has been expired. |
msisdn | string | false | The end-user’s mobile phone. |
status_code | string | true | Code used to report the status of the request. |
message | string | true | A short description associated to the statuscode. |
amount_refunded | numeric | false | Amount refunded. |
Callbacks #
Callbacks are server-to-server requests that fPay sends you to notify you of changes related to your users that you may not be aware of.
Transaction notification #
The transaction notification or payment receipt is a server-to-server request that we make for every transaction you create through the create payment session API. You will only receive 1 notification per transaction unless we have problems reaching your servers. A notification to you is considered failed unless we receive a 2xx HTTP response code, any exceptions like timeouts or invalid ssl exceptions and any other response code will trigger a retry. Our retry policy is to attempt a notification every 10m for 24h for each transaction or until your server replies with a 200 code.
Target URL: Background notification url set in your service configuration or passed when creating the payment session. If both are set, the url passed when creating the payment session will be used
Method: POST
Values: Url encoded form
Name | Type | Mandatory | Description |
---|---|---|---|
STATUSCODE | string | true | All possible values in the status code column in the status code section |
STATUSTEXT | string | true | All possible values in the status text column in the status code section |
STATUSTIME | string | true | The date and time of the last time this transaction has been modified |
GUID | string | true | The guid or transaction id returned when you created a payment session. Unique identifier of the transaction |
AMOUNT | numeric | true | The amount paid by the end-user for this transaction. This value can be: The amount of the one-off payment set in the service configuration or passed on session creation or 0 for a free trial subscription or The amount set for the first transaction of a paid trial subscription or the amount of a normal subscription without trial or any amount set for re-bills of existing subscriptions. |
SID | numeric | true | The service id associated to this transaction |
MOID | numeric | false | If a msisdn has been associated to this transaction, the msisdn id is going to be returned in this parameter. |
MNO | string | false | If a msisdn has been associated to this transaction, the operator alias is going to be returned in this parameter. |
MONUMBER | string | false | If the transaction’s status is CHARGED, the end-user’s mobile number is going to be returned in this parameter. |
SUBSCRIPTIONID | numeric | false | This is the unique subscription identifier that you should use for our subscription APIs. This value is going to be present for most STATUSCODEs for payment flows, but you should only use it for positive status codes: CHARGED, ALREADY_SUBSCRIBED and SUBSCRIPTION_REACTIVATED when you actually need the value to perform operations for active subscriptions. For transaction notifications of re-bills, this value is always going to be present. |
SUBSCRIPTIONBILLINGFREQUENCY | |||
FREETRIAL | boolean | false | Deprecated This value shouldn’t be used as it doesn’t provide any useful information. This value can only be ‘true’ and only added if the service is free trial. You can derive this information on a transaction basis with the following logic: Amount=0 or first transaction |
TRIAL | boolean | false | Deprecated |
SANDBOXMODE | boolean | false | This value is going to be present only if the transaction was in test (sandbox) mode. And the only possible value is ‘true’. |
msisdnDetectionMethod | boolean | true | 3G (Mobile flow), MT (Token Flow) or HYBRID_FLOW (Hybrid Flow); |
requestid | string | false | This parameter is going to be sent back to you with the same value you used when creating the payment session (if present). |
tag | string | false | This parameter is going to be sent back to you with the same value you used when creating the payment session (if present). |
x_* | string | false | All parameters starting with x_ that you sent when creating the payment session will be sent back to you. |
Stop subscription notification #
Stop notifications are server-to-server requests that fPay send every time a user is unsubscribed from the Fonix platform. This callback has the same retry policy as the transaction notification callback. If the request triggers an exception or the response is different from 200, we will retry the same request every 10 minutes for 24 hours. This callback is triggered by:
- Stop api that you can call when a user unsubscribes from your side;
- User sends STOP to shortcode to end the subscription;
- When the subscription hasn’t been successfully renewed in the last 60 days.
Target URL: Unsubscribe url set in your service configuration
Method: POST
Values: Url encoded form
Name | Type | Mandatory | Description |
---|---|---|---|
MONUMBER | string | true | The msisdn of the user that has been stopped |
STOPTYPE | string | true | This value is always going to be ‘STOP’ |
SUBSCRIPTIONID | numeric | true | The subscription id of the subsription that has been stopped |
Post-payment flow user redirection #
The last step you should be able to handle is when the end-user is redirected back to your website. After a successful or failed transaction we present a final screen and the end-user can click on the continue button to be redirected back to your website. When you start thinking about handling a redirected user you should keep in mind a few points:
- Not all users are redirected, so you can’t use this strategy to get accurate information about a transaction. Always use either the transaction notification callback or query the status of the transaction to securely retrieve payment information;
- Data goes through the end-user’s browser, this means that any parameter we pass during the redirect could potentially be changed by an attacker. This means that you shouldn’t rely only on these information – you should either wait for a transaction notification callback or query the status of the transaction;
- In case of network problems (i.e. timeouts, invalid ssl certificate, connection dropped, delays, etc) you may receive the transaction notification callback at any point after the user has been redirected back to you; To avoid this you can adopt a hybrid solution where you use the query transaction status API if you didn’t receive a notification yet when a user is redirected or tries to access the content or use the query transaction status API only or keep waiting for the background notification, but you can give advanced access to the user by comparing the s_token parameter passed by the redirected user with the secret_success_token.
In your service configuration or when you create a payment session you can specify 2 different URLs: success and failure. The user will be redirected to your success url for the following transaction status codes: CHARGED, ALREADY_SUBSCRIBED and SUBSCRIPTION_REACTIVATED and to the failure url for any other status code or when the end-user clicks on the Cancel button.
Below a table of all the parameters that you will receive when the user is redirected back to you through the success url:
Name | Type | Mandatory | Description |
---|---|---|---|
rsid | string | true | Deprecated The payment session id – new clients should ignore this. |
tid | string | true | The transaction external id or GUID that we pass back to the create payment session API and the transaction notification callback. This is the fPay unique transaction identifier that can be used to query the status of the transaction in the query transaction status API. |
s_token | string | true | This value must match the secret_success_token returned by the create payment session API. |
tag | string | false | This value is present only if you passed it to the create payment session API and it’s going to return the same value. |
requestid | string | false | This value is present only if you passed it to the create payment session API and it’s going to return the same value. |
x_* | string | false | Every custom parameter you sent us at the create payment session API (starting with x_) is going to be sent back to you with the same values. |
Below a table of all the parameters that you will receive when the user is redirected back to you through the failure url:
Name | Type | Mandatory | Description |
---|---|---|---|
rsid | string | true | Deprecated The payment session id – new clients should ignore this. |
tid | string | true | The transaction external id or GUID that we pass back to the create payment session API and the transaction notification callback. This is the fPay unique transaction identifier that can be used to query the status of the transaction in the query transaction status API. |
cancel | string (prepay, postpay) | false | postpay value has been deprecated This value is added only if the user clicks on the cancel button. Since postpay has been deprecated, the value is always going to be prepay. |
origin | string (cancel, retry) | true | Value is going to be retry if users have been redirected because they pressed on the retry button (payment failed) or cancel if the cancel button was clicked. |
s_token | string | true | This value must match the secret_failure_token returned by the create payment session API. |
tag | string | false | This value is present only if you passed it to the create payment session API and it’s going to return the same value. |
requestid | string | false | This value is present only if you passed it to the create payment session API and it’s going to return the same value. |
x_* | string | false | Every custom parameter you sent us at the create payment session API (starting with x_) is going to be sent back to you with the same values. |
Codes #
Error codes #
The following is a list of all the errors that we could display in the badconfig error page.
Error code | Error message |
---|---|
0 | Unknown error |
1 | Your transaction has expired |
2 | No service Id (sid) provided |
3 | No service or service not active |
4 | Invalid frequency |
5 | Your session has expired |
6 | Subscription donation is not available for the payforit screens |
7 | No session data available |
8 | Invalid transaction id |
9 | Address not valid |
10 | No terms and conditions found |
11 | Parameter format not valid |
12 | No default amount defined |
13 | Invalid amount. Amount to bill is over the limit |
14 | Unable to retrive the failure page |
15 | Unable to retrive the success page |
17 | This service is not allowed to be displayed in embed mode |
18 | You are not authorized to access this page. |
19 | The request must include the mobile number. |
20 | No service provided. |
21 | This service is not configured correctly. |
22 | This service is not configured correctly. |
23 | This service is not supported for UI customisation |
24 | Redirect session not found |
25 | You’ve been rate limited. Please try again. |
26 | Payment validation failed. Please make sure Javascript is enabled and try again. |
27 | Payment validation failed. Please try again. |
28 | Some or all messages haven’t been configured. Please contact customer service. |
29 | Sending message between 8 PM and 8 AM is prohibited. Please try again in regular hours |
The following is a list of all the errors you could get as response to API calls.
Error code | Error message |
---|---|
2000 | Response format is not valid or service is not properly configured. |
2001 | Invalid response code. |
2002 | Pricepoint not found for this service. |
2003 | Vodacom service id not found. |
2004 | No Vodacom subscription found. |
2005 | Response payload information not found. |
2006 | Response format is not valid or service is not properly configured. |
2007 | Invalid response code. |
2008 | Error in the response or subscription details not found. |
2009 | No transaction data available. |
2010 | Unsuccessful attempt to unsubscribe at Vodacom. |
2011 | Error in the response. |
300000 | Sorry, an unexpected error has occurred. Please try again. |
300001 | Sorry, the mobile number inserted doesn’t have the right format. Please try again. |
300002 | Invalid service id passed. |
300003 | Sorry, an unexpected error has occurred. Please try again. |
300004 | This transaction doesn’t exist or the the API Key is not valid. |
300005 | Sorry, an unexpected error has occurred. Please try again. |
300010 | Sorry, an unexpected error has occurred. Please try again. |
300011 | Already subscribed to this service. Please click on the button to continue using the service. |
300012 | Sorry, an unexpected error has occurred. Please try again. |
300013 | Payment is still processing; try again later |
300014 | Sorry, an unexpected error has occurred. Please try again. |
300015 | Sorry, an unexpected error has occurred. Please try again. |
300016 | HLR Lookup failed. |
300017 | Your Mobile Operator does not support this purchase option. Please return to the previous page and select another payment option. |
300018 | Invalid amount. Amount to bill is over the limit |
300019 | There is no default amount defined in the service and no amount was provided |
300020 | HLR Lookup failed. |
300021 | The number provided has been blocked. |
300101 | Sorry, an unexpected error has occurred. Please try again. |
300102 | Sorry, an unexpected error has occurred. Please try again. |
600003 | Sorry, an unexpected error has occurred. Please try again. |
600015 | Sorry, but you don’t have privileges. Please contact our support team. |
600016 | Sorry, you did not provide a service type |
600017 | No subscriptionID found |
600018 | Invalid SubscriptionID |
600019 | No API Key provided. Access Denied |
600020 | API_KEY mismatch. This API Key does not belong to this service |
600025 | This subscription is no longer active |
600026 | Msisdn not found. |
600027 | This Msisdn has no active subscriptions. |
600036 | No External Id. |
600100 | Sorry, an unexpected error has occurred. Please try again. |
600101 | Please insert a valid token. |
600102 | That’s an invalid token. Please try again. |
600103 | Please insert a valid msisdn. |
600104 | Your payment session has expired |
600105 | Sorry, an unexpected error has occurred. Please try again. |
600106 | Max number of pin retries reached. |
600107 | Too many invalid entries |
600108 | This mobile number reached the maximum number of failed pin verifications. Please wait 24h before trying again. |
600109 | The token has expired. |
600201 | Sorry, an unexpected error has occurred. Please try again. |
600203 | Sorry, an unexpected error has occurred. Please try again. |
600301 | Sorry, an unexpected error has occurred. Please try again. |
600302 | This subscription is no longer active” |
700002 | This service is restricted to users 18 and older. If you are 18 or older, contact your mobile provider to verify your age. |
900000 | Sorry, an unexpected error has occurred. Please try again. |
900001 | Unable to send reminder message. |
Status codes #
STATUSCODE | STATUSTEXT |
---|---|
CREATED | User landed on the payment page |
REQUESTED_MSISDN | Sent validation code to retrieve msisdn |
READY | Transaction is ready to be billed |
PENDING | The request is still processing |
CHARGED | Successful transaction |
INSUFFICIENT_FUNDS | Insufficient credit |
OPERATOR_REJECTED | Request not accepted by operator |
BARRED_MVNO | Request not accepted by virtual mobile operator |
MAX_SPEND_MSISDN | Daily user spend limit exceeded |
OPERATOR_ERROR | Request not accepted by operator |
PERMANENTLY_BARRED | User is permanently barred from request type |
TEMPORARY_BARRED | User is temporarily barred from request type |
TEMPORARY_FAILURE | A temporary failure prevented processing |
UNKNOWN_MSISDN | Mobile number not known to operator |
UNREACHABLE_MSISDN | User mobile is switched off or absent |
UNROUTABLE | We can’t process the request due to a missing route |
UNKNOWN_ERROR | The request failed due to unknown reasons |
ALTERNATE_MSISDN | Selecting an alternate mobile |
ALREADY_SUBSCRIBED | Already subscribed to this service |
INVALID_ORIGINATOR | Originator not accepted by operator |
SMSC_ERROR | Operator SMSC encountered a processing error |
TEMPORARY_OPERATOR_ERROR | Request temprorarely failed by operator |
INVALID_OPERATOR_SERVICE | Request type not accepted by operator |
PERMANENT_OPERATOR_ERROR | Request permanently failed by operator |
ALREADY_PENDING | Already a pending transaction for that user and service |
OPERATOR_TIMEOUT | The billing request has timed out |
D2B_BARRED | User is barred from direct billing |
INVALID_MSISDN | Mobile number not accepted by operator |
SOCKET_CLOSED | SocketException Socket closed |
INVALID_REQUEST | The request is invalid |
MSISDN_NOT_VERIFIED | Msisdn not verified |
MSISDN_VERIFIED | Msisdn verified |
MSISDN_VERIFICATION_TIMEOUT | Msisdn verification timeout |
OPERATOR_NOT_FOUND | Operator not found (HLR Lookup failure) |
OPERATOR_FOUND | Operator found (HLR Lookup success) |
AV_NOT_AUTHORIZED | Service not authorized to perform AV check |
HLR_LOOKUP_NOT_AUTHORIZED | Service not authorized to perform HLR lookup |
OPERATOR_DISABLED | This operator is disabled |
SUBSCRIPTION_REACTIVATED | Subscription has been reactivated |
SECTOR_NOT_ALLOWED | Content block enabled, please call your operator to deactivate it. |
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 tomorrow. |
OPERATOR_SRV_MONTHLY_MAX_SPEND | Sorry, you’ve spent all you can this month, come back tomorrow. |
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 |
TRANSACTION_EXPIRED | The session has timed out, please try again. |
TRANSACTION_WORKFLOW_REBILL_BLOCKED | Rebill Blocked |
TRANSACTION_WORKFLOW_PIN_MAX_ATTEMPTS | Max pin attempts reached |
DAILY_MAX_SPEND_MSISDN | Daily user spend limit exceeded |
MONTHLY_MAX_SPEND_MSISDN | Monthly user spend limit exceeded |
PAYMENT_VALIDATION_FAILED | Payment validation failed. Please make sure Javascript is enabled and try again. |
COUNTRY_NOT_ALLOWED | Country not allowed |
USER_CANCELLED | Transaction cancelled by user |
Operator aliases #
Operator Alias | Operator |
---|---|
voda-uk | Vodafone United Kingdom |
eeora-uk | Orange UK (EE) |
o2-uk | O2 UK |
three-uk | Three UK |
eetmo-uk | T-Mobile UK (EE) |
virgin-uk | Virgin UK |
ee-uk | EE UK |
sky-uk | Sky UK |
voda-za | Vodacom South Africa |
unknown | Operator not available |
Integration checklist #
Single payment and Donation #
- Initiate a payment session;
- Handle transaction notification callback;
- Handle redirected user after a successful or failed transaction.
Subscription #
- Initiate a payment session;
- Handle transaction notification callback;
- Handle redirected user after a successful or failed transaction;
For successfull payment flows only:
- Trigger re-bills at every billing frequency;
- Handle stop subscription notification callback;
- Notify us of any subscription you close on your side.
Subscription with paid or free trial #
- Initiate a payment session;
- Handle transaction notification callback;
- Handle redirected user after a successful or failed transaction;
For successfull payment flows only: