Overview   Solutions   News   Coverage & Tariffs   Affiliate Program

Integration types

Access code

 “Access code” is the preconfigured easy way to accept SMS payments on your website. You can use “Access code” without any additional coding and script handler creating. Just choose the price for your services/goods and the system will generate HTML code for you website. Than you only need to add this code on your website and start earn money.

How it works?

  • User clicks “Pay” button on your site.
  • He gets a short code and a keyword in the payment window. For example German user sees “To get access code please send “sk59” to 44442”.
  • User sends SMS with the keyword and is charged by Mobile Operator.
  • AOneBill receives payment data and sends the unique access code in the SMS response.  
  • User enters the access code on you website and receives offered service/good. For example download link.
  • If you choose weekly payouts, AOneBill starts paying you after the first week.

And two more features:  

  • “Access code” detects the country where the user comes from and provides the user with the data on local mobile operators and prices;
  • And it generates the unique access codes with out any scripts on your side.

To create the Payment Service with the Access code, you need to fill the fields:

  • “Success URL” — Specify the URL that users are redirected to, after they enter the VALID access code.
  • “Error URL” — Specify the URL that users are redirected to, after they enter the INVALID access code.
  • “Limit of use” — Specify how many times or how long you want your customers make use one access code.

 

When the fields are filled and saved, you receive two HTML codes. You should paste these codes to your website. The first one is the code of payment window. It is to be pasted to the page, where the user is required to pay.  And the second one you should paste before the </head> tag on the page, which is closed by the access code.
This type of integration is used to protect the pages from the access without payment. It’s useful fir the digital content distributors first of all.

Protocol of access code authentication

To verify the access code entered by the user, you need to make HTTP GET request to AOneBill platform with URI:


http[s]://AOnebill.com/code-check?service=<service_id>&code=[&checkonly=1][&format=<xml|json|text>]

Parameters:

  • “product” is ID of your payment service
  • “code” is the code entered by the end-user
  • “checkonly” is an optional parameter.   Use it when you need only to check is the code valid, and don’t want to decrease number of times that the code is allowed to be used.  If you don’t specify this parameter, the number of allowed times decreases on 1 point with each request with this code.
  • “format — is an optional parameter which detects the response format.  

Response

Text format

The plain text response consists of 2 lines:

  • First line: «ok» in case of success and «error:N» in case of error. N is the index number of the error.
  • The second line includes the test of error, if the response was error.

E.g.

error:25
[empty line]
code expired
xml Response

xml Response is as follows:

 <?xml version="1.0" encoding='UTF-8'?>
 <response>
     <status>
             error
     </status>
     <error>
             <code>
             25
             </code>
             <message>
                 code expired
             </message>
     </error>
 </response>

Parameter “status” contains the response status “ok” or “Error”, the field  “error->code” contains the index number of the error, and the field  “error->message” contains the test message about the error.

Json Response

The response of this format is the object with the same elements as the xml Response:

  • status
  • error => code, message

E.g.

 {"status":"error","error": { "code" : 25,"message":"some message"} }

Static response

 “Static response” — another preconfigured solution for SMS Payments acceptance.  This integration type allows you to send the universal response to any user. Static Response was created for voting and charity projects, and besides it can be used by “pay what you want” projects and for database building.
Similar to “Access code” setup you don’t need any additional coding. Just fill in all the required fields for payment service creation. And you will get HTML code and you will only have to put it on your website.
All your users will receive the answer, that you’ve specified in payment service settings, such as “Thanks for your vote!” or “Thank you for your donation!”
You can edit this answer any time you like, in your payment service setting at AOneBill.com.
Please remember about text limit in your response:

  • 70 characters if you use Latin with UTF-8 symbols
  • 160 characters if you use pure Latin (7 bit)

API SMS Gateway

“SMS Gateway” is the API for webmasters to create payment service themselves.
AOnebill API is the professional solution that allows individual settings of payment services. You are connected directly to the billing platform. You need to create script-handler and to specify it’s URL in your settings at  http://aonebill.com/services.
 
To create payment service via API, you may need following docs:

  • End-user tariffs and Mobile Operators ID http://aonebill.com/tariffs/?format=csv
  • Instructions for the payment windows in different countries.
  • AOneBill end-user support contacts in different countries

All additional information you can ask Support Team support@aonebill.com

 

The required fields:

  • “Handler” — Specify the URL of your script handler that AOneBill requests should be directed to.
  • “Verification code” — Specify the secret code for AOneBill requests to your script handler.

 

Script handler is the script that receives the request from AOneBill billing platform  and returns the answer in required format.
Script handler URI is the address of your Script handler, which should be hosted somewhere,  in the following format http://www.example/sssms.php. All the requests from AOneBill billing platform  are directed to this address.

Request format

After AOneBill receives SMS from your end-user, it makes GET-request to your Script handler. 
If the Mobile Operator uses MO- tariffication, the user is charged in the moment of message sending.
If the Mobile Operator uses MT- tariffication, the user is charged after the receiving of your response. If the user has enough money to cover the cost of your service, he is charged. The result of charging would be sent to handler by another request.

AOneBill Request Protocol

Request for MO SMS processing:

parameter description
Constant Parameters
msg Full text of the message, which was sent by the end-user, including keyword.
date Date and time of SMS message receiving. Required format: YYYY-MM-DD hh:mm:ss.
operator Mobile Operator name
operator_id Mobile Operator ID
user_id End-user ID
smsid Unique ID of SMS message
cost Partner income in euro
abonent_cost End-user price excluding VAT
abonent_currency End-user currency
in_hold In hold, value 0 (sms paid immediately) and 1 (sms holded). Reparation for the frozen SMS will be credited to the Ballance only after the manager will check these sms to fraud.
num Short code (short number)
country Country ISO-code (the list you can find here http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm)
skey This parameter includes Verification code, which you have specified in your payment service settings. Use it to detect AOneBill requests from any other requests.
skey parameter is formed this way: smsid parameter is appended  (the next line) by the Verification code, than the line is hashing using the md5 algorithm. Code of skey for php:

$skey = md5( $smsid . $verification_code );
You need to check received skey parameter and to compare it with the value on the handler side.
Optional Parameters  
test Test request, value 0 (commercial exploitation) and 1 (test). Usually request about SMS during the  commercial exploitation doesn’t include this parameter.
retry This parameter appears when the first connection to your server failed, and SMS was put into the queue. The first retry is processed in the first minute after the failed connection. User receives the SMS about error. All next requests are sending using the following rule: to the current time is added 5 minutes, multiplied by the number of retry. There can be only 16 retries. If one of retries was successful, the user gets the response from the offered service.
If the connection was established from the first attempt, without retries, there is no  “retry” parameter in the request.
logic This parameter detects the type of tariffication. If the Mobile Operator uses MT- tariffication, this parameter appears in the request with value equal to 1. MT tariffication means that the user is charged after the receiving the response from your service. This parameter appears with value equal to 0 or doesn’t appear at all if the Mobile Operator uses MO- tariffication, when the user is charged in the moment of message sending.

Response format:

status: reply
[empty line]
Text of the response

Text limits:

  • 70 characters if you use Latin with UTF-8 symbols
  • 160 characters if you use pure Latin (7 bit)

 

Additional request

If MT tariffication logic is used, that after the user receives a response you get additional request with the same  sms_id:

parameter description
action=mt_status This parameter indicates the request on the delivering status of MT message.
smsid Unique ID of SMS message
pay_status This parameter indicates was the end-user successfully charged for the SMS (the value is “ok”) or not (the value is “not_ok”)