API Reference 5 Aout 2019 - Mobiyo

Page created by Mathew Hayes
 
CONTINUE READING
API Reference 5 Aout 2019 - Mobiyo
API Reference
                                              Version 1.0

                                                              5 Aout 2019

Mobiyo
Pôle Produit
94 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
                                                                        i
TABLE OF CONTENTS

Table of contents
Overview������������������������������������������������������������������������������������������������� 1
    What is the Mobiyo API?���������������������������������������������������������������������������������������������1
         What is an API?���������������������������������������������������������������������������������������������������������������������������������������������������������1

         What is a REST Web Service?�������������������������������������������������������������������������������������������������������������������������������1

    Who may use the API?�������������������������������������������������������������������������������������������������1
         Knowledge and skills�����������������������������������������������������������������������������������������������������������������������������������������������1

         How to read this documentation?�������������������������������������������������������������������������������������������������������������������������1

API Reference�������������������������������������������������������������������������������������� 2
    Methods available��������������������������������������������������������������������������������������������������������2
         One time��������������������������������������������������������������������������������������������������������������������������������������������������������������������2

         Product and Website����������������������������������������������������������������������������������������������������������������������������������������������2

         Transaction����������������������������������������������������������������������������������������������������������������������������������������������������������������3

         Subscriptions������������������������������������������������������������������������������������������������������������������������������������������������������������3

    Method “onetime/pricing”������������������������������������������������������������������������������������������3
         URL������������������������������������������������������������������������������������������������������������������������������������������������������������������������������3

         HTTP Method������������������������������������������������������������������������������������������������������������������������������������������������������������3

         Authentication����������������������������������������������������������������������������������������������������������������������������������������������������������3

         Parameters ��������������������������������������������������������������������������������������������������������������������������������������������������������������� 4

         Example request����������������������������������������������������������������������������������������������������������������������������������������������������� 5

         Response������������������������������������������������������������������������������������������������������������������������������������������������������������������ 5

         Sample response ��������������������������������������������������������������������������������������������������������������������������������������������������� 6

         Structure of a “price point”������������������������������������������������������������������������������������������������������������������������������������7

                                                                                                                                                                                         ii
Method “onetime/discrete-pricing” ����������������������������������������������������������������������� 8
     URL����������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 8

     HTTP Method����������������������������������������������������������������������������������������������������������������������������������������������������������� 8

     Authentication��������������������������������������������������������������������������������������������������������������������������������������������������������� 8

     Parameters ��������������������������������������������������������������������������������������������������������������������������������������������������������������� 8

     Example request����������������������������������������������������������������������������������������������������������������������������������������������������� 9

     Response������������������������������������������������������������������������������������������������������������������������������������������������������������������ 9

     Sample response ��������������������������������������������������������������������������������������������������������������������������������������������������10

Method “onetime/validate-codes”������������������������������������������������������������������������10
     URL����������������������������������������������������������������������������������������������������������������������������������������������������������������������������10

     HTTP Method����������������������������������������������������������������������������������������������������������������������������������������������������������10

     Authentication��������������������������������������������������������������������������������������������������������������������������������������������������������10

     Parameters for a standard use����������������������������������������������������������������������������������������������������������������������������� 11

     Example request���������������������������������������������������������������������������������������������������������������������������������������������������� 12

     Parameter for use without product ID ������������������������������������������������������������������������������������������������������������ 12

     Example request���������������������������������������������������������������������������������������������������������������������������������������������������� 13

     Parameter for use with a transaction ���������������������������������������������������������������������������������������������������������������� 13

     Example request���������������������������������������������������������������������������������������������������������������������������������������������������� 14

     Response����������������������������������������������������������������������������������������������������������������������������������������������������������������� 14

     Sample response ��������������������������������������������������������������������������������������������������������������������������������������������������16

     Status codes������������������������������������������������������������������������������������������������������������������������������������������������������������16

Method “onetime/button”���������������������������������������������������������������������������������������� 17
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 17

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������� 17

     Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������� 17

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������� 17

     Example request����������������������������������������������������������������������������������������������������������������������������������������������������19

     Response�����������������������������������������������������������������������������������������������������������������������������������������������������������������19

     Sample response ������������������������������������������������������������������������������������������������������������������������������������������������ 20

                                                                                                                                                                                     iii
Method “onetime/discrete-button”���������������������������������������������������������������������� 20
     URL�������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 20

     HTTP Method�������������������������������������������������������������������������������������������������������������������������������������������������������� 20

     Authentication������������������������������������������������������������������������������������������������������������������������������������������������������ 20

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������� 21

     Example request��������������������������������������������������������������������������������������������������������������������������������������������������� 23

     Response���������������������������������������������������������������������������������������������������������������������������������������������������������������� 23

     Sample response ������������������������������������������������������������������������������������������������������������������������������������������������� 24

Method “website”������������������������������������������������������������������������������������������������������� 24
     URL��������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 24

     HTTP Method��������������������������������������������������������������������������������������������������������������������������������������������������������� 24

     Authentication������������������������������������������������������������������������������������������������������������������������������������������������������� 24

     Parameters ������������������������������������������������������������������������������������������������������������������������������������������������������������� 25

     Example request��������������������������������������������������������������������������������������������������������������������������������������������������� 25

     Response���������������������������������������������������������������������������������������������������������������������������������������������������������������� 25

     Sample response �������������������������������������������������������������������������������������������������������������������������������������������������26

Method “product” �����������������������������������������������������������������������������������������������������26
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������26

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������26

     Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������26

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������26

     Example request��������������������������������������������������������������������������������������������������������������������������������������������������� 27

     Response���������������������������������������������������������������������������������������������������������������������������������������������������������������� 27

     Sample response �������������������������������������������������������������������������������������������������������������������������������������������������28

Method “transaction”������������������������������������������������������������������������������������������������� 28
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������28

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������28

     Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������28

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������28

                                                                                                                                                                                   iv
Example request���������������������������������������������������������������������������������������������������������������������������������������������������29

     Response����������������������������������������������������������������������������������������������������������������������������������������������������������������29

     Sample response �������������������������������������������������������������������������������������������������������������������������������������������������� 31

     Status codes������������������������������������������������������������������������������������������������������������������������������������������������������������ 31

Method “transcription/prepare”����������������������������������������������������������������������������� 32
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������32

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������32

     Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������32

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������32

     Example request���������������������������������������������������������������������������������������������������������������������������������������������������34

     Response����������������������������������������������������������������������������������������������������������������������������������������������������������������34

     Sample response �������������������������������������������������������������������������������������������������������������������������������������������������35

Method “transaction/merchant”�����������������������������������������������������������������������������36
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������36

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������36

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������36

     Example request���������������������������������������������������������������������������������������������������������������������������������������������������36

     Response����������������������������������������������������������������������������������������������������������������������������������������������������������������36

     Sample response �������������������������������������������������������������������������������������������������������������������������������������������������38

Method “subcription/list”�����������������������������������������������������������������������������������������38
     URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������38

     HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������38

     Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������38

     Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������39

     Example request�������������������������������������������������������������������������������������������������������������������������������������������������� 40

     Response��������������������������������������������������������������������������������������������������������������������������������������������������������������� 40

     Sample response ������������������������������������������������������������������������������������������������������������������������������������������������ 40

Method “subscription” �������������������������������������������������������������������������������������������� 40
     URL�������������������������������������������������������������������������������������������������������������������������������������������������������������������������� 40
                                                                                                                                                                                    v
HTTP Method�������������������������������������������������������������������������������������������������������������������������������������������������������� 40

         Authentication������������������������������������������������������������������������������������������������������������������������������������������������������ 40

         Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������� 41

         Example request���������������������������������������������������������������������������������������������������������������������������������������������������� 41

         Response����������������������������������������������������������������������������������������������������������������������������������������������������������������� 41

         Sample response �������������������������������������������������������������������������������������������������������������������������������������������������43

    Method “subscription/cancellation”���������������������������������������������������������������������44
         URL���������������������������������������������������������������������������������������������������������������������������������������������������������������������������44

         HTTP Method���������������������������������������������������������������������������������������������������������������������������������������������������������44

         Authentication�������������������������������������������������������������������������������������������������������������������������������������������������������44

         Parameters �������������������������������������������������������������������������������������������������������������������������������������������������������������44

         Example request���������������������������������������������������������������������������������������������������������������������������������������������������44

         Response����������������������������������������������������������������������������������������������������������������������������������������������������������������45

         Sample response �������������������������������������������������������������������������������������������������������������������������������������������������45

    Errors in the API���������������������������������������������������������������������������������������������������������46

Appendix 1 : Error Codes����������������������������������������������������������������� 46

Appendix 2 : Payment types and categories������������������������������48

                                                                                                                                                                                      vi
Overview

What is the Mobiyo API?
Mobiyo 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. Mobiyo 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 appli-
cations.

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 the API?
This API is opened to all merchants who wish to dynamically integrate the Allopass payment solu-
tion 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 (http://www.w3schools.com/webservices),
      - Manipulating an XML document (http://www.w3schools.com/xml)
      - 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 for-
mats, 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 for-
mats available, authentication and data types used.

                                                                                                      1
API Reference

Methods available
One time
The "onetime" category provides a list of methods to handle data related to “one-shot” payments.

HTTP Method                      Ressource                        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 dy-
                                                                  namic 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 selec-
                                                                  tor with available payment op-
                                                                  tions.

POST                             /onetime/discrete-button         Returns modal frame code to
                                                                  create a carousel button selec-
                                                                  tor for discrete payment options.

Product and Website
The "product" and “website” categories provide a list of methods to get information about the web-
sites and the products of a merchant account.

HTTP Method                      Ressource                        Description

GET                              /website                         Returns details of a website and
                                                                  the list of products in it.

GET                              /product                         Returns details of a product.

                                                                                                   2
Transaction
The "transaction" category provides a list of methods to handle payment transactions.

HTTP Method                         Ressource                           Description

GET                                 /transaction                        Returns details of a transaction.

POST                                /transaction/prepare                Prepares a transaction for pay-
                                                                        ment.
                                                                        Returns a purchase URL and the
                                                                        HTML code for a payment but-
                                                                        ton.

GET                                 /transaction/merchant               Provides detail of a specific
                                                                        merchant transaction ID.

Subscriptions
The "subscriptions” categories provide information about the subscriptions made with Internet+
payment methods.

HTTP Method                         Ressource                           Description

GET                                 /transaction                        Returns details of a transaction.

POST                                /transaction/prepare                Prepares a transaction for pay-
                                                                        ment.
                                                                        Returns a purchase URL and the
                                                                        HTML code for a payment but-
                                                                        ton.

GET                                 /transaction/merchant               Provides detail of a specific
                                                                        merchant transaction ID.

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 Mobiyo 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
https://api.allopass.com/rest/onetime/pricing

HTTP Method
GET

Authentication
This method requires authentication.
                                                                                                        3
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 (expec-
                                              ting ISO3166-compliant two-letter country co-
                                              des).

Optional    type                 string [ ]   Filters the list of price points by payment type.
                                              For a list of error codes, see Appendix 2 "Pay-
                                              ment types and categories".

Optional    category             string [ ]   Filters the list of price points by payment cate-
                                              gory.
                                              For a list of error codes, see Appendix 2 "Pay-
                                              ment types and categories"

Optional    customer_ip          inet         If the customer IP address is specified, the
                                              country of the customer is identified via geolo-
                                              cation.

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

                                                                                               4
Example request
REST CALL :                               PHP Mobiyo SDK Call :
https://api.allopass.com/rest/one-        $response = $api->getOnetimePricing
time/pric ing?site_id=123456&pro-         (array(‘site_id’ => 123456));
duct_id=654321 &api_key=c-
fd3b9a6b7b309c06aa53f5527c96e67&
api_ts=1258387836
&api_sig=37d39beae276011bbb9e7d92e-
8585f9ee ae3a42f

Response
Parameter                  Description                        Example

creation_date              Date of server reply (GMT).        2019-08-30T12:04:21+00:00

customer_ip                If the customer IP address is 83.167.62.196
                           specified, the country of the
                           customer is identified via geo-
                           location.

customer_country           Country code of the customer.      83.167.62.196

                           The country is automatically
                           detected from the IP address of
                           the customer (if provided). This
                           two-letters code complies with
                           ISO-3166.

countries                  List of supported countries by
                           region
markets                    List of price points available
                           per country.

                                                                                      5
Sample response

83.167.62.196
FR

08 99 19 01 13
]]>

 1,34€/appel + 0,34€/min. de-
puis une ligne fixe.Obtention du code en < 1,30 min. - coût : 1,80€ ]]>

on your mobile phone, send
                                                                                 6
ALL to 44536
]]>

Info at 1-877-524-8532
     ]]>

Structure of a “price point”
Parameter                    Description

                     price : 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

                   payout : 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 : 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)

               description : Price point description

                                                                                            7
Method “onetime/discrete-pricing”
Returns the list of available dynamic price points for a product or a website.

URL
https://api.allopass.com/rest/onetime/discrete-pricing

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 (expec-
                                                     ting ISO3166-compliant two-letter country co-
                                                     des).

Optional         type                   string [ ]   Filters the list of price points by payment type.
                                                     For a list of error codes, see Appendix 2 "Pay-
                                                     ment types and categories"

Optional         category               string [ ]   Filters the list of price points by payment cate-
                                                     gory. 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 geolo-
                                                     cation.

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

                                                                                                      8
Mandatory       api_sig         string       Signature

Mandatory       api_ts          string       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 Mobiyo SDK Call :
https://api.allopass.com/rest/onetime/    $response = $api->getOnetimeDiscrete-
disc rete-pricing?site_id=123456&a-       Pricing
mount=10.00 &api_key=cfd3b9a6b-           (array(‘site_id’ => 123456, ‘amount’ =>
7b309c06aa53f5527c96e67& api_             10.00,
ts=1258387836                             ‘country’ => ‘FR’));
&api_sig=37d39beae276011bbb9e7d92e-
8585f9ee ae3a42f

Response
Parameter                  Description                        Example

creation_date              Date of server reply (GMT).        2019-08-30T12:04:21+00:00

reference_currency         Base currency (euro is default)    USD

customer_ip                If the customer IP address is 83.167.62.196
                           specified, the country of the
                           customer is identified via geo-
                           location.

customer_country           Country code of the customer.      83.167.62.196

                           The country is automatically
                           detected from the IP address of
                           the customer (if provided). This
                           twoletter code complies with
                           ISO-3166.

countries                  List of supported countries by
                           region
markets                    List of price points available
                           per country.

                                                                                         9
Sample response

2009-08-30T12:04:21+00:00
EUR
83.167.62.196
FR

Method “onetime/validate-codes”
Validates access codes

URL
https://api.allopass.com/rest/onetime/validate-codes

HTTP Method
POST

Authentication
This method requires authentication.

                                                                             10
Parameters for a standard use
Status      Parameter            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_            string        Transaction ID used by the merchant.
            transaction_id

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.

                                                                                           11
Example request
REST CALL :                                      PHP Mobiyo SDK Call :
POST /rest/onetime/validate-codes                $response = $api->validateCodes(array(
HTTP/1.0                                         ‘site_id’ => 123456,
Host: api.allopass.com                           ‘product_id’ => 354926,
Content-Type: application/x-www-for-             ‘code’ => array(‘9M7QU457’)
murlencoded                                      ));
site_id=123456&product_id=654321
&code[]=4A6R5492&data=userid
&api_key=cfd3b9a6b7b309c06aa53f-
5527c96e67& api_ts=1258387836
&api_sig=37d39beae276011bbb9e7d92e-
8585f9ee ae3a42f

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_            string          The transaction ID used by the merchant.
              transaction_id

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

                                                                                                 12
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 Mobiyo SDK Call :
POST /rest/onetime/validate-codes                $response = $api->validateCodes(array(
HTTP/1.0                                        ‘site_id’ => 123456,
Host: api.allopass.com                          ‘product_name’ => ‘spare change topup’,
Content-Type: application/x-www-for-            ‘pricepoint_id’ => 2,
murlencoded                                     ‘code’ => array(‘4A6R5492’)
site_id=123456&product_                         ));
name=spare+change+t opup
&pricepoint_id=2&code[]=4A6R5492&da-
ta=user id
&api_key=cfd3b9a6b7b309c06aa53f-
5527c96e67& api_ts=1258387836
&api_sig=37d39beae276011bbb9e7d92e-
8585f9ee ae3a42f

Parameter for use with a transaction
Status        Parameter            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

Mandatory     api_sig              string         Signature

Mandatory     api_ts               integer        UNIX Timestamp (GMT)

                                                                                              13
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 Mobiyo SDK Call :
POST /rest/onetime/validate-codes            $response = $api->validateCodes(array(
HTTP/1.0                                    ‘site_id’ => 123456,
Host: api.allopass.com                      ‘trxid’ => ‘0c92578d-3143-4bd8-aeae-
Content-Type: application/x-www-for-        72f2455e2499’,
murlencoded                                 ‘code’ => array(‘4A6R5492’)
site_id=123456&trxid=0c92578d-3143-         ));
4bd8aeae-72f2455e2499
&code[]=4A6R5492&api_key=cfd3b9a6b-
7b309c06 aa53f5527c96e67&api_
ts=1258387836
&api_sig=37d39beae276011bbb9e7d92e-
8585f9ee ae3a42f

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-3143-4bd8-
                                                              aeae72f2455e2499 price

price                       Information about the transac-
                            tion price.

                            The reference_amount attri-
                            bute is the price of the tran-
                            saction in the currency and
                            exchange rate specified in the
                            currency and exchange attri-
                            butes.

                                                                                          14
paid                       Amount actually paid by the
                           customer in currency.
                           The reference_amount attri-
                           bute is the price of the tran-
                           saction in the currency and
                           exchange rate specified in the
                           currency and exchange attri-
                           butes.

validation_date            Date the code(s) was/were va- 2019-06-11T08:23:10+00:00
                           lidated

product_name               Name of the product.              MY PRODUCT

website                    Information about the website
                           on which the product is valid.

customer_ip                Customer IP address.              83.167.62.196

customer_country           Country code of the customer. FR
                           This two-letter code complies
                           with ISO-3166.

expected_number_of_codes   Number of codes required to 1
                           access the product.

codes                      List of access codes for this
                           transaction.

merchant_transaction_id    The transaction ID used by the
                           merchant.

data                       Custom merchant data.

affiliate                  Partner code via an affiliate
                           program.

partners                   List of partners defined by the
                           merchant.

                                                                                 15
Sample response

0
success
onetime
0c92578d-3143-4bd8-aeae-72f2455e2499

2009-06-11T08:23:10+00:00

83.167.62.196
FR
2

X058G469879E5

Status codes
Code                       Description               Context

0                          Success                   Access code validated

1                          Failed                    Validation failed

                                                                             16
Method “onetime/button”
Prepares a payment button for all available payment options using a carousel user interface.

URL
https://api.allopass.com/rest/onetime/button

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      Name of the product.

Mandatory       forward_url            string      URL of the page where customers are forwarded
                                                   when an access code has been successfully re-
                                                   deemed 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 (recom-
                                                   mended 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 forwar-
                                                   ded 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.

                                                                                                 17
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 "Pay-
                                               ment types and categories"

Optional    category             string [ ]    Filters the list of price points by payment cate-
                                               gory. For a list of error codes, see Appendix 2
                                               "Payment types and categories"

Optional    merchant_            string        Identifier of the transaction
            transaction_id

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.

                                                                                             18
Example request
REST CALL :                               PHP Mobiyo SDK Call :
                                           $response4 = $api->createButton(array(
https://api.allopass.com/rest/              ‘site_id’ => 123456,
onetime/butt on?amount=3&api_               ‘product_name’ => ‘My Product’,
hash=sha1&api_key=1234abcd d123ab-          ‘forward_url’=>
cabc065c7f3fb11731&api_ts=1277788228       ‘http://www.mysite.com/myproduct.php’,
&forward_url=http%3A%2F%2Fwww.your-         ‘notification_url’ => ‘
company.com&price_mode=price&price_po-     http://www.mysite.com/notification.
licy=                                      php’,
 high-                                      ‘amount’ => 10,
only&product_name=premium+sms+ac-           ‘reference_currency’ => ‘EUR’,
cess&refer ence_currency=US-                ‘price_mode’ => ‘price’,
D&site_id=219509&api_sig=8                  ‘price_policy’ => ‘high-only’,
83a2c88a3c5177e91e7d6d538f53ed9f-           ‘data’ => ‘My free data’,
9cb868c                                     ‘merchant_transaction_id’ =>
                                           ‘TRANS765’,
                                            ‘type’ => array(‘premium-sms’, ‘pre-
                                           miumcalling’, ‘internet-plus’),
                                            ‘country’ => array(‘FR’)
                                            ));

Response
Parameter                  Description                       Example

creation_date              Date of server reply (GMT).       2019-08-30T12:04:21+00:00

button_id                  Temporary button ID issued by 1 2 3 4 5 6 7 8 - 1 2 3 4 - 1 2 3 4 -
                           Mobiyo                        1234123456789012

reference_currency         Base currency (euro is default)   USD

website                    Customer website information 123456
                           – site name, forwarding URL,
                           Mobiyo ID, category, audience
                           restrictions

buy_url                    Secure button link provided by payment.allopass.com URL with
                           Mobiyo                         associated btnid

checkout_button            Code to create a modal win- payment.allopass.com       URL
                           dow for merchant use        with associated btnid and ca-
                                                       rousel javascript code carousel
                                                       presentation

                                                                                           19
Sample response

onetime
12345678-1234-1234-1234-123456789012
 
]]>

Method “onetime/discrete-button”
Prepares a payment button for all available discrete payment options using a carousel user interface.

URL
https://api.allopass.com/rest/onetime/discrete-button

HTTP Method
POST

Authentication
This method requires authentication.

                                                                                                  20
Parameters
Status      Parameter            Type         Description

Mandatory   site_id              Integer      Identifier of the merchant site.

Mandatory   product_name         string       Name of the product.

Mandatory   forward_url          string       URL of the page where customers are forwarded
                                              when an access code has been successfully re-
                                              deemed 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 (recom-
                                              mended 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 forwar-
                                              ded 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

                                                                                            21
Optional   type             string [ ]    Filters the list of price points by payment type.
                                          For a list of error codes, see Appendix 2 "Pay-
                                          ment types and categories"

Optional   category         string [ ]    Filters the list of price points by payment cate-
                                          gory. 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 re-
                                          directed after the transaction.
                                           true – user is redirected automatically after
                                          payment is submitted
                                          false – user receives an access code with no
                                          redirection

Optional   merchant_        string        Identifier of the transaction
           transaction_id

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.

                                                                                        22
Example request
REST CALL :                                 PHP Mobiyo SDK Call :
https://api.allopass.com/rest/             $response4 = $api->createDiscreteBut-
onetime/butt on?amount=3&api_              ton(array(
hash=sha1&api_key=7217cd32 b120b-           ‘site_id’ => 123456,
ba25c065c7f3fb11731&api_ts=1277789322       ‘product_name’ => ‘My Product’,
&forward_url=http%3A%2F%2Fwww.              ‘forward_url’=>
dailybaby.in fo&price_mo-                  ‘http://www.mysite.com/myproduct.php’,
de=price&price_policy=high-only&pro-        ‘notification_url’ => ‘
duct_name=premium+sms+access&refer         http://www.mysite.com/notification.
ence_currency=USD&site_id=219509&a-        php’,
pi_sig=a 52dff535f8a8538097b7dfe-           ‘amount’ => 10,
c4e19596f70cdacb                            ‘reference_currency’ => ‘EUR’,
                                            ‘price_mode’ => ‘price’,
                                            ‘price_policy’ => ‘high-only’,
                                            ‘data’ => ‘My free data’,
                                            ‘merchant_transaction_id’ =>
                                           ‘TRANS765’,
                                            ‘type’ => array(‘premium-sms’, ‘pre-
                                           miumcalling’, ‘internet-plus’),
                                            ‘country’ => array(‘FR’)
                                            ));

Response
Parameter                  Description                       Example

creation_date              Date of server reply (GMT).       2019-08-30T12:04:21+00:00

reference_currency         Base currency (euro is default)   USD

customer_ip                If the customer IP address is 83.167.62.196
                           specified, the country of the
                           customer is identified via geo-
                           location

customer_country           Country code of the customer. US
                           The country is automatically
                           detected from the IP address of
                           the customer (if provided). This
                           code appears in two letters and
                           corresponds to the ISO3166.

button_id                  Temporary button ID issued by 1 2 3 4 5 6 7 8 - 1 2 3 4 - 1 2 3 4 -
                           Mobiyo                        1234123456789012

website                    Customer website information 123456
                           – site name, forwarding URL,
                           Mobiyo ID, category, audience
                           restrictions
                                                                                           23
buy_url                            Secure button link provided by payment.allopass.com URL with
                                   Mobiyo                         associated btnid

checkout_button                    Code to create a modal win- payment.allopass.com       URL
                                   dow for merchant use        with associated btnid and ca-
                                                               rousel javascript code carousel
                                                               presentation

Sample response

 onetime-dynamic
 12345678-1234-1234-1234-123456789012
  
   https://payment.allopass.com/buy/buy.apu?btnid=952aa046-4b45-41e4-8123-
7217945aac74
  
Method “website”
Return the information related to a website and the list of products created in it.

URL
https://api.allopass.com/rest/website/

HTTP Method
GET

Authentication
This method requires authentication.

                                                                                            24
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 Mobiyo SDK Call :
https://api.allopass.com/rest/we-          $response = $api->getWebsite(ar-
bsite/1234 5?api_key=cfd3b9a6b-            ray(‘id’ =>
7b309c06aa53f5527c96e67 &api_              ‘12345’));
ts=1258688153
&api_sig=fb1bab50fd2c3751dab-
07b35fe4abcde1 8ebc4c1

Response
Parameter                  Description                     Example

Website                    Information of the website.     

product                    Information of each product 

                                                                                          25
Sample response

Method “product”
Return the detail of a product.

URL
https://api.allopass.com/rest/product/

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

                                                                                              26
Example request
REST CALL :                                 PHP Mobiyo SDK Call :
https://api.allopass.com/rest/pro-            $ response = $api->getPro-
duct/6543 21?api_key=cfd3b9a6b-             duct(‘654321’);
7b309c06aa53f5527c96e6 7&api_
ts=1258688153
&api_sig=fb1bab50fd2c3751dab-
07b35fe4abcde1 8ebc4c1

Response
Parameter                  Description                       Example

id                         Product identifier.               654321

key                        Product key, also known as 123456/654321/456789
                           "auth".

access_type                Access type of the product.       Onetime

creation_date              Date the product was created.     2009-08-30T12:04:21+00:00

name                       Product name.                     MY PRODUCT

website                    Information on the website on id="123456" name="MYWE-
                           which the product is valid.   BSITE.COM" url="http://
                                                         mywebsite.com" restricted_au-
                                                         dience="false" category="Ad-
                                                         vert"

expected_number_of_codes   Number of codes required to 1
                           access the product (from 1 to 5).

purchase_url               URL of the page where the http://website.com/purchase.
                           payment script is installed. php

forward_url                Base currency (euro is default)   http://website.com/product.
                                                             php

error_url                  Customer website information http://website.com/error.php
                           – site name, forwarding URL,
                           Mobiyo ID, category, audience
                           restrictions

notification_url           Secure button link provided by http://website.com/notif.php
                           Mobiyo

                                                                                           27
Sample response

654321
123456/654321/456789
onetime
2009-06-11T08:23:10+00:00

1

Method “transaction”
Returns details of a transaction.

URL
https://api.allopass.com/rest/transaction/

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)

                                                                                            28
Optional         format               string        Return format: xml or json

Optional         reference_currency   string        Base currency (EUR is default).

Example request
REST CALL :                                        PHP Mobiyo SDK Call :
https://api.allopass.com/rest/transac-            $ response = $api->getTransac-
tion/                                             tion(‘0c92578d-
0c92578d-3143-4bd8-aeae-72f2455e2499?             3143-4bd8-aeae-72f2455e2499’);
api_key=cfd3b9a6b7b309c06aa53f-
5527c96e67&a pi_ts=1258688153
&api_sig=fb1bab50fd2c3751dab-
07b35fe4abcde1 8ebc4c1

Response
Parameter                        Description                       Example

status                           Status code                       0

status_description               Description of status.            success

reference_currency               Base currency (EUR is default).   USD

access_type                      Access type of the product.       onetime

transaction_id                   Identifier of the transaction.    0c92578d-3143-4bd8-aeae-
                                                                   72f2455e2499

price                            Information about the transac-    currency="EUR"
                                 tion price.                       amount="10.00" ex-
                                 The reference_amount attri-       change="0.6762240" refe-
                                 bute is the price of the tran-    rence_amount="14.79"
                                 saction in the currency and
                                 exchange rate specified in the
                                 currency and exchange attri-
                                 butes.

creation_date                    Date the      transaction    was 2009-06-11T08:23:10+00:00
                                 created.

end_date                         End date of the transaction, i.e. 2009-06-11T08:23:10+00:00
                                 when payment has been made.

product_name                     Product Name.                     MY PRODUCT

                                                                                              29
website                    Information on the website on id="123456" name="MY-WEB-
                           which the transaction is valid. SITE.COM" url="http://my-we-
                                                           bsite.com"

customer_ip                If the customer IP address is 83.167.62.196
                           specified, the country of the
                           customer is identified via geo-
                           location.

customer_country           Country code of the customer. US
                           This two-letter code complies
                           with ISO-3166.

expected_number_of_codes   Number of codes required to US
                           access the product.

codes                      List of access codes for this R05F6854
                           transaction.

merchant_transaction_id    The transaction ID used by the IN1237123
                           merchant.

data                       Custom merchant data.         

affiliate                  Partner code via an affiliate 12397654
                           program.

partners                   List of partners defined by the BZFV9281
                           merchant.

                                                                                    30
Sample response

1
success
USD
onetime-dynamic
0c92578d-3143-4bd8-aeae-72f2455e2499

2009-06-11T08:23:10+00:00
2009-06-11T08:44:10+00:00

83.167.62.196
FR 1

R05F6854
...

X058G469879E5

Status codes
Code                       Description               Background

0                          Success                   Payment accepted.

                                                                             31
Method “transcription/prepare”
Prepares a payment transaction. Returns a purchasing URL and HTML code for a payment button for
a specific payment method.

URL
https://api.allopass.com/rest/transaction/prepare

HTTP Method
POST

Authentication
This method requires authentication.

Parameters
Status          Parameter              Type         Description

Mandatory       site_id                Integer      Identifier of the merchant site.

Mandatory       pricepoint_id          Integer      Identifier of a price point as determined by one-
                                                    time/pricing and discrete/pricing.

Mandatory       amount                 float        Amount of the transaction.
                                                    The currency is determined by the price point
                                                    identifier.

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 re-
                                                    deemed 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 (recom-
                                                    mended 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 parame-
                                                    ter localizes the interface to a specific country
                                                    (expecting ISO-3166-compliant two-letter
                                                    country codes).

                                                                                                  32
Optional    error_url            string        Address of the page to which customers are di-
                                               rected 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_            string        The transaction ID used by the merchant.
            transaction-id

Optional    data                 string        Custom merchant 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.

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

                                                                                             33
Example request
REST CALL :                                 PHP Mobiyo SDK Call :
https://api.allopass.com/rest/transac-      $response = $api->prepareTransac-
tion/ prepare/?site_id=123456&price-        tion(array(
point_id=222& amount=10&product_             ‘site_id’ => 123456,
name=share+change+toptup                     ‘pricepoint_id’ => 222,
&forward_url=http%3A%2F%2Fwww.my-web-        ‘product_name’ => ‘My product’,
site.com%2Fmy-                               ‘forward_url’=> ‘http://www.myweb-
account.php&api_key=cfd3b9a6b-              site.com’,
7b309c06aa53f 5527c96e67&api_                ‘amount’ => ‘10’,
ts=1258691527&api_sig=1c90d                  ‘reference_currency’ => ‘EUR’,
5846d16f7f9fede3ff3d6769193fe5b0d1a          ‘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-3143-4bd8-
                                                             aeae72f2455e2499

creation_date              Date the      transaction   was 2009-08-30T12:04:21+00:00
                           created.

price                      Information about the transac-    currency="EUR"
                           tion price.                       amount="10.00" ex-
                           The reference_amount attri-       change="0.6762240" refe-
                           bute is the price of the tran-    rence_amount="14.79"
                           saction in the currency and
                           exchange rate specified in the
                           currency and exchange attri-
                           butes.

pricepoint                 Payment information, essen-   id="222" type="credit-card"
                           tially the payment method and country_code="FR"
                           the country of validity.

website                    Website on which the transac- id="123456" name="MYWE-
                           tion is valid.                BSITE.COM" url="http://
                                                         my-website.com" restric-
                                                         ted_audience="false" catego-
                                                         ry="Advert"

buy_url                    Buy URL for the customer.         See code in response below.

checkout_button            HTML code for the payment See code in response below.
                           button.
                                                                                           34
Sample response

onetime-dynamic
USD
0c92578d-3143-4bd8-aeae-72f2455e2499
2009-06-11T08:23:10+00:00

]]>

                                                                             35
Method “transaction/merchant”
Returns details for a merchant transaction based on a transaction ID.

URL
https://api.allopass.com/rest/transaction/merchant

HTTP Method
GET

Parameters
Status           Parameter             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 :                                         PHP Mobiyo SDK Call :
https://api.allopass.com/rest/transac-             $response = $api->getTransactionMer-
tion/ merchant/REF56789? api_key=c-                chant
fd3b9a6b7b309c06aa53f5527c96e67&a pi_              (‘REF56789’);
ts=1258688153
&api_sig=fb1bab50fd2c3751dab-
07b35fe4abcde1 8ebc4c1

Response
Parameter                         Description                       Example

status                            Status code                       0

status_description                Description of status.            success

access_type                       Access type of the product.       onetime

transaction_id                    Identifier of the transaction.    0c92578d-3143-4bd8-aeae-
                                                                    72f2455e2499
                                                                                                36
price                      Information about the transac-   currency="EUR"
                           tion price.                      amount="10.00" ex-
                           The reference_amount attri-      change="0.6762240" refe-
                           bute is the price of the tran-   rence_amount="14.79"
                           saction in the currency and
                           exchange rate specified in the
                           currency and exchange attri-
                           butes.

paid                       Amount actually paid by the 10.00
                           customer in currency

creation_date              Date when transaction was 2009-06-11T08:23:10+00:00
                           created.

end_date                   End date of the transaction, i.e. 2009-06-11T08:23:10+00:00
                           when payment has been made.

product_name               Merchant    defined   product Top Widget Value Rewards
                           name

website                    Information on the website on id="123456" name="SITE-
                           which the transaction is valid. NAME" url="http://www.
                                                           siteURL.com" audience_res-
                                                           tricted="false" category="Re-
                                                           creation and entertainment

customer_ip                If the customer IP address is 83.167.62.196
                           specified, the country of the
                           customer is identified via geo-
                           location.

customer_country           Country code of the customer. US
                           This two-letter code complies
                           with ISO-3166.

expected_number_of_codes   Number of codes required to 1
                           access the product (from 1 to 5).

codes                      List of access codes for this R05F6854
                           transaction.

merchant_transaction_id    The transaction ID used by the ABC_1234567890
                           merchant.

data                       Custom merchant data.            Widget592

affiliate                  Partner code via an affiliate ID1823BB
                           program.

partners                   List of partners defined by the BZFV9281
                           merchant.

                                                                                           37
Sample response

0
success
onetime
98cbcd8e-c66c-4223-82d2-1b2520c8cf57

IT
1
false

  R05F6854
  ...

Method “subcription/list”
Returns the list of Internet+ subscriptions related to a site, product and payment method.

URL
https://api.allopass.com/rest/subscription/list/

HTTP Method
GET

Authentication
This method requires authentication.

                                                                                             38
Parameters
Status      Parameter         Type      Description                        Example

Mandatory   site_id           integer   Identifier of the merchant site.   12345

Mandatory   product_id        integer   Product identifier.                67890

Mandatory   payment_mode_id integer     Payment mode identifier            14
                                        14 = Internet+ mobile “MPME”
                                        4 = Internet+ box

Mandatory   api_key           string    Merchant API key.                  cfd3b9a6b7b-
                                                                           309c06aa53f
                                                                           5527c96e67

Mandatory   api_sig           string    Signature                          fb1bab50fd2c-
                                                                           3751dab07b
                                                                           35fe4abcde18e-
                                                                           bc4c1

Mandatory   api_ts            integer   UNIX Timestamp (GMT).              1258688153125868
                                                                           815335fe4abc-
                                                                           de18ebc4c1

Optional    api_hash          string    Hash function to use for signing: sha1
                                        md5 or sha1. (SHA-1 is default)

Optional    format            string    Return format: xml or json         xml

Optional    amount            float     Amount of the purchase.            5

Optional    merchant_subscri- string    Merchant subscriber reference UIO98765
            ber_reference               sent.

Optional    msisdn            string    Phone number of the customer 0612345678
                                        is Internet+ mobile payment.

Optional    email             string    Email of the customer if Inter-    test@gmail.com
                                        net+ box payment.

Optional    subscription_date string    Subscription date                  2012/09/20
                                        (YYYY/MM/DD).

Optional    pricepoint_id     integer   Price point ID.                    533

Optional    data              string    Data sent when the transaction Myfreedata
                                        was created.

                                                                                            39
Example request
REST CALL :                                       PHP Mobiyo SDK Call :
https://api.allopass.com/rest/                    $response = $api->getSubscription-
subscription /list?site_id=12345&pro-             List(12345,
duct_id=654321&paym ent_mode_                     654321, 14, array(
id=14&api_key=cfd3b9a6b7b309c06aa                  ‘msisdn’ => ‘0612345678’
53f5527c96e67&api_ts=1258688153&api_              ));
sig=fb 1bab50fd2c3751dab07b35fe4abc-
de18ebc4c1&msi sdn=0612345678

Response
Parameter                         Description                      Example

subscriber reference              Allopass subscriber reference.   ZO582336

Sample response

Method “subscription”
URL
https://api.allopass.com/rest/subscription/

HTTP Method
GET

Authentication
This method requires authentication.

                                                                                       40
Parameters
Status         Parameter             Type       Description

Mandatory      suscriber_reference   integer    Allopass subscriber reference.

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 Mobiyo SDK Call :
https://api.allopass.com/rest/                 $response = $api->getSubscrip-
subscription /Z7654XX8?api_key=c-              tion(‘Z628764’);
fd3b9a6b7b309c06aa53f55 27c96e67&api_
ts=1258688153&api_sig=fb1bab5
0fd2c3751dab07b35fe4abcde18ebc4c1

Response
Parameter                      Description                      Example

status                         Subscription status. 0 = Can- 1
                               celled / 1 = Active

status_description             Subscription status descrip- active
                               tion.

access_type                    Access type of the product.      subscription

subscriber_reference           Allopass subscriber reference.   Z35P9287

merchant_subscriber_refe - Merchant subscriber reference. UTG6543
rence

merchant_transaction_id        Merchant transaction ID.         9875TR67

                                                                                            41
website             Information concerning the 

product             Information concerning the 

offer               Information concerning the of- 

customer_country    Customer country.                FR

customer_locale     Customer locale.                 fr_FR

subscription_date   Subscription date information.   

renewal_date        Subscription renewal date in- 

cancellation_date   Subscription cancellation date 

frequency           Frequency subscription infor- 
                    mation. M = Month / W = Week

pricepoint          Price point ID information.      

data                Free data sent by the merchant MyProductDescription
                    when the transaction was
                    created

customer_carrier    Customer carrier information.    

price               Subscription price information. 

                                                                                 42
payouts                    Payouts information by carrier.       

Sample response

0
  cancelled
  subscription
  Z35P9285
  
  FR
  fr_FR
  
  /!1:200:7YCO4hsEXD0RxT5MWbpFd3orywmiNuAaekzf9gjU/ipx?pf=30
  
                                                                                       43
Method “subscription/cancellation”
Let you unsubscribe an “Internet+ box (ISP Billing)” existing subscription.

URL
https://api.allopass.com/rest/subscription/cancellation

HTTP Method
GET

Authentication
This method requires authentication.

Parameters
Status           Parameter              Type         Description

Mandatory        suscriber_reference    integer      Allopass subscriber reference.

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 Mobiyo SDK Call :
https://api.allopass.com/rest/                      This method is not present on the SDK.
subscription ?subscriber_refe-
rence=Z7654XX8&api_key=cfd
3b9a6b7b309c06aa53f5527c96e67&api_
ts=12586 88153&api_sig=fb1bab50fd2c-
3751dab07b35fe4a bcde18ebc4c1

                                                                                                44
Response
Parameter                   Description                      Example

status                      Subscription status. 0 = Can- 1
                            celled / 1 = Active

status_description          Subscription status descrip- active
                            tion.

subscriber_reference        Allopass subscriber reference.   Z35P9287

merchant_subscriber_refe - Merchant subscriber reference. UTG6543
rence

offer                       Information concerning the of- 

subscription_date           Subscription date information.   

cancellation_date           Subscription cancellation date 

frequency                   Frequency subscription infor- 
                            mation. M = Month / W = Week

customer_carrier            Customer carrier information.    

Sample response

1
   Actif jusqu’au 05-03-2014
  Z35P9285
  
                                                                                        45
Appendix 1 :
   Error Codes

Errors in the API
Status code   HTTP Status Message               Error Description

                                             Authentification

82001         400        Hash algorithm         Hash function not found. Use md5 orsha1.
                         not found

82002         401        Invalid API key        The API key does not exist or is malformed.

82003         401        Missing API key        The API key is missing.

82004         401        Invalid signature      The signature of the request is not correct.

82005         401        Missing signature      The signature is missing.

82006         401        Authentication         The authentication (signature verification) has
                         failed                 failed.

52002         403        Insufficient           The user does not have permission to access
                         permissions            the requested resource.

82008         401        Missing timestamp      The timestamp is missing.

82009         500        Expired timestamp      The timestamp passed in parameter api_ts has
                                                expired and the URL is no longer valid. A URL
                                                is valid for 20 seconds.
                                                Please verify your server’s NTP synchroniza-
                                                tion.

                                                                                               46
Web service status

82101   500   Internal error         An unexpected error occurred. Please contact
                                     us to report the incident.

82102   503   Service current-       A resource is temporarily unavailable.
              ly unavailable         Please try again later.

82103   405   Invalid HTTP           The HTTP method (GET, POST, PUT, DELETE)
              method                 is invalid for the requested resource.

82104   404   Resource not           Resource not found.
              found

                                                                              47
Appendix 2 : Payment
types and categories

 Payment         coverage       Fixed /    Price Point Type   Prince Point Category
 Methods                        Discrete

 Premium          Global         Fixed     Premium-calling    Home-Phone-billing
  Calling

 Premium          Global         Fixed      Premium-sms         mobile-payment
   Texte
 Message

 Internet +       France         Fixed         Mpme             mobile-payment
   Mobile

Mikro Ödeme       Turkey        Fixed &     Mikro-odeme         mobile-payment
                                Discrete

 Paybyme          Turkey         Fixed         mobile           mobile-payment

  Mobile         Belgium,        Fixed         mobile           mobile-payment
                Republic of
              Korea, Germany,
               Canada, USA,
              Czech Republic,
                  Austria,
                 Argentina

                                                                                 48
Cuenta Movil        Chile         Fixed         mobile        mobile-payment

 MobilePay           Italy        Fixed     mobile-payment   Home-Phone-billing

  Payforit      United Kingdom    Fixed     mobile-payment   Home-Phone-billing

Internet+ Box      Europe        Fixed &     internet-plus       isp-billing
                                 Discrete

 Credit card       Europe        Fixed &      credit-card        credit-card
                                 Discrete

   HiPay           Europe        Fixed &        hipay             e-wallet
                                 Discrete

 Dineromail Argentina, Brasil,   Fixed &      Dineromail          e-wallet
             Chile, Mexico       Discrete

    Qiwi            Russia        Fixed          Qiwi             e-wallet

Webmoney            Russia        Fixed       Webmoney            e-wallet

                                                                               49
Neosurf           Benin,         Fixed &          Neosurf           prepaid-card
              Cameroun, Côte       Discrete
              d’Ivoire, Senegal,
               Congo, Algeria,
                   Morocco,
                   Andorra,
               Belgium, Spain,
                 France, Italy,
                 Switzerland

Paysafecard        Global          Fixed &         Paysafecard        prepaid-card
                                   Discrete

  Zeevex            USA            Fixed &           Zeevex           prepaid-card
                                   Discrete

Bancontact/       Belgium          Fixed &    bancontact-mistercash   direct-debit
Mister Cash                        Discrete

ING Homepay       Belgium          Fixed &        ing-homepay         direct-debit
                                   Discrete

 KBC/CBC          Belgium          Fixed &          kbc-cbc           direct-debit
                                   Discrete

  Belfius         Belgium          Fixed &           belfius          direct-debit
                                   Discrete

  Giropay        Germany,          Fixed &           giropay          direct-debit
                Netherland         Discrete

                                                                                     50
Sofortu-     Germany,     Fixed &    sofortuberweisung    direct-debit
berweisung   Netherland,   Discrete
               Austria,
             Switzerland

 Payshop      Portugal     Fixed &        payshop          direct-debit
                           Discrete

Multibanco    Portugal     Fixed &       multibanco       cash-payment
                           Discrete

                                                                          51
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

Mobiyo
Pôle Produit
94 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
                                                            52
You can also read