References

BucksBus practices several approaches to the acceptance of payments. At the integration stage, you will need to choose the one you like best for your business. The following options may affect your integration design.

Payment Page

For your convenience, Service implements the payment page on its side. You receive a URL when calling Create Payment API in the field (PAYMENT_URL) and direct your customer to that page, but you also have the ability to implement the payment page on your side with all information for such page provided in the payment on Create Payment API.

Payment Type

Service supports two types of payment: fixed amount and open amount. The appropriate payment type will be set by the PAYMENT_TYPE parameter in the call Create Payment API and can take two values (FIXED_AMOUNT or OPEN_AMOUNT). The default option is FIXED_AMOUNT.

Fixed amount payment (FIXED_AMOUNT). The payment will only be successful when the payer pays an amount equal to or exceeding the one ordered within the time allowed for payment, otherwise the payment will be considered failed. The payer may make several payments within the time allowed for payment. The service will wait for payment of the entire amount ordered until the time allowed for payment expires.

Open amount payment (OPEN_AMOUNT). The payment will be successful upon receipt of any amount within the time allowed for such payment. The payment will only fail when the payment lifetime expires and no funds are received at the address within that time.

Amount in any currency

You may request creation of a payment from BucksBus indicating the desired amount in a fiat or crypto currency.

Fiat amount. This type of payment is designed for when you need your payer to pay in a crypto currency while your price is in a fiat currency, and you do not want to bother with any exchange rates.
For instance, if you need your customer to pay 100 USD in the BTC equivalent, you need to set the following parameters when calling Create Payment API:
AMOUNT – fiat amount (e.g. 100)
ASSET_ID – fiat currency (e.g. USD)
PAYMENT_ASSET_ID – crypto currency (e.g., BTC).
BucksBus will translate 100 USD into BTC at the going rate, and then will ask the customer to pay an amount in BTC.

Crypto currency amount. This type of payment is designed for when your price is stated in either a crypto or a fiat currency but you want it converted into a crypto currency on your side. For instance, you want your customer to pay 100 USD in BTC, so for an API call you will need to translate 100 USD into BTC yourself, e.g., into 0,037 BTC. The parameters required when calling Create Payment API:
AMOUNT – amount in a currency (e.g. 0,037)
ASSET_ID – currency (e.g. BTC)
PAYMENT_ASSET_ID – crypto currency (e.g. BTC).
BucksBus will ask the customer to pay the amount in BTC.

Markup

To prevent crypto currency volatility from affecting your revenue, you may set a markup for each crypto currency. To set the markup you need to either indicate the absolute amount in crypto currency or a percentage in the merchant’s interface. The Store: Settings -> Assets -> The crypto, fields Markup amount and/or Markup percentage.  For instance, when calling Create Payment API you indicate AMOUNT=100, ASSET_ID = USD, PAYMENT_ASSET_ID = BTC, and in that case, the service will convert the amount of 100 USD into BTC as 0,037 BTC, and will add a minimum markup or a Markup amount, or a Markup percentage from 0,037. If you have stated both, the maximum will be the default selection.

Underpayment threshold

You can also compliment the customer on the crypto currency volatility by providing some tolerance when making payment, through setting certain values in the merchant’s interface. The Store: Settings -> Payments, fields Underpayment threshold and/or Underpayment threshold percentage. The option is only available for fixed amount payments.
For instance, when calling Create Payment API you indicate AMOUNT=100, ASSET_ID = USD, PAYMENT_ASSET_ID = BTC, and in that case, the service will convert the amount of 100 USD into BTC as 0,037 BTC. To complete the payment, the customer must pay 0,037 BTC less a certain threshold amount equal to the minimum of either the underpayment threshold or the percentage of the underpayment threshold percentage of 0,037.

Amount paid

BucksBus will call your system upon completion or cancelation of payment, and for any incoming crypto currency transaction. The call back will contain the payment, and you may use the fields therein or request information from Get Payment, Get Payment Transactions API.
The field Payment Status (OPEN) shows that the payment is being processed and the customer’s transactions are being waited for, status indications (COMPLETE, CANCEL) mean that the payment has been completed. The fields (AMOUNT, ASSET_ID, PAYMENT_ASSET_ID) show what you s-indicated in the call Create Payment API. The fields (PAYMENT_AMOUNT, RATE, RATE_DATE) are the exchange rate and the sums converted. The fields (IP_AMOUNT, IP_ASSET_ID) are what the customer has paid in crypto currency until now, while the fields (PAID_AMOUNT, ASSET_ID) show what has been paid in a fiat currency converted at the exchange rate (RATE, RATE_DATE) effective on the date when the payment was created. To reflect the fiat payment amount in your system, your system will either take the fiat amount (PAID_AMOUNT, ASSET_ID) from the payment, or it will convert the crypto currency amount (IP_AMOUNT, IP_ASSET_ID) on your side at any going rate, e.g., on the date when the crypto currency transaction is published in the blockchain or the payment is completed.

Time allowed for payment

After calling Create Payment API, BucksBus will create a payment and will wait for incoming customer transactions in the blockchain. The timeout is about 60-90 minutes and is indicated in the service, and you may also set your own timeout for the call Create Payment API in the field (TIMEOUT).

Dedicated address

BucksBus allows you to dedicate or assign a particular crypto address for a certain client, so that all incoming crypto on that address will be translated into payment for the client. To activate such option, you will be requested to call Create Dedicate Address API, and as a result, system will dedicate a particular address for the client and return (PAYMENT_URL) that you can provide to the client for payments. You can enhance PAYMENT_URL for user convenience with additional parameters: amount and asset_id like (amount=200&asset_id=USDT.TRC20). You can also implement the payment page on your side, as well. In order to stop that behaviour you need to call Release Dedicated Address API. Address can be allocated from pool or generated as new by specifying parameter address_alloc. You can also reserve address for particular payments. To achieve that it needs to pass parameter dedicate_type as ASSIGN on dedicate creation and then pass the dedicate_id to payment creation, so that the address be used for the payment.

Withdrawals

BucksBus allows customer withdrawals through an API call so that you could be able to implement the withdrawal logic on your side, while service will take care of all technical aspects in the blockchain. For withdrawals through the API, the following risks must be considered:

Security. When you withdraw crypto currency in BucksBus user interface, such withdrawals may be protected with a two-factor authentication, but if you call the withdrawal API security shall be your responsibility. The API call is protected with an API key/API secret therefore compromising such key/secret may result in losing your money.

Fee amount. When you withdraw crypto currency via the BucksBus user interface, you are able to manage the fee amount and control the number of transactions required to make a withdrawal, while you are unable to do so in an API call, and to avoid additional transactions/fees you should keep the balance in a single address sufficient for fund withdrawals.

Payment Page#

Payment Type#

Amount in any currency#

Markup#

Underpayment threshold#

Amount paid#

Time allowed for payment#

Dedicated address#

Withdrawals#