Integration Manual


    Last updated: October 27, 2015


    Integration 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, Burger King, Shell and CVS/Pharmacy. 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:

    Placement - where to display the Openbucks button

    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

    Text - how to describe the Openbucks payment

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


    Graphics - which 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


    Your integration keys

    How it works: understanding integration keys

    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 Openbucks payment button

    How it works: Openbucks payment button

    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

    Selecting style and size

    Openbucks provides button images in several styles and sizes. Available layouts are displayed below.
    If your site requires alternative layouts, please contact your account manager.

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


    Setup the Openbucks payment form

    How it works: Openbucks payment form

    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/payment_v3.php
    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 hi@domain.com 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.


    Setup Transaction Validation

    How it works: validating a transaction

    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.



    Transaction Postback 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 API Call

    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 Steps

    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 your production environment

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


    Update URLs & 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 a Payment in Production

    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


    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!



    Example: Calculating the req_hash field

    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);
    						


    Example: Button & 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 = 'customer@email.com';
    
    // These are your Openbucks Sandbox keys, when you switch to production replace Sandbox Secret Key with Production Secret Key.
    $public_key = 'SANDBOX-PUBLIC-KEY-XXXX-YYYYYYYYYYYY';
    $secret_key = 'SANDBOX-SECRET-KEY-XXXX-YYYYYYYYYYYY';
    
    // 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="148756316558aa699d70f4c6.68133089" />
             <input type="hidden" name="req_customer_anonymous_id" value="UNIQ CUSTOMER ID" />
             <input type="hidden" name="req_public_key" value="SANDBOX-PUBLIC-KEY-XXXX-YYYYYYYYYYYY" />
             <input type="hidden" name="req_token" value="2017-02-19 19:59:25 58aa699d70f582.53726668" />
             <input type="hidden" name="req_hash" value="35309d18c3ad493581e3a98cc229a6a373765ad454a03b79cca9bbbf0cb33121" />
             <input type="hidden" name="req_customer_info_email" value="customer@email.com" />
    
    
             <!-- 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>						


    Example: 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 = 'SANDBOX-PUBLIC-KEY-XXXX-YYYYYYYYYYYY';
    $secret_key = 'SANDBOX-SECRET-KEY-XXXX-YYYYYYYYYYYY';
    
    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);
    }
    						


    Example: Transactions Details API Call

    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 = 'SANDBOX-API-KEY-XXXX-YYYYYYYYYYYY';
    $api_secret_key = 'SANDBOX-API-SECRET-KEY-XXXX-YYYYYYYYYYYY';
    
    // 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>SANDBOX-API-KEY-XXXX-YYYYYYYYYYYY</publicKey>
          <token>2017-02-19 19:59:25 58aa699d9432c1.19409690</token>
          <hash>35f15518233eb9f0ed27eca401f5b14effe481315064a341c2d368b061cdeafc</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: making an API call

    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]

    API Request structure overview

    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

    API Response structure overview

    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

    API: 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

    API: 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)

    API: getTransactionsDetails

    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)

    FAQ

    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 the Sandbox environment?

    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 the Production environment?

    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 set the postback URL?

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

    How can I set 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 set 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 ips do I need to whitelist in order 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 the Postback call, but it looks empty. 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