Integration Documentation

Last updated: October 11, 2017

OVERVIEW


Integrating with Openbucks is easy!

An Openbucks payment starts by you redirecting the user to the Openbucks hosted checkout flow. In this flow Openbucks collects the payment information from the user and redeems the funds. Openbucks notifies you on the success of the transaction, and redirects the user back to your website. You can specify the return URL in your account settings, or provide them dynamically with each payment.

Openbucks has two environments: Sandbox and Production. In the Sandbox you will be able to make payments without real money involved. When you complete your Sandbox integartion, you will need to activate your production environment here. Card numbers for the Sandbox are provided here.

There are two forms in which you can validate successful transaction details: (1) Openbucks will send you a notification to a predetermined postback url before redirecting the user back to your site. (2) Openbucks provides an api to retreive the transaction details at any time. Use the tracking id provided in the 'tid' GET parameter of your success return url.

Follow these simple steps to complete your integration:

Check also our Code Samples and FAQ sections for help with your integration.

BEFORE YOU START


Openbucks works with large Retail brands like Subway, CVS/Pharmacy and Dollar General, ePlus and Pacific Coffee. Our ability to work with these brands also means we have to adhere to some brand standards and regulatory requirements.

Please follow these three simple guidelines:

BUTTON PLACEMENT


The Openbucks network is comprised of major national and international retail brands. In accordance with Retailer brand standards and requirements, ***the Openbucks payment button must be displayed on the Merchant payment wall or checkout page before any and all non-brand and non-network payment options*** (including but not limited to any 'alternative' payments options). Additionally, if there is a fold (such as a 'more options...' button), the Openbucks payment button must be displayed above the fold.


Place Openbucks before other alternative payment methods

Payment Methods

DESCRIBE PAYMENT METHOD


The exact text used to describe the payment method must be: "Pay with Gift Cards".


GRAPHICS TO USE


The graphics displayed to illustrate the payment method should be provided by your account manager or selected from the library of graphics provided here.


Use an image from here: Select your button size and style

INTEGRATION KEYS


HOW IT WORKS


Openbucks has two environments: Sandbox and Production. Sandbox is used for integration testing where no real money is used.

Each environment has three keys: Public Key, Secret Key, API Secret Key.

  • Public Key: used by Openbucks to identify you. Needs to be included in any payment or API request. The public key is the same in Sandbox and Production
  • Secret Key: used by Openbucks to authenticate you on payment requests. This is a secret and should never be visible to a user.
  • API Secret key: used by Openbucks to authenticate you on api requests. This is a secret and should never be visible to a user.

EnvironmentPublic KeySecret KeyAPI Secret Key
Sandbox[SANDBOX-PUBLIC-KEY][SANDBOX-SECRET-KEY][SANDBOX-API-KEY]
Production[PRODUCTION-PUBLIC-KEY][PRODUCTION-SECRET-KEY][PRODUCTION-API-KEY]

CONFIGURING THE BUTTON


HOW IT WORKS


To better serve the end user, Openbucks hosts the payment button image and does not provide static button images. By hosting the image we are able to display the most appropriate brands to your end user based on availablity of retailers on our platform and the users geo location. Note that if you load the Openbucks payment panel within an iFrame, the minimum size of the iFrame should be 724 x 479.

You will need to include your public key in the button url request so we can identify the button is being served to your site. Below you will find working examples. Please note that you need to receive the actual button URL from Openbucks:

Environment URL Example
Sandbox
<img src="https://demo-pay.openbucks.com/paybutton_v2.php?pubkey=[SANDBOX-PUBLIC-KEY]&amp;style=obx-170-50-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards
Production
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

STYLE AND SIZE


Openbucks provides button images in several styles and sizes to choose from (listed below).

*Note: If your site requires alternative layouts, dimensions, card displays or file formats, please contact your Openbucks account manager and we will create a custom button specific for your checkout page.


INDUSTRY SPECIFIC: ONLINE GAMING

Style Size URL Example
obx-170-50-anim 170 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards
obx-150-50-anim 150 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-150-50-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards
obx-130-50-anim 130 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-130-50-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards
obx-110-25-anim 110 x 25
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-110-25-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards
obx-90-60-anim 90 x 60
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-90-60-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

INDUSTRY SPECIFIC: E-COMMERCE/MOBILE TOP-UP (Subway and Dollar General Only)

Style Size URL Example
obx-170-50-2-anim 170 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-2-anim" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

REGION SPECIFIC: CANADA (Subway Only)

Style Size URL Example
obx-170-50-canada 170 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-canada" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

REGION SPECIFIC: HONG KONG (Pacific Coffee Only)

Style Size URL Example
obx-170-50-hong-kong 170 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-hong-kong" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

REGION SPECIFIC: PHILIPPINES (EPlus Only)

Style Size URL Example
obx-170-50-philippines 170 x 50
<img src="https://pay.openbucks.com/paybutton_v2.php?pubkey=[PRODUCTION-PUBLIC-KEY]&amp;style=obx-170-50-philippines" alt="Pay with Gift Cards" style="border: 0;"/>
Pay with Gift Cards

SETUP PAYMENT FORM


HOW IT WORKS


To initiate a payment with Openbucks you need to send a POST request to the Openbucks payment URL. The POST parameters are described later in this section.
Upon receiving your POST request, Openbucks will authenticate your identity, and guide the end user through the checkout process. Upon completion, you will be notified that the transaction has been completed and the user will be redirected back to your website.

There are two common ways to send the POST request:

  • Statically add a form with hidden fields that is preconfigured to POST to the Openbucks payment URL when the Openbucks payment button is selected.
  • Dynamically inject the form to the DOM of your page using Javascript, and use Javascript to submit it.

The Openbucks payment urls are:

Environment Payment URL
Sandboxhttps://demo-pay.openbucks.com/payment_v3.php
Productionhttps://pay.openbucks.com/payment_v3.php

THE HIDDEN FORM


Copy and paste the form below or check our hidden form code sample for a working example. Exchange the placeholders with your own values. The form is prepopulated with your public key.

<!-- The URL below is the Sandbox one. Change to Production when switching. -->

<form action="https://demo-pay.openbucks.com/payment_v3.php" method="POST" name="openbucks_form">

	<!-- Change to your own values, see below Required Hidden Form Fields for explanations. -->

	<input type="hidden" name="req_currency_code" value="USD" />
	<input type="hidden" name="req_amount" value="AMOUNT" />
	<input type="hidden" name="req_item_description" value="ITEM_DESCRIPTION" />
	<input type="hidden" name="req_merchant_tracking_id" value="TRACKING_ID" />
	<input type="hidden" name="req_customer_anonymous_id" value="CUSTOMER_ANONYMOUS_ID" />
	<input type="hidden" name="req_public_key" value="[SANDBOX-PUBLIC-KEY]" />
	<input type="hidden" name="req_token" value="TOKEN" />
	<input type="hidden" name="req_hash" value="HASH" />
	<input type="hidden" name="req_customer_info_email" value="EMAIL" />
	
	<!-- Optional values, see below Optional Hidden Form Fields for explanations. -->

	<input type="hidden" name="req_product_id" value="PRODUCT_ID" />
	<input type="hidden" name="req_success_url" value="SUCCESS_URL" />
	<input type="hidden" name="req_cancel_url" value="CANCEL_URL" />
	<input type="hidden" name="req_select_card" value="SELECT_CARD" />
	<input type="hidden" name="req_force_cards" value="FORCE_CARD1|FORCE_CARD2|..." />
	<input type="hidden" name="req_sub_property_id" value="SUB_PROPERTY_ID" />
	<input type="hidden" name="req_sub_property_name" value="SUB_PROPERTY_NAME" />
	<input type="hidden" name="req_sub_property_url" value="SUB_PROPERTY_URL" />

	<!-- Use only if your product has been rated by an official organization, such as the ESRB. -->

	<input type="hidden" name="req_rating_model" value="OPENBUCKS" />
	<input type="hidden" name="req_product_rating" value="Unrated" />
</form>

FORM ELEMENT ATTRIBUTES

Attribute Description
action Sandbox: always https://demo-pay.openbucks.com
Production: always https://pay.openbucks.com/payment_v3.php
method Always POST
name The form name you want to use (can be anything you want)

REQUIRED HIDDEN FORM FIELDS

POST Parameter Name Example Max Length Description
req_currency_code USD 3 char 3-letter code identifying the currency. Supported currencies: "CAD", "EUR", "GBP", "HKD", "PHP", "USD"
req_amount 3.99 n/a Amount (expressed using the specified currency). Minimum amount supported is $0.1 CAD, €0.1 EUR, £0.1 GBP, $0.1 HKD, ₱10 PHP, $0.1 USD
req_item_description 1500 LuckyBucks 255 Description of the product being sold, as accurate as possible. The req_item_description can contain diacritical characters. But these characters must be escaped for HTML.

Example: Crédits Máquina Straße Œdipus must be passed as: Cr&eacute;dits M&aacute;quina Stra&szlig;e &OElig;dipus

Failure to do so will result in a 400 XML parsing error. Refer to wikipedia.org for a table of the HTML entities.If you want to specify a Unicode character that does not have an HTML entity, you can alternatively use a Unicode XML entity ("&#nnnn;") which works both in XML and HTML.
req_merchant_tracking_id 110207023323 255 Your own tracking ID for this transaction. Must be unique. The Openbucks Payment server will echo it for correlation purposes. This ID is the one that you should use to correlate your own data on your systems.
The req_merchant_tracking_id parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
req_customer_anonymous_id 1f3870be274f6c49b3e31a0c6728957f 65 Any type of customer ID you can provide, that enables Openbucks to identify repeat visits by the same customer. This parameter is required for fraud prevention purposes.
This must be an anonymous ID, such as a one-way hash of the customer ID or customer's login name or customer's email address or any other value that uniquely identify the customer on your internal system.
The req_customer_anonymous_id parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
req_public_key [SANDBOX-PUBLIC-KEY] The Public Key is used by Openbucks to identify you on all payment and API requests. It can be found under the Account Information & Settings page.

Note: Change to the production Public Key when switching to Production mode.
req_token 2012-10-18 17:13:0050809b0c8b73c A non-repeated unique value to be formatted as follow:
YYYY-MM-DD HH:MM:SS[space][at least 10 random printable characters]
This value is used to authenticate you (see req_hash below) and to prevent replay attacks.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_token = date("Y-m-d H:i:s ") . uniqid('', true);

You can use whatever method you want to generate the random characters.
The req_token parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
req_hash e9165e548f0f....28e1ed763474 The SHA-256 hash of req_token + [secret_key] + req_merchant_tracking_id + req_amount + req_currency_code + req_force_cards where [secret_key] is your Openbucks Secret Key, and req_force_cards should be concatenated only if it is set. The hash must be formatted in lowercase hexadecimal with no byte separator.
The Secret Key is used by Openbucks to authenticate you on all payment requests. It can be found under the Account Information & Settings page.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_hash = hash("sha256",
$req_token .
$secret_key .
$merchant_tracking_id .
$amount .
$currency_code .
$force_cards);

Note: Change to the production Secret Key when switching to Production mode.

See example of how to calculate the hash here.
req_customer_info_email [email protected] 63 The ability to associate transactions with an email helps us enforce strict velocity rules and improves security. Optional, but recommended.

OPTIONAL HIDDEN FORM FIELDS

POST Parameter name Example Max Length Description
req_product_id LB-1500 63 The ID of the product being sold. You can use your internal ID scheme or just any ID of your choice. However, we do ask that you use a separate ID for each distinct product type. Example: a package of 500 LuckyBucks is "LB-500", while a package of 1,000 LuckyBucks is "LB-1000" and one of 3,000 is "LB-3000".
The req_product_id parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
req_success_url https://yourdomain.com/success.php 255 A URL to which Openbucks will return the user after a successful transaction is complete. If no URL is supplied here, the default URL defined in the Account Information & Settings page will be used. If neither URLs are provided, the user will not be redirected back to your site at the completion of the payment.

Note: The URL needs to include the "http://" or "https://" prefix.
req_cancel_url https://yourdomain.com/cancel.php 255 A URL to which Openbucks will return the user after a transaction is canceled. If no URL is supplied here, the default URL defined in the Account Information & Settings page will be used. If neither URLs are provided, the user will not be redirected back to your site when a transaction is canceled.

Note: The URL needs to include the "http://" or "https://" prefix.
req_select_card subway 31 Use this parameter to link the user directly to a specific gift card checkout, bypassing the gift card payment wall selection step.

The possible values for this field can be found in the API ID column of the Review Available Cards page in the Sandbox Merchant Admin Portal.
req_force_cards subway, cvs 255 Use this parameter to force only specific gift cards to be listed at checkout. Cards should be separated by '|'.

The possible values for this field can be found in the API ID column of the Review Available Cards page in the Sandbox Merchant Admin Portal.
req_rating_model ESRB Use only if your game or product has been rated by an official organization such as the ESRB.
req_product_rating E Use only if your product has been rated by an official organization.
req_sub_property_id 1015 127 If you are a publisher or an aggregator of multiple websites, you should use the sub property fields to describe the website that the payment is being initiated from. The sub property information is used to provide better reporting, invoicing, analytics, risk management and information to you, Openbucks and the end consumer.

The sub property id can be any kind of unique identifier of the website, for example the id used to store the website information in your database.

req_sub_property_name Lucky Bucks Inc. 127 The legal or commonly used name of the website the payment is being initiated from.
req_sub_property_url http://www.luckybucks.com 127 The URL of the website the payment is being initiated from.

TRANSACTION VALIDATION


HOW IT WORKS


In the event of a successful transaction, you will need to obtain and validate the transaction details.

There are two ways in which you can obtain the transaciton information:
  • Postback Listener - Openbucks can send the transaction details to a URL of your choice before redirecting the user back to your site.
  • API Call - You can pull the transaction details from Openbucks by sending an API request after the user is redirected back to your site.

Please note that you may switch between the two (or even use both) when finalizing your integration code.

The required validation steps are discussed at the end of this section.

POSTLABCK LISTENER


Each successful transaction will trigger an HTTP Post from Openbucks' payment server to a URL of your choice with all the information you need to validate the transaction.
To set the postback URL, you can refer to the Account Information & Settings page.

A few things to take into consideration:
  • Postbacks are only made for successful payments
  • The postback will be sent before the user is redirected back to your success URL. That is, when the payment page redirects the user to your Success URL, your back-end server should already have the information about the transaction
  • Your listener should return an HTTP response code of 200 to indicate that the Postback was received and processed successfully.
  • Your listener should return an HTTP response code of 200 even if you receive multiple postbacks for the same transaction.
  • In case of error (an HTTP response code other than 200), Openbucks will try to send you the results again at the following (approximate) intervals after the transaction:
    10 min, 30 min, 1 hour, 2 hours, 3 hours, 4 hours, 6 hours, 8 hours, 10 hours, 12 hours, 20 hours, 36 hours, 64 hours, and 96 hours.
  • If all these attempts at re-posting fail, an automated warning email will be sent to the administrative contacts we have for your company. If your merchant account has no administrative contact, an email is sent to our personnel so that they can notify you that there is an issue with your back-end server.

Important: returning a response code other than 200 will not cancel the transaction. Important: return a response code of 200 even for multiple postbacks for same transaction.

Refer to Required Validation Steps for validating the information returned.
See our Postback Listener Code Sample in PHP.

EXAMPLE: POSTBACK XML

<?xml version="1.0" encoding="UTF-8" ?>
<pwgc xmlns="http://openbucks.com/xsd/pwgc/2.0">
   <response>
      <requestID>0</requestID>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>OK</errorDescription>
      </error>
      <payment>
         <transaction>
            <transactionID>117830</transactionID>
            <pwgcTrackingID>18eb8626-bf63-4312-890b-43bfc05f525e</pwgcTrackingID>
            <timestampUTC>2012-10-19 00:13:20</timestampUTC>
            <pwgcHash>7f222f3cbefc71e129f1056fed2365b67f15791b3be8d2902b5f170a2e0b8be0</pwgcHash>
         </transaction>
         <amount>
            <currencyCode>USD</currencyCode>
            <amountValue>0.10</amountValue>
         </amount>
         <merchantData>
            <merchantToken>2012-10-18 17:13:0050809b0c8b73c</merchantToken>
            <merchantHash>032b5fb9a1aba6d71c92b3cf271522b569a26a43cda191bac2269262270b70b4</merchantHash>
            <publicKey>f831c668-9dbf-4a26-8920-02dfdb5408bd</publicKey>
            <merchantTrackingID>2012-10-18 17:13:0050809b0c8c327</merchantTrackingID>
            <productID>Los Angeles Credits</productID>
            <itemDescription>Credits at 1 cents each</itemDescription>
            <ratingModel>ESRB</ratingModel>
            <productRating>E</productRating>
         </merchantData>
      </payment>
   </response>
</pwgc>

POSTBACK FIELD DETAILS

XML Element Description
requestID Internal use only. You should not be concerned about this element.
errorCode Always 0 = transaction was successful. Openbucks does not Postback failed transaction attempts.
errorDescription Always "OK" = transaction was successful. Openbucks does not Postback failed transaction attempts.
transactionID The unique ID of the payment transaction. This ID is the one you, the merchant, should use to correlate Openbucks data. It is this ID that we ask for when someone contacts our customer services department. This ID is displayed in the payment page receipt.
pwgcTrackingID A non-repeated unique value. This token is DIFFERENT from the one you passed in req_token.
timestampUTC The UTC date and time of the transaction expressed using the SQL timestamp format YYYY-MM-DD HH:MM:SS.
pwgcHash The SHA-256 hash of publicKey + ":" + pwgcTrackingID + ":" + [secret_key] where [secret_key] is your Openbucks Secret Key.
You use this hash field to authenticate the Openbucks response. At reception you need to re-compute this hash and compare to the one received.

Important: The hash is formatted in lowercase hexadecimal with no byte separator.
PHP Example:
$pwgc_hash = hash("sha256", $public_key . ":" . $pwgc_tracking_id . ":" . $secret_key);
currencyCode Echo of req_currency_code
amountValue Echo of req_amount
merchantToken Echo of req_token
merchantHash Echo of req_hash
publicKey Echo of req_public_key
merchantTrackingID Echo of req_merchant_tracking_id
productID Echo of req_product_id
itemDescription Echo of req_item_description
ratingModel Echo of req_rating_model
productRating Echo of req_product_rating

TRANSACTION DETAILS


After a transaction is complete, we will redirect the user back to the Success URL you provided in the hidden form or in the Account Information & Settings page.
At this time you should make a POST request from your backend server to the API URL provided below to obtain the transaction information.

Note: Use the 'tid' GET parameter which is included on your success URL to extract the trackingID for the api request

Note: For api requests, you should use your api_secret_key instead of secret_key for calculating the hash field

Refer to Required Validation Steps for validating the information returned
See our Transaction Details API Call Code Sample in PHP.


API URLS AND KEYS

Environment URL API Secret Key
Sandbox https://demo-api.openbucks.com [SANDBOX-API-KEY]
Production https://api.openbucks.com [PRODUCTION-API-KEY]

EXAMPLE: REQUEST XML

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>2012-10-18 17:13:5050809b3e4d123</token>
         <hash>e21bce3c39b83531f4629e02307d9f0186334c646ca78c75004d65d41183e97e</hash>
      </authentication>
      <getTransactionPostback>
         <version>1.0</version>
         <params>
            <trackingID>2012-10-18 17:13:0050809b0c8c327</trackingID>
         </params>
      </getTransactionPostback>
   </request>
</pwgcApi>

API REQUEST FIELD DETAILS

XML element Description
publicKey Your public key as appears under Account Information & Settings page.
token A non-repeated unique value to be formatted as follows:
YYYY-MM-DD HH:MM:SS[space][at least 10 random printable characters]
This value is used to authenticate you (see req_hash below) and to prevent replay attacks.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_token = date("Y-m-d H:i:s ") . uniqid('', true);

You can use whatever method you want to generate the random characters.
The token parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
hash The SHA-256 hash of [token] + [api_secret_key] where [api_secret_key] is your Openbucks API Secret Key. The hash must be formatted in lowercase hexadecimal with no byte separator.

The API secret key is used by Openbucks to authenticate you on all API requests. It can be found under the Account Information & Settings page.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_hash = hash("sha256",$token . $api_secret_key);

Note: Change to the production API Secret Key when switching to Production mode.
version Optional. Exclude from the XML to get the latest version.
trackingID Your merchant tracking ID as provided in req_merchant_tracking_id of the hidden form

EXAMPLE: RESPONSE XML

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <response>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>Success</errorDescription>
      </error>
      <authentication>
         <publicKey>f831c668-9dbf-4a26-8920-02dfdb5408bd</publicKey>
         <token>0eaea33c-05b4-466e-a78f-7188bcc300fb</token>
         <hash>ecae3249e8bcbeb476bf0f22c259191c5b00e4e0eb166cb572e115a5212025ad</hash>
      </authentication>
      <getTransactionPostback>
         <version>1.0</version>
         <params>
            <trackingID>2012-10-18 17:13:0050809b0c8c327</trackingID>
         </params>
         <payload>
            <requestID>0</requestID>
            <error>
               <errorCode>0</errorCode>
               <errorDescription>OK</errorDescription>
            </error>
            <payment>
               <transaction>
                  <transactionID>117830</transactionID>
                  <pwgcTrackingID>18eb8626-bf63-4312-890b-43bfc05f525e</pwgcTrackingID>
                  <timestampUTC>2012-10-19 00:13:20</timestampUTC>
                  <pwgcHash>7f222f3cbefc71e129f1056fed2365b67f15791b3be8d2902b5f170a2e0b8be0</pwgcHash>
               </transaction>
               <amount>
                  <currencyCode>USD</currencyCode>
                  <amountValue>0.10</amountValue>
               </amount>
               <merchantData>
                  <merchantToken>2012-10-18 17:13:0050809b0c8b73c</merchantToken>
                  <merchantHash>032b5fb9a1aba6d71c92b3cf271522b569a26a43cda191bac2269262270b70b4</merchantHash>
                  <publicKey>f831c668-9dbf-4a26-8920-02dfdb5408bd</publicKey>
                  <merchantTrackingID>2012-10-18 17:13:0050809b0c8c327</merchantTrackingID>
                  <productID>Los Angeles Credits</productID>
                  <itemDescription>Credits at 1 cents each</itemDescription>
                  <ratingModel>ESRB</ratingModel>
                  <productRating>E</productRating>
               </merchantData>
            </payment>
         </payload>
      </getTransactionPostback>
   </response>
</pwgcApi>

API RESPONSE FIELD DETAILS

XML element Description
errorCode The error code of the API call. Will be 0 upon success or a different number upon failure.
errorDescription "Success" if the API call was successful or a description of the error if not.
publicKey Your public key as appears under Account Information & Settings page.
token A non-repeated unique value.
hash The SHA-256 hash of publicKey + ":" + token + ":" + [API secret_key] where [API secret_key] is your Openbucks API Secret Key.

The API secret key can be found under the Account Information & Settings page.

This hash field is used by you to authenticate the Openbucks response. At reception you need to re-compute this hash and compare to the one received.

Important: The hash is formatted in lowercase hexadecimal with no byte separator.

Important: To be computed on the server side only.

PHP example:
$req_hash = hash("sha256",$public_key . ":" . $token . ":" . $api_secret_key);

Note: Change to the production API Secret Key when switching to Production mode.
version Echo back of the version you provided on the request, or the default one used if it was omitted.
params Echo back the params field from the request
payload The contents of the Postback xml as described in Postback Field Details above

REQUIRED VALIDATION


Below is the list of required validation steps upon retrieving the transaction information via any of the methods described above:

  • Validate the identity of the response by checking that the public key provided is actually yours.
    Note: when using the API, you should validate the public key in the <authentication> tag. You can additionally validate the public_key in the <payload> tag.
  • Authenticate the response as coming from Openbucks by computing a hash and comparing it to the hash received on the response. The computation is:
    Validation OptionComputation
    Postbackhash("sha256", $public_key . ":" . $pwgcTrackingID . ":" . $secret_key)
    APIhash("sha256", $public_key . ":" . $token . ":" . $api_secret_key)
    Note: when using the API, compute the hash with your api_secret_key and compare it to the hash found in the <authentication> tag.
  • Validate the tracking id merchantTrackingID to confirm this is a transaction you are familiar with.
  • Validate the amount amountValue. Since req_amount is passed to our payment page from the client side, a sophisticated user can tamper with it.
  • Validate the currency code currencyCode. Since req_currency_code is passed to our payment page from the client side, a sophisticated user can tamper with it.
  • Validate the errorCode is 0 for forward compatibility.

ACTIVATE PRODUCTION


In order to activate your production account please follow the following steps:

UPDATE URLS AND KEYS


The Production Merchant Admin Portal includes access to the Production variants of the keys and URLs, located in the Settings page.


CHANGES YOU NEED TO DO

Sandbox key or URL Must be replaced by Where
Sandbox public key Production public key req_public_key parameter in Configuring Your Hidden Form.
Sandbox Secret Key Production Secret Key Computation of hash in the Required Hidden Form Fields and in the Transaction Postback Listener.
Sandbox payment URL Production payment URL POST URL in hidden form (See: Configuring Your Hidden Form).
Sandbox button URL (or tracking pixel URL) Production button URL (or tracking pixel URL) Openbucks button code in your purchase page. (See: Choose Your Openbucks Button).
Sandbox API Secret Key Production API Secret Key Computation of hash in Transaction Details API Call.

TEST PAYMENT


Once you have been promoted to production, you can make a payment and test the complete flow in your production environment. There is a special "brand" of card called the "Openbucks Test" card. The card is disabled by default and does not appear on the payment wall. To use the card to perform production testing, please follow the steps from below. NOTE: the "Openbucks Test" card automatically deactivates (and balance restored to $100) every midnight Pacific Time.

HOW IT WORKS


  • Login to the production merchant portal
  • From the menus select Merchant -> Manage Production Test Card or click here
  • Note the card number and pin
  • Set the balance [optional]
  • Click the DISABLED button
  • Click Submit
  • Restart a new Openbucks payment. Notice the addition of the Test Card in the wall Production Test Card
  • Select the "Openbucks Test"
  • Type in the card number and pin that were noted before

CODE SAMPLES


To make your integration easier we provide a list of customized ready to use code samples that you can copy and paste into your code.

Would you like us to provide more examples? let us know!

CALCULATE HASH


Here is an example of the expected output of your req_hash calculation:

Environment Token Secret Key Merchant Tracking Id Amount Currency Code Hash
Sandbox 2012-10-26 23:30:19 508b7f7b0cf1f5.39963962 [SANDBOX-SECRET-KEY] f831c668 10.50 USD 8ee0b7d296d6f93a9f8f7ccc2d9cdbb4431b2dfd306e80a46897acef5de19ede
Production 2012-10-26 23:30:19 508b7f7b0cf1f5.39963962 [PRODUCTION-SECRET-KEY] f831c668 10.50 USD a78624396cf76cddeac1beb8f0aa61d3ec442bba86e1a7625ddb2a2846ee18ba

Sample code in PHP:

$token = "2012-10-26 23:30:19 508b7f7b0cf1f5.39963962";
$secret_key = "[SANDBOX-SECRET-KEY]";
$merchant_tracking_id = "f831c668";
$amount = "10.50";
$currency_code = "USD";
$force_cards = ""; // Empty
$hash = hash("sha256", $token.$secret_key.$merchant_tracking_id.$amount.$currency_code.$force_cards);

BUTTON AND HIDDEN FORM


EXAMPLE

Click on the example button below to initiate a $1.99 payment with your sandbox account, you can even complete the transaction with one of our test cards

Pay with Gift Cards


USAGE

To use the button, just paste in the code below wherever you want it to appear

<img style="border: 0" alt="Pay with Gift Cards" src="https://demo-pay.openbucks.com/paybutton_v2.php?style=obx-170-50-anim&amp;pubkey=[SANDBOX-PUBLIC-KEY]"/>

Note: that we've placed your public key [SANDBOX-PUBLIC-KEY].


The button is wrapped with an <a> tag that points to another script containg the hidden form.

<a href="/api-docs/pay_demo.php">
   <img style="border: 0" alt="Pay with Gift Cards" src="https://demo-pay.openbucks.com/paybutton_v2.php?style=obx-170-50-anim&amp;pubkey=[SANDBOX-PUBLIC-KEY]"/>
</a>

pay_demo.php looks like this:

<?php

// TODO: Replace with the actual amount
$amount = 1.99;

// TODO: Replace with the actual currency code
$currency_code = 'USD';

// TODO: Replace with the actual item description
$item_description = 'Button example test transaction';

// TODO: Replace with your own tracking ID for this transaction.
$merchant_tracking_id = time() . uniqid('', true);

// TODO: Replace this with a unique value identifying your customer
$customer_anonymous_id = 'UNIQ CUSTOMER ID';

// TODO: Replace with your customer email
$email = '[email protected]';

// These are your Openbucks Sandbox keys, when you switch to production replace Sandbox Secret Key with Production Secret Key.
$public_key = '';
$secret_key = '';

// Create a unique token and hash
$token = date('Y-m-d H:i:s ') . uniqid('', true);
$hash = hash('sha256', $token . $secret_key . $merchant_tracking_id . $amount . $currency_code);

?><!DOCTYPE html>
<html lang="en">
   <head>
      <title>Pay with Cash and Gift Cards using Openbucks</title>
   </head>
   <body>
      <form action="https://demo-pay.openbucks.com/payment_v3.php" method="POST" name="openbucks_form">

         <input type="hidden" name="req_currency_code" value="<?php echo $currency_code ?>" />
         <input type="hidden" name="req_amount" value="<?php echo $amount ?>" />
         <input type="hidden" name="req_item_description" value="<?php echo $item_description ?>" />
         <input type="hidden" name="req_merchant_tracking_id" value="<?php echo $merchant_tracking_id ?>" />
         <input type="hidden" name="req_customer_anonymous_id" value="<?php echo $customer_anonymous_id ?>" />
         <input type="hidden" name="req_public_key" value="<?php echo $public_key ?>" />
         <input type="hidden" name="req_token" value="<?php echo $token ?>" />
         <input type="hidden" name="req_hash" value="<?php echo $hash ?>" />
         <input type="hidden" name="req_customer_info_email" value="<?php echo $email ?>" />


         <!-- Use only if your product has been rated by an official organization, such as the ESRB. -->
         <input type="hidden" name="req_rating_model" value="OPENBUCKS" />
         <input type="hidden" name="req_product_rating" value="Unrated" />
      </form>
      <script type="text/javascript">
         document.openbucks_form.submit();
      </script>
   </body>
</html>	

Here's how the compiled pay_demo.php looks like.

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>Pay with Cash and Gift Cards using Openbucks</title>
   </head>
   <body>
      <form action="https://demo-pay.openbucks.com/payment_v3.php" method="POST" name="openbucks_form">

         <input type="hidden" name="req_currency_code" value="USD" />
         <input type="hidden" name="req_amount" value="1.99" />
         <input type="hidden" name="req_item_description" value="Button example test transaction" />
         <input type="hidden" name="req_merchant_tracking_id" value="15112906865a14773e33faf9.03148490" />
         <input type="hidden" name="req_customer_anonymous_id" value="UNIQ CUSTOMER ID" />
         <input type="hidden" name="req_public_key" value="" />
         <input type="hidden" name="req_token" value="2017-11-21 10:58:06 5a14773e33fbd0.17477525" />
         <input type="hidden" name="req_hash" value="5da14b65ad14d15c8015de9a919e64c7698a11051f1c27cade217456617728bf" />
         <input type="hidden" name="req_customer_info_email" value="[email protected]" />


         <!-- Use only if your product has been rated by an official organization, such as the ESRB. -->
         <input type="hidden" name="req_rating_model" value="OPENBUCKS" />
         <input type="hidden" name="req_product_rating" value="Unrated" />
      </form>
      <script type="text/javascript">
         document.openbucks_form.submit();
      </script>
   </body>
</html>	

POSTBACK LISTENER


Below is an example of a basic Postback listener written in PHP.

Save it to a file and make sure to complete the response processing below in the TODO sections.

<?php

// These are your Openbucks Sandbox keys, when you switch to production replace Sandbox Secret Key with Production Secret Key.
$public_key = '';
$secret_key = '';

try {
      // Request must be a POST
      if($_SERVER['REQUEST_METHOD'] != "POST") {
         throw new Exception("An HTTP POST was expected");
      }

      // Request must contain data
      if(!strlen($HTTP_RAW_POST_DATA)) {
         throw new Exception("HTTP POST XML data is empty.");
      }

      // Enable user error handling
      libxml_use_internal_errors(true);

      // Load post data to SimpleXMLElement object
      $xml_response = simplexml_load_string($HTTP_RAW_POST_DATA);

      if ($xml_response === false) {
         throw new Exception("Failed to load XML");
      }

      if (count($xml_response->response->children()) == 0) {
         throw new Exception("A response was expected.");
      }

      // Extract the <requestID> <error> <payment> XML elements
      list($request_id_element,$error_element,$payload) = $xml_response->response->children();

      // We expect a payment response
      if($payload->getName()!="payment"){
         throw new Exception("A payment response was expected.");
      }

      // Check that the response comes from the Openbucks payment server
      $hash = hash("sha256", $public_key . ":" . $payload->transaction->pwgcTrackingID . ":" . $secret_key);
      if($hash != $payload->transaction->pwgcHash){
         throw new Exception("The authenticity of the Openbucks payment server could not be established.");
      }

      // Check that the public key in the repsonse is yours
      if($public_key != $payload->merchantData->publicKey){
         throw new Exception("Could not validate public key.");
      }

      // TODO: Here are more validations you should do before you process Openbucks response:
      //       Validate tracking ID: $payload->merchantData->merchantTrackingID
      //       Validate amount: $payload->amount->amountValue
      //       Validate currency code: $payload->amount->currencyCode

      // TODO: Do rest of response processing here.


} catch (Exception $e) {
   // TODO: Do error processing here (log error, send email, etc..)

   // return code 500 - Internal Server Error
   header('X-PHP-Response-Code: 500', true, 500);
}
	

TRANSACTION DETAILS


Below is sample code to make the getTransactionsDetails API Call. Click on the example button below to initate the API request:

getTransactionsDetails

<?php
header("Content-type: text/xml");

function curl_post($url,$body){
   $ch = curl_init($url);
   curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

   $ar_headers = array();
   $ar_headers[] = "Content-Length: " . strlen($body);
   curl_setopt($ch, CURLOPT_HTTPHEADER, $ar_headers);

   curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 20);
   curl_setopt($ch, CURLOPT_TIMEOUT, 20);
   curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);

   $response = curl_exec($ch);

   $error_code = curl_errno($ch);
   $error_description = curl_error($ch);

   curl_close($ch);
   if($error_code!=0){
      return "curl_post: ${error_description} (${url}) code: $error_code";
   }
   return $response;
}

// These are your Openbucks API Sandbox keys, when you switch to production replace Sandbox API Secret Key with Production API Secret Key.
$api_public_key = 'a281a8c5-ca7d-4c0f-9ddd-7df2310dfccc';
$api_secret_key = 'cccccccc-6ba8-4fb9-93ee-6e2b964df4f8';

// Create a unique token and hash
$token = date('Y-m-d H:i:s ') . uniqid('', true);
$hash = hash('sha256', $token . $api_secret_key);

$xml = <<<EOS
<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>a281a8c5-ca7d-4c0f-9ddd-7df2310dfccc</publicKey>
         <token>2017-11-21 10:58:06 5a14773e363b08.98571639</token>
         <hash>5cf3be9aecb8dfb79a8fd0d3bfacddeb7747ed0d38223a1534f531f1e38df601</hash>
      </authentication>
      <getTransactionsDetails>
         <version>1.1</version>
         <params>
            <status>SUCCESS</status>
               <startTime>2012-10-01 00:00:00</startTime>
               <endTime>2012-10-03 00:00:00</endTime>
         </params>
      </getTransactionsDetails>
   </request>
</pwgcApi>
EOS;

$response = curl_post('https://demo-api.openbucks.com', $xml);
print $response;
?>

NON-PHP


If you're not using PHP, you might have a use for the misc function below.

Would you like use to provide more examples in your language? let us know!

HASH FUNCTION (C#)

The function below creates a SHA256 hash.
public static string sha256(string input) {
   Byte[] inputBytes = Encoding.UTF8.GetBytes(input);
   Byte[] hashedBytes = new SHA256CryptoServiceProvider().ComputeHash(inputBytes);
   return BitConverter.ToString(hashedBytes).Replace("-", string.Empty).ToLower();
}
This is how to use it: sha256("test string");

output: d5579c46dfcc7f18207013e65b44e4cb4e2c2298f4ac457ba8f82743f31e930b

API OVERVIEW


HOW IT WORKS


Openbucks provides several utility APIs to improve your data retreival and processing.

To make an API request make an HTTP POST using the following URLs and keys:

API URLs and keys

Environment URL API Secret Key
Sandbox https://demo-api.openbucks.com [SANDBOX-API-KEY]
Production https://api.openbucks.com [PRODUCTION-API-KEY]

REQUEST STRUCTURE


API responses share the same skeleton structure:
  • An authentication block - containing your publicKey, a random token and a signed hash
  • An API block - which consists of the name of the API, the API version to use and a list of params specific for that API

API REQUEST SKELETON STRUCTURE

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>2012-10-18 17:13:5050809b3e4d123</token>
         <hash>e21bce3c39b83531f4629e02307d9f0186334c646ca78c75004d65d41183e97e</hash>
      </authentication>
      <SPECIFIC_API_NAME>
         <version>1.0</version>
         <params>
            <param1>value1</param1>
            <param2>value2</param2>
            <param3>value3</param3>
         </params>
      </SPECIFIC_API_NAME>
   </request>
</pwgcApi>

API REQUEST AUTHENTICATION BLOCK DESCRIPTION

XML element Description
publicKey Your public key as appears under Account Information & Settings page.
token A non-repeated unique value to be formatted as follows:
YYYY-MM-DD HH:MM:SS[space][at least 10 random printable characters]
This value is used to authenticate you (see req_hash below) and to prevent replay attacks.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_token = date("Y-m-d H:i:s ") . uniqid('', true);

You can use whatever method you want to generate the random characters.
The token parameter can only contain the following characters:
a-z A-Z 0-9 space : . - / ( ) _ [ ] | =
hash The SHA-256 hash of [token] + [api_secret_key] where [api_secret_key] is your Openbucks API Secret Key. The hash must be formatted in lowercase hexadecimal with no byte separator.

The API secret key is used by Openbucks to authenticate you on all API requests. It can be found under the Account Information & Settings page.

IMPORTANT: To be computed on the server side only.

PHP example:
$req_hash = hash("sha256",$token . $api_secret_key);

Note: Change to the production API Secret Key when switching to Production mode.

API REQUEST API BLOCK DESCRIPTION

XML element Description
SPECIFIC_API_NAME Replace this with the particular api name you are calling
version Optional. Exclude from the XML to get the latest version.
param1 Replace this with the particular params of the api you are calling

RESPONSE STRUCTURE


API responses share the same skeleton structure:
  • An error block - indicating whether the api called succeeded, and an error message if not
  • An authentication block - containing your publicKey, a random token issued by Openbucks, and a hash signed by Openbucks using your API Secret Key
  • An API block - containing an echo back of the version and params from your request, and the payload

API RESPONSE SKELETON STRUCTURE

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <response>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>Success</errorDescription>
      </error>
      <authentication>
         <publicKey>f831c668-9dbf-4a26-8920-02dfdb5408bd</publicKey>
         <token>0eaea33c-05b4-466e-a78f-7188bcc300fb</token>
         <hash>ecae3249e8bcbeb476bf0f22c259191c5b00e4e0eb166cb572e115a5212025ad</hash>
      </authentication>
      <SPECIFIC_API_NAME>
         <version>1.0</version>
         <params>
            <param1>value1</param1>
            <param2>value2</param2>
            <param3>value3</param3>
         </params>
         <payload>
            ...SPECIFIC API PAYLOAD...
         </payload>
      </SPECIFIC_API_NAME>
   </response>
</pwgcApi>

API RESPONSE ERROR BLOCK DESCRIPTION

XML element Description
errorCode The error code of the API call. Will be 0 upon success or a different number upon failure.
errorDescription "Success" if the API call was successful or a description of the error if not.

API RESPONSE AUTHENTICATION BLOCK DESCRIPTION

XML element Description
publicKey Your public key as appears under Account Information & Settings page.
token A non-repeated unique value.
hash The SHA-256 hash of publicKey + ":" + token + ":" + [API secret_key] where [API secret_key] is your Openbucks API Secret Key.

The API secret key can be found under the Account Information & Settings page.

This hash field is used by you to authenticate the Openbucks response. At reception you need to re-compute this hash and compare to the one received.

Important: The hash is formatted in lowercase hexadecimal with no byte separator.

Important: To be computed on the server side only.

PHP example:
$req_hash = hash("sha256",$public_key . ":" . $token . ":" . $api_secret_key);

Note: Change to the production API Secret Key when switching to Production mode.

API RESPONSE API BLOCK DESCRIPTION

XML element Description
SPECIFIC_API_NAME Replace this with the particular api name you are calling
version Echo back of the version you provided on the request, or the default one used if it was omitted.
params Echo back the params field from the request
payload The contents of the Postback xml as described in Postback Field Details above

API SPECS


getTransactionPostback


getTransactionPostback allows you to retreive the information that was sent to your backend servers in the postback after the transaction completed.

getTransactionPostback sample request

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>2012-10-18 17:13:5050809b3e4d123</token>
         <hash>e21bce3c39b83531f4629e02307d9f0186334c646ca78c75004d65d41183e97e</hash>
      </authentication>
      <getTransactionPostback>
         <version>1.0</version>
         <params>
            <trackingID>2012-10-18 17:13:0050809b0c8c327</trackingID>
         </params>
      </getTransactionPostback>
   </request>
</pwgcApi>

getTransactionPostback request params

trackingID Your merchant tracking ID as provided in req_merchant_tracking_id of the hidden form

getTransactionPostback sample response

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <response>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>Success</errorDescription>
      </error>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>0eaea33c-05b4-466e-a78f-7188bcc300fb</token>
         <hash>aa640e5cdfae7e4d92692e2686a0b249b9fddce0164edc4a72bd705d9c086d7d</hash>
      </authentication>
      <getTransactionPostback>
         <version>1.0</version>
         <params>
            <trackingID>2012-10-18 17:13:0050809b0c8c327</trackingID>
         </params>
         <payload>
            <requestID>0</requestID>
            <error>
               <errorCode>0</errorCode>
               <errorDescription>OK</errorDescription>
            </error>
            <payment>
               <transaction>
                  <transactionID>117830</transactionID>
                  <pwgcTrackingID>18eb8626-bf63-4312-890b-43bfc05f525e</pwgcTrackingID>
                  <timestampUTC>2012-10-19 00:13:20</timestampUTC>
                  <pwgcHash>7f222f3cbefc71e129f1056fed2365b67f15791b3be8d2902b5f170a2e0b8be0</pwgcHash>
               </transaction>
               <amount>
                  <currencyCode>USD</currencyCode>
                  <amountValue>0.10</amountValue>
               </amount>
               <merchantData>
                  <merchantToken>2012-10-18 17:13:0050809b0c8b73c</merchantToken>
                  <merchantHash>032b5fb9a1aba6d71c92b3cf271522b569a26a43cda191bac2269262270b70b4</merchantHash>
                  <publicKey>f831c668-9dbf-4a26-8920-02dfdb5408bd</publicKey>
                  <merchantTrackingID>2012-10-18 17:13:0050809b0c8c327</merchantTrackingID>
                  <productID>Los Angeles Credits</productID>
                  <itemDescription>Credits at 1 cents each</itemDescription>
                  <ratingModel>ESRB</ratingModel>
                  <productRating>E</productRating>
               </merchantData>
            </payment>
         </payload>
      </getTransactionPostback>
   </response>
</pwgcApi>

getTransactionPostback payload details

payload The contents of the Postback xml as it was sent to your postback URL

getActiveCards


getActiveCards allows you to retreive a list of active (and non-active) gift cards that are available for your consumers during checkout along with fees associated with each card.

getActiveCards sample request

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>2012-10-18 17:13:5050809b3e4d123</token>
         <hash>e21bce3c39b83531f4629e02307d9f0186334c646ca78c75004d65d41183e97e</hash>
      </authentication>
      <getActiveCards>
         <version>1.1</version>
         <params>
         </params>
      </getActiveCards>
   </request>
</pwgcApi>

getActiveCards request params

This API does not accept any params

getActiveCards sample response

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <response>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>Success</errorDescription>
      </error>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>0eaea33c-05b4-466e-a78f-7188bcc300fb</token>
         <hash>aa640e5cdfae7e4d92692e2686a0b249b9fddce0164edc4a72bd705d9c086d7d</hash>
      </authentication>
      <getTransactionPostback>
         <version>1.1</version>
         <params>
            <trackingID>2012-10-18 17:13:0050809b0c8c327</trackingID>
         </params>
         <payload>
            <cards>
               <activeCards>
                  <card>
                     <apiID>subway</apiID>
                     <name>SUBWAY gift card</name>
                     <label>SUBWAY&reg;</label>
                     <fees>
                        <fixed>0</fixed>
                        <percentage>25</percentage>
                     </fees>
                     <currency>USD</currency>
                  </card>
                  <card>
                     <apiID>cvspharmacy</apiID>
                     <name>CVS/pharmacy gift card</name>
                     <label>CVS/pharmacy&reg;</label>
                     <fees>
                        <fixed>0</fixed>
                        <percentage>25</percentage>
                     </fees>
                     <currency>USD</currency>
                  </card>
               </activeCards>
               <nonActiveCards>
                  <card>
                     <apiID>shell</apiID>
                     <name>Shell gift card</name>
                     <label>Shell</label>
                     <fees>
                        <fixed></fixed>
                        <percentage></percentage>
                     </fees>
                     <currency>USD</currency>
                     <reason>Card is disabled</reason>
                  </card>
               </nonActiveCards>
            </cards>
         </payload>
      </getTransactionPostback>
   </response>
</pwgcApi>

getActiveCards payload details

payload Contains a 'cards' tag which contains 'activeCards' and 'nonActiveCards' tags. Each one of those consists of a list of 'card' tags
card:apiID The ID to use when referring to this card for api requests
card:name The name of the gift card. For display purposes
card:label The gift card issuer label. For display purposes
card:fees The fixed fee and percentage fee per transaction associated with gift card
card:reason An indication of why the card is not active
card:currency The currency code of this card (available from api version 1.1)

getTransactionDetails


getTransactionsDetails allows you to retreive information (amount, dates, fees, etc.) for one or more transactions in bulk.

getTransactionsDetails sample request

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <request>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>2012-10-18 17:13:5050809b3e4d123</token>
         <hash>e21bce3c39b83531f4629e02307d9f0186334c646ca78c75004d65d41183e97e</hash>
      </authentication>
      <getTransactionsDetails>
         <version>1.2</version>
         <params>
            <status>SUCCESS</status>
            <startDate>2012-10-01 00:00:00</startDate>
            <endDate>2012-11-01 00:00:00</endDate>
         </params>
      </getTransactionsDetails>
   </request>
</pwgcApi>

getTransactionsDetails request params

status Optional. Default value=ALL. Possible values are:
  • SUCCESS: Retreive only successful non-voided transactions
  • VOIDED: Retreive only voided transactions
  • ALL: Retreive both voided and non-voided transactions
  • TEST: Retreive only test transactions (transactions completed with the Openbucks Test Card)
startDateOptional. Retreive transactions which ended after start date. Format is YYYY-MM-DD hh:mm:ss, and timezone is PDT. Can either be provided alone or in tandem with endDate
endDateOptional. Retreive transactions which ended before endDate. Format is YYYY-MM-DD hh:mm:ss, and timezone is PDT. Can either be provided alone or in tandem with startDate
startTransactionIDOptional. Retreive transactions with IDs >= startTransactionID. Can either be provided alone or in tandem with endTransactionID
endTransactionIDOptional. Retreive transactions with IDs <= endTransactionID. Can either be provided alone or in tandem with startTransactionID
transactionIDOptional. Retreive a single transaction with id=transactionID

getTransactionsDetails sample response

<?xml version="1.0" encoding="UTF-8"?>
<pwgcApi xmlns="http://openbucks.com/xsd/api/1.0">
   <response>
      <error>
         <errorCode>0</errorCode>
         <errorDescription>Success</errorDescription>
      </error>
      <authentication>
         <publicKey>[SANDBOX-PUBLIC-KEY]</publicKey>
         <token>0eaea33c-05b4-466e-a78f-7188bcc300fb</token>
         <hash>aa640e5cdfae7e4d92692e2686a0b249b9fddce0164edc4a72bd705d9c086d7d</hash>
      </authentication>
      <getTransactionsDetails>
         <version>1.1</version>
         <params>
            <status>SUCCESS</status>
            <startDate>2012-10-01 00:00:00</startDate>
            <endDate>2012-11-01 00:00:00</endDate>
         </params>
         <payload>
            <transactions>
               <transaction>
                  <id>121546</id>
                  <currencyCode>USD</currencyCode>
                  <amount>29.99</amount>
                  <fixedFee>0</fixedFee>
                  <percentageFee>2.21</percentageFee>
                  <errorCode>0</errorCode>
                  <dateUTC>1351265666</dateUTC>
                  <date>2012-10-26 7:34:26</date>
                  <voidDateUTC></voidDateUTC>
                  <voidDate></voidDate>
                  <trackingID>f0436a0f-8c49-4efa-a020-1741bbfd19be</trackingID>
                  <merchantTrackingID>2012-10-26 15:26:56508b0e305fbaf</merchantTrackingID>
                  <merchantToken>2012-10-26 15:26:56508b0e305eff6</merchantToken>
                  <invoiceNumber></invoiceNumber>
                  <voidInvoiceNumber></voidInvoiceNumber>
                  <itemDescription>100 farm credits/itemDescription>
                  <subPropertyName></subPropertyName>
                  <cardApiID>subway</cardApiID>
                  <remoteIP>1.2.3.4</remoteIP>
                  <countryCode>USA</countryCode>
                  <stateOrProvince>CA</stateOrProvince>
                  <city>Oakland</city>
                  <netPayout>27.78</netPayout>
               </transaction>
               <transaction>
                  <id>121547</id>
                  <currencyCode>USD</currencyCode>
                  <amount>49.99</amount>
                  <fixedFee>0</fixedFee>
                  <percentageFee>5.02</percentageFee>
                  <errorCode>0</errorCode>
                  <dateUTC>1351265933</dateUTC>
                  <date>2012-10-26 7:38:53</date>
                  <voidDateUTC></voidDateUTC>
                  <voidDate></voidDate>
                  <trackingID>4b4ceff2-d779-41d1-961e-8c4dcd1a016a</trackingID>
                  <merchantTrackingID>2012-10-26 15:26:56508b0e305fbaf</merchantTrackingID>
                  <merchantToken>2012-10-26 15:26:56508b0e305eff6</merchantToken>
                  <invoiceNumber></invoiceNumber>
                  <voidInvoiceNumber></voidInvoiceNumber>
                  <itemDescription>1000 farm credits</itemDescription>
                  <subPropertyName></subPropertyName>
                  <cardApiID>subway</cardApiID>
                  <remoteIP>1.2.3.4</remoteIP>
                  <countryCode>USA</countryCode>
                  <stateOrProvince>TX</stateOrProvince>
                  <city>Houston</city>
                  <netPayout>44.97</netPayout>
               </transaction>
         </payload>
      </getTransactionsDetails>
   </response>
</pwgcApi>

getTransactionsDetails payload details

payload Contains a 'transactions' tag which contains 0 or more 'transaction' tags
transaction:idThe transaction ID
transaction:currencyCodeUSD or CAD
transaction:amountThe transaction amount in the specified currency
transaction:fixedFeeThe nominal fixed fee due to Openbucks from this transaction in the specified currency
transaction:percentageFeeThe nominal variable fee due to Openbucks from this transaction in the specified currency. Equals transaction:amount x gift_card_fee_rate (see business contract for details of fee rates).
transaction:errorCodeThe transaction error code. 0=Success.
transaction:dateUTCThe timestamp of the transaction in UTC (available from api version 1.2)
transaction:dateThe string date representation of the transaction in timezone America/Los_Angeles
transaction:voidDateUTCIf the transaction has been voided, the timestamp of the void in UTC (available from api version 1.2)
transaction:voidDateIf the transaction has been voided, the string date representation of when the void occured in timezone America/Los_Angeles
transaction:trackingIDThe Openbucks tracking id for this transaction
transaction:merchantTrackingIDThe tracking id you passed on the request form: req_merchant_tracking_id
transaction:merchantTokenThe token you passed on the request form req_token
transaction:invoiceNumberThe number of the invoice this transaction belongs to. Will be empty if the transaction hasn't been invoiced yet. Invoices can be viewed here
transaction:voidInvoiceNumberIf the transaction has been voided, the number of the void invoice this transaction belongs to. Will be empty if the transaction hasn't been voided or the void hasn't been invoiced yet. Invoices can be viewed here
transaction:itemDescriptionThe item description you passed on the request form: req_item_description
transaction:subPropertyNameThe sub property name you passed on the request form: req_sub_property_name
transaction:cardApiIDThe card api id of the card that was used in the transaction (available from api version 1.1)
transaction:remoteIPThe remote IP of the consumer making the transaction(available from api version 1.2)
transaction:countryCodeThe 3 letter ISO 3166 country code traced back to the remote IP(see here)(available from api version 1.2)
transaction:stateOrProvinceThe state or province name traced back to the remote IP(available from api version 1.2)
transaction:cityThe city name traced back to the remote IP(available from api version 1.2)
transaction:netPayoutThe net payout due to you for this transaction. Equals transaction:amount - transaction:fixedFee - transaction:percentageFee(available from api version 1.2)

QUESTIONS


Here are some of the most common questions people ask, should you have any further questions, please let us know!

WHERE CAN I FIND TEST CARDS FOR DEVELOPMENT?


Openbucks provides test cards for the Sandbox environment in the Sandbox Merchant Admin Portal.
Those cards can be found under Review Demo Accounts in the "Transactions" menu.


Demo Receipt

WHERE CAN I FIND TEST CARDS FOR PROUCTION?


Once you have been promoted to production, you can make a payment and test the complete flow in your production environment. There is a special "brand" of card called the "Openbucks Test" card. The card is disabled by default and does not appear on the payment wall. To use the card to perform production testing, please follow the steps from below. NOTE: the "Openbucks Test" card automatically deactivates (and balance restored to $100) every midnight Pacific Time.

  • Login to the production merchant portal
  • From the menus select Merchant -> Manage Production Test Card or click here
  • Note the card number and pin
  • Set the balance [optional]
  • Click the DISABLED button
  • Click Submit
  • Restart a new Openbucks payment. Notice the addition of the Test Card in the wall Production Test Card
  • Select the "Openbucks Test"
  • Type in the card number and pin that were noted before

HOW CAN I SETUP THE POSTBACK URL?


You can manage your URLs under Account Information & Settings in the 'Settings' menu.

HOW CAN I SETUP THE RETURN SUCCESS URL?


If you need a dynamic success url, you can provide it with each payment request in the req_success_url field of the Openbucks form.
If you have a static success url, you can specify it under Account Information & Settings in the 'Settings' menu.

HOW CAN I SETUP THE RETURN CANCEL URL?


If you need a dynamic cancel url, you can provide it with each payment request in the req_cancel_url field of the Openbucks form.
If you have a static cancel url, you can specify it under Account Information & Settings in the 'Settings' menu.

HOW DO I CALCULATE THE REQ_HASH FIELD?


Follow this example: Calculating the req_hash field

I AM NOT RECEIVING THE POSTBACK. WHAT CAN I DO?


  • Validate the postback url is set correctly. Sandbox: here, Production here.
  • Validate your firewall is accepting inbound requests from our servers on port 443/80

I HAVE A FIREWALL. WHAT IP ADDRESSES DO I WHITELIST TO RECEIVE THE POSTBACK?


Please whitelist the following ips (ports 443/80):
  • 52.8.39.2
  • 52.8.194.58
  • 54.193.16.214

I AM RECEIVING AN EMPTY POSTBACK CALL. WHAT CAN I DO?


Make sure you are reading the contents of the POST from the raw bytes:

PHP Example:
$xml_response = new SimpleXMLElement($HTTP_RAW_POST_DATA);

ASP Example:
Dim HTTP_RAW_POST_DATA_LEN = Request.Totalbytes
Dim HTTP_RAW_POST_DATA = BinaryToString (Request.BinaryRead(CLng(HTTP_RAW_POST_DATA_LEN)))

WHAT DO I NEED TO DO TO SEND PAYMENTS IN CURRENCIES OTHER THAN USD?


To send payments in currencies other than USD, we require you to digitally sign (hash) the req_currency_code and other fields to prevent end users from tampering with the currency.

Please follow the following three steps:
  • Pass in your desired currency in req_currency_code
  • Include the merchant_tracking_id, amount and currency_code in req_hash as explained here
  • Validate the currency code in your postback listener as explained in Required Validation Steps