How to create unlimited payment widget

General API integration rules

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

Unlimited Linked Payment widget API integration

To accept an unlimited amount of payments for a product with customer-defined price you can use Unlimited Linked 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.

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 API

Creating an Unlimited Linked Payment widget

To create a new Unlimited Linked Payment widget use the following endpoint: 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

Here we describe the most important ones.

  • cryptoCurrencies - the list of available for payment crypto currencies.
  • description - the description of product/service.
  • 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 to 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/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"
  }
}'

Some additional options:

  • You can customize interface of your Payment widget by transmitting return_url, support_url and logo_url fields.
  • By default the transaction fee for transferring the received money from the invoice address (created by Payment widget) to the merchant’s wallet is debited from merchant’s Hot Wallet address. If you want to use Calypso liquidity for paying the transaction fee you may transmit the value “true” to the parameter useLiquidity.

If the creation was successful you would receive the response:

  • Response example 
    {
    "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"
}

Now after you’ve successfully created Payment widget you can send link for payment to your client. Link format: <<widgetUrl>>/pay?widgetKey={idempotencyKey}

Payment widget link view:

Tracking payment state

After creating Unlimited Linked 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

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

As we mentioned earlier Payment widget automatically creates an invoice after your 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 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 Unlimited Linked Payment widget you can use Get Unlimited Linked payment widget By ID endpoint (POST <<baseUrl2>>/api/v1/payment-widget/unlimited-linked/find)

You can request widget by idempotencyKey.

More info on Get Unlimited Linked payment widget By ID endpoint: Get Unlimited Linked Payment widget by ID

Example of the request by id:

curl --location --request POST '<<baseUrl2>>/api/v1/payment-widget/unlimited-linked/find' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "requestId": "5743852b-c182-4b70-8475-2c714c98fdde"
  }
}'

In response you will receive Payment widget data:

  • Response example 
    {
    "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": [
        {
            "invoiceId": 1729,
            "cryptoCurrency": "USDT",
            "invoiceIdempotencyKey": "79fe57a4-0fd6-4346-abcb-98b9969c2409",
            "invoiceExternalId": "unique_id_12345"
        }
    ],
    "createdDate": "2022-11-17T07:36:14.304911"
}

The most important fields you need to pay attention to:

  • 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": 1
  }
}'

In response you will receive invoice data:

  • Response example 
    {
    "id": 1368,
    "invoiceAddress": "0x1a8201e316e5012cf3608c65b6f9d428ca4544ef",
    "type": "UNLIMITED",
    "totalDebitAmount": 0,
    "currency": "ETH",
    "state": "PENDING_PAYMENT",
    "description": "test1",
    "createdDate": "2022-09-01T16:19:54.350408",
    "idempotencyKey": "4d1d24ba-da67-4324-ba3f-f33b6354ba39",
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

The most important fields you need to pay attention to are:

  • totalDebitAmount - total received amount of money to this invoice.

Successful Unlimited Linked 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": 20294,
  "createdDate": "2022-09-05T07:39:18.929518",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
  "data": {
    "type": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
    "amount": 0.01,
    "message": "unlimited invoice for client 2",
    "currency": "ETH",
    "externalId": "unique_id_12345",
    "fiatAmount": {},
    "createdDate": "2022-09-05T07:14:43.673181",
    "description": "Unlimited Linked Payment widget example",
    "paymentDate": "2022-09-05T07:39:18.904215",
    "senderAddress": "0xf17366cf1aa135acfe6b2b91aacd3c95610fad12",
    "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
    "transactionHash": "0x9c1dda28b45d61d74015166fb7ec0e728f02824917ab3697402e65edb7af44ff",
    "parentExternalId": 1375
  }
}

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, externalId or parentExternalId (id in request).

You will see changes in the fields:

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

That means that the money were sent by client and they were received to invoice wallet address (invoiceAddress field).

After receiving money to invoice wallet address received money amount will be credited to the balance.

Updated 6 months ago