Wiki

Clone wiki

wbc-sdk / doc_v1.0.0

Wunderbit Commerce API v1

Connect e-commerce website and start accepting bitcoin payments N|Solid

1. Starting with Wunderbit Commerce API

1.1. Using SDK

Currently, the SDK (software development kit) is available only for PHP. For other languages, use the option without SDK (see 1.2. Part). The SDK can be installed in two ways:

The first option is suitable if Сomposer is already used in your project, for example, if you use such PHP frameworks as Symfony or Laravel.

If you are not comfortable using Composer, you can use the second option. The src folder contains a file with the WbcSDK class - you need to connect it via require (http://php.net/manual/en/function.require.php) or use importing (http://php.net/manual/en/language.namespaces.importing.php).

Please note that using the second option, in order to update the SDK version, the old version will need to be replaced with a new one by downloading it from the above link. When using Composer, it will be enough to write: composer update wunderbit/wbc-sdk.

After the class is connected, you can create its object:

$wbcSDK = new WbcSDK(my_api_key)

You need to pass the API key to the constructor, which can be obtained in your account: http://merchants.Wunderbit Commerce.com/merchant_admin/settings in the API tab. Now you can generate a invoice. To do this, use the WbcSDK::generateInvoice method. This method takes 7 parameters:

  1. customerEmail (required, maximum 150 characters) - customer email. Information on changing the status of the invoice will be sent to this email. It should be noted that the Wunderbit Commerce system will check the spelling of the email, ie, for example, “example@gmail.com” will be a valid email, and not “example @ gmail” or “example.com” will be correct.
  2. totalPrice (mandatory, maximum 100 characters, must be numeric) - the price of the invoice in Euros - either an integer or a number with a point accurate to hundredths. The number will be rounded to the nearest hundredth with great precision. An example of the correct values ​​is 34212, 2333.47, 3453.4
  3. customId (optional, maximum 100 characters) - in the account in the list of orders and on the order page, marked as “Extra ID”. Thanks to this parameter, you can associate the generated invoice with a specific order in your system.
  4. items (optional) - an array of products that the buyer buys. The transferred list of goods will be displayed in the account on the order page. Each product is an associative array, which consists of the following properties (all are required):

    • item_id - product ID;
    • item_name - product name;
    • item_price - product price in Euros;
    • item_amount - quantity of goods.

    The maximum number of products in an array is 150. The maximum length of each property value of a product is 100 characters, except for item_name - 255 characters.

  5. extra (optional, the maximum number of properties is 20, the maximum length of the property name is 100 characters, the maximum length of the value is 255 characters) - an associative array with any additional invoice properties that will be visible on the order page in the cabinet. Array example: [‘customer_name’ => ‘Johan’, ‘'customer_phone' => '+328 3423423', delivery_method => 'courier']. The order info in the cabinet will look like this:

    Additional parameters:

    Parameter Value
    customer_name Johan
    customer_phone +328 3423423
    delivery_method courier
  6. comebackUrl (optional, maximum length 255 characters) - URL address to which the buyer will be redirected after clicking the “Back to merchant's website” button on the invoice page. The URL can contain any parameters, for example, you can add ‘customId’: http://example.com/comeback.php?custom_id=304

  7. paidCallback (optional, maximum length 255 characters) - URL address to which the Wunderbit Commerce system will send a POST request (as a form) after payment of the invoice has been confirmed. URL can contain any GET parameters. POST request contains the following parameters:

    • verification_code - callback verification code, see below;
    • custom_id - extra ID;
    • invoice_code - invoice code;
    • created_at - date and time of creation;
    • customer_email - buyer's email;
    • total_price - amount on invoice, EUR;
    • status - invoice status (currently only "paid");
    • payment_amount - payment amount, EUR;
    • deviation_status - overpaid, underpaid or complete;
    • deviation_amount - difference, EUR;
    • currency - in what currency was the invoice paid - BTC.

    The response to the request should be just text - ‘ok’ (without quotes). If the answer is any other, then a repeated request will be sent to the specified URL with an interval of 12 hours until a ‘ok’ response is received. The maximum number of repeated requests is five - 5.

If everything went well, then the generateInvoice method will return an object of class stdClass, with the following properties:

{#12 
    +"message": "Invoice is generated successfully"
    +"status": "success"
    +"code": "31"
    +"data": {#18 
        +"invoice_code": "122871bf929a9298d09b81234f69bb02"
        +"verification_code": "9385bh9298d09b81234f69bb0202h289a0a"
  • message - message about the result of the request;
  • status - success (success) or error (error);
  • code - response code (for more details, see Part 2);
  • data - a stdClass object with the invoice_code property. In case of an error (status: error), data will be empty.
    • invoice_code - invoice code;
    • verification_code - callback verification code. For added security, the Wunderbit Commerce system will transmit a verification code as a parameter to each callback URL, so that the merchant can later verify that the callback is calling Wunderbit Commerce.

If an error occurs on the API side, null will be returned.

Thus, if the generateInvoice method returned non-null and status: “success”, you can redirect the buyer to the invoice page. You can get the invoice URL using the Wunderbit WbcSDK::getInvoiceUrl method, passing invoice_code from the API response there. Code example:

if ($invoice && $invoice->status == 'success')
{
    return $this->redirect ($wbcSDK->getInvoiceUrl($invoice->data->invoice_code));
}
else
{
 // ...
}

In case of failure, the buyer can be returned back to the order form and / or notify him that an error has occurred and it is necessary to contact the administration of the online store.

1.2. Without SDK

Before reading further, please read 1.1. part, as it describes the basic principle of working with the Wunderbit Commerce API.

You can generate a invoice without the SDK. To do this, it is enough to send a regular POST request with those specified in 1.1. often by parameters on the URL: https://cabinet.commerce.wunderbit.co/api/v1/invoice/generate

An example request with all available parameters is shown below:

POST Parameters

Key Value
api_key 8b317a8dde02938fa7321886ed76d64db704c4312dd306f04710c51e0ef361ab10993f7777025164065f57332354a766c37c6e4d52c1a9dff323b73989392848
custom_id 352
customer_email john@wunderbit.co
extra [customer_name => Johan, customer_phone => +193497902342, payment_method => cash]
items [0 => [item_id => 4, item_name => milk, item_price => 100, item_amount => 2], 1 =>[item_id => 5, item_name => bread, item_price => 100.5, item_amount => 3] ]
total_price 501.5

It should be noted that the PHP version of the image of index and associative arrays is used (http://php.net/manual/ru/language.types.array.php) i.e. using square brackets “[]” and the symbol “=>”.

The response will be received in JSON format:

{
   "message": "Invoice is generated successfully",
   "status": "success",
   "code": "31",
   "data": {
      "invoice_code": "67eb7176ea36bc63e21aa80ec446a80f"
   }
}

2. Wunderbit Commerce API response codes

Each response from the API contains:

  • message - what happened.
  • status - error / success.
  • code - response code.
  • data - data for which the request was sent. The field will be empty in case of an error.

The error code always starts with 7, and the success code with 3.

2.1. Login

Code Message Explanation
71 Authentication Required If a URL is requested that requires authorization
72 An authentication failed If the user is not found using the provided API key
74 API is disabled for provided API key If the service API for the user is turned off
75 API is currently disabled If the service API is disabled for all users

2.2. Invoice generation

All errors start with 73* code

Code Message Explanation
731 "customer_email" parameter is required The parameter "customer_email" is required
732 Max size of "customer_email" is 150 characters The maximum length of the customer_email parameter is 255 characters
733 Invalid "customer_email" parameter. Email must be like "example@gmail.com" Incorrect spelling of the email.
734 "total_price" parameter is required The parameter "total_price" is required
734 "total_price" parameter is required The parameter "total_price" is required
735 "total_price" parameter value can't be empty The parameter "total_price" cannot be empty
736 Max size of "total_price" is 100 characters The maximum length of the parameter "total_price" is 100 characters
737 "total_price" parameter must be numeric The parameter "total_price" must be numeric.
738 Max size of "custom_id" parameter is 100 characters Maximum length of the "custom_id" parameter is 100 characters
739 "items" parameter must be an array The "items" parameter must be an array
7310 Max size of "items" array is 150 Maximum length of the “items” array is 150 elements
7311 Every "item" in "items" parameter requires "item_id" parameter Each “item” in the “items” array must have the “item_id” property
7312 Parameter "item_id" in "item" (inside "items" parameter) can't be empty The property "item_id" in the array "item" (inside the array of "items") cannot be empty
7313 Max size of "item_id" in "item" (inside "items" parameter) is 100 characters The maximum length of the item_id property in the item array (inside the items array) 100 characters
7314 Every "item" in "items" parameter requires "item_name" parameter Each “item” in the “items” array must have the “item_name” property
7315 Parameter "item_name" in "item" (inside "items" parameter) can't be empty The property "item_name" in the array "item" (inside the array of "items") cannot be empty
7316 Max size of "item_name" in "item" (inside "items" parameter) is 255 characters The maximum length of the “item_name” property in the “item” array (inside the “items” array) 255
7317 Every "item" in "items" parameter requires "item_price" parameter Each “item” in the “items” array must have the “item_price” property
7318 Parameter "item_price" in "item" (inside "items" parameter) can't be empty The property "item_price" in the array "item" (inside the array of "items") cannot be empty
7319 Max size of "item_price" in "item" (inside "items" parameter) is 100 characters The maximum length of the item_price property in the item array (inside the items array) 100 characters
7320 Every "item" in "items" parameter requires "item_amount" parameter Each “item” in the “items” array must have the “item_amount” property
7321 Parameter "item_amount" in "item" (inside "items" parameter) can't be empty The property "item_amount" in the array "item" (inside the array of "items") cannot be empty
7322 Max size of "item_amount" in "item" (inside "items" parameter) is 100 characters The maximum length of the item_amount property in the item array (inside the items array) 100 characters
7323 "extra" parameter can have max 20 elements The "extra" array can contain a maximum of 20 elements
7324 Max size of "extra" item key is 100 characters The maximum length of a property in the extra array is 100 characters
7325 Max size of "extra" item value is 255 characters The maximum length of the value in the "extra" array is 255 characters
7326 "extra" parameter must be an array The parameter "extra" must be an array
7327 Max size of "comeback_url" parameter is 255 characters The maximum length of the “comeback_url” parameter is 255 characters
7328 Max size of "paid_callback" parameter is 255 characters The maximum length of the value of the paid_callback parameter is 255 characters

Updated