Initializing a payment

In order to use Web SDK in advanced mode you can specify additional parameters while calling the payment flow.

Endpoint URL:

https://pay.fortumo.com/mobile_payments/[service_id]?[parameter=value pairs]

Add additional parameters by defining the "rel" attribute while creating a payment button:
1
2
3
<a id="fmp-button" href="#" rel="YOUR SERVICE ID?cuid=userId123&operation_reference=order_12345&msisdn=37255555555">
<img src="https://assets.fortumo.com/fmp/fortumopay_150x50_red.png" width="150" height="50" alt="Mobile Payments by Fortumo" border="0" />
</a>

Example URL:

https://pay.fortumo.com/mobile_payments/e2bbf830a55f565375915a94f3309cc?cuid=userId123&operation_reference=order_12345&msisdn=37255555555

An informational XML data sheet is available with price points for each service. This data sheet lists all currently enabled countries, price points and corresponding virtual credit amounts.

The XML file for your service can be accessed using the following URL:

http://pay.fortumo.com/mobile_payments/[service_id].xml

Payment initialization parameters

Below is the full list of parameters that can be used for initializing a payment. When initializing the payment, all parameters should be URL encoded.

Parameter Type Required Description
service_id String Mandatory Specific service you have created on Fortumo dashboard. Example: e2bbf830a55f565375915a94f3309cc
cuid String Optional Specific user record internal to your system. Helps you match every payment to a specific user of your service. In order to prevent fraud we can limit how often one cuid can make a payment. To use this feature please contact Fortumo customer support. Example: Username21
operation_reference String Optional Matches every specific Fortumo payment to specific orders internal to your system. Different from cuid in that it should be unique per every transaction. Example: order_12345
credit_name String Optional Overrides the default credit name value you have configured for your service on Fortumo dashboard. Can be useful in case you are using one Fortumo service for selling several different types of virtual credits. Available only for virtual credit services. Example: purple unicorns
product_name String Optional Overrides the default product name value you have configured for your service on Fortumo dashboard. Can be used with both single item and virtual currency services. When used with virtual credit services, product_name parameter should be used together with tc_amount (should be set as 1) and tc_id. Example: weekly access
price Float, 2 decimals Optional Overrides the virtual currency exchange rate specified on Fortumo dashboard. Price parameter defines the real currency base amount and should be used together with parameters currency and amount. Example: 5.00
currency String, ISO 4217 Optional Overrides the virtual currency exchange rate specified on Fortumo dashboard. Currency parameter specifies the real currency against which virtual currency is converted to. Example: EUR
country_code String, ISO Alpha-2 Optional Preselects consumer country. Can be useful in case your consumers are known to use VPNs, but you have knowledge about their real location. Example: MY
language_code String, ISO Alpha-2 Optional Preselects consumer language. Can be useful in case you want to set a default language for your payment flows. Example: EN
amount Integer Optional Overrides the virtual currency exchange rate specified on Fortumo dashboard. Amount parameter specifies the number of virtual credits that are being sold for the real price and currency also specified in the payment request. Example: 100
display_type String Optional Specifies the virtual currency exchange rate base (user or owner). In case specified as user, consumer will pay X amount of money for Y credits. In case specified as owner, you as a service owner will receive X payout for Y amount of credits sold. Example: user
tc_id Integer Optional Allows you to preselect a specific price point for virtual credit services. Can be used independently, but also together with tc_amount parameter. Tariffclass ID values can be fetched from your service .xml. Example: 39
tc_amount Integer Optional Defines a specific amount of credits that you want to sell at a specified tariffclass. Example: 199
msisdn Integer Optional Prefills consumer phone number in the payment flow in case you already know that. For example from their signup process. Phone number must be in international format (incl country calling code), but must not include the + sign before country calling code. Example: 61234556789
mcc Integer Optional Mobile country code. Used together with mobile network code allows you to preselect consumer carrier in countries with carrier selection. Example: 722
mnc Integer Optional Mobile network code. Used together with mobile country code allows you to preselect consumer carrier in countries with carrier selection. Example: 310
msisdn_edit_disabled Boolean Optional Used together with mobile country code and mobile network code in case you need to prevent consumers from making payments from phone numbers other than they have signed up with. Example: true / false
test String Optional Initialize a payment in sandbox mode even after the service has already been switched live. In case test parameter value is set as ok, sandbox payment is processed successfully. In case test parameter value is set as fail, unsuccessful sandbox payment is processed. Example: ok / fail
sig String Mandatory Protects your payment request from being tampered by third parties. Example: 37aa1c8b8659ebdd7b5e7cf88af485ef
callback_url String Optional Overrides the return to merchant URL configured on Fortumo dashboard. This is the URL where your consumers are directed back after completing the payment. Example: https://your-website.com/cuid/payment-successful

Signature

The signature is added as sig parameter and is calculated as md5 checksum of the request parameters and secret concatenated together. You can find your service secret from the service settings page on Fortumo.com Dashboard. To check whether the sig parameter in the request matches the one that you calculated you can make the same calculation. 

Before calculating the signature:

  • It is important to sort the parameters alphabetically.
  • Parameter values (e.g. callback_url) should be URL decoded (though they have to be encoded prior to composing payment URL).
  • Exclude service_id parameter from the signature calculation.
  • If you're using CUID, make sure to include it in the calculation as cuid parameter.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
PARAMETERS
credit_name = gold
tc_amount = 3333
tc_id = 291
test = ok
secret = bad54c617b3a51230ac7cc3da398855e

CALCULATION STRING
credit_name=goldtc_amount=3333tc_id=291test=okbad54c617b3a51230ac7cc3da398855e

MD5 RESULT AS SIGNATURE
sig = 047f555536f8826825c9079265ad36de

Do not expose your service secret, it allows clients to edit parameters such as tc_amount which can lead to "free" credits.

Help us improve our Merchants Portal. Was this article helpful?