Payment-API

Using the Payment-API, you can harness all benefits Bigpoint's own games enjoy. More than 120 payment methods are available to you and the system itself is maintained by seasoned professionals.

The greatest benefit is the API itself: All you need to do, is to make sure that the three calls outlined on this wiki-page are implemented in your game and to generate a correct Payment-URL for the player to use.

Anything else, like the correct choice of currency and display of the correct items associated with certain currencies, is handled automatically by the Bigpoint payment system.

Important: Please note that the Payment-URL can only handle XML-RPC at present!

Creation of the Payment-URL

For security reasons, Bigpoint's payment system is running on its own set of servers. This ensures the safety of all information stored and processed by it, as there's no direct access to a customers information except from the payment system itself.

Thus, the payment is displayed either in an iFrame or using a popup-window and needs to be accessed using a seperate URL that needs to be recreated every 10 minutes.

To generate a valid Payment-URL, you need to follow a set of steps - first, you need to make sure that you have all required parameters available to you:

Required Parameters

Name of Parameter Type Description
projectID Integer This is the project-ID assigned to your current project. Note that this ID will change for each new instance of your game and after it has been put into live.
userID Integer A numerical representation of an user in your game. This ID is assigned during the registration-process in your game.
username String The name of the user as it will be displayed in the payment windows.
lang String The language as it was selected by the user in your game (2 signs (examples): 'de', 'en', 'fr', … 5 signs: 'pt_BR', 'en_US' (only those two!) - The Payment-API uses ISO-language codes which differ from country-codes (e.g. SE for Sweden, SV for Svenska)
time Integer The current time as an Unix timestamp (number of seconds since the 1/1/1970).
returnURL (Optional) String If this parameter is set, the payment window will not close itself using Javascript after its last step, but will redirect the user to this URL instead. (optional)
action (optional) String For this parameter set to “cancellation”, a cancellation page will displayed, which informs the user, that he has not payed a previous transaction yet and so is not able to create any new ones. This parameter should be used for users, for which you got a “blocked notification”.
sandbox Integer If the payment window is supposed to work using the projectID and secret-key as they are used during the development status of your game, please send “1” as this parameter, in any other case use “0”. (optional)
item String preselect special item (needs to have itemGroup also set within the request!), Format: [item group]_[item type]_[item amount]_[interval]_[interval type] (itemGroup: int (in most cases: 1), item type: realCurrency, item amount: the amount of items to buy, interval: is a subscription (1) or not (0), interval type: if interval = 0, this has to be set to “NONE”) (optional)
itemGroup Integer has to be added, if “item” isset. Value is the “item group”-part from the “item” parameter. In most cases it's value is 1 (optional)

As the next step, you need to put all these parameters in an array and generate the JSON-representation of this array, which in return is encoded to a string using the base64 algorithm.

To authenticate this request, a hash is generated using the secret-key and this base64-encoded string, which will be appended to the payment URL as well.

Here is an example code snippet generating a valid payment URL using PHP:

generatePaymentLinkExample.php
<?php
    $reqOriginal = array(
        'projectID' => 1001,
        'lang'      => 'en',
        'username'  => 'nickname',
        'userID'    => 123456,
        'time'      => time(),
        'returnURL' => 'http://www.bigpoint.com/?parameter=xy',         // optional
        'item'      => '1_realCurrency_5000.0000_0_NONE',               // optional
        'itemGroup' => 1,                                               // optional
        'sandbox'   => 1,                                               // optional
    );
 
    $reqJson = base64_encode( json_encode($reqOriginal) );
    $hashJson = md5($reqJson . $yourSecretKey);
    $urlJson = 'https://ssl.bigpoint.net/billing/?';
    $urlJson .= 'authreq='.urlencode($reqJson) . '&hash='.urlencode($hashJson);
    $urlJson .= '&aid='.$aid;
?> 

bookItem

If an user has successfully purchased an item, you will receive the “bookItem”-call. Besides a number of statistical information you will find the two most important parameters of this call: “type” and “amount”.

Some explanation to their use:

  • The “type”-parameter will either contain a fixed value as it was defined by the payment system (e.g. “realCurrency” or “virtualCurrency” for bookings of money or “premium” for Bigpoint's premium subscription packages). If you added custom packages in the payment setup of your game, the internal names given to each package will be sent as this parameter.
  • The “amount”-parameter must not always contain a positive value. Depending on which “type” of package you are supposed to book, its values can be interpreted in different ways.
  • You might receive negative “amount” values, if our support has decided to fix issues with a purchase and needs to take away money or packages from an user.
  • If the item that needs to be booked is either of the type “premium” or a custom package that is available as a subscription, a positive value will denote that a new subscription is added, a negative value denotes the cancellation of a subscription, a “0” thus means the continuation of an already existing subscription for the given user.

All other parameters are informational and optional, you don't need to process them.

Important: As “amount” and “type” are the most important parameters, you need to put a lot of logic into your game if you choose to create a complex system of packages and subscription. When receiving a “bookItem”-call, you might need to check the user's inventory or balance for existing subscriptions or packages and react accordingly.

Flow chart

Parameters in use

Name of Parameter Type Description
type String Identifier for the item that was purchased by the user.
amount Integer Amount of items of given type that should be booked to the user. Please be aware of the different interpretations of this parameter as outlined above. The amount may also be negative (in case of back postings (e.g. for cancellations of a transaction/item).
uniqueID String A numerical ID that is unique to each “bookItem”-call. You can save this id to avoid the repeated booking of the same purchase by the user.
Please note: The following parameters are transmitted optionally by a call from our payment system. However your API has to handle also calls without those parameters correctly!
accountType String Description of the payment method chosen by the user.
userAmount Double End user price of the selected item.
userAmountCurrency String Currency used for the end user price.
userRevenue Double Revenue as generated by the purchase - this value is calculated by subtracting transaction fees and VAT from the “userAmount”-parameter. To calculate your own revenue, you might want to bring the Devlounge's revenue share into the equation.
userRevenueCurrency String Currency used for the user revenue.
message String Description of purchased item
transactionID Integer Unique ID for this transaction. One transaction may contain more than one bought items.
internalInfo String Internal information used by Bigpoint's payment systems.
geoCountry String The user's country, detected using GeoIP oder a phone number. (ISO-Standard 3166-alpha 2)
accountID Integer Internal identifier for the selected payment method, only used by Bigpoint's payment systems.
subscriptionID Integer Only used with subscription-items, contains an ID for this subscription.
subscriptionDateExpires Integer Only used with subscription-items - contains the expiration date as an UNIX timestamp.
subscriptionInterval Integer Only used with subscription-items, contains the interval after which another bookItem-call for the same item will be initiated.
timestamp Integer Only sent with SMS bookings - contains the UNIX timestamp of the moment the SMS was sent from the user's phone.

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.

In the event of an error, please use an error construct as outlined by the XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

blockedNotify

Sometimes, users might want to cancel the purchase they just made (or made some hours prior). Bigpoint's payment can handle such a case, but to ensure that no fraud can come from this, a player's account is blocked for the duration of the cancellation process, as an item is booked to an user's account immediately after the purchase was successful.

This is where the “blockedNotify”-call comes into play. When a chargeback is initiated, your game will receive this call containing a “1” besides an userID, so you can block this user's account while the chargeback is being processed.

To unblock his account, the user can choose between to paths:

  1. Manually transferring the required amount, thus “repaying” for the item he already received, OR
  2. Contacting your own support team, which in return can contact the Bigpoint payment support to resolve this issue.

In the latter case, the support might choose to simply take some items away from the user to bring his account back into balance, thus you might receive bookItem-calls with negative amounts.

In both cases, you will receive another “blockedNotify”-call containing an empty parameter, reactivating the user's account.

Flow Chart

Parameters in use

Name of Parameter Type Description
blocked String Blocking status of the given user - if this parameter is empty, a user is supposed to be reactivated and able to play the game again. If this parameter contains “1”, the user should be blocked from playing the game, until the issue has been resolved.
transactionID Integer The unique ID of the transaction the user initiated a chargeback or cancellation for.
transactionBlocked String A status identifier for the given transactionID.

Return Codes

On success the following parameters are expected to be returned for this call:

Name of Parameter Type Description
result String Simple string containing “OK”.

In the event of an error, please use an error construct as outlined by the XML-RPC specifications. For help on how to create such a construct manually, please refer to the Error Handling wiki-page.

en/apis/payment-api.txt · Last modified: 2012/08/31 10:08 (external edit)
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0