com.jambool.socialgold.api
Class CurrencyClient

java.lang.Object
  com.jambool.socialgold.api.CurrencyClient

public class CurrencyClient
extends Object

CurrencyClient

Sample code to provide convient access to the Social Gold Currency V1.

API methods that make a call to the service:

• getBalance
• getTransactionStatus
• getTransaction
• creditUser
• debitUser
• refundUser
• buyGoods

methods that generate a URL for merchant to render in a page:

• getBuyCurrencyURL
• getBuyGoodsURL

Notes:

• input validation is weak, if at all
• XML and other parsers are not included at this time
• formal exceptions should be thrown

Changes: note that JSON parsing should be supported in this version using org.json libraries (required), and some proper exceptions are now being thrown. (BRP/2010-6)

Field Summary

private String	offerID WRITEME
private String	secretMerchantKey WRITEME
private String	serverName WRITEME
private Hashtable<String,String>	validCreditTypes WRITEME

Constructor Summary

CurrencyClient(String newServerName, String newOfferID, String newSecretMerchantKey)
---------------------------------------------------------------- -------------

Method Summary

private String	_calculateSignature(Hashtable<String,String> signatureParams) ---------------------------------------------------------------- -------------
private Hashtable<String,String>	_getResponse(String cmdURL) ---------------------------------------------------------------- -------------
private Hashtable<String,String>	_getResponse(String cmdURL, boolean requiresSSL) WRITEME
private String	_getURL(Hashtable<String,String> baseParams, Hashtable<String,String> requiredParams, Hashtable<String,String> optionalParams) ================================================================ ============= private methods below this ========================== ===================================================
private String	_getURL(Hashtable<String,String> baseParams, Hashtable<String,String> requiredParams, Hashtable<String,String> optionalParams, boolean requiresSSL)
private void	_mergeParams(Hashtable<String,String> requiredParams, Hashtable<String,String> signatureParams) ---------------------------------------------------------------- -------------
private String	_paramHashToURI(Hashtable<String,String> params) Convert a parameter hash into an URI
private String	_validateCreditType(String type) _validateCreditType ---------------------------------------------------------------- -------------
void	addValidCreditType(String ident, String description) Add a valid credit type
Map<String,String>	buyGoods(String userID, String name, int pcAmount, int quantity) WRITEME
Hashtable<String,String>	buyGoods(String userID, String name, int pcAmount, int quantity, String format, String externalRefID, String option_name_0, String option_value_0, String option_name_1, String option_value_1, String appParams, String sku, String sku_category) WRITEME
Hashtable<String,String>	creditUser(String userID, int pcAmount, String type, String externalRefID, String description) creditUser: format valid formats = ["json", "xml"] ---------------------- -------------------------------- -----------------------
Hashtable<String,String>	creditUser(String userID, int pcAmount, String type, String externalRefID, String description, String format) creditUser:
Map<String,String>	debitUser(String userID, int pcAmount, String externalRefID, String description) debitUser: valid formats = ["json", "xml"] ---------------------------------------------------------------- -------------
Hashtable<String,String>	debitUser(String userID, int pcAmount, String externalRefId, String description, String format) WRITEME
Hashtable<String,String>	getBalance(String userID) getBalance: errorOnUnkownUser = a boolean to determine if service will return a 0 balance, or an error if service has not seen user_id before valid formats = ["json", "xml", "plaintext"] ------ ------------------------------------------------------------ -----------
Hashtable<String,String>	getBalance(String userID, boolean errorOnUnkownUser) WRITEME
Hashtable<String,String>	getBalance(String userID, boolean errorOnUnkownUser, String format) WRITEME
String	getBuyCurrencyURL(String userID) getBuyCurrencyURL: returns a URL that can be placed into a page as either : - format = html, an a href=" - format = iframe, an iframe src=" valid formats = ["iframe", "html"] Optional: showBalance = boolean to show user their balance during the UI flow appParams = a short String that will be passed back to merchant on postback, can be used identify application, etc ------ ------------------------------------------------------------ -----------
String	getBuyCurrencyURL(String userID, String appParams)
String	getBuyCurrencyURL(String userID, String appParams, boolean showBalance, String format)
String	getBuyGoodsURL(String userID, String name, int pcAmount, int quantity) getBuyGoodsURL and buyGoods getBuyGoodsURL returns a URL that can be placed into a page as either : - format = html, an a href=" - format = iframe, an iframe src=" buyGoods is to be used to record a purchase after the fact - formats = json, xml name = short String descibing item for sale pcAmount = a positive int with 2 digits of implied decimal eg: 100 = $1.00 quanity = a positive int Optional: option_name_0 = a short String, such as "Size" option_value_0 = a short String, such as "Large" option_name_1 = a short String, such as "Color" option_value_1 = a short String, such as "Red" sku = a short String, perhaps merchants internal ID for item, eg: "magic sword" sku_catagory = a short String, perhaps merchants internal ID for item catagory eg: "weapons" externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund appParams = a short String that will be passed back to merchant on postback, can be used identify application, etc -------------------------------------------------------------- ---------------
String	getBuyGoodsURL(String userID, String name, int pcAmount, int quantity, String format, String externalRefID, String option_name_0, String option_value_0, String option_name_1, String option_value_1, String appParams, String sku, String sku_category)
Hashtable<String,String>	getTransaction(String userID, long startTimestamp) getTransaction: errorOnUnkownUser = a boolean to determine if service will return a 0 balance, valid formats = [ "html", "csv", "json", "xml" ] -------------------------------------------------- ---------------------------
Hashtable<String,String>	getTransaction(String userID, long startTimestamp, long endTimestamp, int limit, String orderByCol0, String orderByDir0, String orderByCol1, String orderByDir1, String format)
Hashtable<String,String>	getTransactionStatus(String userID, String externalRefID, String format) getTransactionStatus: returns a response like so: {"polling_expiration_seconds" :300,"polling_interval_seconds":3,"transaction_status":-1} externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund valid formats = ["json", "xml" ] ------------------ -----------------------------------------------------------
Hashtable<String,String>	getValidCreditTypes()
static void	main(String[] args) ================================================================ =============
Hashtable<String,String>	refundUser(String userID, String socialgoldTransactionID, String externalRefId) refundUser: socialgoldTransactionID = id returned from transaction you want to refund externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund valid formats = ["json", "xml"] Optional: description = a short, but meaningful description of the refund so the user will know what it was about ---------------- -------------------------------------------------------------
Hashtable<String,String>	refundUser(String userID, String socialgoldTransactionID, String externalRefId, String description, String format)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

offerID

private String offerID

WRITEME

secretMerchantKey

private String secretMerchantKey

WRITEME

serverName

private String serverName

WRITEME

validCreditTypes

private Hashtable<String,String> validCreditTypes

WRITEME

Constructor Detail

CurrencyClient

public CurrencyClient(String newServerName,
                      String newOfferID,
                      String newSecretMerchantKey)

---------------------------------------------------------------- -------------

Parameters:

newServerName - WRITEME

newOfferID - WRITEME

newSecretMerchantKey - WRITEME

Method Detail

main

public static void main(String[] args)
                 throws org.apache.http.client.ClientProtocolException,
                        IOException

================================================================ =============

Parameters:

args - WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

_calculateSignature

private String _calculateSignature(Hashtable<String,String> signatureParams)

---------------------------------------------------------------- -------------

Parameters:

signatureParams - WRITEME

Returns:

WRITEME

_getResponse

private Hashtable<String,String> _getResponse(String cmdURL)
                                       throws org.apache.http.client.ClientProtocolException,
                                              IOException

---------------------------------------------------------------- -------------

Parameters:

cmdURL - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

_getResponse

private Hashtable<String,String> _getResponse(String cmdURL,
                                              boolean requiresSSL)
                                       throws org.apache.http.client.ClientProtocolException,
                                              IOException

WRITEME

Parameters:

cmdURL - WRITEME

requiresSSL - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

_getURL

private String _getURL(Hashtable<String,String> baseParams,
                       Hashtable<String,String> requiredParams,
                       Hashtable<String,String> optionalParams)

================================================================ ============= private methods below this ========================== ===================================================

Parameters:

baseParams - WRITEME

requiredParams - WRITEME

optionalParams - WRITEME

Returns:

WRITEME

_getURL

private String _getURL(Hashtable<String,String> baseParams,
                       Hashtable<String,String> requiredParams,
                       Hashtable<String,String> optionalParams,
                       boolean requiresSSL)

Parameters:

baseParams - WRITEME

requiredParams - WRITEME

optionalParams - WRITEME

requiresSSL - WRITEME

Returns:

WRITEME

_mergeParams

private void _mergeParams(Hashtable<String,String> requiredParams,
                          Hashtable<String,String> signatureParams)

---------------------------------------------------------------- -------------

Parameters:

requiredParams - WRITEME

signatureParams - WRITEME

_paramHashToURI

private String _paramHashToURI(Hashtable<String,String> params)

Convert a parameter hash into an URI

Parameters:

params - parameters

Returns:

URI

_validateCreditType

private String _validateCreditType(String type)

_validateCreditType ---------------------------------------------------------------- -------------

Parameters:

type - WRITEME

Returns:

WRITEME

addValidCreditType

public void addValidCreditType(String ident,
                               String description)

Add a valid credit type

Parameters:

ident - the identifier (looks_like_this)

description - the human-readable description

buyGoods

public Map<String,String> buyGoods(String userID,
                                   String name,
                                   int pcAmount,
                                   int quantity)
                            throws org.apache.http.client.ClientProtocolException,
                                   IOException

WRITEME

Parameters:

userID - WRITEME

name - WRITEME

pcAmount - WRITEME

quantity - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

buyGoods

public Hashtable<String,String> buyGoods(String userID,
                                         String name,
                                         int pcAmount,
                                         int quantity,
                                         String format,
                                         String externalRefID,
                                         String option_name_0,
                                         String option_value_0,
                                         String option_name_1,
                                         String option_value_1,
                                         String appParams,
                                         String sku,
                                         String sku_category)
                                  throws org.apache.http.client.ClientProtocolException,
                                         IOException

WRITEME

Parameters:

userID - WRITEME WRITEME.

name - WRITEME

pcAmount - WRITEME

quantity - WRITEME

format - WRITEME

externalRefID - WRITEME

option_name_0 - WRITEME

option_value_0 - WRITEME

option_name_1 - WRITEME

option_value_1 - WRITEME

appParams - WRITEME

sku - WRITEME

sku_category - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

creditUser

public Hashtable<String,String> creditUser(String userID,
                                           int pcAmount,
                                           String type,
                                           String externalRefID,
                                           String description)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

creditUser: format valid formats = ["json", "xml"] ---------------------- -------------------------------- -----------------------

Parameters:

pcAmount - = a positive int with 2 digits of implied decimal eg: 100 = $1.00

type - = String, one of "new_user_credit" or "item_sold_credit" merchant can get a list of valid type strings from getValidCreditTypes();

externalRefID - = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund

description - = a short, but meaningful description of the credit so the user will know what it was about

userID - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

creditUser

public Hashtable<String,String> creditUser(String userID,
                                           int pcAmount,
                                           String type,
                                           String externalRefID,
                                           String description,
                                           String format)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

creditUser:

Parameters:

pcAmount - = a positive int with 2 digits of implied decimal eg: 100 = $1.00

type - = String, one of "new_user_credit" or "item_sold_credit" merchant can get a list of valid type strings from getValidCreditTypes();

externalRefID - = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund

description - = a short, but meaningful description of the credit so the user will know what it was about

format - valid formats = ["json", "xml"] ---------------------- -------------------------------- -----------------------

userID - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

debitUser

public Map<String,String> debitUser(String userID,
                                    int pcAmount,
                                    String externalRefID,
                                    String description)
                             throws org.apache.http.client.ClientProtocolException,
                                    IOException

debitUser: valid formats = ["json", "xml"] ---------------------------------------------------------------- -------------

Parameters:

userID - WRITEME

pcAmount - = a positive int with 2 digits of implied decimal eg: 100 = $1.00

externalRefID - = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund

description - = a short, but meaningful description of the debit so the user will know what it was about

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

debitUser

public Hashtable<String,String> debitUser(String userID,
                                          int pcAmount,
                                          String externalRefId,
                                          String description,
                                          String format)
                                   throws org.apache.http.client.ClientProtocolException,
                                          IOException

WRITEME

Parameters:

userID - WRITEME

pcAmount - WRITEME

externalRefId - WRITEME

description - WRITEME

format - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getBalance

public Hashtable<String,String> getBalance(String userID)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

getBalance: errorOnUnkownUser = a boolean to determine if service will return a 0 balance, or an error if service has not seen user_id before valid formats = ["json", "xml", "plaintext"] ------ ------------------------------------------------------------ -----------

Parameters:

userID - the user whose balance is being queried

Returns:

WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getBalance

public Hashtable<String,String> getBalance(String userID,
                                           boolean errorOnUnkownUser)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

WRITEME

Parameters:

userID - WRITEME

errorOnUnkownUser - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getBalance

public Hashtable<String,String> getBalance(String userID,
                                           boolean errorOnUnkownUser,
                                           String format)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

WRITEME

Parameters:

userID - WRITEME

errorOnUnkownUser - WRITEME

format - WRITEME

Returns:

WRITEME WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getBuyCurrencyURL

public String getBuyCurrencyURL(String userID)

getBuyCurrencyURL: returns a URL that can be placed into a page as either : - format = html, an a href=" - format = iframe, an iframe src=" valid formats = ["iframe", "html"] Optional: showBalance = boolean to show user their balance during the UI flow appParams = a short String that will be passed back to merchant on postback, can be used identify application, etc ------ ------------------------------------------------------------ -----------

Parameters:

userID - WRITEME

Returns:

WRITEME

getBuyCurrencyURL

public String getBuyCurrencyURL(String userID,
                                String appParams)

Parameters:

userID - WRITEME

appParams - WRITEME

Returns:

WRITEME

getBuyCurrencyURL

public String getBuyCurrencyURL(String userID,
                                String appParams,
                                boolean showBalance,
                                String format)

Parameters:

userID - WRITEME

appParams - WRITEME

showBalance - WRITEME

format - WRITEME

Returns:

WRITEME

getBuyGoodsURL

public String getBuyGoodsURL(String userID,
                             String name,
                             int pcAmount,
                             int quantity)

getBuyGoodsURL and buyGoods getBuyGoodsURL returns a URL that can be placed into a page as either : - format = html, an a href=" - format = iframe, an iframe src=" buyGoods is to be used to record a purchase after the fact - formats = json, xml name = short String descibing item for sale pcAmount = a positive int with 2 digits of implied decimal eg: 100 = $1.00 quanity = a positive int Optional: option_name_0 = a short String, such as "Size" option_value_0 = a short String, such as "Large" option_name_1 = a short String, such as "Color" option_value_1 = a short String, such as "Red" sku = a short String, perhaps merchants internal ID for item, eg: "magic sword" sku_catagory = a short String, perhaps merchants internal ID for item catagory eg: "weapons" externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund appParams = a short String that will be passed back to merchant on postback, can be used identify application, etc -------------------------------------------------------------- ---------------

Parameters:

userID - WRITEME

name - WRITEME

pcAmount - WRITEME

quantity - WRITEME

Returns:

WRITEME

getBuyGoodsURL

public String getBuyGoodsURL(String userID,
                             String name,
                             int pcAmount,
                             int quantity,
                             String format,
                             String externalRefID,
                             String option_name_0,
                             String option_value_0,
                             String option_name_1,
                             String option_value_1,
                             String appParams,
                             String sku,
                             String sku_category)

Parameters:

userID - WRITEME

name - WRITEME

pcAmount - WRITEME

quantity - WRITEME

format - WRITEME

externalRefID - WRITEME

option_name_0 - WRITEME

option_value_0 - WRITEME

option_name_1 - WRITEME

option_value_1 - WRITEME

appParams - WRITEME

sku - WRITEME

sku_category - WRITEME

Returns:

WRITEME

getTransaction

public Hashtable<String,String> getTransaction(String userID,
                                               long startTimestamp)
                                        throws org.apache.http.client.ClientProtocolException,
                                               IOException

getTransaction: errorOnUnkownUser = a boolean to determine if service will return a 0 balance, valid formats = [ "html", "csv", "json", "xml" ] -------------------------------------------------- ---------------------------

Parameters:

userID - WRITEME WRITEME

startTimestamp - WRITEME

Returns:

WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getTransaction

public Hashtable<String,String> getTransaction(String userID,
                                               long startTimestamp,
                                               long endTimestamp,
                                               int limit,
                                               String orderByCol0,
                                               String orderByDir0,
                                               String orderByCol1,
                                               String orderByDir1,
                                               String format)
                                        throws org.apache.http.client.ClientProtocolException,
                                               IOException

Parameters:

userID - WRITEME

startTimestamp - WRITEME

endTimestamp - WRITEME

limit - WRITEME

orderByCol0 - WRITEME

orderByDir0 - WRITEME

orderByCol1 - WRITEME

orderByDir1 - WRITEME

format - WRITEME

Returns:

WRITEME

Throws:

org.apache.http.client.ClientProtocolException - WRITEME

IOException - WRITEME

getTransactionStatus

public Hashtable<String,String> getTransactionStatus(String userID,
                                                     String externalRefID,
                                                     String format)
                                              throws org.apache.http.client.ClientProtocolException,
                                                     IOException

getTransactionStatus: returns a response like so: {"polling_expiration_seconds" :300,"polling_interval_seconds":3,"transaction_status":-1} externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund valid formats = ["json", "xml" ] ------------------ -----------------------------------------------------------

Parameters:

userID - WRITEME

externalRefID - WRITEME

format - WRITEME

Returns:

WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

getValidCreditTypes

public Hashtable<String,String> getValidCreditTypes()

Returns:

table of valid credit types, key=identifier, value=description

refundUser

public Hashtable<String,String> refundUser(String userID,
                                           String socialgoldTransactionID,
                                           String externalRefId)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

refundUser: socialgoldTransactionID = id returned from transaction you want to refund externalRefID = a unique string that represents the transaction in your systems use a String version of UUID.randomUUID.toString(), if you do not keep track of your own txns, but remember this is the id, you will need to pass into a call to refund valid formats = ["json", "xml"] Optional: description = a short, but meaningful description of the refund so the user will know what it was about ---------------- -------------------------------------------------------------

Parameters:

userID - WRITEME

socialgoldTransactionID - WRITEME

externalRefId - WRITEME

Returns:

WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME

refundUser

public Hashtable<String,String> refundUser(String userID,
                                           String socialgoldTransactionID,
                                           String externalRefId,
                                           String description,
                                           String format)
                                    throws org.apache.http.client.ClientProtocolException,
                                           IOException

Parameters:

userID - WRITEME

socialgoldTransactionID - WRITEME

externalRefId - WRITEME

description - WRITEME WRITEME

format - WRITEME

Returns:

WRITEME

Throws:

IOException - WRITEME

org.apache.http.client.ClientProtocolException - WRITEME