Wunderbit Commerce API v1

Connect e-commerce website and start accepting bitcoin payments

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:

• Composer (https://packagist.org/packages/wunderbit/wbc-sdk): composer require wunderbit/wbc-sdk
• Download repository: https://bitbucket.org/infinites/wbc-sdk/downloads/?tab=tags - the versions on the left are shown in the list, and the download links in the specific format on the right.

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)

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"

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
{
 // ...
}

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

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

2.2. Invoice generation

All errors start with 73* code