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:
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:
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 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:
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 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 |
pos_id | No | String(64) | www.example.com | Identify point of sale |
terminal_id | No | String(64) | C2398 | Payment terminal ID in case of payment in the physical store. |
instrument _id | No | String(64) | XDFM-3982-A5B0 | Unique identifier of payment instrument. I.e. if credit card was used this field should identify the card used for payment. If the card is re-used - the value must be the same. |
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 |
API response error blocks
HTTP Response Codes:
Element | Description |
---|---|
errorCode |
HTTP Response Codes:
|
errorDescription | "Success" if the API call was successful or a description of the error if not. |