How to create a Single fiat invoice payment widget

Process description

To open the payment widget and provide the user with an invoice for payment, you need to do the following:

1

Pass the required and optional parameters to generate a key for the payment widget link for your client - [POST] Payment-widget/single-fiat/create

  • In the response, you will receive a key (UUID) in the "idempotencyKey" parameter, which you need to use in the link to the payment widget.

2

Pass the required key (UUID) from the "idempotencyKey" parameter to the payment widget link, and also use the optional parameters to configure your payment widget.

  • You can also add the "theme" parameter to the widget link and pass the "dark" value to it, your widget will be displayed with a dark theme.

  • You can add the "logo" parameter, "true" or "false" to enable or disable the display of the brand logo on your widget.

3

After opening the widget, the user makes a payment using their chosen payment method or by simply depositing cryptocurrency to the invoice address on the widget. You will then receive the following webhooks depending on the invoice payment status:

  • If a user has overpaid or underpaid on your invoice - INVOICE_PENDING_INTERVENTION (How to automatically process overpayments and underpayments via the API)

  • If the deposit is subject to compliance review - INVOICE_PENDING_COMPLIANCE

  • If the deposit has not passed the compliance check - INVOICE_COMPLIANCE_DECLINED

  • If the payment is successfully completed - INVOICE_PAID

  • If the invoice was not paid within the expiration date/time period - INVOICE_EXPIRED

  • When funds for a paid invoice are transferred to your company account - INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED

After receiving a status change webhook, we recommend checking the reliability of the invoice information via a request - [POST] Payment-widget/single-fiat/find

Invoice statuses

Diagram nodes indicate invoice statuses, arrows indicate processes a successful completion of which transfers an invoice from one status to another.

Status
Description

PENDING_PAYMENT

• A new unpaid invoice. • Client has transferred funds, but the funds has not yet been credited to the account.

MEM_POOL_FOUND

Incoming transaction to invoice wallet is found in blockchain mempool.

PAID

Invoice is paid.

PENDING_INTERVENTION

• Intervention from the merchant is awaited. • Client transferred insufficient amount. • Client has transferred an amount exceeding an invoice amount. • Funds were transferred from different client accounts.

COMPLETED

Funds are transferd to merchant wallet.

ARCHIVED

Invoice is deleted by merchant.

Request and URL examples

Create new Single Fiat Payment widget - [POST] Payment-widget/single-fiat/create

Request:

Body parameters
Type
Field
Description

account

string

required

Merchant account ID. Request will be sent for this account

timestamp

integer

required

Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future

fiatCurrency

string

required

Fiat currency of the widget

fiatAmount

number

required

Amount in fiat currency for invoice created from this payment widget

description

string

required

Description of the payment widget

cryptoCurrencies

string

required

Currency of merchant's wallets where funds will be withdrawn to. The order currencies transmitted to the request will be saved in the interface

logoUrl

string

optional

Link to the logo of merchant which will be shown in the payment widget page. The logo must be in PNG format. Recommended size 24*24 px

returnUrl

string

optional

Link to the web page where client can come back to from payment widget page

supportUrl

string

optional

Link to the merchant support page where client can go to from payment widget page

expiration

string

required

Represents server timestamp of the invoice of the payment widget expiration moment

idempotencyKey

string

optional

The external id in the uuid format that can be generated by user while creating the payment widget

externalId

string

optional

Merchant ID that can be assigned to one or several payment widgets in string format. All invoices created in this payment widget will get the same external id

{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "fiatCurrency": "text",
    "fiatAmount": 1,
    "description": "text",
    "cryptoCurrencies": "text",
    "logoUrl": "text",
    "returnUrl": "text",
    "supportUrl": "text",
    "expiration": "2025-10-23T11:43:27.163Z",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text"
  }
}

Response 200 OK:

{
  "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
  "cryptoCurrencies": "text",
  "widgetType": "SINGLE_FIAT",
  "widgetState": "IN_PROGRESS",
  "fiatCurrency": "text",
  "fiatAmount": 1,
  "description": "text",
  "logoUrl": "text",
  "returnUrl": "text",
  "supportUrl": "text",
  "expiration": "2025-10-23T11:43:27.163Z",
  "externalId": "text",
  "invoices": [
    {
      "invoiceId": "text",
      "cryptoCurrency": "text",
      "invoiceIdempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
      "invoiceExternalId": "text"
    }
  ],
  "createdDate": "2025-10-23T11:43:27.163Z"
}

Single Fiat Payment widget URL

Parameters:

Parameter
Description
Field

widgetKey

A unique identifier received by the merchant via the API to launch the widget.

required

theme

Selecting the widget color configuration dark/light - dark - light The light theme is used by default.

optional

logo

Logo enablement indicator on the widget page. If you've enabled logo display, the Calypsopea logo will be displayed by default. If you submit your logo according to the specified parameters when creating the widget, we'll display it on the widget. - true - false

optional

Widget url example:

https://pay.calypso.finance/pay?widgetKey=ca280558-3250-456c-95fb-397d4b0f172d&logo=true&theme=light

Get Single Fiat Payment widget by ID - [POST] Payment-widget/single-fiat/find

Request:

Body parameters
Type
Field
Description

account

string

required

Merchant account ID. Request will be sent for this account

timestamp

integer

required

Current unix UTC timestamp in milliseconds. Must not be less than 3 minutes in the past and not greater than 3 minutes in the future

requestId

string

required

The external id of the webhook

{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Response 200 OK:

{
  "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
  "cryptoCurrencies": "text",
  "widgetType": "SINGLE_FIAT",
  "widgetState": "IN_PROGRESS",
  "fiatCurrency": "text",
  "fiatAmount": 1,
  "description": "text",
  "logoUrl": "text",
  "returnUrl": "text",
  "supportUrl": "text",
  "expiration": "2025-10-23T11:43:27.163Z",
  "externalId": "text",
  "invoices": [
    {
      "invoiceId": "text",
      "cryptoCurrency": "text",
      "invoiceIdempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
      "invoiceExternalId": "text"
    }
  ],
  "createdDate": "2025-10-23T11:43:27.163Z"
}

PreviousInvoice Payment WidgetNextOnramp

Last updated