How to embed a payment widget on a web page

Introduction

There are two options you can use in Calypso to embed on your web page:

  1. Payment widget - if you want to provide possibility to pay by several crypto currencies.
  2. Payment link - if you want to provide possibility to pay by particular crypto currency.

First of all you need to create a payment widget or payment link.

How to create payment widget?

Detailed guide for payment widget creation is provided on the link: How to create limited fiat payment widget via API and How to create unlimited payment widget. Here we will consider the simplest example.

To create a new Payment widget use the following endpoint: Create new Single Fiat payment widget (POST <<baseUrl2>>/api/v1/payment-widget/single-fiat/create)

You can find the detailed description of all the parameters in the documentation: Create new Single Fiat Payment widget

Here we describe the most important ones.

  • fiatAmount - the amount of fiat money merchant wants to receive for a product/service.
  • fiatCurrency - the fiat currency of future payment. The pay amount in crypto recalculates every 15 minutes after the invoice creation according to this value.
  • description - the description of product/service.
  • cryptoCurrencies - the list of available for payment crypto currencies.
  • idempotencyKey - a specific UUID for the Payment widget link which guarantees uniqueness of the request. It forms the link via client can access the payment widget.
  • externalId - the unique custom ID for your Payment widget and all the future invoices created from it. It allows you to check the status of payment by this parameter after creation.

So to create a payment widget without additional options you just have to send request:

curl --location --request POST '<<baseUrl2>>/api/v1/payment-widget/single-fiat/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "timestamp": 13292792792,
    "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
    "payload": {
        "description": "Single Fiat Payment Widget example",
        "fiatAmount": 100,
        "fiatCurrency": "EUR",
        "cryptoCurrencies": [
          "BTC", "ETH"
        ],
        "idempotencyKey": "5743852b-c182-4b70-8475-2c714c98fdde",
        "externalId": "unique_id_111222333"
    }
}'

You can customize interface of your Payment widget by transmitting returnUrl, supportUrl and logoUrl fields.

If the creation was successful you will receive the response:

  • Response example

    {
    "idempotencyKey": "5743852b-c182-4b70-8475-2c714c98fdde",
    "cryptoCurrencies": [
        "USDC"
    ],
    "widgetType": "SINGLE_FIAT",
    "widgetState": "IN_PROGRESS",
    "fiatCurrency": "EUR",
    "fiatAmount": 100,
    "description": "Single Fiat Payment Widget example",
    "externalId": "unique_id_111222333",
    "invoices": [],
    "createdDate": "2022-11-17T07:07:39.591444"
}

Now after you’ve successfully created a Payment widget you can build a link for payment. Link format: https://pay.calypso.finance/pay?widgetKey={idempotencyKey}.

Payment widget view:

How to create payment link?

Detailed guide for payment link creation is provided on the links:

Here we will consider the simplest example - single payment where the price defined in crypto currency.

To create a payment link you need to create Invoice using the following endpoint: New Invoice (POST <<baseUrl2>>/api/v1/invoice/create)

You can find the detailed description of all the parameters in the documentation: How to create a Limited Invoice via API

Here we consider the most important ones.

  • amount - the amount of money merchant want to receive for a product/service.
  • currency - the crypto currency of payment.
  • description - the description of product/service.
  • idempotencyKey - a specific UUID for the payment link which guarantees uniqueness of the request. It’s possible to check the status of the invoice by this parameter after creation.
  • type - the type of invoice. As we want to create invoice for one fixed payment, we put here “SINGLE”.

So to create invoice without additional options you just have to send request:

curl --location --request POST '<<baseUrl2>>/api/v1/invoice/single/create>' \\
--header 'Key: <your_api_key>' \\
--header 'Sign: <your_sign>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "amount": 0.001,
    "currency": "ETH",
    "description": "invoice for client 1",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "type": "SINGLE"
  }
}'

If the creation was successful you receive the response:

  • Response example

    {
    "id": 1346,
    "invoiceAddress": "0xc7721217b3e919eeb618c5155df278da58521aef",
    "type": "SINGLE",
    "amount": 0.001,
    "fee": 0.000042026017236
    "totalDebitAmount": 0,
    "currency": "ETH",
    "state": "PENDING_PAYMENT",
    "description": "invoice for client 1",
    "createdDate": "2022-08-25T12:47:28.200475",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "expiration": "2022-09-24T12:47:28.171538",
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

To complete the payment the client must pay the amount of money from payAmount field to address specified in invoiceAddress field.

Now after you’ve successfully created an invoice you can build a link for payment. Link format: <<widgetUrl>>/invoice/{idempotencyKey}

Invoice Payment link view:

How embed payment widget / link on a web page using IFrame?

In order to embed payment widget or payment link on your web page you can use html tag <iframe>.

The <iframe> tag specifies an inline frame. An inline frame is used to embed another document within the current HTML document.

Just add this code to your web page replacing url in src attribute by url created by yourself:

<iframe src="<<widgetUrl>>/invoice/{idempotencyKey}" width="800" height="800" style="border: none;"></iframe>

Full html code example:

<html>
<head>
    <title>Pyament button</title>
</head>
<body style="background-color: grey">
<iframe src="<<widgetUrl>>/invoice/{idempotencyKey}" width="800" height="800" style="border: none;"></iframe>  
</body>

</html>

Specifying attributes width and height you can adjust size of the widget on your page.

Here is the example with attributes width="800" height="800":

Here is the example with attributes width="370" height="600":

You also can customize your widget by specifying logoUrl, supportUrl and returnUrl parameters during creating payment widget or invoice:

Updated 6 months ago