How to create a limited fiat payment widget via API

General API integration rules

Before starting an integration please check our Get started with API page for more info.

Payment Widget

Payment Widget is a functionality that allows you to create widget, using which your users will be able to pay for your products/services choosing the currency they’re most comfortable with.

The widget indicates the amount to be paid, the available cryptocurrencies and description of payment.

It uses Invoice functionality inside of it and allows you to customize the widget the way you want to use it.

Limited Fiat Payment widget API integration

To accept a single payment for a product with a fixed price when initial price specified in fiat currency you can use Single Fiat Payment Widget. It allows your client to choose the crypto currency he wants to pay you with.

After choosing the crypto currency the invoice will be automatically created for your client to pay.

The invoice is paid in cryptocurrency but the pay amount is being recalculated every 15 minutes according to fiat amount value that you used during widget creation.

Your client may also return back to Payment widget and choose another crypto currency to pay you with.

You can find more information about other features of Public API integration in our documentation: Payment Widget

Create Single Fiat Payment widget

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"
    }
}'

Some additional options:

  • By default the Payment widget is available for 1 day. You can set custom expiration time of Payment widget by transmitting expiration field in request body but the expiration date may only be less than 30 days from the current moment. After this time the Payment widget will be unavailable for payment.
  • You can customize interface of your Payment widget by transmitting return_url, support_url and logo_url fields.

If the creation was successful you 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 send link for payment to your client. Link format: <<widgetUrl>>/pay?widgetKey={idempotencyKey}

Payment widget link view:

Or you can check a real example of payment widget here or watch entire payment flow here.

Tracking payment state

After creating Single Fiat Payment widget you can receive information about it from the system.

  • The best way to do it is by tracking changes in invoices (created from your Payment widget) via Webhooks.
  • Another way is by manually requesting information about Payment widget and its invoices using API

Receive information about your payments via Webhooks

As we mentioned earlier Payment widget automatically creates an invoice after user chooses the currency he wants to pay with. So by tracking the state of created Invoice you can track the state of your payment.

To track the state of your created Invoice you can use Calypso Pay functionality which is called Webhooks.

Webhook is a way for an app to provide other applications with real-time information.
The Webhooks API allows you to subscribe to events happening with your created objects (Invoices or Payouts) in Calypso. Rather than making an API call to check status of invoice or payout during processing, Calypso can send an HTTP request to an endpoint you configure.

More detailed information about Calypso Webhooks functionality: Webhooks

  1. First of all, to receive information about Invoice state change you need to create a subscription for system events which you want to track.

There are several types of events which you need to track in order to understand what is happening to your Invoices.

The main events are:

Event typeDescription
INVOICE_FUNDS_RECEIVED_FOR_INVOICEThe event shows if funds have been received to invoice wallet

More info on Calypso Webhooks event types: Types of events

We’ll look at more scenarios of using Webhooks in the following sections of this guide.

To create a subscription for those events you can use the Create Webhook Public API endpoint: POST <<baseUrl2>>/api/v1/subscription/webhook/create

curl --location --request POST '<<baseUrl2>>/api/v1/subscription/webhook/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE"
    ],
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "url": "Your App URL"
  }
}'

You can subscribe to all types of events if you specify value “INVOICE” in the notificationServiceTypes field instead of enumeration all types of events in notificationEventTypes.

In the response you will get:

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

More info on Webhooks management in Calypso Pay system: Webhook API

  1. After successful creation of subscription for Payment events and providing your client with Payment Widget link you can wait for your client to make payment.

Get data about specific Payment widget and related invoices

To receive information about earlier created Single Fiat Payment widget you can use Get Single Fiat payment widget By ID endpoint (POST <<baseUrl2>>/api/v1/payment-widget/single-fiat/find).

You can request widget by idempotencyKey.

More info on Get Single Fiat payment widget By ID endpoint: Get Single Fiat Payment widget by ID

Example of the request by id:

curl --location --request POST '<<baseUrl2>>/api/v1/payment-widget/single-fiat/find' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "requestId": "daa596e4-623f-4a01-b47d-6159ffada299"
  }
}'

In response you will receive Payment widget data:

  • Response example 
    {
    "idempotencyKey": "daa596e4-623f-4a01-b47d-6159ffada299",
    "cryptoCurrencies": [
        "USDC"
    ],
    "widgetType": "SINGLE_FIAT",
    "widgetState": "IN_PROGRESS",
    "fiatCurrency": "EUR",
    "fiatAmount": 100,
    "description": "Single Fiat Payment Widget example",
    "externalId": "unique_id_111222333",
    "invoices": [
        {
            "invoiceId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
            "cryptoCurrency": "USDC",
            "invoiceIdempotencyKey": "2b3ea2f9-a3c8-4cb6-a9cb-8c2e395cabe6",
            "invoiceExternalId": "unique_id_111222333"
        }
    ],
    "createdDate": "2022-11-17T07:07:39.593284"
}

The most important fields you need to pay attention to:

  • widgetState - represents status of the Payment widget. More info about possible states in documentation: Payment Widget
  • invoices - list of all invoices created by your client using this Payment widget.

You may also request information about every invoice in the list.

To receive information about earlier created Invoice you can use Get a Specific Invoice endpoint (POST <<baseUrl2>>/api/v1/invoice).

You can request invoice by idor idempotencyKey.

More info on Get a Specific Invoice endpoint: Get a specific Invoice

Example of the request by id:

curl --location --request POST '<<baseUrl2>>/api/v1/invoice' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive invoice data:

  • Response example 
    {
    "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
    "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",
    "invoicePayments": [],
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

The most important fields you need to pay attention to:

  • state - represents status of the invoice. More info about possible states in documentation: Limited Invoice
  • totalDebitAmount - received amount of money to this invoice.

Successful Single Fiat invoice payment scenario

If client successfully paid the invoice you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE.

  • The example of webhook payload: 
    {
  "requestId": "e505bbf7-0dcd-4097-b0c7-70372a5c68d3",
  "id": 20282,
  "createdDate": "2022-09-05T07:07:09.456422",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
  "data": {
    "type": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
    "amount": 125.81,
    "message": "invoice for client 1",
    "currency": "USDC",
    "externalId": "unique_id_111222333",
    "fiatAmount": {},
    "createdDate": "2022-09-05T07:03:52.984874",
    "description": "Single Fiat Payment widget example",
    "paymentDate": "2022-09-05T07:07:09.418771",
    "senderAddress": "0xf17366cf1aa135acfe6b2b91aacd3c95610fad12",
    "idempotencyKey": "f24480cb-2e60-4f23-b585-169576370177",
    "transactionHash": "0x0ee4bfbac386849f63cab5f55c99f897ff2be8f13b732bc76c3c44bcfd82dfa2",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

You can understand that the invoice refers to Payment widget that you created earlier by looking at externalId value. It will be the same value that you have set earlier for Payment widget during its creation.

To get detailed information about invoice you can use Get a Specific Invoice endpoint (POST <<baseUrl2>>/api/v1/invoice) using idempotencyKey or parentExternalId (id in request).

You will see changes in the fields:

  • The value of state is PAID.
  • The value of totalDebitAmount is changed to received payment amount.

That means that the money was sent by client and it was successfully received to the invoice address (invoiceAddress field).

After receiving the correct amount of money to the invoice address in Calypso system the money will be automatically credited to the merchant balance.

You may also get detailed information about Payment widget. For that you can use Get Single Fiat payment widget By ID endpoint (POST <<baseUrl2>>/api/v1/payment-widget/single-fiat/find) using idempotencyKey of Payment widget in the request.

You will see changes in the fields:

  • The value of widgetState is COMPLETED

Updated 2 days ago