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:

  • payment_url: [String] A URL where payment should be POSTed.
  • currency: [String] The code of the requested currency (e.g. “XBT” for Bitcoin).
  • amount: [number] The decimal amount of the sale. The receiving Wallet may round up the amount if it is convenient to do so and merchants should test for “greater than or equal to”, when testing the amount received.
  • description: [String] A short human readable description of the sale.

In addition, it can contain the following keys:

  • seller: [String] The seller's domain name. This should only be provided when payment Coins are to be sent to a third party url (e.g. a public Merchant Gateway).
  • order_id: [String] Private data for the Merchant's convenience. If present this element will be recorded by the Wallet and echoed in the Payment object. This is intended for the Merchant to keep track of this payment.
  • transaction_id: [String] Private data typically used by a Merchant Gateway (or payment service), to keep track of this specific payment. If present this element will be recorded by the Wallet and echoed in the Payment object.
  • acceptable_issuers: [Array of String] [default "*" ] A list of one or more Issuer domains describing the set of Coins that the Merchant is willing to accept. Domains may be wild-carded using asterisk (i.e. "*" ). For example "*.carrotpay.com" indicates that Coins issued with any sub-domain ending in ".carrotpay.com" will be accepted. All Issuers will be accepted if "*" is used. Alternatively, a Merchant may delegate its Home Issuer to provide the list of acceptable domains by enclosing the Home Issuer's domain in brackets (e.g. [ "(bitex.com)"] ). In this case the Wallet should obtain the acceptable list by calling the Issuer's /info function.
  • email_customer_contact: [String max:255] Indicates which email address may be used should the buyer wish to contact the seller. The Wallet should retain this address for future use by the buyer.
  • created: [Date-time ISO 8601] The time when this payment was created.
  • expires: [Date-time ISO 8601] The time after which a payment for this request should no longer be presented. Perhaps due to time limited offers or to minimise exchange drift. Any payment sent after this time is likely to be rejected.
  • time_budget: [Number] [default 60] The minimum number of seconds that a Wallet should wait before deciding that a call to payment_url has failed.
  • polices: [Object] If present this element will describe certain options that are not strictly part of the basic payment process, but rather may enhance the overall purchase experience or aid in advanced error recovery. The possible object keys are:
    • receipt_via_email: [boolean] If true , the merchant is offering to send a sales receipt by email.
    • refund_via_email: [boolean] If true and when appropriate, the Merchant is offering to send a refund by email.
    • issuer_refund_via_email: [boolean] If true , the merchant is offering to ask its Issuer to directly send a refund by email, upon the occurrence of an exception error.

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 = {
  "fullScreen": false, // start with minimized version of the wallet
  "PaymentRequest": {
    "payment_details_version": "1",
    "PaymentDetails": {
      "acceptable_issuers": ["(be.ap.rmp.net)"],
      "amount": 0.0000095,
      "created": new Date().toISOString(),
      "currency": "XBT",
      "description": "test payment 1",
      "payment_url": "https://be.ap.rmp.net/Bitcoin-express/v1/issuer/mockPayment",
      "transaction_id": "XX11"
    }
  }
}

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