How to connect my payment service via the API?

The Payment API is available only with the Business plan. A fee of $0.25 per transaction applies when using the Payment API. This fee will be deducted from your Bukza account balance.

You can connect any payment service to Bukza using the Payment API. To do this, you will need your own server to act as an intermediary between Bukza and your payment service. Programming skills are required.

Please note that this API may be subject to changes in the future.

To enable the Payment API, send a request to support@bukza.com. In your message, specify the URL of your server where Bukza should send requests. We will provide you with your User ID and the key needed to generate a signature hash.

You can view a JavaScript source code example in the online code editor here.

To test this example with your account, follow these steps:

1. Sign up at Glitch.
2. Create a remix of our integration example here by clicking the "Remix" button. This will create your own application with the same source code.
3. Next, open the TERMINAL in Glitch and run the command: npm ci. This will install the required dependencies.
4. Email us at support@bukza.com with the address of your new application. We will set this as your server URL and send you the bukza_user_id and bukza_key.
5. Open your application's .env file and enter the bukza_user_id and bukza_key values. This file is not visible to other Glitch users.
6. Go to your Bukza account. In the payment processing form, enable "Orders with automatic payment processing" and set the required deposit amount.
7. Complete an order using the widget, making sure to use your account's email address. When you use your account's email to complete the order, you will not be charged any fees for using the Payment API.
8. During testing, check the "Logs" tab in Glitch. Here, you will find logs of received and sent requests.
9. Implement your payment form display and handle responses from your payment system in the server.js and index.hbs files. Do not insert your keys or passwords into any file except the .env file. Project files and their entire change history are accessible to other Glitch users.

You can implement one of two options:

1. "With pre-authorization" — this option prevents overbooking. When the order is completed, the amount is first pre-authorized on the card, and then we check that the order is still available and the price has not changed. If the order is no longer available, the pre-authorization is cancelled immediately.
   
   With this integration option, you can manually capture funds later. You can verify the reservation yourself and either capture the funds or cancel the pre-authorization.
   
   
2. "Simplified mode" — this option does not use pre-authorization. In this case, the funds are captured immediately when the order is completed. We still check the order's availability and amount, and if there is an issue, a warning will be added for the manager in the "New order" message.
   
   Use this option if your payment service does not support pre-authorization.

The following parameters are always included in requests:

• userId — your ID in the Bukza system, e.g., 11223.
• orderNumber — the order number in Bukza, e.g., "574285869".
• command — the name of the command to execute. Possible values: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture", or "Refund".
• data — additional command data, such as the transaction number in your payment system: "18493853499".
• amount — the payment amount, e.g., 99.75.
• timestamp — the number of seconds since Unix epoch, e.g., 1596706182. For examples in different programming languages, see: https://www.epochconverter.com.

To create or verify the request signature, concatenate all these parameters into a single string (without spaces or plus signs), calculate the HMAC SHA256 using your key, and convert the result to a base64 string:

Example implementations for different programming languages: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

You can check the calculation here: http://jsfiddle.net/dwyrk513/1/

Important notes:

• When converting the amount value to a string, use a dot as the decimal separator if there is a fractional part.
• When receiving requests, Bukza checks that the timestamp matches the current server time and does not differ by more than 5 minutes.
• When receiving requests from Bukza, we recommend that you also check the hash and timestamp in the same way.

1.1. When the order is completed, Bukza sends a POST request to your server URL with the following body: In response to this request, you should send data in the following format:

• url — the generated address of the payment page. This page can be hosted either on your server or on your payment gateway's server.
• redirect — determines whether the user should be fully redirected to the specified URL. If set to false, the payment form will appear inside the widget in an iframe. You can adjust the iframe size using CSS in the widget settings.
• checkStateToken is added to the url as the parameter bukzaCheckStateToken. This parameter allows you to check the order state on your payment page. Read more about this here.

1.2. The customer now sees your payment form and completes the payment. You should receive a notification from your payment gateway to your server. After receiving this notification, immediately send a POST request to https://public.bukza.com/api/pay. Request body:

1.3. Depending on the order's availability and processing parameters, Bukza may do one of the following: cancel the pre-authorization, immediately capture the funds, or simply place the order while leaving the funds pre-authorized. In the latter case, you can cancel or capture the payment yourself in the Manager's interface. In all cases, Bukza will send requests to your server, which you should then forward to your payment gateway.

To cancel the pre-authorization, Bukza sends you a request with the following body:

To capture pre-authorized funds, Bukza sends you a request with the following body:

You should respond with HTTP status 200 (SUCCESS) to any such request.

2.1. When the order is completed, Bukza also sends a POST request to your server URL, just as in step 1.1.

2.2. The customer now sees your payment form and completes the payment. You should receive a notification from your payment gateway to your server. After receiving this notification, immediately send a POST request to https://public.bukza.com/api/pay. Request body:

You can use the Manager's interface to issue a refund for a specific payment. The refund can be full or partial. When a refund is processed, Bukza sends a request to your server. You must then send a corresponding request to your payment gateway. Request body from Bukza:

You should respond with HTTP status 200 (SUCCESS) to any such request.