Internet + Subscription
Developer Starter GuideVersion 1.1
12 Aout 2019
MobiyoPôle Produit94 Rue de Villiers 92832 Levallois Perret Cedex – France
SAS au capital de 2 486 196€, RCS Paris 824 638 209, N° TVA Intracommunautaire : FR61 824 638 209, Code APE : 6201Z
TABLE OF CONTENTS
Table of contentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Anatomy of a web subscription script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Web subscription workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Mobile Subscription workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Finalizing your transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Error window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Aborted payment window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Success payment window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Set-up products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Add a product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Payment URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Payment scripts integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Website Subscription script integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Direct redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Product page access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Unsubscription script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Generic link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Simplified link (Only available for Internet + mobile ‘MPME’) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Unsubscription workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Notification of a new subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Notification of a renewal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Notification of a cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Signature verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Check the signature of a notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Signature verification example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Introduction
Overview
Description :
Scripts :
A subscription is presented as a product in which the customer can have several offers associated with it.
For each offer, it is possible to define a name, description, billing frequency and a list of price levels by country (see "Anatomy of subscription script").
The scripts available are :
Status : Parameter : Description :
Mandatory Subscription script This script is an Mobiyo pay-ment page. It lets the end user select the offer and the pay-ment method, and then follow the instructions to complete the subscription.
Mandatory Unsubscription script The customer is asked to enter his Mobiyo subscriber reference and the telephone number or the email address used when subscribing to confirm the ter-mination of his membership.
Anatomy of a web subscription script
Product name.
This name can be re-placed with the parame-ter named product_name (see "Integration of scripts: Install Subscrip-tion script ).
Select the country of origin of the buyer.
By default, the buyer is from location-based IP adress.
Pricing of the offer.
Each pacjage offers a rate that depends on the price level selected regarding the country and the desired payment method.
Selecting the me-thod of payment.
The number of offers varies depending on the selected method.
Details of the offer.
Name and description of subscription offers.
Web subscription workflow
Subscribe an offer on the web On the purchase page, the end user is prompted to click on a button offering to subscribe an offer.
Process of payment : The process of payment of the subscription depends on the method of payment selected.
Mobile payment case : The customer must choose his mobile provider to continue.
Payment by Internet+ : The customer must enter his email and choose his ISP to continue.
Mobile Subscription workflow
Subscribe an offer on mobile :
Process of payment :
On the mobile purchase page, the end user is prompted to chose the preferred offer and click on a button offering to subscribe to it.
• If the customers’ device is working without Wi-Fi (directly connected only to the carrier network) he will be redirected auto-matically to the carrier’s page,
• If not (if the device is connected to a Wi-Fi network) the cus-tomer will be asked to choose his carrier and enter his phone nu-mber. depends on the method of payment selected.
Figure 1: With Wi-Fi workflow example
Overview
Error window
Finalizing your transaction
Description :
Error window :
To finalize the transaction the customer must follow the instruc-tions that will be displayed in his mobile provider or ISP. Once the transaction is finished on their side the customer is redirected to an Mobiyo confirmation window.
If there was an error processing the payment, the customer will see this error window :
Aborted payment window
Error window : If the customer aborts the payment in the provider’s window he will see this window :
Success payment window
Condition : If the provider confirms that the transaction was successfully completed, the customer will see the Mobiyo Success Window.
When successful payment Mobiyo window is displayed : Click on “Finaliser mon achat” to finalize your purchase.
• The user is redirected to the product access page.
Set-up products
Add a product
Introduction :
Procedure :
From the "Sites & Products" screen, click on "Add a product…".
To set-up a product, proceed as follow:
Steps Action
1
2
Select the web site or create a new one:
Note: To get the details about creating a new web site, please refer to the “Mobiyo – Developer Starter Guide ” or “Mobiyo – Internet+ Mobile Developer Starter Guide ”.
Select the subscription payment method type that you prefer
Steps Action
3 Choose the desired price points and fill your product information:
Status : URL : Description :
Mandatory Product name This is how the product will ap-pear in your reports. This name does not appear on your cus-tomer’s bill.
Mandatory Purchase URL The address of the page on which customers will see the Mobiyo script and request ac-cess to your product.
Mandatory Product access URL Address of the page on which customers will access your pro-duct once payment is confir-med.
Optional Error URL The address of the page cus-tomers will be directed to if they can’t complete a purchase. This page should include support info
Optional Notification URL The address of the page on which you will receive notifi-cation about your payment do-cument once the payment is confirmed.
Payment URLs
Payment scripts integration
Description : Mobiyo generates a ready-made html code that you can simply copy and paste in your purchase page:
Website Subscription script integrationIntroduction : Mobiyo generates a ready-made html code that you can simply
copy and paste in your purchase page:
Description : To integrate the button, copy the whole script and paste it in your purchase page.
Description : To integrate the iframe, copy the whole script and paste it in your purchase page.
Description : To integrate in full page mode, please use the subscription script URL either in a hyperlink or a HTTP redirection.
Parameters : These variables must or can be transmitted to the two Mobiyo scripts:• subscribe/subscribe.apu• subscribe/button.apu
Button script
I-frame script
Full page script
Mandatory Ids Your site ID as set up in your Mobiyo merchant account
integer
Mandatory idd Your product ID as set up in your Mo-biyo merchant account
integer
Optional product_name The name of the product, it replaces the name of the product in the pay-ment window
string
Optional forward_target Window target for the forward to the product page at the end of the tran-saction. Can be set to parent or current (parent by default)
string
Optional merchant_transaction_id
The transaction ID used by the mer-chant
string
Optional merchant_subscriber_reference
The subscriber reference used by the merchant
string
Optional data Custom merchant datastring
Status Parameter type Description
Status
Status
Parameter
Parameter
type
type
Example
Example
Description
Description
Mandatory Ids Your site ID as set up in your Mo-biyo merchant account
integer 123456
Mandatory Ids Your site ID as set up in your Mo-biyo merchant account
integer 123456
Mandatory idd Your product ID as set up in your Mobiyo merchant account
integer 789012
Mandatory idd Your product ID as set up in your Mobiyo merchant account
integer 789012
Mandatory offer_id The offer ID as set up in your Mo-biyo product
integer 123
Optional country Country code in ISO 3166-1 alpha2 standard
string FR
Optional operator The operator ID under the following details: Orange: 20801 / SFR : 20810 / Bouygues : 20820
string 0612345678
Optional msisdn The mobile phone number of the customer
string
Parameter : URL to call: https://payment.allopass.com/abo/wapplus/purchase.apu
Parameter : URL to call: https://payment.allopass.com/abo/wha/purchase.apu
Internet + mobile (MPME)
Internet + box
Direct redirection
Conditions : If some of the mandatory information is already asked in your site before you call the Mobiyo script, you can always send it directly to the payment page and avoid the Mobiyo pages where the user is asked to fill this information.
Status Parameter type ExampleDescription
Mandatory offer_id The offer ID as set up in your Mo-biyo product
integer 123
Optional lang The language in country code in ISO 3166-1 alpha-2 standard
string FR
Optional operator The operator ID under the following details: Orange : 6 / SFR : 30 / Bouygues : 8 / Alice-Free : 7
string 7
Optional customer_email
The customer’s email address.string
Parameter : The parameters sent to this page are:
Description : At the end of the payment process, if this one was successfully accepted, the customer is redirected to the product page.
Note : For both direct redirection integrations, you can also send all your free data too(data, merchant_transaction_id, merchant_subscriber_reference, etc.).
Product page access
Parameters Type Description
transaction_id uuid Mobiyo transaction ID
subscriber_reference string HiPay Mobiles subscriber refe-rence
merchant_subscriber_reference string The subscriber reference use by the merchant
data string Custom merchant data
Mandatory : To allow your customers to stop their subscriptions, you must in-tegrate the unsubscription link on your purchase page or on your member zone if your website has one.
Description : The generic link will ask your customer to enter: • his subscriber reference (N° abonné) and • his phone number (for Internet+ mobile payments) or email address (for Internet+ box payments).
these information are used to subscribe before to be redirected to the mobile provider or ISP page.
Generic link URL: https://payment.allopass.com/subscribe/cancel.apu
Parameters : These variables must or can be transmitted to the generic un-subscription link:
Create an unsubscription : There are two ways to create your unsubscription link, the generic link and the simplified link.• Generic link• Simplified link
Unsubscription script
Generic link
Mandatory Ids Your site ID as set up in your Mobiyo merchant account
integer
Mandatory idd Your product ID as set up in your Mo-biyo merchant account
integer
Optional Country The county value will define the lan-guage of the unsubscription page. The values supported today are: • FR: French • US: English
string
Optional merchant_subscriber_reference
The subscriber reference used by the merchant
string
Status Parameter type Description
Description : If you save the subscriber references that Mobiyo send to you in the Notifications of payments (see Notifications) and the payment method was Internet+ mobile (MPME) you can “skip” the first step of the Generic unsubscription link (ask your customers their subscriber reference and phone number/email address) sending directly to Mobiyo the subscriber reference related to your client.
Simplified link URL: http://payment.allopass.com/abo/wapplus/cancel.apu
Note : Important! Your site has a member zone? If you have sent a “merchant_subscriber_reference” for the subscription, you must send it again to the unsubscription link
Simplified link (Only available for Internet + mobile ‘MPME’)
Mandatory subscriber_reference Your customer’s subscriber_referenceinteger
Status Parameter type Description
Example :
Example :
Linkhttps://payment.allopass.com/subscribe/cancel.apu?ids=xxxxx&idd=zzzzzz&country=FR&merchant_subscriber_reference=cus-tomerid
Linkhttps://payment.allopass.com/abo/wapplus/cancel.apu?-subscriber_reference=Z564307N
Parameters : These variables must or can be transmitted to the simplified un-subscription link:
Unsubscription workflow
• When your customer clicks in “Accèder à votre portail XXX” he will be redirected to his service provider page.• He must login into his customer area and cancel his subscription there.
Notifications
Overview
Introduction :
Notification types :
Note :
Status Code
The notification URL defined when the merchant creates a Pro-duct in the Mobiyo merchant account (see Set up products: Step 3) lets the merchants receive acknowledgments of their transac-tions on a URL placed on their server.
This URL can receive three notification types. For each notifica-tion, an action parameter identifies the type of event (see table below), the returned parameters depend on the type of notifica-tion.
The parameters returned to the notification URL are sent with the HTTP GET method. These parameters are signed with the API keys (see Signature ve-rification section).
Event type
Description
Success
Error
Charged back transaction
Code
0
1
5
Description
Example
Payment accepted
Insufficient funds
Chargebacked
payment-confirm Notification of a new subscrip-tion
payment-renewal Renewal of a valid subscription.
subscription-cancellation Cancellation of a subscription.
Notification of a new subscription
Description : At the end of a subscription to a subscription offer, the notification URL is called with the parameters defined in the table below.
Parameter : Description : Example :
action Describes the type of event for which we notify.
payment-confirm
test Allows the merchant to iden-tify the test transactions.
false
transaction_id Unique ID for the transaction Mobiyo.
0c92578d-3143-4bd8aeae-72f2455e2499
status Status of the transaction (For a complete list of status codes, see table below).
0
status_description Description of the status of the transaction (For a complete list of status codes, see table below).
Success
access_type Product type. subscription
date Transaction date. 2011-0107T09:51:01+00:00
subscriber_reference Unique reference of the Mo-biyo subscriber
Z8635S59
merchant_subscriber _reference
Merchant subscriber reference that the merchant has infor-med when making payment.
My reference
pricepoint_id Price point Id used for the subscription.
502
type Payment method Mpme
data Data that the merchant has informed when making pay-ment.
Widget592
merchant_transaction _id Merchant transaction Id that the merchant has informed when making payment.
IN1234132
customer_country Country code of the customer. This two-letter code complies with ISO-3166 .
FR
site_id Identifier of the merchant site. 123456
product_id Identifier of the product. 987654
offer_id Identifier of the subscription offer.
55
amount Amount of the transaction. The currency is determined by the price point identifier
1,50
paid Amount actually paid by the customer in currency.
1,50
currency Local currency for the transac-tion.
EUR
reference_currency Base currency (EUR is default). EUR
reference_amount Amount of the transaction in base currency.
1.50
reference_paid Amount actually paid by the customer in base currency.
1.50
reference_payout Amount of the merchant payout in base currency.
0,65
payout_currency Payout currency for the tran-saction.
EUR
carrier Optional: Carrier information if available
Orange
msisdn Optional: MSISDN information if available
0612345678
api_key Merchant API key. c fd 3 b 9 a 6 b 7 b 3 0 9 c 0 6 a a 5 3f5527c96e67
api_ts UNIX Timestamp (GMT) 1258691527
api_hash Hash function to use for si-gning: md5 or sha1. (SHA-1 is default)
sha1 md5
api_sig Signature fb1bab50fd2c3751dab0 7b35…
Notification of a renewal
Description : After each automatic renewal, the merchant is notified of the re-newal at the end of the term of the subscription.
Parameter : Description : Example :
action Describes the type of event for which we notify.
payment-renewal
test Allows the merchant to iden-tify the test transactions.
false
transaction_id Unique ID for the transaction Mobiyo.
0c92578d-3143-4bd8aeae-72f2455e2499
status Status of the transaction (For a complete list of status codes, see table below).
0
status_description Description of the status of the transaction (For a complete list of status codes, see table below).
Success
access_type Product type. subscription
date Transaction date. 2011-0107T09:51:01+00:00
subscriber_reference Unique reference of the Mo-biyo subscriber
Z8635S59
merchant_subscriber _reference
Merchant subscriber reference that the merchant has infor-med when making payment.
My reference
pricepoint_id Price point Id used for the subscription.
502
type Payment method Mpme
data Data that the merchant has informed when making pay-ment.
Widget592
merchant_transaction _id Merchant transaction Id that the merchant has informed when making payment.
IN1234132
customer_country Country code of the customer. This two-letter code complies with ISO-3166 .
FR
site_id Identifier of the merchant site. 123456
product_id Identifier of the product. 987654
offer_id Identifier of the subscription offer.
55
amount Amount of the transaction. The currency is determined by the price point identifier
1,50
paid Amount actually paid by the customer in currency.
1,50
currency Local currency for the transac-tion.
EUR
reference_currency Base currency (EUR is default). EUR
reference_amount Amount of the transaction in base currency.
1.50
reference_paid Amount actually paid by the customer in base currency.
1.50
reference_payout Amount of the merchant payout in base currency.
0,65
payout_currency Payout currency for the tran-saction.
EUR
carrier Optional: Carrier information if available
Orange
msisdn Optional: MSISDN information if available
0612345678
api_key Merchant API key. c fd 3 b 9 a 6 b 7 b 3 0 9 c 0 6 a a 5 3f5527c96e67
api_ts UNIX Timestamp (GMT) 1258691527
api_hash Hash function to use for si-gning: md5 or sha1. (SHA-1 is default)
sha1 md5
api_sig Signature fb1bab50fd2c3751dab0 7b35…
Notification of a cancellation
Description : After each automatic renewal, the merchant is notified of the re-newal at the end of the term of the subscription.
action Describes the type of event for which we notify.
payment-renewal
status Status of the transaction (For a complete list of status codes, see table below).
0
status_description Description of the status of the transaction (For a complete list of status codes, see table below).
Success
access_type Product type. subscription
date Transaction date. 2011-0107T09:51:01+00:00
subscriber_reference Unique reference of the Mo-biyo subscriber
Z8635S59
pricepoint_id Price point Id used for the subscription.
502
type Payment method Mpme
data Data that the merchant has informed when making pay-ment.
merchant_subscriber _reference
Merchant subscriber reference that the merchant has infor-med when making payment of the subscription.
customer_country Country code of the customer. This two-letter code complies with ISO-3166 .
FR
site_id Identifier of the merchant site. 123456
product_id Identifier of the product. 987654
offer_id Identifier of the subscription offer.
55
Parameter : Description : Example :
api_key Merchant API key. c fd 3 b 9 a 6 b 7 b 3 0 9 c 0 6 a a 5 3f5527c96e67
api_ts UNIX Timestamp (GMT) 1258691527
api_hash Hash function to use for si-gning: md5 or sha1. (SHA-1 is default)
sha1 md5
api_sig Signature fb1bab50fd2c3751dab0 7b35…
Status Code
Description
Success
Code
0
Example
Subscription cancelled.
Signature verification
Check the signature of a notification
Description :
Verification of the signature :
Find the Secret Key :
A unique signature is sent each time that Mobiyo contacts a merchant page (api_sig).
To verify this signature, you will need your API Secret Key.
You will find this key in your Mobiyo back office under the " Toolbox "category.
Signature verification exampleExample in PHP :
<?php $parameters = $_GET; $signature = $parameters[‘api_sig’]; unset($parameters[‘api_sig’]); ksort($parameters); $secretKey = ‘’; // fill here with your personal secret key $string2compute = ‘’;
foreach ($parameters as $name => $value) { $string2compute .= $name . $value; } // true if OK, false if not // if you are using md5 instead of sha1 please replace if (sha1($string2compute . $secretKey) == $signature) { $code = 0; $message = ‘OK’; } else { $code = 1; $message = ‘KO’; } header(‘Content-Type: text/xml; charset=UTF-8’);
echo ‘<?xml version="1.0" encoding="UTF-8" ?>’; ?> <response status="1"> <code><?php echo $code; ?></code> <message><?php echo $message; ?></message> </response>
For more information, don’t hesitate to contact our support service or your account manager.
The Mobiyo Team
www.mobiyo.com
More ways to pay
MobiyoPôle Produit94 Rue de Villiers 92832 Levallois Perret Cedex – France
SAS au capital de 2 486 196€, RCS Paris 824 638 209, N° TVA Intracommunautaire : FR61 824 638 209, Code APE : 6201Z