oBucks API documentation

Overview

Setup account

The oBucks card is a closed-loop, digital prepaid card issued by Openbucks Corp. oBucks cards are redeemable in over 1,000+ online games.

There are two methods for resellers to order oBucks cards:

  1. 1. Card batches: Ordered via a PDF “Purchase Order” form.
  2. 2. API: Using an Openbucks’ RESTful Obucks issue API
This document describes the Obucks card issue API, which enables approved merchants to issue Obucks cards on demand, and to check Obucks card balances.

If you have any technical questions, please contact support@openbucks.com

Sandbox vs Production

While integrating and testing you will use the Sandbox environment. Your merchant account in the Sandbox environment does not need to be funded, and the cards generated are dummies that cannot be used by customers to pay on Openbucks.

Obtaining sandbox keys

In order to start integrating you the following:

  1. 1. Whitelisting: please send us the IP of the server(s) that will make the calls to our API
  2. 2. Your sandbox dashboard credentials (provided by your Openbucks account manager)
  3. 3. This documentation
Once you have received your Sandbox dashboard credentials, log in to the Sandbox dashboard at https://demo-merchant.openbucks.com . Once logged in, you can find your Sandbox keys (Public key + API Secret Key) under Settings > Account Keys and URLs.

In order to make an API request to the Sandbox, you will need the “Public Key” and “API Secret Key”:

Obtaining production keys

Once successfully integrated in Sandbox, ask Openbucks to promote you to production. In order to prevent confusion between Sandbox and Production cards, which would cause serious customer service issues, please request the closing of your Sandbox account before moving to Production, and make sure to store separately (or destroy) all the Sandbox cards you have generated while testing.

Both your Public Key and API Secret Key are different in Production than in Sandbox. To retrieve your Production keys, log into the Production dashboard at https://merchant.openbucks.com. Once logged in, you can find your production keys (Public key + API Secret Key) under Settings > Account Keys and URLs.

Funding account

Funding your merchant account

Note that you need to fund your merchant account before you can issue Obucks cards using this API. This is done offline by transferring money to Openbucks. For more details, please contact Openbucks finance at purchases@openbucks.com. Once your account is funded, it will be charged each time you issue a card. If it goes under an agreed minimum, you will receive a friendly reminder to reload your account in order to avoid service interruptions.

Check merchant account balance

In Sandbox, you don’t need a prepaid balance in order to issue Obucks cards.

In production, there are two ways you can get your current balance:

  1. 1. By capturing it when you get the response from the API
  2. 2. By logging into the merchant dashboard at https://merchant.openbucks.com and going to Transactions > Review Balance.

API

How to use the API

The API is designed to issue one card per API request (not batches). If you’d like to generate a batch of cards, you need to run requests in a loop.

To make an API request make an HTTP POST using the following URLs and keys. All parameters in Requests and Responses are in JSON format.

API URLs and keys

Use the following URLs and keys provided to you by Openbucks:

Environment URL API secret key
Sandbox https://demo-services.openbucks.com/v1.0 See "Obtaining sandbox keys"
Production https://services.openbucks.com/v1.0 Provided by Openbucks
Request and response calls

Request and respond card issue (<url>/card/issue)

Request (JSON format):

Parameter Required Type Example Comments
public_key Yes String Provided by Openbucks
tracking_id Yes String(85) 167672aba Tracking ID of your choice and must be unique
requested_on Yes Date 2014-06-17T16:22:42+02:00 ISO8601 Local time with delta from UTC
buyer_id Yes String(63) johnsky Unique handle of the user, consistent over multiple requests for this user
buyer_ip Yes String(15) 156.123.45.12 Populate this field if making a request from your backend service. If not provided the request’s ip will be assumed to be the buyer’s ip
buyer_email No String(63) johnsky@blog.com
buyer_mobile No String(15) 6502223333 Used for sms delivery
card_api_id Yes String(25) openbuckscard Always openbuckscard
denom Yes Integer 25 Options (please inform us if you need other denoms): 0, 1, 5, 5.5, 6.5, 6.55, 10, 10.5, 13, 15, 20, 21, 25, 26, 50, 100
currency Yes String(3) USD iso 3166-1 alpha-3
delivery Yes String(3) Yes Default: No
redeem_merchant_id No String(10) S3128 Will provided by Openbucks if relevant
signature Yes String(127) 0cced0d448b182c5e2510ae246ef4485e5540b0e219283107f76e25c669447d7 See instructions in the next section


Response (JSON format):

Parameter Type Example Comments
transaction_id String(31) 326576
card_number String(25) 1234123412341234
pin String(25) 1234
denom Integer 12
balance Integer 5
currency String(3) USD
discount Double -0.47 (10%) Per contract
net_cost Double 5.47 = Denom - Discount
purchased_by String(63) johnsky@blog.com Unique user identifier and buyer_id from request
delivered_to_email String(63) johnsky@blog.com
delivered_to_mobile String(15) 6509998888 Used for sms confirmation
merchant_balance Double 1000.00 Merchant balance after current issue request and can be negative but not lower than merchant_credit
merchant_credit Double 500.00 Merchant is allowed to issue cards up to this amount after balance reaches 0
error_code Integer 0
error_message String(127) ok
signature String(127) 0cced0d448b182c5e2510ae246ef4485e5540b0e219283107f76e25c669447d7 See instructions in the next section
completed_on Date 2014-06-17T16:22:42+02:00 ISO8601 Local time with delta from UTC


Request example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"buyer_email":" homsky@openbucks.com ",
"buyer_id":"0123456789ABCDEFGH",
"buyer_ip":"100.200.100.200",
"buyer_mobile":"",
"card_api_id":"openbuckscard",
"currency":"USD",
"delivery":"Yes",
"denom":"5",
"public_key":"f831c668-9dbf-4a26-8920-02dfdb5408bd",
"requested_on":"2019-02-07T04:10:44-08:00",
"sub_property_id":"",
"sub_property_name":"",
"sub_property_url":"",
"tracking_id":"2019-02-07 04:10:445c5c2044d7184",
"Signature":"6e2b7b0c1ccd6c515efe9ee6d37395228585101e7e29295fc7dcf788221a27ef"
}


Response example:

{
"transaction_id":2157,
"card_number":"3259741400543824",
"pin":"3836",
"denom":"5",
"balance":5,
"currency":"USD",
"discount":"-0.47",
"net_cost":"5.47",
"purchased_by":"0123456789ABCDEFGH",
"delivered_to_email":" homsky@openbucks.com ",
"delivered_to_mobile":"",
"error_code":0,
"error_message":"",
"signature":"b9ab09e975a9e8bd325edfac1d36c6924c1d658d367025eef59b59486d44e937",
"completed_on":"2019-02-07T04:10:45-08:00"
}

Request and respond card balance (<url>/transaction/balance)

Request (JSON format):

Parameter Required Type Example Comments
public_key Yes String Provided by Openbucks
tracking_id Yes String(85) 167672aba Tracking ID of your choice and must be unique
requested_on Yes Date 2014-06-17T16:22:42+02:00 ISO8601 Local time with delta from UTC
currency Yes String(3) USD iso 3166-1 alpha-3
card_api_id Yes String(25) openbuckscard
card_number Yes String(25) 4021737940879178
pin Yes String(25) 8140
signature Yes String(127) 0cced0d448b182c5e2510ae246ef4485e5540b0e219283107f76e25c669447d7 See instructions in the next section


Response (JSON format):

Parameter Type Example Comments
currency String(3) USD
balance Integer 5
error_code Integer 0
error_message String(127) ok
signature String(127) 0cced0d448b182c5e2510ae246ef4485e5540b0e219283107f76e25c669447d7 See instructions
completed_on Date 2014-06-17T16:22:42+02:00 ISO8601 Local time with delta from UTC

Request example:

 1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"card_api_id" : "openbuckscard" ,
"card_number" : "4021737940879178" ,
"currency" : "USD" ,
"pin" : "8290" ,
"public_key" : "f831c668-9dbf-4a26-8920-02dfdb5408bd" ,
"requested_on" : "2019-04-23T05:58:32-07:00" ,
"services" : "services" ,
"sub_property_id" : "" ,
"sub_property_name" : "" ,
"sub_property_url" : "" ,
"tracking_id" : "2019-04-23 05:58:325cbf0bf903672" ,
"signature" : "df9c0802e24b9de8cf6243f7e478a2884b500c11e860843e07b191d270122182"
}


Response example:

1
2
3
4
5
6
7
8
{
"currency" : "USD" ,
"balance" : 10 ,
"error_code" : 0 ,
"error_message" : "" ,
"signature" : "b5df2fcfb7599d60aa9714b063e3e397391f7935492b3128db359161b7d788d1" ,
"completed_on" : "2019-04-23T05:58:33-07:00"
}

Signature generation

Element Description
publicKey Your public key will be provided by Openbucks.
signature The SHA-256 hash of [ all params] + [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 will be provided by Openbucks.

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 of function to generate signature:

function generateSignature($request_params, $secret_key) {
ksort($request_params);
$data = implode(',', array_map(function ($v, $k) { return $k . '=' . $v; },
$request_params, array_keys($request_params))) . "," . $secret_key;
return hash('sha256', $data);
}

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

API response error blocks

HTTP Response Codes:

  • SUCCESS = 200;
  • BAD REQUEST = 400;
  • INTERNAL ERROR = 500;
Element Description
errorCode

HTTP Response Codes:

  • SUCCESS = 0;

  • BAD_REQUEST_FORMAT = 100;

  • INVALID SIGNATURE = 201;
  • MISSING PARAM = 202;
  • INVALID PARAM = 203;
  • BAD_FORMAT PARAM = 204;
  • INVALID API VERSION = 205;
  • INVALID ACCOUNT = 206;
  • NON JSON = 207;

  • MAX AMOUNT EXCEEDED = 602;
  • MIN AMOUNT ERROR = 603;
  • OVER TRANSACTION LIMIT = 604; (Velocity Error)
  • INVALID USER IP = 609;
  • INACTIVE COUNTRY = 610;
  • DENOM NOT AVAILABLE = 611;
  • CARD ISSUE LIMIT EXCEEDED = 616;
  • MERCHANT BALANCE TOO LOW = 617;

  • INTERNAL ERROR = 900;
errorDescription "Success" if the API call was successful or a description of the error if not.