Congrats! That's the right choice.

Come join our service. Let's set up your account. Already have one? Sign in here.

E-mail or phone number: Your email is safe with us. We hate spam just as much as you do. Password: Tip: the longer, the better. Perhaps try a long sentence (that's up to you). check password (check here to uncover your password)

Welcome back!

Balance Url

The OEM Configure Options form presents to providers the ability to provide a Balance URL.

The Balance URL is used by Zoiper to retrieve information about an end user's current balance with the provider.

The information gathered consists of the amount of the balance of the end user's account, the currency used and optionally - the minutes left.

The "Balance URL" field in the Configure Options form needs to look similar to the following examples:
http://example.com/script.php?username=${USERNAME}&password=${PASSWORD}&currency=${CURRENCY}
http://example.com/get_balance.php?u=${USERNAME}&p=${PASSWORD}&c=${CURRENCY}
http://example.com/balance.php/${USERNAME}/${PASSWORD}/${CURRENCY}

The URL contains the following placeholders:
${USERNAME}
${PASSWORD}
${CURRENCY}

The placeholders ${USERNAME} and ${PASSWORD} are required.
The placeholder ${CURRENCY} is optional.

All placeholders need to be in capital letters.

The following are NOT valid placeholders:
${username}
${Password}
${passWord}

The placeholders may appear in any order.

The Balance URL is used by Zoiper as described below.

Zoiper will replace the placeholders ${USERNAME}, ${PASSWORD} and ${CURRENCY} (the latter only if provided) and send an HTTP request to the resulting url.

For example:
http://example.com/get_balance.php?u=${USERNAME}&p=${PASSWORD}&c=${CURRENCY}
will become:
http://example.com/get_balance.php?u=someusername&p=somepassword&c=EUR

The response should be valid XML and should be formatted as the following example:

<?xml version="1.0" encoding="UTF-8"?>
<balance>
	<currency>EUR</currency>
	<amount>50.00</amount>
	<minutes>15:12</minutes>
</balance>

The root XML tag of the response is:
<balance>

Of the tags it contains, 'currency' and 'amount' have to be always present, 'minutes' is optional.

The tags should contain values in the following formats.

<currency> should contain a currency code, present in the "ISO 4217" standard.
"ISO 4217" standard reference links:
http://en.wikipedia.org/wiki/ISO_4217
http://www.iso.org/iso/home/standards/currency_codes.htm
http://www.currency-iso.org/dam/downloads/dl_iso_table_a1.xml
The <currency> tag may contain the default currency the provider uses or may contain the currency Zoiper has requested by replacing the placeholder ${CURRENCY} in the request url.
The ${CURRENCY} placeholder also needs to be replaced with a value, present in the "ISO 4217" standard.

<amount> should contain a floating point value.

<minutes> should be in the format:
minutes:seconds
'minutes' and 'seconds' need to be integers, separated by a colon ( : )

For example 30 minutes, 10 seconds will be formatted as:
30:10

The provider script may also return XML, stating an error has occurred.

NOTE: For the time being the error will not be shown to the user.

In the case of an error the XML should be formatted in the following fashion:

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<message>human friendly error message</message>
	<code>404</code>
</error>

The root XML tag in case of an error is:
<error>

<message> should be a human friendly error message
<code> code should be an integer error code

A test/example Balance URL is:
https://oem.zoiper.com/test/balance1.php?u=${USERNAME}&p=${PASSWORD}&c=${CURRENCY}

Available usernames are:

username:user1 password:password1
username:user2 password:password2

Available currencies are:
EUR
BGN
USD

Requesting
https://oem.zoiper.com/test/balance1.php?u=user1&p=password1&c=USD

results in

<?xml version="1.0" encoding="UTF-8"?>
<balance>
	<currency>USD</currency>
	<amount>52.7</amount>
	<minutes>2:43</minutes>
</balance>