API Reference. Version 1.0

Transcription

1 API Reference Version 1.0 1

2 Table of contents Table of contents... 2 Overview... 6 What is the HiPay Mobile API?... 6 What is an API?... 6 What is a REST Web Service?... 6 Who may use this API?... 6 Knowledge and skills... 6 How to read this documentation?... 6 API Reference... 7 Methods available... 7 Onetime... 7 Product and Website... 7 Transaction... 7 Subscriptions... 8 Method "onetime/pricing"... 9 URL... 9 HTTP Method... 9 Authentication... 9 Parameters... 9 Example request... 9 Response...10 Sample response...10 Structure of a price point...11 Method "onetime/discrete-pricing"...12 URL...12 HTTP Method...12 Authentication...12 Parameters...12 Example request...12 Response...13 Sample response...13 Method onetime/validate-codes

3 URL...14 Method HTTP...14 Authentication...14 Parameters for a standard use...14 Example request...14 Parameter for use without product ID...15 Example request...15 Parameters for use with a transaction...15 Example request...16 Response...16 Sample response...17 Status codes...17 Method onetime/button...17 URL...17 HTTP Method...18 Authentication...18 Parameters...18 Example request...19 Response...19 Sample response...19 Method "onetime/discrete-button"...21 URL...21 HTTP Method...21 Authentication...21 Parameters...21 Example request...22 Response...22 Sample response...23 Method "website"...24 URL...24 HTTP Method...24 Authentication...24 Parameters...24 Example request...24 Response...24 Sample response

4 Method "product"...25 URL...25 HTTP Method...25 Authentication...25 Parameters...25 Example request...25 Response...25 Sample response...26 Method "transaction"...27 URL...27 HTTP Method...27 Authentication...27 Parameters...27 Example request...27 Response...27 Sample response...28 Status codes...29 Method transaction/prepare...30 URL...30 HTTP Method...30 Authentication...30 Parameters...30 Example request...31 Response...31 Sample response...32 Method "transaction/merchant"...33 URL...33 HTTP Method...33 Parameters...33 Example request...33 Response...33 Sample response...34 Method "subscription/list"...35 URL...35 HTTP Method...35 Authentication

5 Parameters...35 Example request...36 Response...36 Sample response...36 Method "subscription"...37 URL...37 HTTP Method...37 Authentication...37 Parameters...37 Example request...37 Response...37 Sample response...38 Method "subscription/cancellation"...40 URL...40 HTTP Method...40 Authentication...40 Parameters...40 Example request...40 Response...40 Sample response...41 Appendix 1: Error Codes...42 Errors in the API...42 Appendix 2: Payment types and categories

6 Overview What is the HiPay Mobile API? HiPay Mobile provides access to key features of its payment engine through an API or Web Service. There are several types of Web Services, like REST, XML-RPC, SOAP, etc. HiPay Mobile offers an API based on the most common type, REST. What is an API? An API (Application Programming Interface) is a library of functions or procedures to develop applications. What is a REST Web Service? REST (Representational State Transfer) is a way to build Web services. This is neither a protocol nor a format but a style of architecture. Systems that follow the REST principles are based simply on the architectural style of the Web, mainly revolving around the HTTP protocol. Who may use this API? This API is opened to all merchants who wish to dynamically integrate the Allopass payment solution in their sites or applications. This document is specifically aimed at developers. Knowledge and skills The Allopass API requires that the user is familiar with the following: - Basic understanding of Web Services ( - Manipulating an XML document ( - Mastery of a programming language allowing the use of Web Services. How to read this documentation? This documentation describes in detail the capabilities of the API: Methods, parameters, output formats, syntax and error codes. Please refer to the API Developer Reference Manual or SDK Developer Reference Manual to know the basic concepts of the API: How to create a request, how to interpret a response, the different formats available, authentication and data types used. 6

7 API Reference Methods available Onetime The "onetime" category provides a list of methods to handle data related to one-shot payments. HTTP Method Resource Description GET /onetime/pricing Returns the list of available fixed price points for a product or a website. GET /onetime/discrete-pricing Returns the list of available dynamic price points for a product or a website. POST /onetime/validate-codes Validates access codes. POST /onetime/button Returns modal frame code to create a carousel button selector with available payment options POST /onetime/discrete-button Returns modal frame code to create a carousel button selector for discrete payment options Product and Website The "product" and website categories provide a list of methods to get information about the websites and the products of a merchant account. HTTP Method Resource Description GET /website Returns details of a website and the list of products in it. GET /product Returns details of a product. Transaction The "transaction" category provides a list of methods to handle payment transactions. HTTP Method Resource Description GET /transaction Returns details of a transaction. POST /transaction/prepare Prepares a transaction for payment. Returns a purchase URL and the HTML code for a payment button. GET /transaction/merchant Provides detail of a specific merchant transaction ID 7

8 Subscriptions The "subscriptions categories provide information about the subscriptions made with Internet+ payment methods. HTTP Method Resource Description GET /subscription/list Returns the list of Internet+ subscriptions related to a site, product and payment method. GET /subscription Return the details of a specific subscription reference. GET /subscription/cancellation If available, let you unsubscribe an existing subscription. 8

9 Method "onetime/pricing" Returns the list of static price points available for a product or a website. This method is used to obtain the list of price points supported by the HiPay Mobile API, each price point being set for a payment method, a country and a user price. It returns a list of supported countries and detailed information for each available price point. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameter Type Description mandatory site_id integer Identifier of the merchant site. optional product_id integer Product identifier (for one-shot micropayment). optional country string Filters the list of price points by country (expecting ISO compliant two-letter country codes). optional type string[] Filters the list of price points by payment type. For a list of error codes, see Appendix 2 "Payment types and categories" optional category string[] Filters the list of price points by payment category. For a list of error codes, see Appendix 2 "Payment types and categories" optional customer_ip inet If the customer IP address is specified, the country of the customer is identified via geolocation. optional only4ip boolean Geolocates the customer_ip and filters the list of price points for the identified country. optional reference_currency string Base currency (EUR is default). mandatory api_key string Merchant API key mandatory api_sig string Signature mandatory api_ts integer UNIX Timestamp (GMT) optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default) optional format string Return format: xml or json. Example request REST Call: PHP HiPay Mobile SDK Call: 9

10 ing?site_id=123456&product_id= &api_key=cfd3b9a6b7b309c06aa53f5527c96e67& api_ts= &api_sig=37d39beae276011bbb9e7d92e8585f9ee ae3a42f $response = $api->getonetimepricing (array('site_id' => )); Response Parameter Description Example creation_date Date of server reply (GMT) T12:04:21+00:00 customer_ip customer_country countries markets If the customer IP address is specified, the country of the customer is identified via geolocation. Country code of the customer. The country is automatically detected from the IP address of the customer (if provided). This twoletter code complies with ISO List of supported countries by region. List of price points available per country US Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <creation_datet imestamp=" " date=" t12:04:21+00:00" /> <customer_ip> </customer_ip> <customer_country>fr</customer_country> <countries> <region name="europe"> <country code="fr" name="france"/> </region> <region name="northamerica"> <country code="us" name="unitedstates"/> </region> </countries> <markets> <market country_code="fr"country="france"> <pricepoint id="2"code="fr"type="premium-calling" category= mobile-payment > <price currency="eur"amount="1.80" exchange=" " reference_currency="eur"reference_amount="1.80"/> <payout currency="eur"amount="1.00" exchange=" "reference_currency="eur" reference_amount="1.00"/> <buy_url> <![CDATA[ </buy_url> <phone_numbers> <phone_numbervalue=" "> <description> <![CDATA[ Pour recevoir votre code, appelez le :<br /> <span class="phone-number"> </span> ]]> </description> </phone_number> </phone_numbers> <description> <![CDATA[ La communication vous sera facturée :<br /> 1,34 /appel + 0,34 /min. depuis une ligne fixe.<br />Obtention du code en < 1,30 min. - coût : 1,80 ]]> </description> </pricepoint> </market> <market country_code="us" country="unitedstates"> <pricepoint id="166" code="us" type="premium-sms" category= mobile-payment > <price currency="usd" amount="3.99" exchange=" " reference_currency="eur"reference_amount="2.70"/> <payout currency="eur" amount="1.34" exchange=" " reference_currency="eur"reference_amount="1.34"/> <buy_url> <![CDATA[ </buy_url> <keywords> <keyword name="all" shortcode="44536" operators="*"number_billed_messages="1"> 10

11 <description> <![CDATA[ To receive an access code<br />on your mobile phone, send<br /> <span class="keyword">all</span> to <span class="shortcode">44536</span> ]]> </description> </keyword> </keywords> <description> <![CDATA[ $ 3.99/SMS Standard text messaging rates apply<br /> Info at ]]> </description> </pricepoint> </market> </markets> </response> Structure of a price point Parameter price payout buy_url description Description End-user price currency : local currency in which the end-user is billed amount : amount of the transaction exchange : exchange rate of the day reference_currency : base currency (euro is default) reference_amount : amount of the transaction in base currency Merchant outpayment currency : currency in which the merchant is paid amount : outpayment amount exchange : exchange rate of the day reference_currency : base currency (euro is default) reference_amount : outpayment amount in base currency Buy URL for the customer (Not Applicable when not utilizing a product_id along with the following payment methods: MPME, Mikro-Odeme and SMS US WO) Price point description 11

12 Method "onetime/discrete-pricing" Returns the list of available dynamic price points for a product or a website. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameter Type Description mandatory site_id integer Identifier of the merchant site. mandatory amount float Amount to bill. optional currency string Local currency in which the end-user is billed. optional country string Filters the list of price points by country (expecting ISO compliant two-letter country codes). optional type string[] Filters the list of price points by payment type. For a list of error codes, see Appendix 2 "Payment types and categories" optional category string[] Filters the list of price points by payment category. For a list of error codes, see Appendix 2 "Payment types and categories" optional customer_ip inet If the customer IP address is specified, the country of the customer is identified via geolocation. optional only4ip boolean Geolocates the customer_ip and filters the list of price points for the identified country. optional reference_currency string Base currency (EUR is default). mandatory api_key string Merchant API key mandatory api_sig string Signature mandatory api_ts integer UNIX Timestamp (GMT) optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default) optional format string Return format: xml orjson. Example request REST Call: PHP HiPay Mobile SDK Call: rete-pricing?site_id=123456&amount=10.00 &api_key=cfd3b9a6b7b309c06aa53f5527c96e67& api_ts= &api_sig=37d39beae276011bbb9e7d92e8585f9ee ae3a42f $response = $api->getonetimediscretepricing (array('site_id' => , 'amount' => 10.00, 'country' => 'FR')); 12

13 Response Parameter Description Example creation_date Date of server reply (GMT) T12:04:21+00:00 reference_currency Base currency (euro is default) USD customer_ip customer_country countries markets If the customer IP address is specified, the country of the customer is identified via geolocation. Country code of the customer. The country is automatically detected from the IP address of the customer (if provided). This code appears in two letters and corresponds to the ISO List of countries supported. List of price points available per country US Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <creation_date timestamp=" "> t12:04:21+00:00</creation_date> <reference_currency>eur</reference_currency> <customer_ip> </customer_ip> <customer_country>fr</customer_country> <countries> <region name="europe"> <country code="fr" name="france"/> </region> </countries> <markets> <market country_code="fr"country="france"> <pricepoint id="222"code="fr"type="credit-card" category= credit-card > <price currency="eur"amount="10.00"exchange=" "reference_amount="10.00"/> <payout currency="eur"amount="8.50"exchange=" "reference_amount="8.50"/> <description /> </pricepoint> <pricepoint id="224"code="fr"type="hipay" category= e-wallet > <price currency="eur"amount="10.00"exchange=" "reference_amount="10.00"/> <payout currency="eur"amount="8.50"exchange=" "reference_amount="8.50"/> <description /> </pricepoint> </market> </markets> </response> 13

14 Method onetime/validate-codes Validates access codes. URL Method HTTP POST Authentication This method requires authentication. Parameters for a standard use Status Parameters Type Description mandatory site_id integer Identifier of the merchant site. mandatory product_id integer Identifier of a product. mandatory code string[] Access code(s) optional merchant_transaction_id string Transaction ID used by the merchant. optional data string Custom data. optional ap_ca string Partner code. optional ap_ca_idc integer[] Partner ID. optional ap_ca_mnt string[] Partner revenue share (in %). optional ap_ca_map integer[] Affiliate program ID. optional customer_ip inet Customer IP address. optional reference_currency string Base currency (EUR is default). mandatory api_key string Merchant API key mandatory api_sig string Signature mandatory api_ts integer UNIX Timestamp (GMT) optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default) optional format string Return format: xml or json. Example request REST Call: PHP HiPay Mobile SDK Call: POST /rest/onetime/validate-codes HTTP/1.0 Host: api.allopass.com Content-Type: application/x-www-formurlencoded site_id=123456&product_id= &code[]=4a6r5492&data=userid &api_key=cfd3b9a6b7b309c06aa53f5527c96e67& api_ts= &api_sig=37d39beae276011bbb9e7d92e8585f9ee ae3a42f $response = $api->validatecodes(array( 'site_id' => , 'product_id' => , 'code' => array('9m7qu457') )); 14

15 Parameter for use without product ID Status Parameter Type Description mandatory site_id integer Identifier of the merchant site. mandatory product_name string Name of the product. mandatory code string[] Access code(s) optional pricepoint_id integer The price point id parameter is used to restrict code validation to a given price point. This does not apply to discrete billing. optional merchant_transaction_id string The transaction ID used by the merchant. Optional data string Custom data. optional ap_ca string Partner code. optional ap_ca_idc integer[] Partner ID. optional ap_ca_mnt string[] Partner revenue share (in %). optional ap_ca_map integer[] Affiliate program ID. optional customer_ip inet Customers IP address. optional reference_currency string Base currency (EUR is default). mandatory api_key string Merchant API key. mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). optional format string Return format: xml or json. Example request REST Call: POST /rest/onetime/validate-codes HTTP/1.0 Host: api.allopass.com Content-Type: application/x-www-formurlencoded site_id=123456&product_name=spare+change+t opup &pricepoint_id=2&code[]=4a6r5492&data=user id &api_key=cfd3b9a6b7b309c06aa53f5527c96e67& api_ts= &api_sig=37d39beae276011bbb9e7d92e8585f9ee ae3a42f PHP HiPay Mobile SDK Call: $response = $api->validatecodes(array( 'site_id' => , 'product_name' => 'spare change topup', 'pricepoint_id' => 2, 'code' => array('4a6r5492') )); Parameters for use with a transaction Status Parameters Type Description mandatory site_id integer Identifier of the merchant site. mandatory trxid uuid Identifier of a merchant transaction. mandatory code string[] Access code(s). optional reference_currency string Base currency (EUR is default). mandatory api_key string Merchant API key. 15

16 mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). optional format string Return format: xml or json. Example request REST Call: POST /rest/onetime/validate-codes HTTP/1.0 Host: api.allopass.com Content-Type: application/x-www-formurlencoded site_id=123456&trxid=0c92578d bd8- aeae-72f2455e2499 &code[]=4a6r5492&api_key=cfd3b9a6b7b309c06 aa53f5527c96e67&api_ts= &api_sig=37d39beae276011bbb9e7d92e8585f9ee ae3a42f PHP HiPay Mobile SDK Call: $response = $api->validatecodes(array( 'site_id' => , 'trxid' => '0c92578d bd8-aeae- 72f2455e2499', 'code' => array('4a6r5492') )); Response Parameter Description Example status Status code 0 status_description Status description Success access_type Access type of the product. Onetime transaction_id Identifier of the transaction. 0c92578d bd8-aeae- 72f2455e2499 price Information about the transaction price. The reference_amount attribute is the price of the transaction in the currency and exchange rate specified in the currency and exchange attributes. paid Amount actually paid by the customer in currency. The reference_amount attribute is the price of the transaction in the currency and exchange rate specified in the currency and exchange attributes. validation_date Date the code(s) was/were validated T08:23:10+00:00 product_name Name of the product. MY PRODUCT website Information about the website on which the product is valid. customer_ip Customer IP address customer_country expected_number_of_codes Country code of the customer. This two-letter code complies with ISO Number of codes required to access the product. FR 1 16

17 codes merchant_transaction_id data affiliate partners List of access codes for this transaction. The transaction ID used by the merchant. Custom merchant data. Partner code via an affiliate program. List of partners defined by the merchant. Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <status>0</status> <status_description>success</status_description> <access_type>onetime</access_type> <transaction_id>0c92578d bd8-aeae-72f2455e2499</transaction_id> <price currency="eur" amount="3.60" exchange=" " reference_currency="eur" reference_amount="3.60" /> <paid currency="eur" amount="3.60" exchange=" " reference_currency="usd" reference_amount="3.60" /> <validation_date> t08:23:10+00:00</validation_date> <product_name><![cdata[spare CHANGE TOPUP]]></product_name> <website id="123456" name="my-website.com" url=" /> <customer_ip> </customer_ip> <customer_country>fr</customer_country> <expected_number_of_codes>2</expected_number_of_codes> <merchant_transaction_id><![cdata[ ]]></merchant_transaction_id> <affiliate>x058g469879e5</affiliate> <partners> <partner id=" " share="10" map="" /> </partners> <codes> <code value="5mhe5939"> <pricepoint id="2" code="fr" type="premium-calling" category= mobile-payment /> <price currency="eur"amount="1.80" exchange=" " reference_currency="eur"reference_amount="1.80"/> <paid currency="eur"amount="1.80" exchange=" " reference_currency="eur"reference_amount="1.80"/> <payout currency="eur"amount="1.00" exchange=" "reference_currency="eur" reference_amount="1.00"/> </code> <code value="6q5gf542"> <pricepoint id="2"code="fr"type="premium-calling" category= mobile-payment /> <price currency="eur"amount="1.80" exchange=" " reference_currency="eur"reference_amount="1.80"/> <paid currency="eur"amount="1.80" exchange=" " reference_currency="eur"reference_amount="1.80"/> <payout currency="eur"amount="1.00" exchange=" "reference_currency="eur" reference_amount="1.00"/> </code> </codes> </response> Status codes Code Description Context 0 Success Access code validated. 1 Failed Validation failed. Method onetime/button Prepares a payment button for all available payment options using a carousel user interface. URL 17

18 HTTP Method POST Authentication This method requires authentication. Parameters Status Parameter Type Description mandatory site_id integer Identifier of the merchant site. mandatory product_name string Product name. mandatory forward_url string URL of the page where customers are forwarded when an access code has been successfully redeemed or when a payment without code was successful. optional forward_target string Specifies where to open the forward and error URL. Allowed values are: parent uses the parent window (default) current uses the current window (recommended if the payment dialog is loaded into an iframe) mandatory price_mode string Defines what "amount" refers to. Currently, only end-user price is supported ("price") optional error_url string URL of the page where customers are forwarded if a transaction is denied. optional notification_url string Payment notification URL mandatory amount float Amount of the transaction. The currency is determined by the price point identifier. mandatory price_policy string Affects sorting and prioritization of retrieved price points. Given an amount: high-preferred First retrieves and presents those higher than amount, then those below high-only Only returns price points above the defined amount low-preferred First retrieves and presents those lower than amount, then those higher low-only Only returns price points below the defined amount nearest Price points are sorted and listed by the absolute value difference to amount mandatory reference_currency string Base currency (EUR is default). optional country string[] Filters the list of price points by country optional type string[] Filters the list of price points by payment type. For a list of error codes, see Appendix 2 "Payment types and categories" optional category string[] Filters the list of price points by payment category. For a list of error codes, see Appendix 2 "Payment types and categories" optional merchant_transaction_id string Identifier of the transaction 18

19 optional data string Custom data. optional ap_ca string Partner code. optional ap_ca_idc integer[] Partner ID. optional ap_ca_mnt string[] Partner revenue share (in %). optional ap_ca_map integer[] Affiliate program ID. Example request REST Call: on?amount=3&api_hash=sha1&api_key=1234abcd d123abcabc065c7f3fb11731&api_ts= &forward_url=http%3a%2f%2fwww.yourcompany.com&price_mode=price&price_policy= highonly&product_name=premium+sms+access&refer ence_currency=usd&site_id=219509&api_sig=8 83a2c88a3c5177e91e7d6d538f53ed9f9cb868c PHP HiPay Mobile SDK Call: $response4 = $api->createbutton(array( 'site_id' => , 'product_name' => 'My Product', 'forward_url'=> ' 'notification_url' => ' 'amount' => 10, 'reference_currency' => 'EUR', 'price_mode' => 'price', 'price_policy' => 'high-only', 'data' => 'My free data', 'merchant_transaction_id' => 'TRANS765', 'type' => array('premium-sms', 'premiumcalling', 'internet-plus'), 'country' => array('fr') )); Response Parameter Description Example creation_date Date of server reply (GMT) T12:04:21+00:00 button_id Temporary button ID issued by HiPay Mobile reference_currency Base currency (euro is default) USD website buy_url Customer website information site name, forwarding URL, HiPay Mobile ID, category, audience restrictions Secure button link provided by HiPay Mobile payment.allopass.com URL with associated btnid checkout_button Code to create a modal window for merchant use payment.allopass.com URL with associated btnid and carousel javascript code carousel presentation Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <access_type>onetime</access_type> <button_id> </button_id> <creation_date timestamp=" " date= T12:04:21+00:00 /> 19

20 <website id="123456"name="site_name" url=" audience_restricted="false"category="family, health, well-being, education"/> <buy_url> <![CDATA[ </buy_url> <checkout_button> <![CDATA[ <!-- Begin Allopass Checkout-Button Code --><script type="text/javascript" src=" aac74"></script> <noscript> <a href=" style="border:0"> <img src=" style="border:0" alt="buy now!" /> </a> </noscript> <!-- End Allopass Checkout-Button Code -->]]> </checkout_button> </response> 20

21 Method "onetime/discrete-button" Prepares a payment button for all available discrete payment options using a carousel user interface. URL HTTP Method POST Authentication This method requires authentication. Parameters Status Parameter Type Description mandatory site_id integer Identifier of the merchant site. mandatory product_name string Product name. mandatory forward_url string URL of the page where customers are forwarded when an access code has been successfully redeemed or when a payment without code was successful. optional forward_target string Specifies where to open the forward and error URL. Allowed values are: parent uses the parent window (default) current uses the current window (recommended if the payment dialog is loaded into an iframe) mandatory price_mode string Defines what "amount" refers to. Currently, only end-user price is supported ("price") optional error_url string URL of the page where customers are forwarded if a transaction is denied. optional notification_url string Payment notification URL mandatory amount float Amount of the transaction. The currency is determined by the price point identifier. mandatory price_policy string Affects sorting and prioritization of retrieved price points. Given an amount: high-preferred First retrieves and presents those higher than amount, then those below high-only Only returns price points above the defined amount low-preferred First retrieves and presents those lower than amount, then those higher low-only Only returns price points below the defined amount nearest (recommended) Price points are sorted and listed by the absolute value difference to amount mandatory reference_currency string Base currency (EUR is default). optional country string[] Filters the list of price points by country 21

22 optional type string[] Filters the list of price points by payment type. For a list of error codes, see Appendix 2 "Payment types and categories" optional category string[] Filters the list of price points by payment category. For a list of error codes, see Appendix 2 "Payment types and categories" optional direct_access boolean (true by default) Controls where the user is redirected after the transaction. true user is redirected automatically after payment is submitted false user receives an access code with no redirection optional merchant_transaction_id string Identifier of the transaction optional data string Custom data. optional ap_ca string Partner code. optional ap_ca_idc integer[] Partner ID. optional ap_ca_mnt string[] Partner revenue share (in %). optional ap_ca_map integer[] Affiliate program ID. Example request REST Call: on?amount=3&api_hash=sha1&api_key=7217cd32 b120bba25c065c7f3fb11731&api_ts= &forward_url=http%3a%2f%2fwww.dailybaby.in fo&price_mode=price&price_policy=highonly&product_name=premium+sms+access&refer ence_currency=usd&site_id=219509&api_sig=a 52dff535f8a b7dfec4e19596f70cdacb PHP HiPay Mobile SDK Call: $response4 = $api->creatediscretebutton(array( 'site_id' => , 'product_name' => 'My Product', 'forward_url'=> ' 'notification_url' => ' 'amount' => 10, 'reference_currency' => 'EUR', 'price_mode' => 'price', 'price_policy' => 'high-only', 'data' => 'My free data', 'merchant_transaction_id' => 'TRANS765', 'type' => array('premium-sms', 'premiumcalling', 'internet-plus'), 'country' => array('fr') )); Response Parameter Description Example creation_date Date of server reply (GMT) T12:04:21+00:00 reference_currency Base currency (euro is default) USD customer_ip If the customer IP address is specified, the country of the customer is identified via geolocation customer_country Country code of the customer. US 22

23 countries The country is automatically detected from the IP address of the customer (if provided). This code appears in two letters and corresponds to the ISO List of countries supported. button_id Temporary button ID issued by HiPay Mobile reference_currency Base currency (euro is default) USD website Customer website information site name, forwarding URL, HiPay Mobile ID, category, audience restrictions buy_url Secure button link provided by HiPay Mobile payment.allopass.com URL with associated button_id checkout_button Checkout code with javascript provided by HiPay Mobile payment.allopass.com URL with associated button_id and button javascript code Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <access_type>onetime-dynamic</access_type> <button_id> </button_id> <creation_date timestamp=" " date= T12:04:21+00:00 /> <website id="123456"name="site_name" url=" audience_restricted="false"category="family, health, well-being, education"/> <buy_url> <#cdata-section> </#cdata-section> </buy_url> <checkout_button> <#cdata-section> <!-- Begin HiPay Mobile Checkout-Button Code --><script type="text/javascript" src=" <noscript> <a href=" dd6-2c5731e8d661" style="border:0"> <img src=" style="border:0" alt="buy now!" /> </a> </noscript><!-- End HiPay Mobile Checkout-Button Code --> </#cdata-section> </checkout_button> </response> 23

24 Method "website" Return the information related to a website and the list of products created in it. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameter Type Description optional id integer Website identifier. If the id is not defined, the method will return all the sites and products created in the merchant s account. mandatory api_key string Merchant API key. mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). optional format string Return format: xml or json. Example request REST Call: PHP HiPay Mobile SDK Call: 5?api_key=cfd3b9a6b7b309c06aa53f5527c96e67 &api_ts= &api_sig=fb1bab50fd2c3751dab07b35fe4abcde1 8ebc4c1 $response = $api->getwebsite(array('id' => '12345')); Response Parameter Description Example website Information of the website. <website id="12345" name="my WEBSITE" url=" audience_restricted="false" category="advert"> product Information of each product created in the website. <product id="987654" name="my PRODUCT"/> Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <website id="12345" name="my WEBSITE" url=" audience_restricted="false" category="cultural recreation"> <product id=" " name="my PRODUCT"/> <product id=" " name="generic Product"/> <product id=" " name="generic Product"/> </website></response> 24

25 Method "product" Return the detail of a product. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameter Type Description mandatory id integer Product identifier. mandatory api_key string Merchant API key. mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). optional format string Return format: xml or json. Example request REST Call: 21?api_key=cfd3b9a6b7b309c06aa53f5527c96e6 7&api_ts= &api_sig=fb1bab50fd2c3751dab07b35fe4abcde1 8ebc4c1 PHP Allopass SDK Call: $ response = $api->getproduct('654321'); Response Parameter Description Example id Product identifier key Product key, also known as "auth" /654321/ access_type Access type of the product. Onetime creation_date Date the product was created T12:04:21+00:00 name Product name. MY PRODUCT website Information on the website on which the product is valid. id="123456" name="my- WEBSITE.COM" url=" restricted_audience="false" category="advert" 25

26 expected_number_of_codes purchase_url forward_url error_url Number of codes required to access the product (from 1 to 5). URL of the page where the payment script is installed. URL of the page where customers are forwarded when an access code has been successfully redeemed or when a payment without code was successful. URL of the page where customers are forwarded if a transaction is denied notification_url Payment notification URL. Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <id>654321</id> <key>123456/654321/456789</key> <access_type>onetime</access_type> <creation_date> t08:23:10+00:00</creation_date> <name><![cdata[spare CHANGE TOPUP]]></name> <website id="123456" name="my-website.com" url=" restricted_audience="false" category="advert" /> <expected_number_of_codes>1</expected_number_of_codes> <purchase_url><![cdata[ <forward_url><![cdata[ <error_url /> <notification_url><![cdata[ </response> 26

27 Method "transaction" Returns details of a transaction. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameters Type Description mandatory id uuid Transaction Identifier. mandatory api_key string Merchant API key. mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). optional format string Return format: xml or json. optional reference_currency string Base currency (EUR is default). Example request REST Call: 0c92578d bd8-aeae-72f2455e2499? api_key=cfd3b9a6b7b309c06aa53f5527c96e67&a pi_ts= &api_sig=fb1bab50fd2c3751dab07b35fe4abcde1 8ebc4c1 PHP Allopass SDK Call: $ response = $api->gettransaction('0c92578d bd8-aeae-72f2455e2499'); Response Parameter Description Example status Status code. 0 status_description Description of status. success reference_currency access_type transaction_id Base currency (EUR is default). Access type of the product. Identifier of the transaction. USD onetime 0c92578d bd8-aeae-72f2455e2499 price Information about the currency="eur" amount="10.00" 27

28 transaction price. exchange=" " reference_amount="14.79" creation_date end_date The reference_amount attribute is the price of the transaction in the currency and exchange rate specified in the currency and exchange attributes. Date the transaction was created. End date of the transaction, i.e. when payment has been made. product_name Product Name. MY PRODUCT T08:23:10+00: T08:44:08+00:00 website customer_ip customer_country Information on the website on which the transaction is valid. If the customer IP address is specified, the country of the customer is identified via geolocation. Country code of the customer. id="123456" name="my-website.com" url=" US expected_number_of_codes codes merchant_transaction_id This two-letter code complies with ISO Number of codes required to access the product. List of access codes for this transaction. The transaction ID used by the merchant. 1 R05F6854 IN data Custom merchant data. <![CDATA[userid=1981&login=username@host.com]]> affiliate partners Partner code via an affiliate program. List of partners defined by the merchant BZFV9281 Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <status>1</status> <status_description>success</status_description> <reference_currency>usd</reference_currency> <access_type>onetime-dynamic</access_type> <transaction_id>0c92578d bd8-aeae-72f2455e2499</transaction_id> <price currency="eur" amount="10.00" exchange=" " reference_amount="14.79" /> <creation_date> t08:23:10+00:00</creation_date> <end_date> t08:44:10+00:00</end_date> <product_name><![cdata[spare CHANGE TOPUP]]></product_name> <website id="123456" name="my-website.com" url=" /> <customer_ip> </customer_ip> <customer_country>fr</customer_country> 28

29 <expected_number_of_codes>1</expected_number_of_codes> <codes> <code pricepoint_id="100">r05f6854</code> <code pricepoint_id="100">...</code> </codes> <merchant_transaction_id><![cdata[ ]]></merchant_transaction_id> <affiliate>x058g469879e5</affiliate> <partners> <partner id=" " share="10" map="" /> </partners> </response> Status codes Code Description Background 0 Success Payment accepted. 29

30 Method transaction/prepare Prepares a payment transaction. Returns a purchasing URL and HTML code for a payment button for a specific payment method. URL HTTP Method POST Authentication This method requires authentication. Parameters Status Parameters Type Description mandatory site_id integer Identifier of the merchant site. mandatory pricepoint_id integer Identifier of a price point as determined by onetime/pricing and discrete/pricing. mandatory (for discrete price points) amount float Amount of the transaction. mandatory product_name string Product name. The currency is determined by the price point identifier. mandatory forward_url string URL of the page where customers are forwarded when an access code has been successfully redeemed or when a payment without code was successful. optional forward_target string Specifies where to open the forward and error URL. Allowed values are: parent uses the parent window (default) current uses the current window (recommended if the payment dialog is loaded into an iframe) optional product_id integer Identifier of the merchant product. optional country string For international price points only, this parameter localizes the interface to a specific country (expecting ISO-3166-compliant two-letter country codes). optional error_url string Address of the page to which customers are directed if a transaction is denied. optional notification_url string Event notification URL. This address is automatically called to notify of events such as confirmation of payment. optional reference_currency string Base currency (EUR is default) optional merchant_transaction_id string The transaction ID used by the merchant. optional data string Custom merchant data. optional ap_ca string Partner code. 30

31 optional ap_ca_idc integer[] Partner ID. optional ap_ca_mnt string[] Partner revenue share (in %). optional ap_ca_map integer[] Affiliate program ID. mandatory api_key String Merchant API key. mandatory api_sig string Signature. mandatory api_ts integer UNIX Timestamp (GMT). optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default) optional format string Return format: xml or json. Example request REST Call: prepare/?site_id=123456&pricepoint_id=222& amount=10&product_name=share+change+toptup &forward_url=http%3a%2f%2fwww.mywebsite.com%2fmyaccount.php&api_key=cfd3b9a6b7b309c06aa53f 5527c96e67&api_ts= &api_sig=1c90d 5846d16f7f9fede3ff3d fe5b0d1a PHP Allopass SDK Call: $response = $api->preparetransaction(array( 'site_id' => , 'pricepoint_id' => 222, 'product_name' => 'My product', 'forward_url'=> ' 'amount' => '10', 'reference_currency' => 'EUR', 'data' => 'My free data', 'merchant_transaction_id' => 'TRANS765', )); Response Parameter Description Example access_type Access type of the product. onetime-dynamic reference_currency Base currency (EUR is default). EUR transaction_id Transaction identifier. 0c92578d bd8-aeae- 72f2455e2499 creation_date Date the transaction was created T12:04:21+00:00 price pricepoint Information about the transaction price. The reference_amount attribute is the price of the transaction in the currency and exchange rate specified in the currency and exchange attributes. Payment information, essentially the payment method and the country of validity. currency="eur" amount="10.00" exchange=" " reference_amount="14.79" id="222" type="credit-card" country_code="fr" website Website on which the transaction is valid. id="123456" name="my- WEBSITE.COM" url=" restricted_audience="false" category="advert" buy_url Buy URL for the customer. See code in response below. checkout_button HTML code for the payment button. See code in response below. 31

32 Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <access_type>onetime-dynamic</access_type> <reference_currency>usd</reference_currency> <transaction_id>0c92578d bd8-aeae-72f2455e2499</transaction_id> <creation_date> t08:23:10+00:00</creation_date> <price currency="eur" amount="10.00" exchange=" " reference_amount="14.79" /> <pricepoint id="222" type="credit-card" category= credit-card country_code="fr" /> <website id="123456" name="my-website.com" url=" restricted_audience="false" category="advert" /> <buy_url><![cdata[ <checkout_button><![cdata[ <script src=" aeae-72f2455e2499" type="text/javascript"></script> <noscript><a href=" style="border:0"> <img src=" alt="buy now!"/> </a></noscript>]]> </checkout_button> </response> 32

33 Method "transaction/merchant" Returns details for a merchant transaction based on a transaction ID. URL HTTP Method GET Parameters Status Parameters Type Description mandatory id string The transaction ID used by the merchant. mandatory api_key String Merchant API key mandatory api_sig string Signature mandatory api_ts integer UNIX Timestamp (GMT) optional api_hash string Hash function to use for signing: md5 or sha1. (SHA- 1 is default) Example request REST Call: merchant/ref56789? api_key=cfd3b9a6b7b309c06aa53f5527c96e67&a pi_ts= &api_sig=fb1bab50fd2c3751dab07b35fe4abcde1 8ebc4c1 PHP Allopass SDK Call: $response = $api->gettransactionmerchant ('REF56789'); Response Parameter Description Example status Status code. 0 status_description Description of the status of the transaction. Success access_type Access type of the product. onetime transaction_id Transaction identifier. 0c92578d bd8-aeae- 72f2455e2499 price Information about the transaction price paid The reference_amount attribute is the price of the transaction in the currency and exchange rate specified in the currency and exchange attributes. Amount actually paid by the customer in currency creation_date Date when transaction was created T12:04:21+00:00 end_date End date of the transaction, i.e. when payment has been made T08:44:08+00:00 33

34 product_name Merchant defined product name Top Widget Value Rewards website customer_ip customer_country Information about the website on which the transaction is valid. If the customer IP address is specified, the country of the customer is identified via geolocation. Country code of the customer. id="123456" name="sitename" url=" audience_restricted="false" category="recreation and entertainment" US expected_number_of_codes This two-letter code complies with ISO Number of codes required to access the product (from 1 to 5). codes List of access codes for this transaction. R05F6854 merchant_transaction_id The transaction ID used by the merchant. ABC_ data Custom merchant data. Widget592 affiliate Partner code via an affiliate program. ID1823BB partners List of partners defined by the merchant. BZFV9281 Sample response <?xml version="1.0" encoding="utf-8"?> <response xmlns=" message="ok"> <status>0</status> <status_description>success</status_description> <access_type>onetime</access_type> <transaction_id>98cbcd8e-c66c d2-1b2520c8cf57</transaction_id> <price currency="eur" amount="4.00" exchange=" " reference_currency="eur" reference_amount= "4.00"/> <paid currency="eur" amount="0.00" exchange=" " reference_currency="eur" reference_amount=" 0.00"/> <creation_date timestamp=" " date=" t07:46:46+00:00"/> <end_date timestamp="" date=""/> <product_name> <![CDATA[ 40 credits ]]> </product_name> <website id="20" name="mysite" url=" audience_restricted="false" category="fa mily "/> <customer_ip/> <customer_country>it</customer_country> <expected_number_of_codes>1</expected_number_of_codes> <direct_access>false</direct_access> <codes> <code pricepoint_id="100">r05f6854</code> <code pricepoint_id="100">...</code> </codes> <merchant_transaction_id> <![CDATA[ TRANS765 ]]> </merchant_transaction_id> <data> <![CDATA[ My customer information ]]> </data> <affiliate/> <partners/> </response> 1 34

35 Method "subscription/list" Returns the list of Internet+ subscriptions related to a site, product and payment method. URL HTTP Method GET Authentication This method requires authentication. Parameters Status Parameter Type Description Example mandatory site_id integer Site identifier mandatory product_id integer Product identifier mandatory payment_mode_id integer Payment mode identifier 14 = Internet+ mobile MPME 4 = Internet+ box 14 mandatory api_key string Merchant API key. cfd3b9a6b7b309c06aa53f 5527c96e67 mandatory api_sig string Signature. fb1bab50fd2c3751dab07b 35fe4abcde18ebc4c1 mandatory api_ts integer UNIX Timestamp (GMT) optional api_hash string Hash function to use for signing: md5 or sha1. (SHA-1 is default). sha1 optional format string Return format: xml or json. xml optional amount float Amount of the purchase. 5 optional merchant_subscriber_reference string Merchant subscriber reference sent. optional msisdn string Phone number of the customer is Internet+ mobile payment. optional string of the customer if Internet+ box payment. optional subscription_date string Subscription date (YYYY/MM/DD). UIO test@mail.com 2012/09/20 optional pricepoint_id integer Price point ID. 533 optional data string Data sent when the transaction was created. Myfreedata 35