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', 'BTC.LN', '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_id`	Unique ID of the transaction in the Bitvolo system
`reference`	Your order reference (3rd parameter in your call to `bitvolo.setup`)
`hash`	Unique transaction hash / Transaction number on the blockchain or tangle (empty for SEPA)
`address`	Address the payment was sent to
`amount`	Amount sent (in the coin used for the transaction)
`amount_outstanding`	If the customer sent an insufficient amount, this is the amount still outstanding
`coin`	Cryptocurrency/coin used for the payment
`requested_currency`	Currency used in the original request
`requested_amount`	Amount requested originally (in requested_currency)
`custom_field`	Custom field sent in the original request
`ipn_seal`	Seal 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.
`confirmations`	Number of confirmations received (always 1 for IOTA/XLM/XRP/EOS/TLOS/WAX)
`success`	`1` 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:

Scenario	Parameters sent by Bitvolo
Full payment was made successfully	`success=1`
Partial payment was made successfully	`success=0`
Payment failed	`failure=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:

`status`	One 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
`data`	Array 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)