Javascript

The Javascript version of Money Button is very similar to the HTML version, but with a few key differences. First, values can be typed instead of necessarily being strings. For instance, some properties are boolean, some are objects, and some are functions. Second, properties are camelCased instead of being prefixed with 'data-'. Third, the button can be updated dynamically by rendering it again.

(The Javascript version of the button is actually what the HTML version is using under the hood.)

To use the Javascript Money Button, first add this script somewhere inside your HTML:

<script src="https://www.moneybutton.com/moneybutton.js"></script>

The moneyButton object

The script defines a global object called moneyButton. It provides only one function: render.

render

<div id='my-money-button'></div>
<script>
  const div = document.getElementById('my-money-button')
  moneyButton.render(div, {
    to: "[email protected]",
    amount: "1",
    currency: "USD",
    label: "Wait...",
    clientIdentifier: "some public client identifier",
    buttonId: "234325",
    buttonData: "{}",
    type: "tip",
    onPayment: function (arg) { console.log('onPayment', arg) },
    onError: function (arg) { console.log('onError', arg) }
  })
</script>

moneyButton.render takes two parameters. The first one is an DOM node. The button is going to be placed inside that DOM node. The second one is an object with options.

The available options are:

All the options are matched with the attributes of the HTML API, and have the exact same behavior. The HTML version uses the Javascript version under the hood.

to

This attribute specifies who is going to receive the payment. It's a string, and depending on its format it is interpreted in different ways:

This argument works together with amount and currency. If one of them is present the other two have to be present too.

If this attribute is present then outputs attributes cannot be present.

amount and currency

amount is a decimal number expressed as a string.

currency is the ISO code of the currency for fiat, or the ticker symbol for cryptocurrencies. It's always a three letter code. Popular currencies include 'USD', 'ARS', 'GBP', and many others. For a full list, see currencies.

These two combined specify the amount of money to be transferred when the button is swiped. The amount is converted into BSV at the moment of the swipe.

Both of them work together with to. If any of the three is present, the other two have to be present too.

label

Is the label of the button.

successMessage

After a successful payment the button shows a success animation with a success message. This attribute allows you to specify a custom success message.

When this value is not present the button has different defaults regarding its type. Tip buttons shows Thank you!, and buy buttons show It's yours!.

opReturn

If this attribute is present an extra output is added to the transaction with a simple OP_FALSE OP_RETURN script to post data on the BSV blockchain. The string is encoded in UTF-8 and used directly in the script. The size limit is 99000 bytes as determined by the BSV protocol.

This attribute is a convenience method that always inserts the string moneybutton.com at the start of the script. If you want to put large amounts of data in an OP_RETURN output, and have full control over the contents of the script, please follow these instructions.

outputs

This attribute is used to specify a lists of outputs on the BSV transaction. This is what you want to use if you want to send to multiple different people at the same time, or "multiple recipients." It can't be used at the same time with to, amount or currency.

outputs is an array containing a lists of output objects. Each element may have the following properties:

to, amount and currency work exactly as the top level attributes with the same name, except for the detail that all the outputs have to use the same currency. If there are 2 outputs using different currencies the button will fail before rendering.

Instead of using to argument you can specify which kind of output you are using with one of the attributes paymail, userId, address, or script.

An example of a button that pays to three addresses looks like this:

moneyButton.render(div, {
  outputs: [
    {
      address: "[email protected]",
      amount: "0.085",
      currency: "USD"
    },
    {
      address: "[email protected]",
      amount: "0.075",
      currency: "USD"
    },
    {
      address: "[email protected]",
      amount: "0.065",
      currency: "USD"
    }
  ]
})

An example of a button that pays to two users looks like this:

moneyButton.render(div, {
  outputs: [
    {
      userId: "6",
      amount: "0.085",
      currency: "USD"
    },
    {
      userId: "1040",
      amount: "0.015",
      currency: "USD"
    }
  ]
})

cryptoOperations

Money Button is a client-side, non-custodial Bitcoin SV (BSV) wallet. Users have their keys and our company cannot access them. The keys are used to sign Bitcoin transactions.

The same keys the user uses to sign BSV transactions can also be used to sign arbitrary data for use inside OP_RETURN scripts. Further, those same keys can also be used to encrypt and decrypt data on-chain.

Better still, with paymail we can sign data with a human-readable name (a paymail). We can also encrypt data to a paymail and decrypt data with a paymail.

These concepts form the fundamental pieces of an own your data paradigm for the internet whereby users can have full custody of their own data.

In order to enable this advanced functionality, we have created the crypto operations API. The basic idea of crypto operations is to pass in an array specifying methods to be performed, such as signing or encrypting data, and then for that data to be substituted for variables inside a transactions or to be returned off-chain (such as for decryption) using the onCryptoOperations callback.

For detailed information, please see the crypto operations API documentation.

clientIdentifier

Each app that uses Money Button is called a "client" in the jargon of OAuth. Money Button supports multiple clients per account. This is useful when a user wants to use Money Button to build several apps. When a transaction is done on a specific client the owner of the client can see the transaction even if they are not a recipient or sender of the funds.

You can create an app, which includes a client and the associated clientIdentifier, on the apps page in your user settings. Please see the apps documentation.

buttonId

This attribute is an identifier of the payment of the button. It can be used as an invoice number or reference number. It can be any string and it's attached to the payments created with a specific button. Payments are stored with that string and then can be queried later using this attribute.

buttonData

This attribute can be any string, but is meant to be a valid JSON string. The user can set arbitrary data here, that is associated with the payment and sent on the webhooks and retrieved with the API.

onPayment

A function that is called when the user makes a successful payment.

Example:

function myCustomCallback (payment) {
  console.log('A payment has occurred!', payment)
}

moneyButton.render(div, {
  to: "[email protected]",
  amount: "0.085",
  currency: "USD",
  onPayment: myCustomCallback
})

The payment attribute is a javascript object with the following attributes:

The function is always called in the context of 'window' object.

You can make a simple pay wall using the onPayment callback. An example is as follows:

<div id="my-button"></div>
<div id="my-hidden-content"></div>

<script>
  function displayHiddenContent (payment) {
    // be sure to validate the transaction - does it have the right outputs?
    document.getElementById('my-hidden-content').innerHTML = 'Hidden content.'
  }

  moneyButton.render(document.getElementById('my-button'), {
    to: "1040",
    amount: "0.01",
    currency: "USD",
    onPayment: displayHiddenContent
  })
</script>

Note that this simple example is not very secure. If you want to make a secure pay wall, you should use the api-client and/or webhooks.

onError

A function that is called when an error occurs during the payment. Is not called if there is a problem with the parameters of the button or if there is a problem related with compatibility.

<div id="my-button"></div>

<script>
  function myCustomCallback (error) {
    console.log(`An error has occurred: ${error}`)
  }

  moneyButton.render(document.getElementById('my-button'), {
    to: "1040",
    amount: "0.01",
    currency: "USD",
    onError: myCustomCallback
  })
</script>

The parameter received by the function is the description of the error. The function is always called in the context of window object.

onLoad

A function that is called when the button has finished loading.

<div id="my-button"></div>

<script>
  function myCustomCallback () {
    console.log(`The button has loaded.`)
  }

  moneyButton.render(document.getElementById('my-button'), {
    to: "1040",
    amount: "0.01",
    currency: "USD",
    onLoad: myCustomCallback
  })
</script>

editable

When this attribute is true the button is displayed in an editable mode, allowing the user to set the amount of the transaction before pay. When this attribute is set to true the values of to, amount, currency and outputs are ignored. Editable buttons are able to have OP_RETURN using the attribute opReturn.

disabled

When this attribute is true the button is displayed in a disabled mode where it cannot be swiped.

devMode

This attribute is false by default. If it is set to true the button becomes a dummy component. It doesn't execute any callback and doesn't interact with the backend at all. Instead it always succeeds.

preserveOrder

Money Button sorts inputs and outputs following BIP 69 in order to improve privacy. By sorting inputs and outputs this way, the change address cannot be distinguished from the rest of the outputs, making it harder for third-parties to track funds. Other inputs and outputs also have less identifiable information associated with them. This is a valuable feature to improve privacy.

However, sorting input and output order can be problematic for some applications that require fixing the order n a particular way. To support these applications, the preserveOrder property is available to fix the order of inputs and outputs.

If preserveOrder is set to true, the transaction will have outputs in the same order as they appear in the outputs property, and BIP 69 will not be used. Additionally, the change output will always appear last.

Note that this property should only ever be used if it is a requirement for the application because it decreases the privacy of transactions.

Also note that sometimes one payment output, such as to a paymail, can actually correspond to more than one output in the transaction. Thus fixing the order does not actually fix the number. Paymail outputs can be more than one output because the paymail recipient may desire to have their payment received at multiple outputs.