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 3 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.
A single payment with a customer-defined price. The customer inputs the amount he wants to pay.
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 (recommended way):

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.

Using a dynamic payment widget link (not recommended):

The merchant forms the link to create dynamic payment widget link. The dynamic link means that each time the client follows the link a new payment widget will be created with no way to see the state of previous payment.
A client follow the link and specify 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 static payment widget? (recommended)

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://public-gateway.calypso.finance/api/v1/pub/payment-widget/single-fiat/create or POST https://public-gateway.calypso.finance/api/v1/pub/payment-widget/unlimited-linked/create)
Form a payment widget static link for sharing it with client using earlier received idempotencyKey in response
Send formed link to the client or embed in the web site.

Example of the create SINGLE_FIAT payment widget request:

{
  "nonce": 13292792792,
  "request": {
    "description": "Payment Widget №1",
        "fiatAmount": 100,
        "fiatCurrency": "EUR",
        "hotWallets": [
            {
                "address": "reprehenderit ad",
                "cryptoCurrency": "USDC"
            },
            {
                "address": "tempor v",
                "cryptoCurrency": "USDT"
            },
            {
                "address": "tempor v",
                "cryptoCurrency": "USDT_TRX"
            }
        ],
        "upperCommission": true,
        "useLiquidity": false,
        "returnUrl": "https://google.com/",
        "supportUrl": "https://google.com/",
        "idempotencyKey": "e73ed7b1-a941-429e-9d59-315591bfeb68"
  }
}

Example of the create UNLIMITED_LINKED payment widget request:

{
  "nonce": 13292792792,
  "request": {
    "cryptoCurrencies": [
      "MATIC",
      "FRAX",
      "USDT",
      "USDT_TRX",
      "ETH",
      "BTC"
    ],
    "description": "Unlimited Linked Payment Widget 1",
    "upperCommission": true,
    "useLiquidity": false,
    "returnUrl": "https://google.com/",
    "supportUrl": "https://google.com/",
    "idempotencyKey": "3eea9433-d545-479f-95e1-0be86c7c8b59"
  }
}

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://ui.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.

How to create and use a dynamic payment widget? (not recommended)

To create a dynamic 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://public-gateway.calypso.finance/api/v1/pub/reusable-key-service)
Send link with payment widget and configured parameters to the client or embed it to the web-site where the payment is needed.

Example of dynamic 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/payment?currency=EUR&amount=1&description=Pay amount determined by merchant&key=fd441c87-3939-44d0-b0d3-6f7cbceda44c&full=true&btc_wallet=bc1ql3k0gh0ysvyxtfuntvrjmtp4r266s4wpspse67&eth_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe&usdt_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe&usdc_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe&trx_wallet=TYqokfymRRWQLN6J2uvwzf3SCLp5jKcDUe&usdt_trx_wallet=TYqokfymRRWQLN6J2uvwzf3SCLp5jKcDUe&xdg_wallet=DSZnQMhM6p6MrUXfdYY3tMn38nYo5rYM41&dai_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe&frax_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe&busd_eth_wallet=0xf857cf4be74a7b97e8bca24c53507773f60ed5fe" class="button_1661340660317" target="_blank">
            Pay fix amount in crypto
        </a>
</body>

</html>

To access the widget, a link is formed with a certain set of parameters. Depending on the specified parameters you can create different types of payment widget for particular use case you need.

A single payment for a product with a fixed price

https://ui.calypso.finance/payment?currency={fiat_currency}&amount={payment_amount}&description={text}&btcwallet={_btc_address}ðwallet={_eth_address}&usdtwallet={_usdt_address}&trxwallet={_trx_address}&usdttrx_wallet={_usdt_trx_address}&xdgwallet={_xdg_address}&daiwallet={_dai_address}&fraxwallet={_frax_address}&usdcwallet={_usdc_address}&busdeth_wallet={_busd_eth_address}&bnbwallet={_bnb_address}&busdwallet={_busd_address}&maticwallet={_matic_address}&usdtmatic_wallet={_usdt_matic_address}&key={genereted_reusable_key}&full={true_or_false}&idempotencykey={_idempotency_key}&logourl={_logo_logo}&returnurl={_url_to_return_page}&supporturl={_support_url}

A single payment with a customer-defined price

https://ui.calypso.finance/payment?currency={fiat_currency}&description={text}&btcwallet={_btc_address}ðwallet={_eth_address}&usdtwallet={_usdt_address}&trxwallet={_trx_address}&usdttrx_wallet={_usdt_trx_address}&xdgwallet={_xdg_address}&daiwallet={_dai_address}&fraxwallet={_frax_address}&usdcwallet={_usdc_address}&busdeth_wallet={_busd_eth_address}&bnbwallet={_bnb_address}&busdwallet={_busd_address}&maticwallet={_matic_address}&usdtmatic_wallet={_usdt_matic_address}&key={genereted_reusable_key}&full={true_or_false}&idempotencykey={_idempotency_key}&logourl={_logo_logo}&returnurl={_url_to_return_page}&supporturl={_support_url}

Several payments with a customer-defined price

https://ui.calypso.finance/payment?type=unlimited&description={text}&key={genereted_reusable_key}&full={true_or_false}&idempotencykey={_idempotency_key}&logourl={_logo_logo}&returnurl={_url_to_return_page}&supporturl={_support_url}

Depending on the specified parameters you can create different types of payment widget for particular use case you need.

Description of parameters

currency - the currency in which the payment is made. Not obligatory for unlimited payments; string, optional.
amount - the amount for which the payment is made. Don't specify it if you want to give possibility to customer to difine the amount of money he will pay; number, optional.
type - type of payment widget. Default value is "fiat". Set value "unlimited" if you want to create widget for unlimited payments; string, optional.
description - description or comment that is displayed in the widget; string, obligatory.
btc_wallet - the address of the bitcoin wallet to which the funds from the invoice payment will be received. Not obligatory for unlimited payments; string, optional.
eth_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received.Not obligatory for unlimited payments; string, optional.
usdt_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received in USDT. Not obligatory for unlimited payments; string, optional.
trx_wallet - the address of the tron wallet to which the funds from the invoice payment will be received. Not obligatory for unlimited payments; string, optional.
usdt_trx_wallet - the address of the tron wallet to which the funds from the invoice payment will be received in USDT (TRC20). Not obligatory for unlimited payments; string, optional.
xdg_wallet - the address of the doge wallet to which the funds from the invoice payment will be received. Not obligatory for unlimited payments; string, optional.
dai_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received in DAI. Not obligatory for unlimited payments; string, optional.
frax_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received in FRAX. Not obligatory for unlimited payments; string, optional.
usdc_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received in USDT. Not obligatory for unlimited payments; string, optional.
busd_eth_wallet - the address of the ethereum wallet to which the funds from the invoice payment will be received in BUSD (ERC20). Not obligatory for unlimited payments; string, optional.
bnb_wawllet - the address of the binance smart chain wallet to which the funds from the invoice payment will be received. Not obligatory for unlimited payments; string, optional.
busd_wallet - the address of the binance smart chain wallet to which the funds from the invoice payment will be received in BUSD. Not obligatory for unlimited payments; string, optional.
matic_wallet - the address of the polygon wallet to which the funds from the invoice payment will be received. Not obligatory for unlimited payments; string, optional.
usdt_matic_wallet - the address of the polygon wallet to which the funds from the invoice payment will be received in USDT. Not obligatory for unlimited payments; string, optional.
key - a reusable key with a limited validity period, which is generated by the user via the Public API using the api key; string, obligatory.
full - if true, the full version of the widget is displayed, if false, the mini version of the widget is shown; boolean; optional.
idempotencyKey - idempotency key in the uuid4 format, that allows to get created invoice by idempotencyKey field; string, optional.
logo_url - link to the logo of merchant which will be shown in the payment widget. The logo must be in PNG format. Recommended size 100*24 px; string, optional.
return_url - link to the web page where client can come back to from payment widget; string, optional.
support_url - link to the merchant support page where client can go to from payment widget; string, optional.

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 static payment widget (recommended)
A dynamic payment widget with fixed price set of parameters

If you want to receive a single payment for your product with a customer-defined price you'll need to use:

A dynamic payment widget with a customer-defined price set of parameters

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

An UNLIMITED_LINKED static payment widget (recommended)
A dynamic payment widget with several payments & customer-defined price set of parameters