Simple Button

Creates a simple CoinPayments button which upon clicking creates an invoice for $1.23 USD and renders the button into a <div> on the page.

Note: These samples use client side integration calling the CoinPayments API directly, the createInvoice method can just as well make a call to your server, it just needs to return a Promise<string> that resolves to the CoinPayments invoice id.

CoinPayments.Button({

  //
  // the `createInvoice` method is called when the user presses the
  // Pay with CoinPayments button.
  //

  createInvoice: async function (data, actions) {
    const invoiceId = await actions.invoice.create({
      clientId: "CoinPaymentsDemoClient",
      amount: {
        currencyId: "5057",    // USD
        value: "123"           // $ 1.23 USD  (123 cents)
      },
      requireBuyerNameAndEmail: true,
      buyerDataCollectionMessage: "Your email and name is collected for customer service purposes such as order fulfillment."
    });
    return invoiceId;
  }

  //
  // the button is rendered into a div with id `cps-button-container-1`
  //

}).render("cps-button-container-1");

Try it out

Customized Style

The color and style of the button can be customized by specifying an additional style object. The available colours are white (default), black and blue. Optionally a width can also be specified, if not provided then the button defaults to 225 pixels wide.

CoinPayments.Button({
  style: {
    color: "blue",
    width: 180
  },
  createInvoice: function (data, actions) {
    // ... see above
  }
}).render("cps-button-container-2");

Items and details

Additional details about the invoice can be provided and they'll appear on the checkout screens and your dashboard. See the documentation for a full definition of all the properties accepted by the invoice.create method.

Note: When a breakdown and additional prices are specified they must add up to the invoice total. The subtotal must be the sum of the items amounts and the total the sum of all amounts in the breakdown.

Note: The currencyId can be specified at the level of the invoice, then all monetary amounts are assumed to be in that currency.

{
  clientId: "CoinPaymentsDemoClient",
  currencyId: "5057",   // USD
  items: [
    {
      name: "First test item in the cart",
      description: "this is a description of the first test item",
      quantity: 1,
      amount: "1000"    // $ 10.00 USD
    },
    {
      name: "There are two of these items",
      description: "this is the second item in the shopping cart",
      quantity: 2,
      amount: "1234"    // $ 12.34 USD
    }
  ],
  amount: {
    breakdown: {
      subtotal: "2234", // $ 22.34 USD (items 10.00 + 12.34)
      shipping: "999",  // $ 9.99 USD
      handling: "100",  // $ 1.00 USD
      taxTotal: "500"   // $ 5.00 USD
    },
    value: "3833"       // $ 31.33 USD total
  }
}

Callbacks

Implement the onConfirmed method which is called after the invoice has been paid and the payments confirmed on the blockchain. You'll want to validate the payment here on the server side before completing the order in your system.

Likewise implement the onCancelled method which is called when the invoice payment is cancelled. For example by the user closing the payment window or the invoice expiring before payment is completed.

Note: You can specify the invoiceId and a customData dictionary of strings to store additional data along with the invoice. These can help with correlating and validating the invoice in your system.

Note: You must validate the invoice data on server-side, client-side only validation is NOT safe. For example, in the onConfirmed method make an AJAX call to your backend to verify the invoice server-side. Validate that the invoiceId and amount match the expected values before completing the order on your side.

CoinPayments.Button({

  //
  // you can specify the `invoiceId` and `customData` dictionary of strings to store 
  // along with the invoice so that you can correlate the invoice in your system
  //

  createInvoice: async function (data, actions) {
    const invoiceId = await actions.invoice.create({
      clientId: "CoinPaymentsDemoClient",
      invoiceId: "YOUR_CUSTOM_INVOICE_ID",  // your internal invoice ID
      customData: {
        foo: "bar",
        hello: "world"
      },
      amount: {
        currencyId: "5057",    // USD
        value: "123"           // $ 1.23 USD  (123 cents)
      }
    });
    return invoiceId;
  },
  onConfirmed(data) {
    // called when the invoice is paid and confirmed on the blockchain
    // the payments may not yet have been transferred to your wallets
    alert("Invoice confirmed: " + data.invoiceId);
  },
  onCancelled(data) {
    // called when the invoice is cancelled and can no longer be paid
    // e.g. user closes the payment window or timeout expires
    alert("Invoice cancelled: " + data.invoiceId);
  }
}).render("cps-button-container-4");

Webhooks (IPN)

Webhook Instant Payment Notifications (IPNs) are sent at various stages of an invoices life-cycle. For example when an invoice is created, paid and confirmed on the blockchain.

Webhook notification endpoints can be configured in your merchant dashboard and are implemented as POST requests to those endpoints with a JSON body of the invoice and payment details.

Note: all webhook notifications include a X-CoinPayments-Signature header that contains the HMAC SHA256 hash of the message body signed with your app secret. You MUST verify the signature to ensure that the notification has not been tampered with.

Note: webhook notifications will be retried up to 10 times if your server responds with an error code and may arrive out of order.

infoClick "Pay with CoinPayments"

infoWebhook IPN notifications will show here