Payment Widget

Overview

Calypso provides users with the ability to generate widgets for invoice payment, which can be sent to the client or embedded on any web page. The widget indicates the amount to be paid, the available cryptocurrencies and description of payment. When paying the amount specified in the fiat currency, the exchange rate is fixed for 15 minutes (60 minutes for BTC) from the moment the invoice is created.

There are 2 types of payment widget depending on use case you need:

A single payment for a product with a fixed price. The price customer needs to pay is defined by merchant in fiat currency.
Several payments with a customer-defined price. The customer can pay many times any amount of money for one invoice.

Features:

Payment of an invoice without the need to create it specifically in the system
Allows to specify the payment amount in a fiat currency or to give a posibility to define the payment amount to customer
Exchange rate is fixed for 15 minutes
Flexible parameter setting: the ability to choose a different cryptocurrency, full or reduced frame of widget, add a description
The possibility to pay for one invoice unlimited number of time

How does it work?

There are two possible use cases for payment widget functionality.

Using a static payment widget link:

The merchant specifies the currencies, description, expiration and other options and creates payment widget using Calypso APIs.
The merchant receives payment widget unique idempotencyKey in response and forms a static link using this value. The static link means that client will always be able to open earlier created payment widget to see its state.
A client follows the link and specifies the cryptocurrency he wants to pay with.
The client clicks the button "Proceed to payment".
Clicking the button triggers a call to Calypso Invoice API to create a new invoice.
When the invoice is created, the widget shows to the client a payment page.
The client completes the payment.
The client sees the message that transaction is processing.
Transaction is completed by a network.
The client sees the notification that payment is complete successfully.

The examples of how you can use it in your service to accept different types of payments are provided on the page

How to create and use a payment widget?

To create a static payment widget, there are the following steps to be performed:

Send an API request to create SINGLE_FIAT or UNLIMITED_LINKED payment widget (POST https://api.calypso.finance/api/v1/payment-widget/single-fiat/create or POST https://api.calypso.finance/api/v1/payment-widget/unlimited-linked/create)
Form a payment widget static link for sharing it with client using earlier received idempotency_key in response
Send formed link to the client or embed in the web site.

Example of the create SINGLE_FIAT payment widget request:

{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
        "description": "Single Fiat Payment Widget example",
        "fiatAmount": 100,
        "fiatCurrency": "EUR",
        "cryptoCurrencies": [
          "MATIC",
          "FRAX",
          "USDT",
          "USDT_TRX",
          "ETH",
          "BTC"
        ],
        "idempotencyKey": "5743852b-c182-4b70-8475-2c714c98fdde",
        "externalId": "unique_id_111222333"
    }
}

Example of the create UNLIMITED_LINKED payment widget request:

{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "cryptoCurrencies": [
      "MATIC",
      "FRAX",
      "USDT",
      "USDT_TRX",
      "ETH",
      "BTC"
    ],
    "description": "Unlimited Linked Payment widget example",
    "idempotencyKey": "5743852b-c182-4b70-8475-2c714c98fdde",
    "externalId": "unique_id_12345"
  }
}

To access the widget, a static link is formed. This link allows you to always get access to the widget to see it's current payment state.

The method of link generation is the same for both widget types (SINGLE_FIAT and UNLIMITED_LINKED):

https://pay.calypso.finance/pay?widgetKey={idempotencyKey}

Example of static payment widget embedded in the web site:

<!-- Put this code to the file index.html and open in browser to see how it works -->
<html>
<head>
    <title>Pay</title>
</head>
<body>
    <style>
        .button_1661340660317 {
            display: inline-block !important;
            text-decoration: none !important;
            background-color: #1e37ff !important;
            color: #ffffff !important;
            border: 3px solid #3967ff !important;
            border-radius: 5px !important;
            font-size: 16px !important;
            padding: 17px 50px !important;
            transition: all 1.6s ease !important;
        }
        .button_1661340660317:hover{
            text-decoration: none !important;
            background-color: #8294ff !important;
            color: #ffffff !important;
            border-color: #4e67ff !important;
        }
        </style>
        <a href="https://ui.calypso.finance/pay?widgetKey={*idempotencyKey*}" class="button_1661340660317" target="_blank">
            Pay fix amount in crypto
        </a>
</body>

</html>

Payment widget statuses

Status	Description
IN_PROGRESS	The payment widget has been created and is active
COMPLETED	The invoice created from payment widget has been payed
ARCHIVED	The payment widget has expired and was automatically archived

Diagram nodes indicate subscription statuses, arrows indicate processes of changing payment widget's state.

Quick guide on payment widget type

To summarize, here is a quick guide on what type of payment widget you need to use for your purposes.

If you want to receive a single payment for your product with a fixed predetermined price you'll need to use:

A SINGLE_FIAT payment widget

If you want to receive several payments with a customer-defined price you'll need to use:

An UNLIMITED_LINKED payment widget