FPAY Carrier Billing API (Checkout)


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

fPay token flow

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.

fPay 3g flow

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.

fPay token flow

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.

fPay single payment with token flow

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.

fPay donation with token flow

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.

fPay subscription with token flow

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.

fPay subscription free trial with token flow

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.

fPay subscription paid trial with token flow

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.

Workflow

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:

Delayed notification diagram

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.

Query transaction status flow

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 #

Subscription #

For successfull payment flows only:

Subscription with paid or free trial #

For successfull payment flows only:

Powered by BetterDocs

How we work with brands