How to connect my payment service via the API?

The payment API is available on the Business plan. Additional Bukza commission when using the Payment API is 0.8%. For payments in other currencies we will convert amount to USD and calculate the commission at the time of payment. The result commission for each payment will be rounded up to an integer number of cents. At the end of the billing cycle (caused either by renewal or by downgrading of your plan), the total commission will be debited from your Bukza balance. You will be able to pay this amount during the renewal of your Bukza plan.

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. If our API is not suitable to connect to your payment gateway, please contact us via support@bukza.com, and we will try to improve it.

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.

Send us a request to support@bukza.com for enabling your payment API. We will ask you for the URL of your server to which Bukza will send requests. We will also send your ID and the key to generate a signature hash (for example: 7kd9sl8s0bsm409rdsk3jn20).

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).