Guides

Limited Fiat Payment Widget changes

API General changes

Before moving from Calypso 1.0 to Calypso 2.0 please check our General API changes page for more info.

Limited Fiat Payment widget API integration changes

Create Single Fiat Payment widget

The endpoint for Limited invoice creation itself differs from v1.0: 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

The request body for Limited Fiat widget has also been changed. Now to create 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"
    }
}'

List of new request parameters:

  • cryptoCurrencies - represents list of cryptocurrencies which Payment Widget supports.

List of deprecated parameters:

  • hotWallets - there is no Hot Wallets in Calypso 2.0, there are Accounts instead.
  • upperCommission - has been removed to simplify the invoice creation flow.
  • useLiquidity - the liquidity logic is by default always used in Calypso 2.0 to simplify the user experience.
  • cartItems

If the creation was successful you now receive the response:

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

List of new response parameters:

-

List of deprecated response parameters:

  • useLiquidity - the liquidity logic is by default always used in Calypso 2.0 to simplify the user experience.
  • cartItems

The Payment Widget link format: <<widgetUrl>>/pay?widgetKey={idempotencyKey} remains the same as in Calypso 1.0

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

The Webhooks API didn't change apart from General API changes.

You can find Webhooks integration guide in Limited Fiat Payment Widget integration guide for Calypso 2.0.

Get data about specific Payment widget and related invoices

The endpoint itself differs from Calypso 1.0: Get Single Fiat payment widget By ID (POST <<baseUrl2>>/api/v1/payment-widget/single-fiat/find). Although the requested data remains the same apart from General API changes.

Example of the request by idempotencyKey:

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 the following Payment Widget data:

{
    "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": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
            "cryptoCurrency": "USDC",
            "invoiceIdempotencyKey": "2b3ea2f9-a3c8-4cb6-a9cb-8c2e395cabe6",
            "invoiceExternalId": "unique_id_111222333"
        }
    ],
    "createdDate": "2022-11-17T07:07:39.593284"
}

The list of changes corresponds to the list of changes in the New Limited Fiat payment widget response.

To receive information about earlier created Invoice you can use Get a Specific Invoice endpoint (POST <<baseUrl2>>/api/v1/invoice). The endpoint itself differs from Calypso 1.0/ Although the requested data remains the same apart from General API changes.

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": "75867d4d-764c-4dd2-94a5-3e07a41c22ea"
  }
}'

In response you will receive invoice data:

{
    "id": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
    "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
}

List of new response parameters:

  • invoicePayments.serviceFee - the Calypso fee for each invoice transaction is now returned in response.

List of deprecated response parameters:

  • hotWallet - there are no more Hot Wallets in Calypso 2.0. Account are used instead.
  • fiat
  • fiatInInvoiceWallet
  • useLiquidity - the liquidity logic is by default always used in Calypso 2.0 to simplify the user experience.
  • payAmount- in Calypso 2.0 this parameter is equal to amount , so, use amount instead.
  • invoicePayments
  • amountInInvoiceWallet
  • cartItems

Successful Limited Fiat Invoice payment scenario

The successful Invoice payment scenario has not changed in its essence. You can find its description in Limited Fiat Payment Widget integration guide for Calypso 2.0.

Updated 7 months ago