A Merchant may request a payment by calling the function PaymentRequest supplied by the BitcoinExpress library. A PaymentDetails JSON parameter determines the payment details.

The payment details object must include at least the following keys:

  • currency: the currency of the payment.
  • amount: price of the item to sold.
  • memo: a short description of the product being sold.
  • issuers: the list of Issuer domains whose Coins the merchant is willing to accept.
  • merchant_data: a reference created and used exclusively by the Merchant to track this payment.
  • payment_url: the location where the Merchant wishes to receive the Payment object containing Coins. When Coins are received, they should be verified at the Merchant's Home Issuer and a PaymentAck returned.

If the payment Coins are acceptable, the PaymentRequest resolves to a PaymentAck, otherwise it is rejected with an error string. The sales page may then use data from the PaymentAck to determine an appropriate next step (e.g. say thank you or link to a new page).

NOTE: the following example calls the /mockPayment Issuer endpoint. This function is provided so that developers may quickly test their payment script before they have a back-end implementation in place.

Payment 0.0000095 XBT


var paymentDetails = {
  currency: "XBT",
  amount: 0.0000095,
  memo: "The art of asking",
  issuers: ["(*.carrotpay.com)"],
  merchant_data: "sale999264",
  email: {
    contact: "sales@merchant.com",
    receipt: true,
    refund: false
  },
  payment_url: "https://eu.carrotpay.com/Bitcoin-express/v1/issuer/mockPayment"
};

document.getElementById("mock_payment_button").addEventListener('click', function () {
  BitcoinExpress.Wallet.PaymentRequest(paymentDetails).then(function(container) {
    window.location.replace(container.PaymentAck.return_url);
  }).catch(function(err) {
    console.log("PaymentRequest error returned ", err);
  });
});