NAV
shell

What is fpay?

fpay is Fonix’s Payforit billing solution, offering a quick and easy way to integrate mobile billing into your website.

How it works

To use fpay you are first required to be a registered merchant with us.

After creating an account you’ll be able to access your Dashboard through accounts.fonix.io, where you can check stats and generate html buttons to embed onto your website.

This will present users with the option to pay for products or services using operator billing, all according to PayforIt regulations. For every purchase we will keep a record and notify you in the background.

Security and connectivity

Example API KEY:
 X-API-KEY:live_123456789abcdefg

On Account creation we will give you an API Key. This is to be used in all API calls to https://fpay.fonix.io.

The API key must be added as a HTTP header to all API requests. The key:value pair for the header is X-API-KEY:apiKey

Creating a Service

Account service fields

Before using the API, a service has to be created and a number of parameters configured. A service ID (sid) is created in the process to uniquely identify the product or service you’re selling.

Here is a list of required and optional parameters to use when creating a service. Some parameters can also be overwritten dynamically (customised) through the create session API.

(*) Mandatory fields

After you create your service it will be in a Pending Approval state. Client Services will be contacted automatically to configure and add an API Key to your service. This is a manual process and may take 1 day (during normal UK working hours).

Advanced

Uploads

Extra

The payment screens

After a service is created and configured, to access the payment screens you will need the sid (service ID). Here’s an example of a payment for a service with [sid] using html code:

<a href="http://fpay.co/?sid=[sid]">Buy Now</a>

Mandatory parameters

sid - This required integer is the Service ID of this service or product.

Dynamic customisation

The payment link to a service can be customised, where any of the above allowed variables can be overwritten.

Name Type Description
type string Use embed as value if you want to embed the payment screen in your website within an iframe.
custom boolean (true or false) Shows either the payforit screens (false) or the fonix screens (true).
requestid up to 80 characters (0-9, a-z, A-Z) An optional string for passing through your unique reference ID for a transaction. The value will be returned to you on the notification, success and failure URLs.
tag up to 80 characters (0-9, a-z, A-Z) An optional string that you can use to further identify payments. The value will be returned to you on the notification, success and failure URLs.
x_{your param name} string You can send us as many custom parameters as you need (e.g. x_user_id) and we will send them back to you to the failure, success and notification url.

Embed Flow

There is also the option to display Payforit embedded on your page, rather than through a button link. To do this, please add type=embed on an iframe link.

An example of an embed payment for a service using html code:

<iframe src="http://fpay.co/?sid={your service id}&type=embed"></iframe>

To embed the payment page into your website you need client service’s approval.

General error codes

In some circumstances you or your customers could be redirected to a “Bad configuration page” displaying the error code that triggered this event. Below the table explaining the meaning of each code:

Code Name Description
0 UNKNOWN_ERROR Unexpected error - might be an internal issue or you are requesting an unknown resource or using the wrong HTTP Method.
2 NO_SERVICE_ID_PROVIDED You requested a resource without sending your service id.
3 NO_SERVICE_OR_SERVICE_NOT_ACTIVE The service id provided doesn’t exist or is no longer active.
4 INVALID_FREQUENCY The billing frequency passed is not valid.
5 SESSION_EXPIRED The payment session is no longer active.
6 SUBSCRIPTION_DONATION_PAYFORIT Subscription donation is not available for payforit.
7 NO_SESSION_DATA Invalid session id.
8 INVALID_TRANSACTION_ID The transaction id doesn’t exist.
9 ADDRESS_NOT_VALID The address provided on session creation is not valid.
10 NO_TERMS_FOUND You didn’t provide any Terms and Conditions.
11 CUSTOM_NOT_ALLOWED Your service is not enabled to use the Fonix screens - you can use payforit only. You need client service’s approval to be able to use them.
12 NO_AMOUNT_DEFINED No default amount has been setup in your service configuration or passed on session creation.
13 AMOUNT_OVER_LIMIT The amount is exceeding the limit of £10. You can contact client services to be able to bill up to £30.
14 NO_FAILURE_PAGE_FOUND The user clicked the exit button but the service is not configured with a failure url.
15 NO_SUCCESS_PAGE_FOUND The user clicked on the continue button but the service is not configured with a success url.
17 EMBED_NOT_ENABLED Your service is not enabled to be used within an frame. You need client service’s approval to be able to do it.
18 NOT_AUTHORIZED You are not allowed to see the requested screen.
19 MOBILE_NOT_PASSED Some services are configured to bill only the msisdn passed on session creation - the request didn’t have this parameter.

Simulate payment errors

When your service is in Test mode (Sandbox mode) you can simulate some of the most frequent payment errors passing the appropriate code to the create session api. Here the table with the codes and the expected transaction status we’ll send you through the background notification url.

https://fpay.fonix.io/rest/sessions/create?sid={your service id}&sandboxErrorCode={code}
Code STATUSCODE
3006 INSUFFICIENT_FUNDS
3009 MAX_SPEND_MSISDN
3011 PERMANENTLY_BARRED
3012 TEMPORARY_BARRED
3014 UNKNOWN_MSISDN
3017 UNKNOWN_ERROR
3024 PERMANENT_OPERATOR_ERROR
3025 ALREADY_PENDING
3026 OPERATOR_TIMEOUT
3034 OPERATOR_NOT_FOUND
3036 AV_NOT_AUTHORIZED
3038 OPERATOR_DISABLED

Please refer to the Code Reference Section for more informations about STATUSCODE

Custom payment screens

Rather then using the default payforit screens you may want to use our new payment screens. To do so, you first need approval from client services and then we will display them instead of payforit.

One of the biggest advantages of the custom screens is the possibility to fully customise their appearance by simply uploading your CSS file into our platform. For security reasons when your service is in test mode you will be able to pass the url of your custom css on session creation passing the parameter cssUrl={url to the css}, making sure that it is uploaded on the same domain whitelisted in the “Site Url” field in your service configuration. Once your service goes live you won’t be able to pass this url so you must send it to us - we will review it and if everything is fine we will set it up on your service.

The Payment Flows

All the payment flows have 2 screens as mandated by the Mobile Network Operators. The first screen is where the payment details are displayed to the user and the second screen is where the user confirms acceptance of the payment.

Msisdn Flow

When the user accesses the payment screens using a mobile device on 3G / 4G, we are able to detect the MSISDN, in this instance we display the payment screens without the consumer entering their mobile number.

MT Flow

When the user is on WIFI we are unable to detect the MSISDN, in this instance we display the first screen with a MSISDN entry box. On entering the MSISDN the user is sent a token / pin via SMS which then needs to be entered on the second screen in order to verify the MSISDN and confirm payment.

Hybrid Flow

When we detect the MSISDN of the user, but the Mobile Network Operator does not allow the MSISDN flow, we display a hybrid pin flow which is a combination of the MSISDN and the MT flow. The first screen is where the payment details are displayed to the user, without the requirement to enter a MSISDN, the second screen, is where the user needs to input the pin / token displayed on the screen into a field entry box to confirm acceptance of the payment.

Flexible Amounts

As part of Fonix’s drive to improve our products, we have implemented the ability for clients to charge flexible price points on our fpay platform for single payments only. The new functionality will enable you to specify a dynamic value to charge your customers in increments of a single penny (£0.01).

To request a price point for your clients, you will first have to make a call to fpay to request a session ID to be generated. This session ID will be provided with an accompanying URL that can be forwarded to the client to process the payment.

Workflow

Here’s an example of the workflow to request and present a payment screen with a custom amount.

Workflow

No Step Description
1 Ready to make payment The user has indicated that they would like to make a purchase and has requested the payment screen
2 Request payment page The merchant must send a request to PFay to request the payment page for a specified variable amount
3 Generate unique session and forward URL fpay will return a unique session ID and a bespoke URL to forward to the client
4 Forward redirect to customer for payment The customer can now be forwarded to the URL provided by fpay for payment
5 Customer makes payment At this point the customer has successfully made payment on the fpay screen and notification has been sent to fpay. The customer will already have seen a successful payment screen
6 Payment notification fpay will provide a notification back to the merchant on the success (or failure) of payment

Session creation API call

To enable the usage of flexible amounts, a merchant must first request a session ID from the fpay Servers.

The call

https://fpay.fonix.io/rest/sessions/create

Merchants must perform a GET request to the url

Mandatory headers

X-API-KEY:live_abcdef123456

X-API-KEY - the api key of the service for which you are requesting a session id for. This must be added to the headers of the call

Mandatory parameters

https://fpay.fonix.io/rest/sessions/create?sid=100000

sid - This required integer is the Service ID of this service or product.

Optional parameters

You can customize the payment screens by adding the parameters below

Name Type Description
type string (embed) Use embed as value if you want to embed the payment screen in your website within an iframe.
custom boolean (true or false) Shows either the payforit screens (false) or the fonix screens (true).
requestid up to 80 characters (0-9, a-z, A-Z) An optional string for passing through your unique reference ID for a transaction. The value will be returned to you on the notification, success and failure URLs.
amount Numeric value in pence to charge. This will override the default value
frequency string The billing frequency. This will override the default value
mobile string (format 07XXX or 447XXX) This value will prepopulate the MSISDN (mobile number) input box if the user is on WIFI.
successUrl string (An absolute URL http://my.full.url/?with=parameters) Populate this field to override the services default success URL.
failureUrl string (An absolute URL http://my.full.url/?with=parameters) Populate this field to override the services default failure URL.
notifyUrl string (An absolute URL http://my.full.url/?with=parameters) Populate this field to override the services default notification URL.
cssUrl string (An absolute URL http://my.full.url/css/fonixscreens.css) Test services and Fonix screens only - you can pass a css url to customise the fonix screens. This css can be uploaded in the whitelisted domain specified in “Site URL” in your service configuration. You won’t be able to pass this field anymore when you service goes live so once you finished your tests you can send it to us and we will set it up for you.
tag up to 80 characters (0-9, a-z, A-Z) An optional string that you can use to further identify payments. The value will be returned to you on the notification, success and failure URLs.
imageUrlFirstButton string (An absolute URL http://my.full.url/images/firstscreen.jpg) Overrides the image specified in the service configuration as “Image url first screen”. The image must be hosted in the same domain whitelisted in “Site URL” in your service configuration.
imageUrlSecondButton string (An absolute URL http://my.full.url/images/secondscreen.jpg) Overrides the image specified in the service configuration as “Image url second screen”. The image must be hosted in the same domain whitelisted in “Site URL” in your service configuration.
sandboxErrorCode Integer (list of allowed values below) Test services only - if passed, it allows you to simulate the most common errors that might occur while we process a payment. Fpay will send you a notification as it would do for a normal transaction.
x_{your param name} string You can send us as many custom parameters as you need (e.g. x_user_id) and we will send them back to you to the failure, success and notification url.

The response

{
    "code":0,
    "message":"ok",
    "session":{
        "redirectUrl":"newpayment.jsp?rsid=F112345678963E4335336BAA7GEE84"
    }
}

The response will be in JSON format and will have the following keyword:value pairs

keyword value
code a response code, 0 will mean success, any other number is a failed request.
message a response message, this will contain the description for the response code above.
session.redirectUrl the relative URL to redirect the user to, a merchant should redirect the user to http://fpay.co/newpayment.jsp?rsid=123456…etc

Notifications

Example Payment Notification

POST /path/transaction HTTP/1.1
Content‐Type: application/x-www-form‐urlencoded
Connection: Keep-Alive

STATUSCODE=CHARGED&STATUSTEXT=Successful+transaction&GUID=987654321&REQUESTID=123
&STATUSTIME=20140901102030&AMOUNT=150&TAG=web&MOID=184001&x_custom=extra+info

If you specify a background notification url in the service configuration, fpay will invoke an asynchronous background HTTPS POST to that url for each transaction. The POST will contain information about the payment transaction, as well as any custom variables sent along with the transaction.

The parameters sent to you in the Notification API can be found in below:

Check the status of a payment

Example

{
    "transaction": {
        "guid": "123456789",
        "statuscode": "CHARGED",
        "statustext": "Successful transaction",
        "requestid": "ABCDEFGH",
        "statustime":"20140901235959",
        "amount":"150",
        "tag":"web",
        "moid":"184001",
        "monumber":"447700000000",
        "x_custom":"I am a custom variable",
    }
}

You can query the status of a payment at any time to confirm it’s been successfully billed by sending a GET request to the URL below, including your transactionId:

https://fpay.fonix.io/rest/transactions/<transactionId>

We will return the same parameters as we would send in the Notification API above.

Here are the possible status for a payment

Subscriptions

Sometimes you will want a user to subscribe to a service rather than asking them to perform one-off payments. You can create a Subscription service and after the user has subscribed, you can use fpay to bill them.

How it works

Example

{
    "transaction": {
        "guid": "123456789",
        "statuscode": "CHARGED",
        "statustext": "Successful transaction",
        "requestid": "ABCDEFGH",
        "statustime":"20140901235959",
        "amount":"150",
        "moid":"184001",
        "monumber”:”447700000000",
        "subscriptionId”:”123456"
    }
}

We will create a “subscription type” service in the fpay dashboard. When a user makes a payment (subscribes) to this service, we will generate a subscriptionID and send it in the #backgroundNotifyURL of the success call:

You can then make a POST requests to fpay with this subscriptionID and we will bill the user:

https://fpay.fonix.io/rest/subscriptions/<subscriptionID>

Your API key must be added as a HTTP header. The key:value pair for the header is X-API-KEY:live_123456789abcdefg

We will send a post to the background notification url defined in the service and return the transaction report:

backgroundNotify POST

Example subscription notification

POST /path/transaction HTTP/1.1
Content‐Type: application/x-www-form‐urlencoded
Connection: Keep-Alive

STATUSCODE=CHARGED&STATUSTEXT=Successful+transaction&GUID=987654321&REQUESTID=123
&STATUSTIME=20140901102030&AMOUNT=150&MOID=184001
&SUBSCRIPTIONID=123456

The notification POST in subscriptions is the same as the single payment, with the addition of the SUBSCRIPTIONID

Inactive Subscriptions

{
    "message": "This subscription is no longer active",
    "code": 600025
}

If the subscription is inactive (because the user has sent in a STOP request), when attempting to bill a subscribed user you should see the following

Unsubscribe (STOP requests)

If a user is subscribed to a service, they can unsubscribe by sending a STOP SMS message to us. The user will then be unsubscribed from the last service they subscribed to and we will POST the STOP request to the unsubscribeUrl configured in your service.

If the user texts STOP ALL, then we will unsubscribe them from all subscription services.

If the user contacts you directly to stop a subscription we ask that you make an API call to us to inform us of this stopped subscription. You simply need to POST either the MSISDN to the following URL:

https://fpay.fonix.io/rest/subscriptions/msisdn/447700000000/stop

Unsubscribing a service will mark the subscription as inactive, this means if you try to bill the subscription it will show that “This subscription is no longer active”, however, if there is time left on a susbcription (for e.g. user unsubscribes after 2 days on a 7 day subscription) and the user subscribes again, we will reactivate the subscription ID and send a SUBSCRIPTION_REACTIVATED status code.

Free Trial Susbcriptions

If you wish, you can provide a free trial period to your users. To do this, you will need to tick the “Free trial” checkbox in your service configuration. This will enable your service to provide a free trial period. You will be asked to set a “Free trial amount” and a “Free trial measure” (for e.g. 24 hours, 2 day, 1 month, etc).

Example free trial subscription notification

POST /path/transaction HTTP/1.1
Content‐Type: application/x-www-form‐urlencoded
Connection: Keep-Alive

STATUSCODE=CHARGED&STATUSTEXT=Successful+transaction&GUID=987654321&REQUESTID=123
&STATUSTIME=20140901102030&AMOUNT=150&MOID=184001
&SUBSCRIPTIONID=123456&FREETRIAL=true

When a user subscribes we will not bill them, we will generate a subscription ID and send a new keyword:value in the notification POST, FREETRIAL=true

SMS examples

Here are a list of example messages for all the different stages/flows of using fpay

Pin verification message

"FreeMsg: To verify your mobile number and continue with purchase of <service_name> for <price> from <merchant> enter <pin> Help? <cc_number>"

This is the message we send after the user inserts their mobile number on the payment screen and can change based on the type of the service. This is because the user is on Wifi flow or we are unable to detect the msisdn.

Receipt message (Single payment)

"Thank you for your payment of <price> for <service_name> from <merchant>. Help? <cc_number>"

This is the message a user will receive immediately after a payment has been successful

Receipt message (Subscription)

"Thank you for subscribing to <service_name> for <price> per <billing_frequency> from <merchant> until you text STOP to <stop_shortcode>. Help? <cc_number>."

This is the message a user will receive immediately after a payment has been successful on a subscription service

Receipt message (Free trial Subscription)

"Thank you, your free trial of <service_name> from <merchant> will end on <date>. Then <price> per <billing_frequency> until you text STOP to <stop_shortcode>. Help? <cc_number>."

This is the message a user will receive immediately after a payment has been successful on a subscription service

Reminder message (Subscription)

"Reminder. You are subscribed to <service_name> for <price> per <billing_frequency> from <merchant> until you text STOP to <stop_shortcode> Help? <cc_number>"

This is a reminder message that is sent automatically to users who are subscribed to a service. this message is sent for every £20 spent, or every 30 days, whichever comes first.

STOP message (Subscription)

"FreeMsg: You have been unsubscribed from <merchant> until you text STOP to <stop_shortcode> Help? <cc_number>"

This is the message we send when a user unsubscribes from the service

Updates

Those informations may change over time. If you’d like to see all the latest text messages please refer to the payforit examples.

Document Version

v1.0

Fonix