Quick start guide Calls

Prerequisite

Sign up for free to VoiPay and create your first Call service.

Embedding VoiPay in your site

Your site can be built in any language on any platform - you just need to add a few simple lines of HTML to embed the VoiPay Flash object. You will need to make a 'hole' in your site which is 468px wide and 184px high.

VoiPay must not sit within an iFrame - as it needs to expand beyond the boundaries of the object when required (eg. for the user to view their account details).

Once logged in you will find your embed code in your management console - copy and paste this into your site. This is different for each service / DDI you want to connect users to on your telephony platform.

Once you have embedded your code you need to submit for approval in order that we can activate credit card billing (again this is done via your management console) - each site requires approval for compliance with credit card processing regulations. This will take up to 3 working days.

 

Sandbox mode Calls

Testing your services before putting it live

Sandbox mode allows developers to test VoiPay services without a credit card. Even though the service may be rated at 3 credits, sandboxed services will route the call through as normal but will have a maximum call duration of 1 minute. This will allow you to test and ensure the call is routed as expected without having to put through your credit card information.

 

JavaScript API Calls

Overview

VoiPay's client-side JavaScript API allows you to query the embed object for information with regards to the active session. This is also known as the Status API.

Status API methods are namespaced with the prefix of "VoiPay.Status". All methods are asynchronous and therefore require a callback function in order to return data.

Status API reference

Method Returns
VoiPay.Status.getUID(callback) [string] Returns the unique User ID. Returns -1 if user is not logged in.
VoiPay.Status.getCredits(callback) [string] Returns the number of credits for the user. Returns 0 if user is not logged in.
VoiPay.Status.hasCredits(callback) [string] Returns true or false.
VoiPay.Status.isLoggedIn(callback) [string] Returns true or false.
VoiPay.Status.isInCall(callback) [string] Returns true or false.

Example

							
$(document).ready(function() {
	VoiPay.Status.getUID(function(data) {
		console.log(data);	// returns the UserID or "-1" if not logged in
	});
});							
							

 

Quick start guide MicroPayments

Prerequisite

Sign up for free to VoiPay and create your first MicroPayment service.

How it works

A "Single MicroPayment" is a one-off (non-recurring) purchase in which you can request a predefined amount of VoiPay credits to charge users. Users will be presented with a confirmation page, detailing the description and amount of VoiPay credits that you will pass, before confirming the payment. If the user has sufficient credits for the requested amount, then the transaction will be completed and both the user and the merchant (you) will be notified of the new transaction.

 

Sandbox mode MicroPayments

Testing your services before putting it live

Sandbox mode allows developers to test VoiPay services without a credit card. Even though the service may be rated at 3 credits, sandboxed services will process the transaction through as normal but will not charge the user. This will allow you to test and ensure the transaction is processed as expected without having to put through your credit card information.

 

Reference MicroPayments

To use VoiPay MicroPayments, you are first required to be a registered merchant of VoiPay. (Not registered? Click here to sign up now for free). Communication with VoiPay MicroPayments is achieved via an HTTP POST. You are required to construct a payment request using the compulsory and optional parameters below.

The payment request must be an HTTP POST to the following url:

http://live.voipay.net/micropayment.jsp

 

Table of payment request parameters

Name Type Pre-configurable Description
sid integer required no Unique ID for this MicroPayment service.
amount integer required yes The amount of VoiPay credits to charge.
description string required yes The description of what is being charged. This will be displayed to the end user on the confirmation page.
correlationId string optional yes An optional string that you can use to pass through your unique reference ID for this transaction.
tag string optional yes An optional tag that you wish to add and mark this MicroPayment transaction.
successUrl string optional yes The absolute URL that the end user will be redirected to upon a successful transaction.
failureUrl string optional yes The absolute URL that the end user will be redirected to upon a failed transaction.
successNotifyUrl string optional yes The absolute URL to which VoiPay will invoke an HTTP POST to notify the result of a successful MicroPayment transaction.
failureNotifyUrl string optional yes The absolute URL to which VoiPay will invoke an HTTP POST to notify the result of a failed MicroPayment transaction.
x_* string optional no Any custom variables that you wish to pass through the transaction and receive back. This needs a prefix of "x_" otherwise the parameter will not be passed through.

Note on custom Parameters:

VoiPay MicroPayments allows you to pass custom variables through to the payment process such that they will be returned back to you for tracking purposes. All custom variables must have a prefix of "x_" (i.e. "x_mytrackingid") and will be returned as they are passed (i.e. returned exactly as "x_mytrackingid"). The x_ prefix adds a namespace so as to ensure custom parameters do not clash with VoiPay MicroPayment parameters.

For added security, because the successUrl and failureUrl are end user facing URLs (i.e. they can see the URL from their browser, unlike the successNotifyUrl), only pre-specified custom variables will be returned to the successUrl and failureUrl. However all custom variables will be returned to the successNotifyUrl and failureNotifyUrl. The way to pre-specify which custom variable are returned to the successUrl and failureUrl is by adding a token "%%(custom_variable_name)%%" onto the URLs.

example:

Let's assume examplewebsite.com sells picture gallerys and needs 3 custom parameters:

  • galleryId
    • used on the success url to determine which gallery to present to a user who has successfully purchased the content.
  • errorMessage
    • used on the failure url to display the error message to a user who has failed the purchase process.
  • transactionId
    • for internal use - stored in the database for future reference (should not be displayed to the end user).

Below are the steps of how examplewebsite.com would use these custom variables:

  1. Prefix each custom parameters with "x_"
    x_galleryId, x_errorMessage, x_transactionId
  2. Set the succesUrl with the %%x_galleryId%% token
    successUrl=http://examplewebsite.com/success.php?galleryId=%%x_galleryId%%
  3. Set the failureUrl with the %%x_errorMessage%% token
    failureUrl=http://examplewebsite.com/failure.php?error=%%x_errorMessage%%
  4. Set the successNotifyUrl (no need for tokens as all custom variables will be passed)
    successNotifyUrl=http://examplewebsite.com/successnotifylistener.php
  5. Set the failureNotifyUrl (no need for tokens as all custom variables will be passed)
    failureNotifyUrl=http://examplewebsite.com/failurenotifylistener.php

Simple example of MicroPayment using HTML form

 
							
<form action="http://live.voipay.net/micropayment.jsp" method="post" name="micropayment_01">
									
	<!-- Required Parameters -->
	<input type="hidden" name="sid" value="101120">
	<input type="hidden" name="description" value="Gallery #8">
	<input type="hidden" name="amount" value="50">

	<!-- Optional Parameters -->
	<input type="hidden" name="correlationId" value="123456">
	<input type="hidden" name="tag" value="gallery">
	<input type="hidden" name="successNotifyUrl" value="http://examplewebsite.com/successnotifylistener.php">
	<input type="hidden" name="failureNotifyUrl" value="http://examplewebsite.com/failurenotifylistener.php">
	<input type="hidden" name="successUrl" value="http://examplewebsite.com/success.php?galleryId=%%x_galleryId%%">
	<input type="hidden" name="failureUrl" value="http://examplewebsite.com/failure.php?error=%%x_errorMessage%%">

	<!-- Custom Parameters -->
	<input type="hidden" name="x_galleryId" value="9">
	<input type="hidden" name="x_errorMessage" value="Access Denied - You must purchase before viewing this gallery">
	<input type="hidden" name="x_transactionId" value="12BE3F173GA81234">

	<button onclick="micropayment_01.target='POPUPW'; POPUPW = 
	window.open('about:blank','POPUPW','width=700,height=600');">Buy Now</button>
</form>
							

 

Advanced MicroPayments

Pre-configuration of payment request parameters

Typically the successNotifyUrl is where a developer would place code to allow access for an end user to consume the content. For that reason, it may not be safe to display the successNotifyUrl for public viewing (i.e. the URL is easily visible on the source of the HTML form).

Fortunately, VoiPay MicroPayments provides a feature whereby you can pre-configure some of the parameters on our systems beforehand so that you do not have to pass them via the initial HTTP POST request. If you have pre-configured some (if not all) of the optional parameters, all you will have to pass is the required sid parameter and from that, VoiPay MicroPayments will retrieve the remaining pre-configured settings (e.g. successNotifyUrl, failureNotifyUrl, successUrl, failureUrl, etc.) and process the transaction as normal.

Setting up a pre-configuration for your VoiPay MicroPayment will help to reduce the possibility of fraud on your system as well as ensuring your system critical information remains invisible to the public.

 

Notification API MicroPayments

If the merchant (you) specify a successNotifyUrl and/or failureNotifyUrl in the MicroPayments configuration, VoiPay will invoke an asynchronous background HTTP POST to the successNotifyUrl in the event of a successful transaction or failureNotifyUrl in the event of a failed transaction. The POST will contain VoiPay parameters containing information about the payment transaction, as well as any custom variables sent along with the transaction. The parameters provided can be found in the table below.

Table of notification parameters

Name (key) Description
transactionResponseCode The transaction’s response code (Please refer to the Error Code Reference Section for more information).
transactionResponseMessage The transaction’s response message (Please refer to the Error Code Reference Section for more information).
transactionId A unique ID for the transaction.
correlationId The correlation ID that was passed initially in the configuration.
creationDate The date of the transaction.
amount The amount of VoiPay Credits charged for the transaction.
description The description that was used for the transaction.
tag The tag that was used for the transaction.
uid The unique user ID associated with the transaction.
username The username of the user associated with the transaction.
x_* Any custom variables that you passed. This needs a prefix of "x_" otherwise the parameter will not be passed through.

Please note that both the successNotifyUrl and failureNotifyUrl will receive the same POST parameters.

 

Error codes MicroPayments

Table of error codes

Code Description
600100 Unknown error
600111 Insufficient credits. The user did not have sufficient VoiPay credits to complete the purchase
600114 User account suspended