Javascript integration

Payment buttons

On your checkout page, add a tag which will be a placeholder for the payment buttons, e.g.:
...
<div id='bv-buttons'></div>
...
Make sure the tag has an id associated with it, e.g. bv-buttons in this example.

Then, add javascript which will render the buttons and initiate a transaction:
<script src='https://bitvolo.com/bitvolo.js'></script>
<script>
var bitvolo = new Bitvolo();
bitvolo.setup("bv-buttons", // ID of the tag to host the buttons
              2,            // ID of the bitvolo account to be used
              "CART123",    // your order reference number (max 64 chars, allowed characters: alphanumeric, dash, underscore) - this must be a unique code, different for each payment request
              "SEAL",       // server-side generated seal: your server-side code must calculate sha1 of the concatenation of your secret key, reference number, currency and amount requested, see below for the details
              10,           // total price to be paid by the customer in the currency indicated as the next parameter, e.g. 10 or 10.00
              "USD",        // currency (can be normal currency codes such as USD, EUR, CHF etc or one of the supported cryptocurrencies: IOTA, XLM etc.) 
              ["BTC", "BANK"], // list of coins to be accepted (one of: 'BTC', 'XRP', 'ETH', 'ADA', 'BANK' - which means bank transfer) -- these coins must be properly configured on the Bitvolo settings page; for ETH tokens use ETH/xxx
              {             // array with extra (non-mandatory) options
                  callback_url: "https://myserver/ipn.php", // URL of the callback script on your server; it can include GET parameters
                  success_url: "https://myserver/done.php", // URL of the success page; it can include GET parameters (it's possible to call a javascript function instead of redirecting, see the details below)
                  update: function(status, data) {/*...*/}, // if success_url is not specified, Bitvolo will call this function whenever the transaction status changes (see the details below)
                  custom_field: "XYZ123", // your custom field which will be send back along with your IPN call
                  lang: "en", // 2-letter language code (ISO 639-1) of the user interface (default is English)
              });
</script>

Server-side-generated seal

Important: The 4th parameter in the call to bitvolo.setup (seal) MUST BE generated on the server-side. You cannot do it on the client-side as you'd be publishing your secret key. The seal is the concatenation of (with no separating characters): secret key, reference number, requested currency and requested amount (in the exact same format passed in the 5th parameter: total price). Here's a php sample for seal calculation:
bitvolo.setup(..., "CART123", "<?php echo sha1('my-secret-key' . 'CART123' . 'USD' . '10'); ?>", 10, "USD", ...);
This is all you must do in order to display the payment buttons to the customer and allow them to initiate a payment.

Currency conversion

If the price is specified in a fiat currency (EUR / USD / CHF etc.), we'll use the current (approximate) exchange rate between the fiat currency and the cryptocurrency used to make the payment.

IPN response

When the payment is sent, Bitvolo will call a script on your server identified by callback_url passed to the setup function. The following parameters will be POSTed to the script:
transaction_idUnique ID of the transaction in the Bitvolo system
referenceYour order reference (3rd parameter in your call to bitvolo.setup)
hashUnique transaction hash / Transaction number on the blockchain or tangle (empty for SEPA)
addressAddress the payment was sent to
amountAmount sent (in the coin used for the transaction)
amount_outstandingIf the customer sent an insufficient amount, this is the amount still outstanding
coinCryptocurrency/coin used for the payment
requested_currencyCurrency used in the original request
requested_amountAmount requested originally (in requested_currency)
custom_fieldCustom field sent in the original request
ipn_sealSeal you should use in order to check the authenticity of the IPN call. It's the sha1 checksum of the concatenation of: secret key, reference number, hash: sha1('my-secret-key' . 'reference' . 'hash'). Note that this seal includes the transaction hash which is not a part of the original seal sent when creating a transaction.
confirmationsNumber of confirmations received (always 1 for IOTA/XLM/XRP/EOS/TLOS/WAX)
success1 if the entire amount has been sent successfully (means that amount_outstanding is 0). In case of partial payment, the value will be 0
If the payment has not been sent 24 hours after creation (for all cryptos except EOS) or 1 hour (for EOS/TLOS/WAX) or 21 days (for bank transfer), Bitvolo will call the IPN script with the parameter failure set to 1. Other parameters listed above will also be sent.

To summarise, the IPN script will only be called in one the following three scenarios:
ScenarioParameters sent by Bitvolo
Full payment was made successfullysuccess=1
Partial payment was made successfullysuccess=0
Payment failedfailure=1


The IPN script must return OK in the HTTP response body (and the status code 200) to indicate it has successfully processed the transaction.

Redirection of customer to success page

After making the HTTP call to the IPN URL (callback), the bitvolo javascript will redirect the customer to the URL of the success page defined by you (in success inside the setup options).

If you don't want any redirection to happen, simply don't define success_url but rather specify a javascript function to be executed in update. This function should take two parameters:
statusOne of the following values:
new-transaction - transaction has been initiated in the bitvolo system
waiting - waiting for the payment
pending - pending transaction found
success - confirmed transaction found
cancelled - transaction has been cancelled by the customer
dataArray including the following data:
tag - bitvolo-generated tag which the customer must include in their transaction
coin - coin used (e.g. IOTA or XLM)
amount - amount sent
address - address the payment must be sent to
transaction_id - bitvolo transaction ID
hash - transaction hash on the blockchain or tangle (if already known)