How to connect my payment service via the API?

The Payment API is only available in the Business plan. You will also be charged $0.25 per transaction through the Payment API. This fee will be deducted from your Bukza account balance.

You can connect any payment service to Bukza via the payment API. To connect, you need your own server — a mediator between Bukza and your payment service. Programming skills are also required.

This API may have some changes in the future.

Send us a request to support@bukza.com for enabling your payment API. In your message specify the URL of your server to which Bukza will send requests. We will send you your User ID and the key to generate a signature hash.

You can check out the JavaScript source code example in the online code editor service here.

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

1. Sign up on Glitch.
2. Create a remix of our integration example here by clicking the "Remix" button. This will set up your own application with the same source code.
3. After this, we recommend opening the TERMINAL in Glitch and running the command: npm ci. This will install the required dependencies.
4. Email us at support@bukza.com with the address of your created application. We'll then set it as the URL address for your server and send you the bukza_user_id and bukza_key.
5. Open your application's .env file and insert the bukza_user_id and bukza_key values. This file is not visible to other Glitch users.
6. Go to your Bukza account. On the payment processing form, enable "Orders with automatic payment processing" and set the required deposit amount.
7. Complete an order using the widget, using your account's email. By using your account's email when completing the order, you won't incur any fees for using the payment API.
8. During testing, check the "Logs" tab in Glitch. There, you'll find logs of received and sent requests.
9. Implement the display of your payment form and the handling of responses from your payment system in the server.js and index.hbs files. Avoid inserting your keys and passwords into any file except the .env file. Project files and the entire history of their changes are accessible to other Glitch users.

You can implement one of two options:

1. "With pre-authorization" — option that prevents overbooking. When the order is completed, the amount is first pre-authorized on the card, and then we additionally check that the order is still available and the price has not changed. If the order is no longer available, the pre-authorization is cancellled immediately.
   
   You can use this integration option to capture funds later manually. You can verify the reservation yourself and either capture funds or cancel the pre-authorization. However, if the funds are still not captured after 3 days, Bukza will send a request to cancel the pre-authorization.
   
   
2. "Simplified mode" — this is an option without pre-authorization. In other words, the funds have already been captured at the moment when the order is completed. However, we still check the availability and amount of the order, and if there is a problem, we will add a warning for the manager in "New order" message.
   
   This option should be used if your payment service does not support pre-authorization.

The following parameters are always present in requests:

• userId — your ID in the Bukza system, e.g 11223.
• orderNumber — an order number in Bukza, e.g "574285869".
• command — a name of the command to run. One of the values: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture" or "Refund".
• data — additional command data, such as the transaction number in your payment system: "18493853499".
• amount — payment amount, e.g 99.75.
• timestamp — the number of seconds of Unix time, e.g 1596706182. Examples of getting it in different programming languages: https://www.epochconverter.com.

To create or verify the request signature, you need to concatenate all these parameters into a single string (without spaces or plus signes), calculate hmac sha256 with your key, and convert the result to a base64 string:

Implementation examples 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 points:

• When converting an amount value to a string, use a dot as the separator if there is a fractional part of the number.
• When receiving your requests, Bukza checks that the timestamp matches the current server time and does not lag by more than 5 minutes.
• When receiving requests from Bukza, we recommend you to check the hash and the 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 the data like this:

• url — this is the generated address of the payment page. This page can be located either on your server or on the server of your payment gateway.
• redirect — a parameter that determines whether the user should be completely redirected to the specified URL. If the value is false, the payment form will appear inside the widget in an iframe. You can change the size of the iframe using css in the widget settings.
• checkStateToken has been added to the url with the name of the parameter bukzaCheckStateToken. This parameter will help 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 makes the payment. Accordingly, you should receive a notification to your server from your payment gateways. After receiving this notification, you should immediately send a POST request to https://public.bukza.com/api/pay. Request body:

1.3 Then, depending on the availability of the order and the order processing parameters, Bukza can do one of the following: cancel the pre-authorization, immediately capture the funds, or simply place an order, leaving the funds pre-authorized. In the latter case, you can cancel or capture the payment yourself in the Manager's interface. In any case, Bukza will send requests to your server that you should send to your payment gateway.

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

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

You should send any response with the HTTP status 200 (SUCCESS).

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

2.2 The customer now sees your payment form and makes the payment. Accordingly, you should receive a notification to your server from your payment gateways. After receiving this notification, you should 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 making a refund, Bukza sends a request to your server. You have to send a corresponding request to your payment gateway. Request body from Bukza:

You should send any response with the HTTP status 200 (SUCCESS).