Boku Technical Reference

www.boku.
com
STANDARD TECHNICAL
REFERENCE FOR DEVELOPERS
Details on standard Boku API calls and callback notifications
Date
2014-07-02
©2014 Boku Inc. All rights reserved. • Boku Standard Technical Reference for Developers • 2014-07-02
Confidential information. Do not copy or distribute without prior permission.
Page 1 of 64
Table of Contents
Table of Contents
TABLE OF CONTENTS......................................................................................................... 2
1 INTRODUCTION & OVERVIEW .................................................................................... 3
PURCHASE FLOW SCHEME DIAGRAM ..............................................................................................4
REFUND SCHEME DIAGRAM ..........................................................................................................4
2 FORMATTING CONVENTIONS .................................................................................... 5
PRESENTATION OF EXAMPLES AND TABLES.......................................................................................5
CURRENCY VALUES IN API CALLS AND CALLBACK NOTIFICATIONS ........................................................5
PROPER PRICE DISPLAY .................................................................................................................6
3 PRICE INFORMATION API CALLS ................................................................................. 7
DISCUSSION: USING “CONTINUOUS PRICES” ....................................................................................7
‘PRICE-LIST’ API CALL ...................................................................................................................9
‘PRICE-INFO’ API CALL............................................................................................................... 14
STATIC MATRIX PRICE REQUEST (‘SERVICE-PRICES’) API CALL .......................................................... 17
ON-DEMAND PRICE POINTS REQUEST (‘PRICE’) API CALL ............................................................... 21
4 TRANSACTIONAL API CALLS ..................................................................................... 27
TRANSACTION INITIATION (‘PREPARE’) API CALL ............................................................................ 27
TRANSACTION VALIDATION (‘VERIFY-TRX-ID’) API CALL................................................................... 34
5 FORWARD-TO URLS ................................................................................................. 37
6 CALLBACK NOTIFICATIONS....................................................................................... 39
FINAL RESULT (BILLINGRESULT) CALLBACK NOTIFICATIONS............................................................... 39
INTERMEDIATE STATUS (EVENT) CALLBACK NOTIFICATIONS.............................................................. 47
REFUND (CHARGEBACK) CALLBACK NOTIFICATIONS ........................................................................ 51
REQUIRED CALLBACK NOTIFICATION ACKNOWLEDGEMENTS (ACKS) ................................................. 53
APPENDIX A. TEST NUMBER USAGE ............................................................................ 56
APPENDIX B. PARTIAL FULFILLMENT ........................................................................... 59
APPENDIX C. NETWORK CODES AND NAMES............................................................... 61
Page 2 of 64
Introduction & Overview
1 Introduction & Overview

The Boku Technical Reference for Developers contains all the technical information needed
to successfully implement the Boku mobile payments solution. You should read the Boku
Solution Overview first: it gives step-by-step instructions for setting up an account and
provides important information about why you might use a given API call or parameter. You will
also need to review the Boku Security Implementation Guide to secure communications
between your servers and the Boku servers.
This document contains four major sections:
• Price Information API calls: details different methods of retrieving price information from
Boku's servers;
• Transactional API calls: used to initiate transactions, verify the status of a transaction, and
replay transaction status notifications;
• Forward-to URLs: information about URLs used to redirect consumers after a completed
transaction;
• Callback notifications: provides details of the callback notification mechanism used to
send transaction status information to merchants' callback servers for the purpose of
content fulfillment and de-fulfillment.
The appendix includes information about using test transactions, which will be useful during
development and QA.
Page 3 of 64
Introduction & Overview
Purchase Flow Scheme Diagram
Refund Scheme Diagram
Page 4 of 64
Formatting Conventions
2 Formatting Conventions
Presentation of Examples and Tables

Example URLs are shown in a grey box with orange borders around parameter names:
Base API URL: https://www.example.com/request
Example API call:

https://www.example.com/request? paramname1 =paramvalue1& paramname2 =paramva
lue2& paramname3 =3
HTTP request parameter name/value tables (e.g. API calls) have an orange column header:
Parameter Type Description Required Comments

1 paramname1 enum Example parameter description #1. Yes Example parameter comments #1.
2 paramname2 string Example parameter description #2. Yes Example parameter comments #2.
3 paramname3 number Example parameter description #3. Yes Example parameter comments #3.
Example XML responses are shown in a grey box with the element/attribute values in blue:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<response>
<fieldname1>fieldvalue1</fieldname1>
<fieldname2>fieldvalue2</fieldname2>
<fieldname3 fieldformat='number'>3</fieldname3>
</response>
XML element/attribute tables are shown with a dark blue column header:
Field Type Description Returned Comments

1 fieldname1 enum Example element description #1. Yes Example field comments #1.
2 fieldname2 string Example element description #2. Yes Example field comments #2.
3 fieldformat enum Example attribute description. Conditional Example field comments #3a
4 fieldname3 number Example element description #3. Yes Example field comments #3b.
Currency Values in API Calls and Callback Notifications

All currency values contained in Boku callback URL notifications will be expressed in the
fractional currency unit (lowest common denominator) for the specified currency. For example,
the US Dollar (USD) has 100 fractional units (cents), and therefore $1.00 is expressed as “100.”
The British Pound Sterling (GBP) also has 100 fractional units (pence), and therefore £25.00 is
expressed as “2500.”
Page 5 of 64
Formatting Conventions
STANDARD FRACTIONAL CURRENCY UNIT EXAMPLES

currency- Fractional units per primary
Country Country Code Currency Unit
decimal-places currency unit
United Kingdom GB GBP 2 100
United States US USD 2 100
While most currencies have 100 fractional units per primary currency unit, there are some
exceptions. The table below lists the markets in which non-standard fractional currency units
are used.
COUNTRIES WITH NON-STANDARD FRACTIONAL CURRENCY UNITS

currency- Fractional units per primary
Country Country Code Currency Unit
decimal-places currency unit
Bahrain BH BHD 3 1,000
Indonesia ID IDR 0 1
Jordan JO JOD 3 1,000
Korea (South) KR KRW 0 1
Oman OM OMR 3 1,000
Vietnam VN VND 0 1
IMPORTANT! Merchant API calls must express currency values in fractional currency units. For
example, a ‘prepare’ API call to initiate a USD $5.00 transaction would include the following
parameters: currency=USD and price-inc-salestax=500.
Proper Price Display

Mobile network operators require that prices are correctly displayed in the consumer's local
currency format. For your convenience and because price display rules are complex, Boku
provides a ‘display-price’ attribute in API responses, detailed in the Price Information API
Calls section of this document. This attribute contains the exact string to display when offering
a price to a consumer.
Boku previously recommended using several currency formatting price attributes (‘currency-
decimal-places’, ‘currency-symbol’, and ‘currency-symbol-orientation’) to format prices for
display to consumers. Now that ‘display-price’ information is available, these attributes should
not be used.
In some countries (e.g. Russia and Singapore) the value of ‘price-inc-salestax’ will be slightly
higher than the price displayed on the payment panel, because mobile network operators in
those markets allow Boku to display the price without fees as long as the Boku terms and
conditions explicitly state that additional fees may apply.
Page 6 of 64
Price Information API Calls
3 Price Information API Calls

The Boku Price Information APIs are used to retrieve information about the prices that
merchants can offer to consumers. This information includes how much can be charged (the
price points or price ranges – together, the “prices”), the payout amount for a given price, which
networks support each price, and how to correctly display the price to the consumer.
There are four Price Information API Calls: ‘price-list’, ‘price-info’, ‘service-prices’, and ‘price’.
Three of them – ‘price-list’, ‘service-prices’, and ‘price’ – retrieve sets of available price points
based on input parameters. The fourth – ‘price-info’ – retrieves information about a specific
price point.
• The ‘price-list’ API call is used to retrieve price points and price ranges for one or all
markets. The ‘price-list’ API response includes one or more ‘country’ elements, each of
which has one or more price rules that define “country prices” and “network-specific
prices”. The “country prices” are available on all networks in the market, and “network-
specific prices” each network’s prices, which may be different than the country prices.
• The ‘price-info’ API is used to retrieve details about a specific price point. It is designed
to be used in conjunction with the ‘price-list’ API call when the ‘price-list’ results are
returned in “continuous-price” format. The ‘price-info’ API provides price-point-specific
details such as formatting specifications, tax information, and payout information.
• The ‘service-prices’ API call is used to retrieve the price points that you’ve stored in
your Service Price Matrices.
• The ’price’ API call can be used to retrieve the “best-matching” price point in each of
one or more markets by specifying “dynamic parameters”.
Chapter 5 of the Boku Solution Overview, “Retrieve Price Information,” discusses the use
case for each Price Information API call. The Boku Pricing Best Practices Guide details the
recommended Price Information API usage for merchants selling virtual currency or otherwise
allowing users to “top up” a balance.
Discussion: Using “Continuous Prices”

A growing number of mobile network operators now support “continuous prices”: merchants can
charge arbitrary amounts to consumers within the ranges established by each carrier. For
example, T-Mobile US supports continuous prices from USD $1.00 to $80.00: any price, in
increments of $0.01, can be charged in this range. This capability is particularly helpful to
Page 7 of 64
merchants offering a shopping-cart checkout flow, in which consumers may select many items
of different prices and then pay for them at once.
Boku’s ‘price-list’ and ‘price-list’ APIs allow merchants to use these continuous prices where
available, while still maintaining support for carriers that have not yet provided this feature.
The ‘price-list’ API call is used to retrieve price points and price ranges for one or all markets.
The ‘price-list’ API response includes one or more ‘country’ elements, each of which has one or
more price rules that define “country prices” and “network-specific prices”. The “country prices”
are available on all networks in the market, whereas “network-specific prices” are available only
on some networks in the market.
The ‘price-info’ API is used to retrieve details about a specific price point. It is designed to be
used in conjunction with the ‘price-list’ API call when the ‘price-list’ results are returned in
“continuous-price” format. The ‘price-info’ API provides price-point-specific details such as
formatting specifications, tax information, and payout information.
UNDERSTANDING PRICE RANGE ATTRIBUTES
Price ranges (price rules listed in “continuous-price” format) are used to compactly describe the
large number of individual price points that form a continuous range; for example a continuous
range from USD $1.00 to $10.00 has 901 individual possible prices. This format can also be
used to define individual (discrete) price points, either singly or in sets.
Price ranges are defined by the following three attributes, all of which are in fractional currency
units1:
1. min-price: The minimum price in the range.

2. max-price: The maximum price in the range.
3. increment: The defined interval between each price in a price range.
a. If the 'increment' is 0, the price range represents a single discrete price point; the
min- and max-price attributes will be equal.
b. If the 'increment' is 1, the price range is continuous.
i. One cent is the fractional currency unit of the US Dollar, and therefore results
specifying “currency=USD”, “min-price=1”, “max-price=3000”, and
“increment=1” define a price range starting at 1 US cent (USD $0.01) and
1
Fractional currency units are discussed in the “Currency Values in API Calls and Callback Notifications” section of
the Boku Technical Reference for Developers
Page 8 of 64
continuing in 1 cent increments (e.g. to 2 cents, 3 cents, 4 cents, etc.) up to a

maximum of 3000 US cents (USD $30.00).
c. If the 'increment' is > 1 (with four exceptions noted below), the price range is a
continuous representation of a set of discrete prices.
i. For example, the values “currency=USD”, “min-price=100”, “max-price=300”,
and “increment=50” specify this set of prices: $1.00, $1.50, $2.00, $2.50, and
$3.00.
ii. The Hong Kong Dollar (HKD), Hungarian Forint (HUF), Japanese Yen (JPY),
and New Taiwan Dollar (TWD) are special cases. These currencies were
historically divisible into fractional currency units but the fractional units are
no longer in use. For example, the Japanese Yen was divided into 100 Sen
or 1000 Rin until 1953, at which point these subunits were demonetized. As
such, a price range for one of these currencies with “increment=100” is, in
fact, a continuous range.
‘price-list’ API Call

The ‘price-list’ API is used to retrieve country prices and, optionally, any network-specific prices.
To retrieve all generally-available prices (country prices) from Boku, call the ‘price-list’ API with
only the authentication parameters (either “password”, or “sig” and “timestamp”). Additional
parameters such as “country”, “currency”, “service-id”, and “network” can be used to further
restrict the prices returned.
Use the “show-all-networks” parameter to include network-specific prices in the response.
The price rules are in “continuous-price” (price range) format by default; they can also be
returned in “discrete-price” (price point) format by specifying “price-type=discrete” in the API call.
The default “continuous-price” format may be used to retrieve prices for markets that don’t fully
support continuous price ranges: the API response includes one or more discrete price points
(price ranges with increment=0). For example, the set of price points {2, 3, 5, 10} is defined
using four price ranges:
1. min-price=2, max-price=2, increment=0

Similarly, the “discrete-price” format can also be used for markets that do support continuous
pricing. The API response will list 20-50 evenly spaced discrete price points within the
Page 9 of 64
continuous range. For example, the continuous range min-price=1, max-price=100,

increment=1 would be represented as 20 discrete prices: {5, 10, 15, … 90, 95, 100}. The
response is limited to 20-50 price points to avoid excessively large result sets. In this example,
the prices not returned (e.g. 8 or 93) are still available for use and can be validated with the
‘price-info’ API.
If the optional “show-all-networks” parameter is included in a ‘price-list’ API call, network-specific

prices are included in the response.
REQUEST EXAMPLE
Base ‘price-list’ API URL: https://api2.boku.com/pricing/1.0/price-list
Example ‘price-list’ API call:

https://api2.boku.com/pricing/1.0/price-list? merchant-
id =bokutest& service-
id =3faee566469704d816bf0ca0& timestamp =1333159135& sig =
4507c9665d3a24400e86a41b526d177c
‘PRICE-LIST’ API CALL - REQUEST PARAMETERS

1 country string Country code in ISO 3166-1- Conditional Filters the result to just the specified
alpha-2 standard. country. Required if ‘network’ is specified.
2 merchant- string Your Merchant Portal Yes Your Merchant Portal account ID was
id primary account ID. selected during initial account setup.
3 network string Alphanumeric network code No If this parameter is used, a valid and
for the mobile network matching country is required.
operator.
4 password string Your API password. Conditional Do not confuse this with the password
used to login to the Merchant Portal. Do
not include this parameter when using
secure hashing authentication.
5 price-type Requested pricing format of
string No The default pricing format if no price type
response; either ‘discrete’ or is reported is ‘continuous’.
‘continuous’
6 reference- string Merchant reference currency No If this parameter is not included, “USD”
currency in ISO 4217 standard. will be used.
7 service-id string The unique alphanumeric ID No Filters the result to the specific service
of a configured type and the countries configured on the
product/service. specified service.
8 show-all- boolean Report a value to “true” to No The default is “false” if this parameter is
networks retrieve country and network not specified.
level pricing.
9 sig string MD5 hash computation Conditional See Boku Security Implementation Guide
signature generated by the for more details.
merchant.
10 timestamp string Network Time Protocol (NTP) Conditional The API call must be made within 300
Unix epoch timestamp. seconds of the API call time.
Page 10 of 64
‘PRICE-LIST’ API CALL XML RESPONSE EXAMPLE - CONTINUOUS-PRICE FORMAT
The following “continuous-price” format ‘price-list’ API response does not contain network-
specific prices.

<pricing-response>
<timestamp string=”2012-05-01 17:08:37”>1340384917404</timestamp>
<time-of-last-forex-update string="2012-05-22
02:00:00">1337652000000</time-of-last-forex-update>
<result-code>0</result-code>
<result-msg>Operation Successful</result-msg>
<api-version>1.0</api-version>
<reference-currency>USD</reference-currency>
<country code=”DE”>
<continuous-price currency=”EUR” min-price=”20” max-price=”3000”
increment=”1” reference-currency=”USD” exchange=”0.81389” status=”1”/>
</country>
<country code=”KR”>
<continuous-price currency=”KRW” min-price=”1” max-price=”300000”
</country>
<country code=”SE”>
<continuous-price currency=”SEK” min-price=”2” max-price=”2”
</country>
</pricing-response>
‘PRICE-LIST’ API CALL XML RESPONSE - CONTINUOUS-PRICE FORMAT
The following elements and attributes are returned in “continuous-price” format.

1 country code stringCountry code in ISO 3166-1-alpha-2 Yes
standard.
2 currency string Currency code in ISO 4217 standard. Yes
Specifies the currency of the local
pricing values.
3 exchange number Exchange rate between the local Yes
currency and the ‘reference-
currency’.
4 increment integer The incremental fractional unit (in Yes The defined interval between
local currency) used to determine each price point in a pricing
the available prices in the range. For USD currency, a
continuous price range. value of “1” indicates a one
cent increment.
Page 11 of 64
5 max-price integer The maximum allowable price, in Yes For USD currency, a value of
fractional units for the indicated “3000” would indicate thirty
country. dollars (USD $30.00).
6 min-price integer The minimum allowable price, in Yes For USD currency, a value of
fractional units for the indicated “20” If currency is USD, would
country. indicate twenty cents (USD
$0.20).
7 reference- string Currency in ISO 4217 standard. Yes “USD” if not supplied in
currency request.
8 status boolean Market availability status. Yes 0 = not available (under
maintenance)
1 = available
‘PRICE-LIST’ API CALL XML RESPONSE EXAMPLE - DISCRETE-PRICE FORMAT
The following “discrete-price” format ‘price-list’ API response does not contain network-specific
prices.

<pricing-response>
<timestamp string=”2012-05-01 17:08:37”>1340384917404</timestamp>
<country code=”DE”>
<discrete-price currency=”EUR” amount=”50” price-inc-tax=”50” price-ex-
tax=”42” receivable-gross=”33” receivable-net=”29” reference-
currency=”USD” exchange=”0.81389” reference-price-inc-tax=”61”
reference-price-ex-tax=”51” reference-receivable-gross=”40” reference-
receivable-net=”36” status=”1” display-price=” 0,50 €”/>
<discrete-price currency=”EUR” amount=”100” price-inc-tax=”100” price-
ex-tax=”84” receivable-gross=”65” receivable-net=”59” reference-
currency=”USD” exchange=”0.81389” reference-price-inc-tax=”122”
reference-price-ex-tax=”103” reference-receivable-gross=”80” reference-
receivable-net=”72” status=”1” display-price=”1,00 €”/>
</country>
</pricing-response>
XML RESPONSE ELEMENTS AND ATTRIBUTES – DISCRETE-PRICE FORMAT
The following elements and attributes are returned in “discrete-price” format.

1 amount* integer The price displayed to the consumer Yes
in the Boku payment panel.
Page 12 of 64
pricing values.
3 display-price string Full string of the specific price point Yes
formatted correctly with the proper
currency symbol, currency symbol
orientation, decimal symbol, and
decimal place.
currency’.
5 price-ex-tax* integer Price excluding tax (e.g. GST, VAT, Yes
etc.).
6 price-inc-tax* integer Price including tax (e.g. GST, VAT, Yes
etc.).
7 receivable- integer Payout before the Boku Fee is Yes
gross* deducted.
8 receivable-net* integer Payout after the Boku Fee is Yes
deducted.
currency request.
10 reference-price- integer The ‘price-ex-tax’ value in the Yes
ex-tax* reference currency.
11 reference-price- integer The ‘price-inc-tax’ value in the Yes
inc-tax* reference currency.
12 reference- integer The ‘receivable-gross’ value in the Yes
receivable- reference currency.
gross*
13 reference- integer The ‘receivable-net’ value in the Yes
receivable-net* reference currency.
14 status boolean Market availability status. Yes 0 = not available (under
maintenance)
1 = available
* These values are returned in fractional currency units, e.g. $1.50 is returned as “150” to
denote 150 cents. Fractional currency units are discussed in the “Currency Values in API Calls
and Callback Notifications” section of the Boku Technical Reference for Developers.
‘PRICE-LIST’ XML RESPONSE - VALID RESULT VALUES

“result-code” value “result-message” value Description
0 Operation Successful Successful request.
32 Bad Bind Credentials Invalid password or authentication value.
33 Invalid Or Missing Currency Code The specified 'reference-currency' is not a valid
currency code.
34 Invalid Or Missing Service-Id The service-id does not exist for this merchant-id.
36 Invalid Country Code Either a country was not provided but a network
was provided, or the provided 'country' code is not
valid.
43 Invalid Request 'show-all-networks' and 'network' were both
provided in the request and they cannot both be
specified.
Page 13 of 64

93 Unsupported network The network code provided does not exist for the
specified country.
‘Price-list’ API responses in “discrete-price” format include the “price-inc-tax”, “price-ex-tax”, and
“net-payout” attributes. When the ‘price-list’ API response is in the default “continuous-price”
format, these attributes – which apply to a specific price point – should be retrieved via the
‘price-info’ API.
‘price-info’ API Call

The ‘price-info’ API is used to retrieve details about a specific price point such as the proper
local pricing format, tax information, and payout values. It is designed to be used in conjunction
with the ‘price-list’ API call when the ‘price-list’ results are returned in “continuous-price” format.
The ‘price-info’ API can also be used to verify that a specific price point exists within a
continuous range. If a ‘price-info’ request is made for an invalid price point, an error response
will be returned.
REQUEST EXAMPLE
Base ‘price-info’ API URL: https://api2.boku.com/pricing/1.0/price-info
Example ‘price-info’ API call:

https://api2.boku.com/pricing/1.0/price-info? merchant-
id =bokutest& timestamp =1333159135& sig =4507c9665d3a24400e86a41b526d177c&
price =100& country =DE
‘PRICE-INFO’ API CALL - REQUEST PARAMETERS

1 country string Country code in ISO 3166-1- Yes The currency is inferred based on the local
alpha-2 standard. currency for the specified country.
2 network string Alphanumeric network code No If this parameter is used, a valid and
for the mobile network matching country is required.
operator.
3 merchant- string Your Merchant Portal Yes Your Merchant Portal account ID was
id primary account ID. selected during initial account setup.
4 password string Your API password. No Do not confuse this with the password
secure hashing authentication.
5 price integer The price for which display, Yes The ‘price’ value will be matched with the
tax and payout information ‘amount’ value of a discrete price point.
should be computed.
Page 14 of 64

6 reference- string Merchant reference currency No If this parameter is not included, “USD”
currency in ISO 4217 standard. will be used.
7 sig string MD5 hash computation No See Boku Security Implementation Guide
signature generated by the for more details.
merchant.
8 timestamp string Network Time Protocol (NTP) No The API call must be made within 300
Unix epoch timestamp. seconds of the API call time.
‘PRICE-INFO’ API CALL XML RESPONSE EXAMPLE
The ‘price-info’ API response includes price-point-specific information including payout, display
formatting, and networks that support the price.

<pricing-response format="discrete">
<timeStamp string="2013-10-21 23:11:31">1382397091330</timeStamp>
<response-code>0</response-code>
<response-message>Operation Successful</response-message>
<country code="US">
<discrete-price status="1" reference-receivable-net="539" reference-
receivable-gross="599" reference-price-inc-tax="999" reference-price-
ex-tax="999" reference-currency="USD" receivable-net="539" receivable-
gross="599" price-inc-tax="999" price-ex-tax="999" exchange="1.00000"
display-price="$9.99" currency="USD" amount="999">
<network name="AT&T" code="13f020"/>
<network name="US Cellular" code="13f021"/>
<network name="T-Mobile" code="13f040"/>
</discrete-price>
</country>
</pricing-response>
XML RESPONSE ELEMENTS AND ATTRIBUTES
The following elements and attributes are returned in the ‘price-info’ API response.

1 country code string Country code in ISO 3166-1-alpha-2 Yes
standard.
2 amount* integer The price displayed to the consumer Yes
in the Boku payment panel.
pricing values.
4 display-price string Full string of the specific price point Yes
formatted correctly with the proper
Page 15 of 64
orientation, decimal symbol, and

decimal place.
currency’.
6 price-ex-tax* integer Price excluding tax (e.g. GST, VAT, Yes
etc.).
7 price-inc-tax* integer Price including tax (e.g. GST, VAT, Yes
etc.).
8 receivable- integer Payout before the Boku Fee is Yes
gross* deducted.
9 receivable-net* integer Payout after the Boku Fee is Yes
deducted.
currency request.
11 reference-price- integer The ‘price-ex-tax’ value in the Yes
ex-tax* reference currency.
12 reference-price- integer The ‘price-inc-tax’ value in the Yes
inc-tax* reference currency.
13 reference- integer The ‘receivable-gross’ value in the Yes
gross*
14 reference- integer The ‘receivable-net’ value in the Yes
receivable-net* reference currency.
15 status Boolean Market availability status. Yes 0 = not available (under
maintenance)
1 = available
16 network name string Human-readable name of the Yes
mobile network operator.
17 network code string Alphanumeric network code for the Yes
mobile network operator.
* These values are returned in fractional currency units, e.g. $1.50 is returned as “150” to
denote 150 cents. Fractional currency units are discussed in the “Currency Values in API Calls
and Callback Notifications” section of the Boku Technical Reference for Developers.
‘PRICE-INFO’ XML RESPONSE - VALID RESULT VALUES

0 Operation Successful Successful request.
29 Unsupported Price Point The requested price does not existing within the
specified parameters.
31 Invalid or Missing Price A price was not supplied in the request, which is a
required parameter.
32 Bad Bind Credentials Invalid password or authentication value.
33 Invalid Or Missing Currency Code The specified 'reference-currency' is not a valid
currency code.
36 Invalid Country Code Either a country was not provided but a network
was provided, or the provided 'country' code is not
valid.
Page 16 of 64
Static Matrix Price Request (‘service-prices’) API Call

The ‘service-prices’ API call is used to retrieve price points that are stored in the services' Static
Price Matrices. Configuring and storing prices in static matrices (i.e. the “static pricing method)
is the recommended method for merchants selling virtual currency. See the Key decision:
how to set/select price points information box in Chapter 4 of the Boku Solution Overview.
Base ‘service-prices’ API URL: https://api2.boku.com/billing/request
Example ‘service-prices’ API call:

https://api2.boku.com/billing/request? action =service-prices& merchant-id =
bokutest& password =test321& service-id =18e050091eac44e3bcd15b63
‘SERVICE-PRICE’ API CALL - PARAMETERS

1 action enum Specifies the API call type. Yes For this call type, use action=service-
prices.
2 country string Country code in ISO 3166-1- No If the specified market is not approved for
alpha-2 standard the service, error code 42 (“Country Not
(www.iso.org/iso/english_co Available On Requested Service”) will be
untry_names_and_code_ele returned.
ments).
3 merchant-id string Your Merchant Portal Yes
Your Merchant Portal account ID was
primary account ID. selected during initial account setup.
MD5 hashing authentication.
5 row-ref number Row number identifier in the No ‘Row-ref’ numbers can be found in the
static product/service price Service Price Matrix. Note that row-ref
matrix. numbers are always sequential: if a row is
deleted, the numbering of subsequent
rows will be updated.
6 service-id string The unique alphanumeric ID No If included, results will be limited to the
of a configured price points selected for the specified
product/service. service.
7 sig string MD5 hash signature Conditional Required when using MD5 hashing
generated by the merchant. authentication.
8 timestamp string Network Time Protocol (NTP) Conditional Required when using MD5 hashing
Unix epoch timestamp. authentication. The API call must be
made within 300 seconds of this time.
‘SERVICE-PRICES’ API CALL XML RESPONSE - EXAMPLE

<service-prices>
<action>service-prices</action>
Page 17 of 64
<service id="18e050091eac44e3bcd15b63" name="Demo Merchant" reference-
currency="USD" price-mode="price">
<key-value row-ref="0" key="100">
<pricing country="US" amount="100" currency="USD" currency-symbol="$"
currency-symbol-orientation="l" currency-decimal-places="2" price-
inc-salestax="100" price-ex-salestax="100" receivable-gross="54"
receivable-net="49" exchange="1.00000" reference-amount="100"
reference-price-inc-salestax="100" reference-price-ex-salestax="100"
reference-receivable-gross="54" reference-receivable-net="49" number-
billed-messages="1" status="1"/>
<pricing country="GB" amount="75" currency="GBP" currency-symbol="£"
</key-value>
<key-value row-ref="1" key="500">
reference-receivable-gross="288" reference-receivable-net="259"
number-billed-messages="1" status="1"/>
<pricing country="GB" amount="350" currency="GBP" currency-symbol="£"
reference-receivable-gross="351" reference-receivable-net="316"
number-billed-messages="2" status="1"/>
</key-value>
</service>
</service-prices>
‘SERVICE-PRICES’ API CALL XML RESPONSE - GENERAL ELEMENTS
The following elements are returned once with each ‘service-prices’ API call response:

1 action enum Specifies the API call type. Yes For this call type, the XML
response will include:
<action>service-
prices</action>
Page 18 of 64

2 reference- string
Currency in ISO 4217 standard Yes If this parameter was not
currency (www.xe.com/iso4217.php). included, “USD” will be used.
Specifies the currency unit of the
‘reference-’ attributes.
3 result-code number Numeric response code to indicate Yes Non-zero results are errors.
the result of the API call. See the following table for
details.
4 result-msg string
Human-readable response message Yes See the following table for
corresponding to the ‘result-code.’ details.
5 row-ref number Row number identifier in the static Yes ‘Row-ref’ numbers can be
product/service price matrix. found in the product/service
price matrix. ‘Row-ref’
numbers are always
sequential: if a row is
deleted, the numbering of
subsequent rows will be
updated.
6 sig string MD5 hash signature for the XML Yes Returned in the XML header.
response returned by Boku. Validate using process
detailed in the Boku Security
Implementation Guide.
7 service-id string The unique alphanumeric ID of a Yes
configured product/service.
8 service name string The configured product/service Yes
name.
‘SERVICE-PRICES’ API CALL XML RESPONSE - PRICE-POINT ATTRIBUTES
The following attributes are returned for each price in the ‘service-prices’ API call response:

1 amount* number The price displayed to the consumer Yes
in the Boku Payment Panel.
2 comments string Deprecated: Indicates whether the Conditional Use the ‘price-list’ and ‘price-
price point is only available for info’ APIs to retrieve network-
certain mobile network operators in specific information instead.
a country.
3 country string Country code in ISO 3166-1-alpha-2 Yes
standard
(www.iso.org/iso/english_country_
names_and_code_elements).
4 currency string Currency code in ISO 4217 standard Yes
(www.xe.com/iso4217.php).
5 currency- number Deprecated: Number of decimal Yes Use the “display-price”
decimal- places for the currency unit. attribute instead.
places
6 currency- string Deprecated: Currency symbol. Yes Use the “display-price”
symbol attribute instead.
Page 19 of 64

7 currency- enum Deprecated: Orientation of Yes Use the “display-price”
symbol- currency symbol relative to currency attribute instead.
orientation value.
8 display-price string Properly-formatted string for the Yes Use this string to display this
specific price point. Includes the price on your website.
orientation, and decimal places.
currency.’
10 price-ex- number Price excluding tax. Yes
salestax*
11 price-inc- number Price including tax (the total amount Yes
salestax* the consumer will pay).
12 receivable- number Indicative payout before the Boku Yes Actual payouts may vary due
gross* fee. to exchange-rate
movements, discrepancies,
chargebacks, and withholding
taxes.
13 receivable- number Indicative payout after the Boku fee. Yes Actual payouts may vary due
net* to exchange-rate
taxes.
14 reference- number The ‘amount’ value in the reference Yes
amount* currency.
15 reference- number The ‘price-ex-salestax’ value in the Yes
price-ex- reference currency.
salestax*
16 reference- number The ‘price-inc-salestax’ value in the Yes
price-inc- reference currency.
salestax*
17 reference- number The ‘receivable-gross’ value in the Yes
gross*
18 reference- number The ‘receivable-net’ value in the Yes
net*
maintenance)
1 = available
* These values are returned in fractional currency units, e.g. $1.50 is returned as “150” to denote
150 cents. Please see the Currency Values in API Calls and Callbacks section in this
document.
‘SERVICE-PRICES’ XML RESPONSE - VALID RESULT VALUES
Page 20 of 64
result-code result-message
0 Operation Successful
20 Missing or Invalid 'cmd=' value
28 Invalid signature
32 Bad Bind Credentials
35 Internal Error
60 Invalid row-ref value
On-Demand Price Points Request (‘price’) API Call

RETRIEVING “BEST-MATCH” PRICE POINTS
The ’price’ API call can be used to retrieve the price point(s) closest to a targeted value in each
of one or more markets by specifying “dynamic parameters”. These dynamic parameters are
detailed in the ‘Price’ API Call - Dynamic Parameters table on the following pages. If the
specified dynamic parameters are too restrictive then no price point solutions may be found for
some countries and users in those countries will be unable to use the Boku mobile payments
service.
Base ‘price’ API URL: https://api2.boku.com/billing/request
Example ‘price’ API call retrieving “best-match” price points:
https://api2.boku.com/billing/request? action =price& merchant-id

=bokutest& password =test321& service-id =18e050091eac44e3bcd15b63
& dynamic-price-mode =price& dynamic-deviation =2& dynamic-deviatio
n-policy =hi-only& target =100& currency =USD
‘PRICE’ API CALL - GENERAL PARAMETERS

1 action enum Specifies the API call type. Yes For this call type, use
action=price.
2 country string Country code in ISO 3166-1-alpha-2 No If the specified market is not
standard approved for the service,
(www.iso.org/iso/english_country_n error code 42 (“Country Not
ames_and_code_elements). Available On Requested
Service”) will be returned.
3 currency string Currency code in ISO 4217 standard No If this parameter is not
(www.xe.com/iso4217.php). included, “USD” will be used
Specifies the currency unit of the as the default value. Ignored
“target” value. when used with dynamic
parameters.
4 ip-address string Consumer's IP address. No If this parameter is included,
the XML response will include
a ‘geo-countrycode’ attribute.
Page 21 of 64

5 merchant-id string Your Merchant Portal primary Yes Your Merchant Portal account
account ID. ID was selected during initial
account setup.
6 password string Your API password. Conditional Do not confuse this with the
password used to login to the
Merchant Portal. Do not
include this parameter when
using MD5 hashing
authentication.
7 reference- string Merchant reference currency unit in No Used to set the currency unit
currency ISO 4217 standard of the ‘reference-’ attributes
(www.xe.com/iso4217.php). in the XML response.
If this parameter is not
reported, “USD” will be used.
When dynamic parameters
are used, this parameter
specifies the currency of the
‘target’ parameter.
8 service-id string The unique alphanumeric ID of a Conditional When this parameter is
configured product/service. included results will be
limited to markets approved
for the specified service.
Required when using dynamic
parameters.
9 sig string MD5 hash signature generated by Conditional Required when using MD5
the merchant. hashing authentication.
10 timestamp string Network Time Protocol (NTP) Unix Conditional Required when using MD5
epoch timestamp. hashing authentication. The
API call must be made within
300 seconds of this time.
‘PRICE’ API CALL - DYNAMIC PARAMETERS

A dynamic ‘price’ call requires the ‘target’ and ‘dynamic-deviation’ parameters and will return
at most one price point per country/market. If no price point can be found in the calculated
range, “No payment solution available” (result-code=41) will be returned.
1 dynamic- number The % deviation (± 0-1,000) from the Yes
deviation ‘target’ value that is acceptable.
2 dynamic- enum Indicates whether values higher or No The Valid ‘Dynamic-
deviation- lower than the ‘target’ value are Deviation-Policy’ Field Values
policy permissible. table on the next page lists
the options. If not reported,
the “nearest-no-preference”
policy will be used.
3 dynamic- enum Specifies whether the matching No The Valid ‘Dynamic-Price-
price-mode algorithm seeks a match with the Mode’ Field Values table on
end-user price or the net payout the next page lists the
value. options. If not reported, the
“price” mode will be used.
Page 22 of 64

4 target number The desired value, in fractional Yes The currency of this ‘target’
currency units, of the specified value is based on the
‘reference-currency.’ reported ‘reference-currency’
parameter. This value must
be entered in fractional
currency units, e.g. $1.50 is
entered as “150” to denote
150 cents. Please see the
Currency Values in API Calls
and Callbacks section in this
document.
VALID ‘DYNAMIC-DEVIATION-POLICY’ FIELD VALUES

Value Description
hi-only The closest price point to the ‘target’ value within the range from ‘target’ to ‘target’
x (1 + ‘dynamic-deviation’) will be returned.
nearest-no-preference The closest price point to the ‘target’ value will be selected regardless of whether
the value is higher or lower than ‘target’ value. If there exist equidistant price
points higher and lower, then the higher price point will be returned.
VALID ‘DYNAMIC-PRICE-MODE’ FIELD VALUES

Use the ‘dynamic-price-mode’ parameter to specify which price element is matched by the
dynamic algorithm.
Value Description
price The ‘target’ value will be matched to ‘price-inc-salestax’ values.
payout-net The ‘target’ value will be matched to ‘receivable-net’ (net payout) values.
‘PRICE’ API CALL XML RESPONSE - EXAMPLE

<pricing>
<timestamp string="2010-09-01 18:28:05">1283365685828</timestamp>
<action>price</action>
<pricing country="CH" amount="100" currency="CHF" currency-symbol="CHF"
currency-symbol-orientation="l" currency-decimal-places="2" price-inc-
salestax="100" price-ex-salestax="93" receivable-gross="40"
currency-symbol-orientation="l" currency-decimal-places="2" price-inc-
salestax="100" price-ex-salestax="100" receivable-gross="54"
Page 23 of 64
</pricing>
‘PRICE’ API CALL XML RESPONSE - GENERAL ELEMENTS
The following elements are returned once with each ‘price’ API call response:

1 action enum Specifies the API call type. Yes For this call type, the XML
response will include:
<action>price</action>
2 geo- stringConsumer’s country code in ISO Conditional Returned if the “ip-address”
countrycode 3166-1-alpha-2 standard parameter was included in
(www.iso.org/iso/english_country_ the ‘price’ API call.
names_and_code_elements) based
on the user's IP address.
3 reference- string Currency in ISO 4217 standard Yes If this parameter was not
currency (www.xe.com/iso4217.php). included, “USD” will be used.
4 result-code number Numeric response code to indicate Yes Non-zero results are errors.
the result of the API call. See the following table for
details.
5 result-msg string Human-readable response message Yes See the following table for
corresponding to the ‘result-code.’ details.
6 sig string MD5 hash signature for the XML Yes Returned in the XML header.
response returned by Boku. Validate using process
detailed in the Boku Security
7 time-of-last- string Time when FX rates were last Yes
forex-update updated.
string
8 timestamp string Network Time Protocol (NTP) Unix Yes
epoch timestamp.
9 timestamp string API server timestamp. Yes
string
‘PRICE’ API CALL XML RESPONSE - PRICE-POINT ATTRIBUTES
The following attributes are returned for each price-point in the ‘price’ API call response:

1 amount* number The price displayed to the consumer Yes
in the Boku Payment Panel.
Page 24 of 64

2 comments string Deprecated: Indicates whether the Conditional Use the ‘price-list’ and ‘price-
price point is only available for info’ APIs to retrieve network-
certain mobile network operators in specific information instead.
a country.
standard
local, non reference-currency
values.
5 currency- number Deprecated: Number of decimal Yes Use the “display-price”
decimal- places for the currency unit. attribute instead.
places
6 currency- string Deprecated: Currency symbol. Yes Use the “display-price”
symbol attribute instead.
7 currency- enum Deprecated: Orientation of Yes Use the “display-price”
symbol- currency symbol relative to currency attribute instead.
orientation value.
8 display-price string Properly-formatted string for the Yes Use this string to display this
specific price point. Includes the price on your website.
orientation, and decimal places.
currency.’
10 price-ex- number Price excluding tax. Yes
salestax*
11 price-inc- number Price including tax (the total amount Yes
salestax* the consumer will pay).
12 receivable- number Indicative payout before the Boku Yes Actual payouts may vary due
gross* fee. to exchange-rate
taxes.
13 receivable- number Indicative payout after the Boku fee. Yes Actual payouts may vary due
net* to exchange-rate
taxes.
14 reference- number The ‘amount’ value in the reference Yes
amount* currency.
15 reference- number The ‘price-ex-salestax’ value in the Yes
price-ex- reference currency.
salestax*
16 reference- number The ‘price-inc-salestax’ value in the Yes
price-inc- reference currency.
salestax*
Page 25 of 64

17 reference- number The ‘receivable-gross’ value in the Yes
gross*
18 reference- number The ‘receivable-net’ value in the Yes
net*
maintenance)
1 = available
* These values are returned in fractional currency units, e.g. $1.50 is returned as “150” to denote 150
cents. Please see the Currency Values in API Calls and Callbacks section in this document.
‘PRICE’ API CALL XML RESPONSE - VALID RESULT VALUES

result-code result-message Notes
30 Unknown IP address
33 Invalid Or Missing Currency Code
34 Invalid Or Missing Service-Id
35 Internal Error
36 Invalid or Missing Country Code
41 No payment solution available This result-code will be returned if there is no valid mobile
price point found for the specified dynamic parameters.
43 Invalid Request
Page 26 of 64
Transactional API Calls
4 Transactional API Calls

The ‘prepare’ and ‘verify-trx-id’ API calls pertain to individual transactions. The ‘prepare’ call is used
to initiate a new transaction and the ‘verify-trx-id’ call can be used to check the status of non-expired
transactions that were started within the last three days. The ‘verify-trx-id’ should only be used if the
merchant is unable to implement MD5 hashing as recommended (see the Boku Security
Implementation Guide for details).
Transaction Initiation (‘prepare’) API call

Use a ‘prepare’ API call to initiate a consumer transaction. There are three types of ‘prepare’ calls;
the type that you use will depend on how you select and manage which price points you’ll use.
1) Exact-match ‘prepare’ calls allow you to specify the exact price that you want the consumer to
pay.
2) Row-reference ‘prepare’ calls specify a row in a Boku Service Price Matrix (configured in your
Boku Merchant Portal account). The transaction will use the price point that has been selected for
that row, for the specified country. Dynamic-match ‘prepare’ calls find the best-matching price
point given the dynamic parameters passed in as part of the ‘prepare’ call. Some conditions may
cause no match to be found.
Base ‘prepare’ API URL: https://api2.boku.com/billing/request
Example exact-match ‘prepare’ call:

https://api2.boku.com/billing/request? action =prepare& merchant-id =bokutest&
password =test321& service-id =18e050091eac44e3bcd15b63& currency =USD& country
=US& price-inc-salestax =100& consumer-id =testuser9876
Example row-reference ‘prepare’ call:

https://api2.boku.com/billing/request? action =prepare& merchant-id =bokutest&
password =test321& service-id =18e050091eac44e3bcd15b63& row-ref =3& consumer-
id =testuser9876& country =US
Example dynamic-match ‘prepare’ call:

https://api2.boku.com/billing/request? action =prepare& merchant-id =bokutest
& password =test321& service-id =18e050091eac44e3bcd15b63& dynamic-price-mode =
price& dynamic-deviation =0& dynamic-deviation-policy =hi-
only& currency =USD& target =100& consumer-id =testuser9876& country =US
Page 27 of 64
PAYMENT PANEL DISPLAY OVERRIDE PARAMETERS
Certain ‘prepare’ call parameters can be used to override values statically configured during the
product/service configuration. These parameters are listed in the table and shown in the image
below.
Parameter Description Example Value Shown in Image

msisdn Pre-populated phone number 600022333
sub-merchant-name Game name StuffPet
desc Product description 100 Coins
Page 28 of 64
‘PREPARE’ API CALL - PARAMETERS

1 action enum Specifies the API call type. Yes
For this call type, use
action=prepare.
2 callback-url string Reporting this value overrides the No Can be used to dynamically
callback URL specified on the override the configured
merchant service. callback URL on a per
transaction basis.
3 consumer-id string Consumer identifier in merchant Yes This value is used to perform
system. payment transaction risk
checks which are intended to
limit fraud targeted at using
many MSISDNs by the same
consumer account in a
merchant system.
Restrict to 255 characters;
longer strings will be
truncated.
4 country string Country code in ISO 3166-1-alpha-2 Yes • If the specified market is
standard not approved for the
(www.iso.org/iso/english_country_ service, error code 42
names_and_code_elements). (“Country Not Available
On Requested Service”)
will be returned.
5 currency string Currency code in ISO 4217 standard Conditional If this parameter is not
(www.xe.com/iso4217.php). included, “USD” will be used.
Specifies the currency of the ‘target’ Required if making an “exact-
or ‘price-inc-salestax’ value. match” ‘prepare’ call (using
‘price-inc-salestax’).
6 desc string The exact quantity and name of the Conditional Restrict to 20 characters;
item(s) being purchased. If more longer strings will be
than one of an item is being truncated. Do not report the
purchased (e.g. “1000 Credits”), the dollar ($) symbol in this field
quantity must be included. value. This string is displayed
Overrides the “Product Description” to the end-user in the Boku
displayed on the Payment Panel. payment panel and is subject
to operator approval.
Please do not use commas
(e.g. use “1000” not “1,000”).
7 fwdurl string Overrides the successful transaction No Restrict to 255 characters;
forward-to URL. If ‘fail-fwdurl’ longer strings will be
(below) is not specified, it will also truncated.
override the failed transaction
forward-to URL.
8 fail-fwdurl string Overrides the failed transaction No Restrict to 255 characters;
forward-to URL. longer strings will be
truncated.
9 merchant-id string Your Merchant Portal primary Yes Your Merchant Portal
account ID. account ID was selected
during initial account setup.
Page 29 of 64

10 msisdn string Pre-populates the Payment Panel No Will not work in some
mobile number field. countries where this
functionality is not allowed
(e.g. United States).
11 param string Pass-through parameter for No Restrict to 100 characters;
merchant’s use. longer strings will be
truncated.
If included, this parameter
will be returned in callback
notifications and appended
to forward-to URLs.
12 password string Your API password. Conditional Do not confuse this with the
password used to login to the
Merchant Portal. Do not
include this parameter when
using MD5 hashing
authentication.
13 price-inc- number Price including tax (the total amount Conditional If included, ‘currency’
salestax the consumer will pay). Used with parameter is required.
“exact-match” ‘prepare’ calls as This value must be entered in
described above. fractional currency units, e.g.
$1.50 is entered as “150” to
denote 150 cents. Please see
the Currency Values in API
Calls and Callbacks section in
this document.
14 row-ref number Row number identifier in the static Conditional ‘Row-ref’ numbers can be
product/service price matrix. found in the Service Price
Matrix. ‘Row-ref’ numbers
are always sequential: if a
row is deleted, the
numbering of subsequent
rows will be updated.
15 sig string MD5 hash computation signature Conditional Required when using MD5
generated by the merchant. hashing authentication.
17 sub- string End-merchant identifier when a Conditional Required for all transactions
merchant-id payment enabler account is being conducted by a payment
used to conduct the transaction. enabler account.
18 sub- string Name of application, game or No Restrict to 15 characters;
merchant- website for which this transaction is longer strings will be
name being conducted. The user should truncated.
recognize this name. Overrides the This value is displayed to the
“Service Name” displayed on the end-user in the Boku
Payment Panel and in SMS payment panel and is subject
messages. to operator approval.
Page 30 of 64

19 target number The desired value, in fractional Yes The currency unit of this
currency units, of the specified ‘target‘ value is based on the
‘currency.’ reported ‘currency‘
150 cents. Please see the
Currency Values in API Calls
and Callbacks section in this
document.
20 timestamp string Network Time Protocol (NTP) Unix Conditional Required when using MD5
epoch timestamp. hashing authentication. The
API call must be made within
300 seconds of this time.
‘PREPARE’ API CALL - DYNAMIC PARAMETERS

The ‘target’ and ‘dynamic-deviation’ parameters are required when making a dynamic
‘prepare’ call. A dynamic ‘price’ call will return at most one price point per country/market. If no
price point can be found in the dynamically calculated range, a “No payment solution available”
error (result-code=41) will be returned.

1 dynamic- number The % deviation (± 0-1,000) from Yes Required when using
deviation the ‘target’ value that is acceptable dynamic pricing parameters
as a price point selection. in the Boku ‘prepare' API
request.
2 dynamic- enum Indicates whether values higher or No See the Valid ‘Dynamic-
deviation- lower than the ‘target’ value are Deviation-Policy’ Field
policy permissible. Values table on page 27. If
not reported, this value
defaults to “nearest-no-
preference” policy.
3 dynamic- enum Specifies whether the matching No See the Valid ‘Dynamic-Price-
price-mode algorithm seeks a match with the Mode’ Field Values table on
end-user price or the net payout the page 27. If not reported,
value. this value will default to
“price” mode.
Page 31 of 64

4 target number The desired value, in fractional Yes The currency of this ‘target’
currency units, of the specified value is based on the
‘reference-currency.’ reported ‘reference-currency’
150 cents. See the Currency
Values in API Calls and
Callbacks section.
‘PREPARE’ API CALL XML RESPONSE - EXAMPLE
<?xml version='1.0' encoding='ISO-8859-1' ?>

<prepare-request>
<action>prepare</action>
<trx-id>b368363a00bbddbf794eba33</trx-id>
<button-markup>

<div>
<script language="JavaScript"
src="https://buy.boku.com/checkoutbutton/b368363a00bbddbf794eba33/buy.js">
</script>
</div>

</button-markup>
<buy-url>
https://buy.boku.com/checkoutidentify/b368363a00bbddbf794eba33/buy.js
</buy-url>
</prepare-request>
Two critical pieces of information are returned in the 'prepare' API XML response:
1. trx-id: the unique Boku transaction ID. Use this ID to match the initiated purchase with
the ‘event,’ ‘billingresult,’ and ‘chargeback’ callback notifications.
2. buy-url: the URL of the payment panel for the transaction. We recommend that you
load this payment panel URL into an embedded or overlay iFrame for the best user
experience. The Boku Merchant Technical Solutions team
(merchantsupport@boku.com) can provide an overlay iFrame sample code pack on
request.
Page 32 of 64
‘PREPARE’ API CALL XML RESPONSE - ELEMENTS & ATTRIBUTES

Parameter Type Description Returned Comments
1 action enum Specifies the API call type. Yes In this case, you will see the
following in the XML response:
<action>prepare</action>
2 button-markup string HTML code to render a “Buy Yes Only for use in certain MySpace
Now” button. implementations. Contact Boku
Merchant Technical Solutions
(merchantsupport@boku.com)
for more information.
3 buy-url stringUnique payment panel URL for Yes
a transaction.
4 result-code number Numeric code to indicate the Yes Non-zero results are errors. See
result of the API call. the following table for details.
5 result-msg string Human-readable message Yes See the following table for
corresponding to the 'result- details.
code'.
6 sig string MD5 hash signature for the Yes Returned in the XML header.
XML response returned by Validate using process detailed in
Boku. the Boku Security
7 trx-id string Unique ID for each transaction Yes
generated by Boku.
‘PREPARE’ API CALL XML RESPONSE - VALID RESULT VALUES

result-code result-msg Notes
13 Invalid Payment Panel Style Specified
29 Unsupported Price Point
31 Invalid Or Missing Price
33 Invalid Or Missing Currency Code
34 Invalid Or Missing Service-Id
35 Internal Error
36 Invalid or Missing Country Code
37 Invalid Dynamic Pricing Mode
38 Invalid Dynamic-match
39 Invalid or missing Dynamic-deviation
40 Invalid or missing Dynamic-deviation-
policy
60 Invalid 'row-ref' value
41 No payment solution available This result-code will be returned if there is no valid mobile
price point found for the specified dynamic parameters.
42 Country not available on requested This result will be returned when the country specified in
service the API call is not enabled and/or approved for the service,
or is approved but has no price points selected in the
Page 33 of 64
Service Price Matrix (the Service Price Matrix is only

applicable to row-reference ‘prepare’ calls)
91 Missing or invalid user parameter(s)
99 Boku undergoing maintenance When this result is returned, there will be no ‘trx-id’
returned, the ‘buy-url’ returned will be
“http://maintenance.boku.com/,” and the XML response
will not be signed.
Transaction Validation (‘verify-trx-id’) API call

The proper way to secure communications between your servers and the Boku system is by using
MD5 signatures as specified in the Boku Security Implementation Guide. However, if you are
unable to do so, you may confirm that a ‘billingresult’ callback notification is genuine by calling ‘verify-
trx-id’ after receiving the ‘billingresult’ callback, and verifying that the transaction status details match.
IMPORTANT! The ‘verify-trx-id’ API call will return an error if the transaction (a) was
initiated more than 72 hours before the ‘verify-trx-id’ call is made, or (b) failed as expired.
Base ‘verify-trx-id’ API URL: https://api2.boku.com/billing/request
Example ‘verify-trx-id’ API call:

https://api2.boku.com/billing/request? action =verify-trx-id& merchant-id =
bokutest& password =test321& trx-id =3faee566469704d816bf0ca0
‘VERIFY-TRX-ID’ API CALL - PARAMETERS

1 action enum Specifies the API call type. Yes For this call type, use action=verify-trx-id.
2 merchant-id string Your Merchant Portal primary Yes Your Merchant Portal account ID was
account ID. selected during initial account setup.
MD5 hashing authentication.
4 sig string MD5 hash computation Conditional Required when using MD5 hashing
signature generated by the authentication.
merchant.
5 timestamp string Network Time Protocol (NTP) Conditional Required when using MD5 hashing
Unix epoch timestamp. authentication. The API call must be made
within 300 seconds of this time.
generated by Boku.
Page 34 of 64
‘VERIFY-TRX-ID' API CALL - XML RESPONSE EXAMPLE
<?xml version="1.0" encoding="ISO-8859-1" ?>

<billing-request>
<action>verify-trx-id</action>
<trx-id>bb158d0900ec7c94d5dxxxxx</trx-id>
<amount>100</amount>
<paid>100</paid>
</billing-request>
‘VERIFY-TRX-ID’ API CALL - XML RESPONSE ELEMENTS & ATTRIBUTES

1 action enum Specifies the API call type. Yes For this call type, the XML response
will include: <action>verify-trx-
id</action>
2 amount* number The price displayed to the Yes
consumer on the Boku Payment
Panel.
3 paid* number The value paid by the consumer Yes
in local currency.
4 result-code number Numeric code to indicate the Yes Non-zero results are errors. See
result of the API call. following table for details.
5 result-msg string Human-readable message Yes See following table for details.
corresponding to the ‘result-
code.’
6 sig string MD5 hash signature for the XML Yes
Returned in the XML header.
response returned by Boku. Validate using process detailed in
the Boku Security Implementation
Guide.
7 test-mode Boolean Will be returned with a value of Conditional This element is only returned for test
“TRUE” if the transaction is a test transactions.
transaction.
generated by Boku.
‘VERIFY-TRX-ID’ XML RESPONSE - VALID RESULT VALUES

-1 Unknown Error Code This result indicates that the ‘verify-trx-id’ API call failed (it
does not indicate the transaction status).
1 Throttle limit exceeded: please re-try
2 Internal Server error: please re-try
3 Failed – Insufficient funds
Page 35 of 64

4 Failed - Consumer barred
5 Failed - Consumer not known
7 Anti-Spam - Transaction rejected In certain cases, anti-fraud limits may result in a transaction
failing as part-paid. If at all possible, you should fulfill a pro-
rata amount of credit based on the 'paid' value (provided in
the ‘event’ and ‘billingresult’ callback notifications).
8 Failed - Cancelled by consumer
9 Part Paid - Expired without completing If at all possible, you should fulfill a pro-rata amount of credit
based on the 'paid' value (provided in the ‘event’ and
‘billingresult’ callback notifications).
10 Part Paid - Cancelled by user If at all possible, you should fulfill a pro-rata amount of credit
based on the 'paid' value (provided in the ‘event’ and
‘billingresult’ callback notifications).
11 Regulatory Spend Limit Reached
12 Merchant Spend Limit Reached
14 Service suspended Applicable only to subscription services.
20 Missing or Invalid 'cmd=' value This result indicates that the ‘verify-trx-id’ API call failed (it
23 Still in progress
28 Invalid signature This result indicates that the ‘verify-trx-id’ API call failed (it
32 Bad Bind Credentials This result indicates that the ‘verify-trx-id’ API call failed (it
43 Invalid Or Missing Trx-Id This result indicates that the ‘verify-trx-id’ API call failed (it
does not indicate the transaction status). The API call failed
due to:
• The ‘trx-id’ parameter was missing; or
• A non-existent/invalid ‘trx-id’ was requested; or
• The transaction was started more than 24 hours ago.
82 Subscription Already in Progress Applicable only to subscription services. Consumers are
limited to one concurrent subscription per service.
98 Transaction not yet started
Page 36 of 64
Forward-to URLs
5 Forward-to URLs
When a transaction is finished the payment panel will display a message to the user indicating either
success or failure and a “continue” button. When the user clicks “continue,” he or she will be
redirected to a URL specified by the merchant (a “forward-to URL”).
In the Boku Merchant Portal service configuration, there is the ability to statically configure two
possible forward-to URLs on a per-product/service basis.
• Failure forward-to URL: a user is redirected to this page when the transaction fails (the
result-code is not zero)
• Default forward-to URL: a user is redirected to this page after a transaction closes if there is
no "failed forward-to URL" configured. If there is a "failure forward-to URL" value configured,
then a closed transaction will only redirect to this page when the transaction is successful
(result-code is zero).
A general forward-to URL can be optionally reported via the ‘fwdurl’ parameter of a ‘prepare’ call and
will be used for both successful and failed transactions, overriding both of the forward-to URLs
configured within the Boku service settings. If a general forward-to URL value is not passed in via the
‘prepare’ call parameter, the user will be redirected to the appropriate forward-to URL configured
within the Boku service configuration based on the aforementioned rules.
IMPORTANT!
1 - Because users can repeatedly refresh their browser, do not use forward-to URLs to
fulfill purchases. Instead, please use callback notifications to award (or retract) items
purchased.
2 - If a user is redirected to the forward-to URL, but no Boku parameters are appended,
the page should by default redirect the user to a message indicating that their
purchase could not be completed and request for the user to try again.
If the payment panel is being displayed within an iFrame, be sure not to set the forward-to URL page
as your main webpage as that will cause a "replication effect" where the user will see the main web
page within an iFrame rather than only on the main browser page.
Page 37 of 64
Forward-to URLs
Base merchant forward-to URL: https://your-domain.com/success_forward.php
Example merchant forward-to URL:

https://your-domain.com/success.php? trx-id =bb158d0900ec7c94d5dxxxxx
& param =abc123& test =1
The table below lists the parameters which are appended to the forward-to URLs:
FORWARD-TO URL PARAMETERS

1 param string Pass-through parameter for Conditional Returned if the parameter was
merchant’s use. included in the ‘prepare’ API call.
Values longer than 100 characters will
be truncated.
2 test Boolean Included with a value of "1" if Conditional Only included for test transactions.
the transaction is a test
transaction.
3 trx-id string Unique ID for each Boku Yes
transaction.
Page 38 of 64
Callback Notifications
6 Callback Notifications
The Boku system sends HTTP GET requests to designated merchant URLs (“callback URLs”) to
communicate transaction status information. Callback notifications are asynchronous with user
redirection to a forward-to URL. Each product/service has one callback URL, configured in the
Merchant Portal.
There are three types of callback notifications:
• Final result (‘billingresult’) callback notifications communicate the final status of each
transaction, either successful or failed. (A transaction can, however, later be refunded).
• Intermediate status (‘event’) callback notifications provide transaction status updates; use
them to award partial credit to users who have made a partial payment.
• Refund (‘chargeback’) callback notifications alert the merchant to consumer refunds. Use
these callbacks to retract credit for the refunded purchases.
IMPORTANT! Callback notifications are disabled by default for new accounts and must
be enabled on the Merchant Portal 'Settings > Callback Notifications' page.
Every callback notification will include the unique transaction ID (‘trx-id’); use this value to match the
incoming callbacks with transaction records in your system.
Final Result (billingresult) Callback Notifications

A ‘billingresult’ callback notification provides a transaction’s final status. On the ‘Settings > Callback
Notifications’ page in the Merchant Portal, you can activate/deactivate ‘billingresult’ callbacks and
select which optional parameters are to be included in ‘billingresult’ callbacks.
Use ‘billingresult’ callback notifications to fulfill purchases. Be sure to check that a given transaction,
identified by the unique ‘trx-id’ field value, is only fulfilled once (you may receive a ‘billingresult’
callback for the same transaction more than once if there are communication issues between the
Boku system and your servers; this can be caused by improper ACKing, among other reasons).
Page 39 of 64
Example merchant callback URL: https://your-domain.com/boku_callback.php
Example ‘billingresult’ callback notification:

http://your-domain.com/boku_callback.php? action =billingresult& trx-
id =b8b2db3f0117e53b6bdef56e& test
=1& result-code =0& result-msg =Operation+Successful& merchant-
ref =test+ret+12345& content-id =test+id&
encoded-
mobile =988765432100& paid =300& amount =300& currency =GBP& locale =en_GB& rec
eivable-gross =184
& receivable-net =147& reference-currrency =USD& reference-
amount =535& reference-paid =535& reference-receivable-
gross =328& reference-receivable-net =262
‘BILLINGRESULT’ CALLBACK NOTIFICATION PARAMETERS

Max
# Parameter Type Description Returned
Lengt Comments
h
1 action enum Specifies the callback notification Yes 20 This callback will include
type. action=billingresult.
2 amount* number The price displayed to the consumer Conditional int32
on the Boku Payment Panel.
3 consumer- string Consumer identifier in merchant Conditional 50 Returned based on the
id system which is used in the value reported in the
payment transaction risk checks. 'prepare' API call.
4 content-id string Merchant-defined field, set on a Conditional 50
per-product/service basis.
5 country string Country code in ISO 3166-1-alpha-2 Conditional 50
standard
6 currency string Currency code in ISO 4217 standard Conditional 3
local, non reference-currency
values.
7 encoded- number Boku-assigned unique identifier for Conditional 20
mobile a mobile number.
8 locale string This 5-character string consists of a Conditional 5
2-character language code, an
underscore, and the 2-character
country code.
9 merchant- string Merchant-defined field, set on a Conditional 50
ref per-product/service basis.
Page 40 of 64
Max
Lengt Comments
h
10 operator- string Specifies the operator tax treatment Conditional 20 • ‘VAT_OPTION_1’
tax- on this transaction. Indicates tax has not
treatment been paid by the
operator.
• ‘VAT_OPTION_2’
Indicates tax has been
paid by the operator.
Indication from MNO
or Aggregator that
VAT has been
collected and paid.
However, we are still
awaiting written
confirmation of this.
Please ask for further
information if
necessary.
There is no VAT type
tax system in this
country. VAT
treatment is not
applicable.
11 paid* number The value the consumer has paid for Conditional int32
the specified transaction.
12 paid-ex- number The value the consumer has paid for Conditional int32
salestax* the specified transaction, excluding
any sales tax.
13 paid-inc- number The value the consumer has paid for Conditional int32
salestax* the specified transaction, including
any sales tax.
14 param string Pass-through parameter for Conditional 100 Returned if the
merchant’s use. parameter was included
in the ‘prepare’ API call.
Values longer than 100
characters will be
truncated.
15 receivable number Indicative payout before the Boku Conditional int32 Actual payouts may vary
-gross* fee. due to exchange-rate
movements,
discrepancies,
chargebacks, and
withholding taxes.
Page 41 of 64
Max
Lengt Comments
h
16 receivable number Indicative payout after the Boku fee. Conditional int32 Actual payouts may vary
-net* due to exchange-rate
movements,
discrepancies,
chargebacks, and
withholding taxes.
17 reference- number The ‘amount’ value in the reference Conditional int32
amount* currency.
18 reference- string Currency in ISO 4217 standard Conditional 3 If this parameter was not
currency (www.xe.com/iso4217.php). included, “USD” will be
Specifies the currency unit of the used.
19 reference- number The ‘paid’ value in the reference Conditional int32
paid* currency.
20 reference- number The ‘paid-ex-salestax’ value in the Conditional int32
paid-ex- reference currency.
salestax*
21 reference- number The ‘paid-inc-salestax’ value in the Conditional int32
paid-inc- reference currency.
salestax*
22 reference- number Conditional int32 Deprecated; do not use.
receivable
-fixed
23 reference- number The ‘receivable-gross’ value in the Conditional int32
receivable reference currency.
-gross*
24 reference- number The ‘receivable-net’ value in the Conditional int32
-net*
25 result- number Numeric response code to indicate Yes
int32 Non-zero results are
code the result of the API call. errors. See the following
table for details.
26 result-msg string Human-readable response message Conditional 255 See the following table
corresponding to the ‘result-code.’ for details.
27 service-id string The unique alphanumeric ID of a Conditional 50
28 sig string MD5 hash computation signature Yes 255 Validate using process
generated by Boku. detailed in the Boku
Security Implementation
Guide.
29 test Boolean Included with a value of "1" if the Conditional int32 Only included for test
transaction is a test transaction. transactions.
30 time- string Time of transaction completion in Conditional UTC
completed UTC format: YYYY-MM-DD date
HH:MM:SS.
31 time- string Time of transaction request in UTC Conditional UTC
requested format: YYYY-MM-DD HH:MM:SS. date
Page 42 of 64
Max
# Parameter Type Description Returned Lengt Comments
h
32 timestamp string Network Time Protocol (NTP) Unix Yes int64
epoch timestamp.
33 trx-id string Unique ID for each Boku Yes 50
transaction.
VALID RESULT VALUES IN THE 'BILLINGRESULT' CALLBACK NOTIFICATION

result result-msg Explanation of Result Portal Report Error Messages
-code
0 Operation Returned for a fully paid, successful transaction. • Operation Successful
Successful
2 Internal BOKU Internal BOKU server error which needs to be • Authorization failed
error reported to Boku for further investigation. • Duplicate Purchase
• error at billing provider - please
retry
• Internal Error
• Invalid Purchase
• Invalid Request
• MSISDN network incorrectly
identified
• Purchase expired
3 Failed - Indicates that the consumer does not have enough • billing failed - insufficient funds
Insufficient credit to make the transaction.
funds
4 Failed - This error message indicates that the consumer's • Carrier blacklisted
Consumer mobile number has been blocked either by the • MSISDN is blacklisted
barred carrier, at the request of the mobile plan owner or
due to an anti-fraud mechanism.
Page 43 of 64

-code
5 Failed - external This error message occurs when Boku is unable to • billing failed - undeliverable mt
billing failure bill the user's mobile handset due to an error result message
received from the mobile operator. Below are • Fund reservation already open
some common reasons why this error would occur: • Partner authorization failed
• User enters an invalid phone number in the
Boku payment panel.
• User selects the wrong network (we do not
have the capability to detect the user's
mobile network in all countries) for their
mobile number.
• The service is not allowed for that mobile
number. Some mobile carriers automatically
block the Premium SMS service and expect
the user to contact them to activate the
feature.
• The user's mobile number is blacklisted from
within their mobile carrier's network.
• The user's mobile phone is low on credits.
Some mobile carriers will reject billed
messages to phones which don't have
enough credit to fulfill the smallest segment
of the bill.
6 Failed - This error occurs when Boku does not receive a • expired waiting for billing cycle
Transaction response from the consumer within the 24 hour to be completed
timed out timeout period and therefore the transaction times • The PIN code has expired
out due to lack of consumer feedback. This error • Timed out while waiting for
can also result when there is a problem continuing opt-in
the payment, but Boku has detected no user • Timed out while waiting for pin
response. Below are some common scenarios
which could cause this error:
• The user never sends back the proper
response (a specified keyword to a specified
shortcode).
• The user is unable to send back a response
which could be due to a network problem or
a block placed on their phone.
• The user is part of the mobile payment flow
which expects them to enter a pin code, but
they changed their mind and didn't enter the
pin code.
• The user was supposed to enter their pin
code, but their browser has crashed and they
are unaware that they can resume their
transaction to enter in the pin code.
• The user's mobile network is experiencing a
problem causing messages and/or billing to
be delayed.
Page 44 of 64

-code
7 Anti-Spam - In certain cases, anti-fraud limits may result in a • ANTI-SPAM - too many
Transaction transaction failing as part-paid. You should fulfill a incorrect PIN Entry Attempts
Rejected pro-rata amount of credit based on the amount • ANTI-SPAM - too many MSISDN
paid. Boku sends the amount paid via intermediate for this Consumer-id
status (‘event’) callback notifications. • ANTI-SPAM - too many
requests for this end-user ip
• ANTI-SPAM - too many
requests for this MSISDN
8 Failed - The consumer sent back the keyword to cancel the • billing cancelled by support
Cancelled by transaction. • billing cancelled by user
consumer • User canceled transaction
during web redirect
9 Part Paid - You should fulfill a pro-rata amount of credit based • Part Paid - Expired without
Expired without on the amount paid. Boku sends the amount paid completing
completing via intermediate status (‘event’) callback
notifications.
10 Part Paid - The consumer paid for a portion of the transaction, • Part Paid - Cancelled by end
Cancelled by but canceled the transaction before they could fully user
user pay. You should fulfill a pro-rata amount of credit
based on the amount paid. Boku sends the amount
paid via intermediate status (‘event’) callback
notifications.
11 Regulatory Regulatory (per mobile operator rules) spend limit • Carrier spend limit reached
Spend Limit has been reached by the consumer. • Regulatory Spend Limit
Reached Reached
12 Merchant Merchant-chosen spend limit has been reached by • Merchant Spend Limit Reached
Spend Limit the consumer.
Reached
14 Service Applicable only to subscription services. • Service suspended
suspended
15 Network This error will be returned when a network is down • Carrier network currently
currently for maintenance. disabled
unavailable
46 Invalid PIN This error result is caused by too many incorrect • maximum PIN Entry Attempts
PIN code entry attempts made by the end user.
67 Product issue This error occurs when product descriptions need • Product Description Pending
(e.g. pending to be provisioned by the network carrier and the Approval
approval, etc) product has not yet been approved.
68 Rejected This error occurs when product descriptions which • Rejected Product Description
Product were submitted for approval to the network carrier
Description are rejected.
82 Subscription Applicable only to subscription services. • Subscription Already in
Already in Consumers are limited to one concurrent Progress
Progress subscription for the same service.
90 Pre-paid Pre-paid mobiles are not supported by certain • Pre-paid account not
account not networks. supported
supported
Page 45 of 64

-code
95 Pricepoint not The user selected a price point that is not available • Pricepoint not supported on
supported on for their mobile network. this network
this network
96 Account not Mobile account plan cannot use that type of • Account is inactive
authorized for premium service on the mobile operator's network • Account is invalid
purchase as specified by the mobile operator. • Account is locked
• Account not authorized for
purchases
• Agreement Validation Failed
• Authorization failed
• Content Blocked
• Message Blocked
97 Invalid Zip Code Applicable for certain carrier workflows which • Invalid Zip Code
require that the correct zip code of the mobile
subscriber is entered for validation.
101 Fulfillment A problem with callback ACK caused a fulfillment • Fulfillment failed
failed failure and as a result, this transaction was not
billed. This is applicable to mobile network which
require that fulfillment occur before billing the
user.
500 Consumer info Applicable to various scenarios such as: • Gambling Merchant
validation error Certain carrier workflows require that • Geo location mismatch
additional information is entered to validate the • Inactive Account
mobile subscriber such as the zip code. • Invalid Account
Risk prevention measures are enforced on • Invalid MSISDN
accounts based on regulations. • OFAC Sanctioned Country
• User Not Found
700 Handset error Error due to handset issues which are causing • Incompatible Handset
problems either sending or receiving the necessary • Phone Related Failure
SMS messages to proceed with the transaction.
800 Subscriber not Certain user types as logged by the mobile network • Subscriber not eligible
eligible (e.g. minor) cannot make purchases using our
system.
850 Internal Needs further investigation by Boku. • Internal subscription error
subscription
error
900 Internal Needs further investigation by mobile network. • Connection Limit Failure
operator Error • Operator unknown error
• Routing Failed
• Web redirect failure - final
NOTE: All callback notifications sent to a merchant's callback URL must be

acknowledged (ACKed) with an XML response in a specified format. See the
“Required Callback Notification Acknowledgements (ACKs)” section below.
Page 46 of 64
Intermediate Status (event) Callback Notifications

Some Boku transactions are composed of multiple billed segments. For example, in the UK, a user
making a £30 purchase will be billed £10 three times. However, in some cases, not all segments will
complete successfully. The user will have paid some amount less than the full transaction amount.
Boku refers to these transactions as “part-paid.” For example, the user may be charged £20
successfully (i.e. successfully billed £10 twice), but the third £10 charge will fail (perhaps the user ran
out of phone credit, or their mobile phone lost network coverage).
Because the user did pay £20 (and due to current mobile network operator limitations Boku is unable
to automatically refund the charge), we ask that merchants partially fulfill the purchase. If the user
was purchasing 300 Poker Chips for £30, and only successfully paid £20, the merchant should credit
the user with 200 Poker Chips.
The ‘billingresult’ callback notification will include details of how much the user successfully paid once
the transaction is complete (this can take up to 24 hours). However, customers will not be happy to
have made a payment (albeit partial) without receiving any credit until 24 hours later. We therefore
recommend that merchants enable ‘event’ callback notifications and use them to award incremental
credit as soon as the user has completed an incremental payment.
To do so, compare the value of the ‘paid’ parameter to any previously received 'event' callback
notification ‘paid’ value. If the value has increased, award the appropriate amount of incremental
credit.
In some cases a successful ‘billingresult’ callback notification will be received before all of the ‘event’
callback notifications are received for that transaction. If this happens, award all remaining credit for
that transaction when the successful ‘billingresult’ callback notification is received, and take no
additional action when the remaining ‘event’ callback notifications are received.
More details about the specific messaging events are detailed in the ‘Event’ Callback Notification -
Valid ‘Event-Code’ Values table below. You may configure the parameters included in ‘event’
callback notifications on the ‘Settings > Callback Notifications’ page in the Merchant Portal.
Page 47 of 64
Example ‘event’ callback notification:

http://your-domain.com/boku_callback.php? action =event& trx-id =b8b2db3fe
0117e53b6bdef56e& test =1& event-code =1& msg =PSMS+MT+Submitted& amount =300&
paid =0& message-cost =300& currency =GBP& time =2008-10-01+14:57:38& expected
-count-of-premium-messages =1& premium-message-count =1& receivable-gross =0
& receivable-net =0& reference-currency =USD& reference-amount =535& reference
-paid =535& reference-receivable-gross =0& reference-receivable-net =0
‘EVENT’ CALLBACK NOTIFICATION PARAMETERS

# Parameter Type Description Returned Max Comments
Length
1 action enum Specifies the callback notification Yes 20 This callback will include
type. action=event.
2 amount* number The price displayed to the consumer Yes int32
on the Boku Payment Panel.
3 currency string Currency code in ISO 4217 standard Conditional 3
local, non reference-currency values.
4 event- number Numeric code indicating a Yes int32 See the following table for
code transaction event. details.
5 expected- number Number of premium messages Conditional int32 Can be used for computing
count-of- required to bill the total amount. partial fulfillment.
premium-
messages
6 message- number The amount charged to the user for Conditional int32 Can be used for computing
cost the specific premium message. partial fulfillment.
7 msg string Human-readable response message Conditional 255 See the following table for
corresponding to the ‘event-code.’ details.
8 paid* number The value the consumer has paid for Conditional int32 This value increases
the specified transaction. incrementally as the
transaction progresses and
the 'paid' value by the user
increases.
9 paid-ex- number The value the consumer has paid for Conditional int32
salestax* the specified transaction, excluding
any sales tax.
10 paid-inc- number The value the consumer has paid for Conditional int32
salestax* the specified transaction, including
any sales tax.
11 param string Pass-through parameter for Conditional 100 Returned if the parameter
merchant’s use. was included in the
‘prepare’ API call. Values
longer than 100 characters
will be truncated.
Page 48 of 64

Length
12 premium- number Count of premium messages Conditional int32 Deprecated; do not use.
message- successfully billed.
count
13 receivable number Indicative payout before the Boku Conditional int32 Actual payouts may vary
-gross* fee. due to exchange-rate
chargebacks, and
withholding taxes.
14 receivable number Indicative payout after the Boku fee. Conditional int32 Actual payouts may vary
-net* due to exchange-rate
chargebacks, and
withholding taxes.
15 reference- number The ‘amount’ value in the reference Conditional int32 Reported in 'price' API call
amount* currency. XML output, but can be
enabled or disabled to be
sent in the callback
notifications.
16 reference- string Currency in ISO 4217 standard Conditional 3 Optional callback parameter
currency (www.xe.com/iso4217.php). which can be enabled or
Specifies the currency unit of the disabled via the Merchant
‘reference-’ attributes. Portal.
Defaults to USD if not
included.
17 reference- number The ‘paid’ value in the reference Conditional int32
paid* currency.
18 reference- number The ‘paid-ex-salestax’ value in the Conditional int32
paid-ex- reference currency.
salestax*
19 reference- number The ‘paid-inc-salestax’ value in the Conditional int32
paid-inc- reference currency.
salestax*
20 reference- number Conditional int32 Deprecated; do not use.
receivable
-fixed
21 reference- number The ‘receivable-gross’ value in the Conditional int32
-gross*
22 reference- number The ‘receivable-net’ value in the Conditional int32
-net*
23 sig string MD5 hash computation signature Yes 255 Validate using process
generated by Boku. detailed in the Boku
Security Implementation
Guide.
24 test Boolean Included with a value of "1" if the Conditional int32 Only included for test
transaction is a test transaction. transactions.
Page 49 of 64

Length
25 time string Time of event in UTC format: YYYY- Yes date
MM-DD HH:MM:SS.
26 timestamp string Network Time Protocol (NTP) Unix Yes int64
epoch timestamp.
27 trx-id string Unique ID for each Boku transaction. Yes 50
‘EVENT’ CALLBACK NOTIFICATION - VALID ‘EVENT-CODE’ VALUES
There are four types of ‘event’ callback notifications. You may select which types are sent to the
callback URL on the ‘Settings > Callback Notifications’ page. To track billed events, activate event-
codes 2 and 3 (“PSMS MT Confirmed” and “PSMS MO Received”). Event-codes 1 and 4 can be left
deactivated, as they do not indicate billing events.
event-code msg Billed Event Description

1 PSMS MT Submitted No A billing attempt has been initiated (the consumer is not
charged in this step).
2 PSMS MT Delivery Yes The consumer has been successfully charged (not necessarily
Confirmed to end user the full transaction amount).
3 PSMS MO Received Yes The consumer has been successfully charged (not necessarily
the full transaction amount).
4 NON PSMS MO No The consumer has confirmed that he or she wishes to proceed
Received with transaction (the consumer is not charged in this step).
Below are some properties of 'event' callback notifications for which you should be aware:
• 'Event' callback notifications are sent from several different servers so it is possible that they
will arrive out of order. You should therefore only process the billed 'event' callback
notification with the highest 'paid' amount for a specific trx-id and disregard those for the same
transaction which have a lower 'paid' amount.
• For some markets and carriers, event code 2 may not be sent, but in those cases, a final
'billingresult' callback will be sent to confirm that the transaction has completed.
• Once a merchant receives a 'billingresult' callback for a transaction, they should stop
processing any 'event' callbacks for that specific transaction.

acknowledged (ACKed) with an XML response in a specified format. See the “Required
Callback Notification Acknowledgements (ACKs)” section below.
Page 50 of 64
Refund (chargeback) Callback Notifications

Mobile network operators can notify Boku when a full or partial refund has been issued to a consumer.
Additionally, Boku Customer Support may issue full or partial refunds to consumers when requested
by mobile network operators, merchants or directly by end-users. Boku will then notify the merchant of
the refund amount and associated chargeback amount via a ‘chargeback’ callback notification. Like
other callback notifications, ‘chargeback’ callback notifications must be activated on the Merchant
Portal “Settings” >> “Callback Notifications” page.
We strongly recommend that you retract the purchased items from a user when he or she has
refunded a transaction. You may also wish to flag the user account for additional monitoring or take
further action. Only one 'chargeback' callback notification should be processed per Boku trx-id.
Example ‘chargeback’ callback notification:

http://your-domain.com/boku_callback.php? action =chargeback& merchant-
id =bokutest& trx-id =b8b2db3f011
7e53b6bdef56e& service-id =18e050091eac44e3bcd15b63& reason-id =9& reason =Did
not receive content& time-completed =2010-01-01
00:00:00& paid =300& amount =300& currency =usd& country =us& chargeback-
date =2010-01
-01
00:00:00& chargebackamount =300& param =MREF9876xyz& refundsource =Carrier& time
stamp =1262304044& sig
=7baf22d060b6e471b650b2d02e35348d
PARAMETERS FOR ‘CHARGEBACK’ CALLBACK NOTIFICATION

# Parameter Type Description Returned Comments
1 action string Specifies the callback notification Yes This callback will include
type. action=chargeback
2 amount* number The value refunded to the consumer. Yes
3 chargebackam number The value clawed back from the Yes Proportional to the value
ount* merchant. refunded to the consumer
4 chargebackdat string Time of chargeback request in UTC Yes
e format: YYYY-MM-DD HH:MM:SS.
standard
(www.iso.org/iso/english_country_n
ames_and_code_elements).
Specifies the transaction currency.
Page 51 of 64
# Parameter Type Description Returned Comments

7 merchant-id string Your Merchant Portal primary Yes Your Merchant Portal account
account ID. ID was selected during initial
account setup.
8 paid* number The value the consumer has paid for Yes
the specified transaction.
9 param string Pass-through parameter for Yes Returned if the parameter was
merchant’s use. included in the ‘prepare’ API
call. Values longer than 100
characters will be truncated.
10 reason number Text description describing the Yes Reason-IDs and reasons will
reason for the refund. vary from mobile carrier to
mobile carrier. Please review
the ‘Chargeback’ Callback
Notifications - Reason-IDs table
on the next page for more
information.
11 reason-id string Numeric code to specify a reason for Yes Reason-IDs and reasons will
this action. vary from mobile carrier to
mobile carrier. Please review
the ‘Chargeback’ Callback
Notifications - Reason-IDs table
on the next page for more
information.
12 refundsource enum Source of the refund request. Yes Carrier, Boku, or Merchant
14 sig string MD5 hash computation signature Yes Validate using process detailed
generated by Boku. in the Boku Security
15 test Boolean Included with a value of "1" if the Condition Only included for test
transaction is a test transaction. al transactions.
16 time- string Time of transaction completion in Yes
completed UTC format: YYYY-MM-DD
HH:MM:SS.
17 timestamp string Network Time Protocol (NTP) Unix Yes
epoch timestamp.
18 trx-id string Unique ID for each Boku transaction. Yes
‘CHARGEBACK’ CALLBACK NOTIFICATIONS - REASON-IDS

reason-id reason
1 Billing error
2 Carrier reconciliation
3 Child/teen used or registered for service
4 Customer did not accept terms and conditions
Page 52 of 64
reason-id reason
5 Customer did not get the message
6 Customer did not like the content or service
7 Customer did not read the terms and conditions
8 Customer did not receive the content or service
9 Customer did not request the content or service
10 Customer did not understand there was a charge
11 Customer did not understand there were recurring charges
12 Customer received invalid message
13 Language barrier
14 Opt-out error
15 Other
16 Purchase did not match description
17 Received a recycled MSISDN
18 Someone else used or registered for service
19 Spouse/partner used or registered for service
20 Suspected refund abuse
21 Unable to opt-out of subscription
22 Unauthorized charges
23 Unknown
24 Customer did not use the content or service
25 Duplicate purchase or subscription
26 Too expensive
27 Partial payments not accepted
28 Expired transaction but customer still billed
29 Data is not usable
30 Data Usage Dispute
31 Chargeback Tool Refund
32 Refund from Google Developer

acknowledged (ACKed) with an XML response in a specified format. See the “Required
Callback Notification Acknowledgements (ACKs)” section below.
Required Callback Notification Acknowledgements (ACKs)

Once Boku has sent a ‘billingresult,’ ‘event,’ or ‘chargeback’ callback notification to a merchant’s
configured callback URL, the merchant must ACK the callback via an HTTP response after validating
the incoming Boku callback notification.
To validate the callback notification, (a) verify that the callback has been properly signed by Boku (see
the Boku Security Implementation Guide), (b) verify that the timestamp is within 300 seconds of the
time you received the callback, (c) verify that you have record of the ‘trx-id’ in your system as an
initiated transaction, and (d) award or retract the purchased content as appropriate.
Page 53 of 64
Once you have successfully validated the callback notification, send a properly formatted ACK to
Boku. The ACK is in XML format. Please note that valid XML should not contain any extra
whitespaces, but the examples shown below contain line feeds for display purposes.
Unless Boku receives a properly formatted ACK, the Boku system will assume that the callback
notification has not been successfully received, and will retry the callback notification on a staggered
basis of 1 minute, 5 minutes, 5 minutes, 15 minutes, and then every hour up to 24 hours after the
initial callback was sent. After this time, the callback notification will not be retried again.
IMPORTANT! You must ACK all Boku callback notifications if you do not want the
callback to be re-sent to your callback URL. Note that ACKing a callback does not affect the
underlying transaction. It is simply an indication that you have received the message
correctly.
EXAMPLE CALLBACK NOTIFICATION ACCEPTANCE ACK
Sending an “OK” status in the ACK response indicates acceptance of the validity of the callback
notification: “OK” should be sent for all callback notifications, both successful and failed transactions.
The “event-code” element is required only when ACKing ‘event’ callback notifications.

<callback-ack>
<trx-id>xxxxxxxxx</trx-id>
<event-code>x</event-code> ONLY REQUIRED FOR 'EVENT' CALLBACK
<status code="0">OK</status>
</callback-ack>
EXAMPLE CALLBACK NOTIFICATION REJECTION ACK
Sending a rejection ACK response or no ACK response indicates rejection of the callback notification.
Again, the “event-code” element is required only when ACKing ‘event’ callback notifications.

<callback-ack>
<trx-id>xxxxxxxxx</trx-id>
<event-code>x</event-code> ONLY REQUIRED FOR 'EVENT' CALLBACK
<status code="53" invalidfield="result-code">Invalid field
value</status>
</callback-ack>
POSSIBLE CALLBACK ACK XML RESPONSE STATUS CODES
Page 54 of 64
status code status Usage Notes

-1 Unknown error code This status message is a generic message to accommodate all other
error conditions.
0 OK Return this status message when the callback passes your validation
steps.
0 Trx Already ACKed Report this status code and value when the callback passes your
validation steps, but you have already processed the indicated "trx-id"
for this callback notification type in your system.
5 Failed - unknown trx Use when the reported "trx-id" is unknown.
28 Invalid signature Use when the signature validation step fails.
43 Invalid Request An invalid transaction ID is one of the scenarios which would prompt
this status message.
51 Expired timestamp Use when the timestamp is not within 300 seconds of the time of
when you received the callback.
52 Incorrect field Use when one of the fields is reported in an unknown format. Please
format indicate the field name in the "invalidfield" attribute.
53 Invalid field value Use when one of the fields is reporting an invalid field value such as a
date which is in the future for a date field. Please indicate the field
name in the "invalidfield" attribute.
SENDING BACK DIFFERENTIATED ACK RESPONSES
If you want to send back differentiated callback ACKs which help you easily distinguish between the
ACK response for a successful versus a failed transaction, then you can send back additional detail in
the 'status' element string, but please note that if you have successfully validated the format and
authenticity of the Boku callback notification, then you must send back a status code value of "0" to
acknowledge that you have successful received the Boku callback notification.
Below are two generic examples showing you the proper ACK responses which should be sent back
to Boku in successful transaction and failed transaction scenarios:
Proper ACK response for a successful transaction:
<?xml version='1.0' encoding='ISO-8859-1'?><callback-ack><trx-

id>xxxxxxxxxxxxxxxxxxxxxxxxx</trx-id><status code='0'>OK-
Successful Trx</status></callback-ack>
Proper ACK response for a failed transaction:
<?xml version='1.0' encoding='ISO-8859-1'?><callback-ack><trx-

id>xxxxxxxxxxxxxxxxxxxxxxxxx</trx-id><status code='0'>OK- Failed
Trx</status></callback-ack>
Page 55 of 64
Test Number Usage
APPENDIX A. Test Number Usage

Boku provides test numbers that allow merchants to test their Boku implementation without actual
billed transactions (i.e. testers do not need to have an actual handset/SIM for the market tested, and
do not need to be geographically located in the market tested).
The first step in using the test numbers is to activate the feature in the Merchant Portal. Use the
‘Enable Test Numbers’ checkbox found at the top of the service configuration page for each
product/service to be used for testing. The product/service status will show “TEST” in addition to
“PENDING (TEST)” or “LIVE (TEST)” status when test numbers are enabled. Note that before test
numbers can be used a given market (country), the product/service must be approved (“LIVE TEST”
status) and the market must be approved (“Approved and Live” status).
Page 56 of 64
Test Number Usage
Once the test numbers feature is activated, you can enter a test number into the Boku Payment Panel
to simulate a payment event. A test number has two parts: a country code and a result-code. The
two-letter country code is specified by ISO 3166-1-alpha-2: For example, use “CA” to simulate testing
from Canada and “DE” to simulate testing from Germany. The result-code is used to control the
outcome of the simulated transaction. For example result-code “00” simulates a successful
transaction, and the result-code “11” simulates a transaction that failed because the consumer’s
spend limit was reached. Therefore to test a successful transaction in Canada, use the test number
“CA00.” To test a spend-limit-reached failure in Germany, use “DE11.”
COUNTRY CODE EXAMPLES

Country Code Country
CA Canada
DE Germany
FR France
GB United Kingdom
US United States
RESULT CODE LIST

result-code result-msg
02 Internal Server error: please re-try
04 Failed - Consumer barred
05 Failed - external billing failure
07 Anti-Spam - Transaction rejected
08 Failed - Cancelled by Consumer
11 Failed - Spend Limit Reached
SUCCESSFUL TRANSACTION TEST FLOW EXAMPLE
These test steps are written for testing from Canada, but can be used for any country by selecting the
desired country in step 2 and replacing “CA” with the appropriate country code in step 3.
1. Open a Payment Panel.

2. If a country selection drop-down menu appears, select Canada. If not, click the small flag
displayed in the top right of the Payment Panel, select Canada from the drop-down menu, and
click the green button (“Continue” or the translated equivalent).
3. Enter the test number “CA00” (Operation Successful) into the Mobile Number field and click
the green button (Continue).
4. If a red error message (“Sorry, we couldn't identify your mobile network” or the translated
equivalent) appears, select an available network (any networks not grayed out) and click the
green button (Continue) again.
Page 57 of 64
Test Number Usage
5. Verify that the Payment Panel displays “Success! Your payment is complete. Please click
continue to retrieve your goods. Thank you for using BOKU.”
6. Verify that the Payment Panel closes when the Continue button is pressed.
7. Verify that the browser loads the appropriate forward-to URL.
8. Verify that the appropriate amount of credit has been awarded to the user account.
NOTES ON USING TEST NUMBERS
Below are some useful notes to keep in mind when using test numbers:
• Because test numbers (e.g. “US00”) are not real phone numbers, the mobile network operator
lookup will fail and you'll see a message asking you to select a mobile network from a
dropdown list. When this occurs, just select any available network and continue your
transaction.
• Please note that the country base (”US,” “CA,” and so on) must be entered in upper case.
• When a test number is used the ‘test’ parameter with a value of “1” will be appended to all
Boku callback notifications and to the forward-to URL. This will enable the merchant to
distinguish between test and live transactions.
WARNING! We strongly recommend that you do not fulfill callback notifications

reporting the "test=1" parameter pair in your production region since all users with the
ability to access the payment panel for a service with test mode enabled will be able to
transact using these test numbers.
• When test numbers are enabled, non-test (real) MSISDNs will still initiate actual billing events:
if you use a real mobile handset for a transaction, that handset will be charged.
• Test numbers will not work on a product/service when the ‘Enable Test Numbers’ option is
disabled for that service.
• Test number transactions are shown in a separate report in the Boku Merchant Portal and will
only be returned for up to three days from the time that the test transaction was initiated.
• Transactions using test numbers do not appear in the XML response results returned from the
'reporting' API call.
Page 58 of 64
Partial Fulfillment
APPENDIX B. Partial Fulfillment

Partial payments can occur when a mobile price point requires more than one SMS message to
complete the transaction. For example, consider a scenario where a pre-paid Australian mobile user
has a balance of AUD $10.00 and is trying to purchase an item which costs AUD $15.00. Please note
that the AUD $15.00 price point consists of 3 billed messages, each costing AUD $5.00 (multi-billed
price point breakdowns can be different and are determined by the base mobile tariffs allowed by the
carriers). Given the current scenario, this mobile user would only be able to successfully pay for AUD
$10.00 out of the total $15.00 transaction cost. Typically transactions are given 24 hours to complete
(there are some carrier exceptions) after which, if full payment is not successful, the transaction would
expire. Thus, if this user does not top up their mobile phone with at least another AUD $5.00 within
24 hours, then their transaction will expire and indicate a partial payment result.
As implied in the prior paragraph, only certain price points could possibly result in a partial payment.
This is because most price points consist of only one billed message. To determine which price
points could result in a partial payment, you would reference the ‘number-billed-messages’ attribute
which is returned in the XML response from the Boku pricing (‘price-info’, ‘price’, or ‘service-prices’)
API calls. Any price points with 'number-billed-messages' > 1 could possibly incur a partial payment.
Partial transactions are very infrequent, but you can leverage your Boku integration code to perform
automatic incremental fulfillment either on a real-time or delayed basis.
AUTOMATED, REAL-TIME INCREMENTAL FULFILLMENT
This fulfillment method would require you to process Boku 'event' callback notifications. Details about
the 'event' callback notification type can be found in the "Intermediate Status (event) Callback
Notifications" subchapter of this document. Of the provided event codes, your code would fulfill upon
receiving event codes "2" and "3" as those are the only codes which confirm that a consumer has
been billed.
It is also explained that you will have to enable the specific 'event' callbacks you wish to receive by
adjusting some settings within your Boku Merchant Portal account. These options are found in the
'Settings > Callback Notifications' (https://merchants.boku.com/portal/merchant_manage_events.jsp)
settings in your PP account.
AUTOMATED DELAYED PARTIAL FULFILLMENT
Page 59 of 64
Partial Fulfillment
Alternatively, you can partially fulfill when you receive the Boku 'billingresult' callback notification since
it provides final result of the transaction. To do this, you would add logic to your fulfillment code which
would determine whether the "paid" value is greater than zero when you receive a 'billingresult' for a
failed transaction. A failed transaction only indicates that a transaction was not FULLY paid, therefore
partially paid transactions fall into the failed transaction category. If you receive a ‘billingresult’
callback notification where 0 < paid < amount, that transaction was “partially paid” and should fulfill
the portion of the transaction based on the faction of amount that was paid (i.e. divide paid/amount
and fulfill that percentage of the purchase).
However, it should be noted that using this notification type may delay the fulfillment of the transaction
since a transaction could take up to 24 hours to expire. Regardless, the 'billingresult' callback
notification does allow you to at least provide the user with the portion of the content for which they
have paid.
Please note that if your callback server receives a 'billingresult' callback notification for a transaction,
then your server should note be processing any subsequent 'event' callback notifications for that
same transaction since the 'billingresult' indicates the final status and therefore overrides any 'event'
callback notifications.
MANUAL PARTIAL FULFILLMENT
Merchants who are not able to automatically perform partial fulfillment using the Boku callback details
will need ensure that their Customer Support teams are equipped to handle partial fulfillment
scenarios. If Boku receives is notified of a partial payment situation where partial fulfillment did not
occur, your customer support team will be notified to provide compensation to the user which could be
by awarding the partial virtual credit amount, providing a product of equivalent value such as game
credits which may be exchanged for virtual item(s), or any other fair method of compensation to
accommodate the user for their partial payment.
Page 60 of 64
Network Codes and Names
APPENDIX C. Network Codes and Names

The following table lists the mappings between network codes, countries, and networks names. Use
these codes when requesting network-specific price information.
Country Code Network Code Network Name Country Code Network Code Network Name
AE 24F410 Etisalat CH 22F820 Sunrise
AE 24F430 DU CH 22F830 Orange
AR 27F201 Movistar CL 37F001 Entel
AR 27F202 Nextel CL 37F002 Movistar
AR 27F213F0 Claro CL 37F003 Claro
AR 27F243F0 Personal CN 64F000 China Mobile
AT 32F210 Mobilkom CN 64F010 China Unicom
AT 32F230 T-Mobile CN 64F020 China Telecom
AT 32F270 tele.ring CO 37F203 Tigo
AT 32F250 One CO 37F223 Movistar
AT 32F201 H3G CO 37F201 Comcel
AT 32F221 YESSS CY 82F010 Cytamobile-Vodafone
AU 50506 3 CY 82F001 Areeba
AU 5050299 Virgin CZ 32F020 O2 (Eurotel)
AU 05F510 Telstra CZ 32F010 T-Mobile
AU 05F520 Optus CZ 32F030 Vodafone (Oskar)
AU 05F530 Vodafone DE 62F210 T-Mobile
BE 02F610 Proximus DE 62F220 Vodafone
BE 02F601 Mobistar DE 62F230 e-plus
BE 02F602 BASE DE 62F270 O2
BE 02F650 Telenet DE 62F90F1 Debitel
BG 82F410 Mobiltel DE 62F231 Mobilcom
BG 82F450 Globul DE 62F241 Talkline
BG 82F430 Vivatel DK 32F810 TDC
BH 24F610 Batelco DK 32F820 Telenor
BH 24F620 Zain DK 32F802 Telia DK
BR 27F420 TIM DK 32F830 Orange
BR 27F450 Claro DK 32F877 Tele2 DK
BR 27F460 Vivo DK 32F860 3
BR 27F461 Oi DO 73F010 Orange
CA 03F256F1 Bell DO 73F020 Claro
CA 03F221F0 Virgin Mobile DO 73F030 Tricom
CA 03F256F5 MTS DO 73F040 Viva
CA 03F227F0 Rogers EC 47F001 Claro
CA 03F273F0 Fido EC 47F000 Movistar
CA 03F256F4 SaskTel EC 47F002 Alegro
CA 03F256F3 Telus EE 42F810 EMT
CA 03F205F0 Videotron Wireless EE 42F820 Elisa
CH 22F810 Swisscom EE 42F830 Tele2
Page 61 of 64
EG 06F210 Mobinil ID 15F010 Indosat
EG 06F220 Vodafone ID 15F011 XL Axiata
EG 06F230 Etisalat ID 15F012 IM3
ES 12F470 Movistar ID 15F013 TelkomFlexi
ES 12F430 Orange ID 15F014 Mobile8
ES 12F440 Yoigo ID 15F015 3
ES 12F480 Euskaltel [VOD] IE 72F220 O2
ES 12F410 Vodafone IE 72F210 Vodafone
FI 42F419 Sonera IE 72F230 Meteor
FI 42F450 Elisa IE 72F250 3
FI 42F412 Saunalahti IL 24F510 Orange
FI 42F490 DNA IL 24F520 Cellcom
FR 02F802 Bouygues IL 24F530 Pelephone
FR 02F810 Orange IL 24F577 Mirs / Amigo
FR 02F801 SFR IN 04F420 Airtel
FR 02F899 Alice IN 04F490 Reliance
FR 02F898 Free IN 04F450 Vodafone
GB 32F451 Vodafone IN 04F408 BSNL
GB 32F433 Orange IN 04F552 Tata/Virgin
GB 32F403 T-Mobile IN 04F412 Loop Mobile
GB 32F413 Virgin (T-Mobile IN 04F486 MTNL - Delhi
MVNO) IN 04F496 MTNL - Mumbai
GB 32F401 O2 IN 04F440 Idea
GB 32F402 Three IN 04F518F3 Uninor
GR 02F250 Vodafone IT 22F210 TIM
GR 02F210 Cosmote IT 22F201 Vodafone
GR 02F201 WIND IT 22F288 WIND
GR 02F290 Qtel [WIND] IT 22F299 3
GT 07F410 Claro JO 14F687 Umniah
GT 07F320 Comcel / Tigo JO 14F677 Orange (Mobilcom)
GT 07F430 Movistar JO 14F610 Zain
HK 54F400 1O1O, one2free (CSL) JP 44F002 SoftBank Mobile
HK 54F440 Hutch JP 44F003 NTT docomo
HK 54F401 NWM JP 44F005 KDDI
HK 54F461 PCCW KR 54F020 KT
HK 54F421 Peoples KR 54F050 SKT
HK 54F460 Smartone (Vod) KR 54F060 LG U+
HN 07F820 Celltel / Tigo LB 14F510 Alfa
HN 07F810 Claro LB 14F563 MTC
HR 12F910 T-Mobile LT 42F610 Omnitel
HR 12F920 Tele2 LT 42F620 Bite
HR 12F901 VIPnet LT 42F630 Tele2
HU 12F610 Telenor (Pannon) LV 42F710 LMT
HU 12F603 T-Mobile (Westel) LV 42F720 Tele2
HU 12F607 Vodafone LV 42F750 Bite
ID 15F001 Telkomsel MA 06F400 Meditel
Page 62 of 64
MA 06F410 Macrotel RO 226001 Vodafone
MA 06F425 Wana RO 226003 Cosmote
MX 33F420 Telcel RO 226010 Orange
MX 33F430 Movistar RU 52F010 MTS
MX 33F440 Iusacell RU 52F099 Beeline
MX 33F410 Nextel RU 52F019 Megafon
MY 05F291 Celcom RU 52F020 Megafon
MY 05F261 DiGi RU 52F028 Megafon
Telecommunications RU 52F022 Megafon
MY 05F221 Maxis Mobile RU 52F023 Megafon
MY 05F231 Telekom Cellular RU 52F024 Megafon
NI 17F003 Movistar RU 52F025 Megafon
NI 17F012 Claro RU 52F026 Megafon
NL 02F480 KPN RU 52F027 Megafon
NL 02F421 Telfort RU 52F002 Tele2
NL 02F420 Tele2 RU 52F053 Motiv
NL 02F402 Orange (Dutchtone) RU 52F061 NTC
NL 02F416 T-Mobile (BEN) RU 52F070 Smarts
NL 02F440 Vodafone RU 52F072 Smarts
NO 42F220 Netcom RU 52F073 Astrakhan GSM
NO 42F240 Tele2 RU 52F074 Smarts
NO 42F250 Network Norway RU 52F075 Smarts
NO 42F210 Telenor RU 52F076 Smarts
NZ 35F010 Vodafone RU 52F077 Smarts
NZ 35F020 Telecom RU 52F030 Ulyanovsk GSM
NZ 35F042 2 Degrees RU 52F021 BaikalWestCom
OM 24F212 Nawras RU 52F100 Yaroslav GSM
OM 24F220 Oman Mobile SA 24F010 STC
PA 17F401 Movistar SA 24F030 Mobily
PA 17F402 Cable&Wireless SA 24F040 Zain
PE 17F610 Claro SE 42F010 Telia
PE 17F607 Movistar SE 42F070 Tele2
PH 15F501 Globe GCASH SE 42F080 Telenor
PH 15F520 Globe Telecom SE 42F090 Djuice
PH 15F503 Smart SE 42F020 3
Communications SG 25F530 M1
PH 15F505 Sun Cellular SG 25F510 SingTel
PL 62F020 T-Mobile SG 25F550 Starhub
PL 62F030 Orange SI 92F314 Mobitel
PL 62F060 Play SI 92F304 SiMobil
PL 62F010 Plus GSM SI 92F307 Tusmobil
PS 24F350 Jawwal SK 32F110 Orange
PT 62F860 TMN SK 32F120 T-Mobile
PT 62F830 Optimus SK 32F160 O2
PT 62F810 Vodafone SY 14F710 Syriatel
QA 24F710 Qtel SY 14F720 MTN
Page 63 of 64
TH 25F010 AIS US 13F021 US Cellular
TH 25F081 Dtac US 13F050 Sprint
TH 25F099 TrueMove US 13F001 Virgin
TH 25F088 TrueMove H US 13F040 T-Mobile
TR 82F610 Turkcell US 13F090 Alltel
TR 82F620 Vodafone US 13F024F0 Cincinnati Bell
TR 82F630 Avea VE 37F420 Digitel
TW 64F660 FET VE 37F440 Movistar
TW 64F688 KGT VE 37F460 Movilnet
TW 64F699 TAT VN 54F200 MobiFone
TW 64F639 TCC VN 54F240 Viettel Mobile
TW 64F611 CHT VN 54F289 Vietnamobile
TW 64F629 APBW VN 54F299 EMobile
TW 64F698 Vibo VN 54F202 VinaPhone
UA 52F510 MTS VN 54F230 S-Fone
UA 52F530 Kyivstar VN 54F270 Beeline
UA 52F560 life :) ZA 56F570 Cell C (Pty)
US 13F020 AT&T ZA 56F501 MTN
US 13F030 Verizon Wireless ZA 56F510 Vodacom
US 13F070 Nextel
US 13F080 Boost (Prepay)
US 13F011 Boost Unlimited
Page 64 of 64

Boku Technical Reference

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Boku Technical Reference

Загружено:

Авторское право:

Доступные форматы

www.boku.

1 Introduction & Overview

This document contains four major sections:

Purchase Flow Scheme Diagram

Refund Scheme Diagram

Presentation of Examples and Tables

Base API URL: https://www.example.com/request

Example API call:

Parameter Type Description Required Comments

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Field Type Description Returned Comments

Currency Values in API Calls and Callback Notifications

STANDARD FRACTIONAL CURRENCY UNIT EXAMPLES

COUNTRIES WITH NON-STANDARD FRACTIONAL CURRENCY UNITS

Proper Price Display

3 Price Information API Calls

Discussion: Using “Continuous Prices”

UNDERSTANDING PRICE RANGE ATTRIBUTES

1. min-price: The minimum price in the range.

continuing in 1 cent increments (e.g. to 2 cents, 3 cents, 4 cents, etc.) up to a

‘price-list’ API Call

Use the “show-all-networks” parameter to include network-specific prices in the response.

1. min-price=2, max-price=2, increment=0

continuous range. For example, the continuous range min-price=1, max-price=100,

If the optional “show-all-networks” parameter is included in a ‘price-list’ API call, network-specific

Base ‘price-list’ API URL: https://api2.boku.com/pricing/1.0/price-list

Example ‘price-list’ API call:

‘PRICE-LIST’ API CALL - REQUEST PARAMETERS

‘PRICE-LIST’ API CALL XML RESPONSE EXAMPLE - CONTINUOUS-PRICE FORMAT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

‘PRICE-LIST’ API CALL XML RESPONSE - CONTINUOUS-PRICE FORMAT

The following elements and attributes are returned in “continuous-price” format.

Field Type Description Returned Comments

‘PRICE-LIST’ API CALL XML RESPONSE EXAMPLE - DISCRETE-PRICE FORMAT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

XML RESPONSE ELEMENTS AND ATTRIBUTES – DISCRETE-PRICE FORMAT

The following elements and attributes are returned in “discrete-price” format.

Field Type Description Returned Comments

‘PRICE-LIST’ XML RESPONSE - VALID RESULT VALUES

“result-code” value “result-message” value Description

‘price-info’ API Call

Base ‘price-info’ API URL: https://api2.boku.com/pricing/1.0/price-info

Example ‘price-info’ API call:

‘PRICE-INFO’ API CALL - REQUEST PARAMETERS

Parameter Type Description Required Comments

‘PRICE-INFO’ API CALL XML RESPONSE EXAMPLE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

XML RESPONSE ELEMENTS AND ATTRIBUTES

Field Type Description Returned Comments

orientation, decimal symbol, and

‘PRICE-INFO’ XML RESPONSE - VALID RESULT VALUES

Static Matrix Price Request (‘service-prices’) API Call

Base ‘service-prices’ API URL: https://api2.boku.com/billing/request

Example ‘service-prices’ API call:

‘SERVICE-PRICE’ API CALL - PARAMETERS

‘SERVICE-PRICES’ API CALL XML RESPONSE - EXAMPLE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

‘SERVICE-PRICES’ API CALL XML RESPONSE - GENERAL ELEMENTS

Field Type Description Returned Comments

Field Type Description Returned Comments

‘SERVICE-PRICES’ API CALL XML RESPONSE - PRICE-POINT ATTRIBUTES

Field Type Description Returned Comments

Field Type Description Returned Comments

‘SERVICE-PRICES’ XML RESPONSE - VALID RESULT VALUES