Unlimited Linked 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.

Unlimited Linked Payment widget API integration changes

Create Unlimited Linked Payment widget

The endpoint for Limited invoice creation itself differs from v1.0: Create new Unlimited Linked payment widget (POST <<baseUrl2>>/api/v1/payment-widget/unlimited-linked/create)

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

The request body for Unlimited Linked 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/pub/payment-widget/unlimited-linked/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "cryptoCurrencies": [
      "MATIC",
      "FRAX",
      "USDT",
      "USDT_TRX",
      "ETH",
      "BTC"
    ],
    "description": "Unlimited Linked Payment widget example",
    "idempotencyKey": "5743852b-c182-4b70-8475-2c714c98fdde",
    "externalId": "unique_id_12345"
  }
}'

List of new request parameters:

-

List of deprecated parameters:

  • 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": [
        "BTC",
        "ETH",
        "MATIC",
        "USDT_TRX",
        "USDT",
        "FRAX"
    ],
    "description": "Unlimited Linked Payment widget example",
    "widgetType": "UNLIMITED_LINKED",
    "widgetState": "IN_PROGRESS",
    "externalId": "unique_id_12345",
    "invoices": [],
    "createdDate": "2022-11-17T07:36:14.303687"
}

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.
  • upperCommission - has been removed to simplify the invoice creation flow.
  • 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": 1730,
            "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 Unlimited Linked 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": 1346
  }
}'

In response you will receive invoice data:

{
    "id": 1346,
    "invoiceAddress": "0xc7721217b3e919eeb618c5155df278da58521aef",
    "type": "UNLIMITED_LINKED",
    "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:

  • 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

Funds Withdrawal

The Funds Withdrawal endpoint has been deprecated.

Withdrawal of funds is now performed automatically when you receive funds on any your Unlimited Linked Invoices.

Funds are automatically transferred to account on which Unlimited Linked payment widget has been created.

Successful Unlimited Linked Invoice payment scenario

The successful Invoice payment scenario has not changed in its essence apart from Funds Withdrawal deprecation. You can find its description in Unlimited Linked Payment Widget integration guide for Calypso 2.0.

Updated 6 months ago