How to create a limited fiat payment widget via API
Last updated
Last updated
Before starting an integration please check our page for more info.
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.
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:
To create a new Payment widget use the following endpoint: Create new Single Fiat payment widget (POST https://api.calypso.finance/api/v1/payment-widget/single-fiat/create)
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:
JSX
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 exampleJSON
Now after you’ve successfully created a Payment widget you can send link for payment to your client. Link format: https://pay.calypso.finance/pay?widgetKey={idempotencyKey}
Payment widget link view:
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
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.
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:
INVOICE_FUNDS_RECEIVED_FOR_INVOICE
The event shows if funds have been received to invoice wallet
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 https://api.calypso.finance/api/v1/subscription/webhook/create
Bash
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:
JSON
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.
To receive information about earlier created Single Fiat Payment widget you can use Get Single Fiat payment widget By ID endpoint (POST https://api.calypso.finance/api/v1/payment-widget/single-fiat/find).
You can request widget by idempotencyKey.
Example of the request by id:
Bash
In response you will receive Payment widget data:
Response exampleJSON
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 https://api.calypso.finance/api/v1/invoice).
You can request invoice by idor idempotencyKey.
Example of the request by id:
Bash
In response you will receive invoice data:
Response exampleJSON
The most important fields you need to pay attention to:
totalDebitAmount - received amount of money to this invoice.
If client successfully paid the invoice you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE.
The example of webhook payload:JSON
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 https://api.calypso.finance/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 https://api.calypso.finance/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
You can find the detailed description of all the parameters in the documentation:
Or you can check a real example of payment widget or watch entire payment flow .
More detailed information about Calypso Webhooks functionality:
More info on Calypso Webhooks event types:
More info on Webhooks management in Calypso Pay system:
More info on Get Single Fiat payment widget By ID endpoint:
widgetState - represents status of the Payment widget. More info about possible states in documentation:
More info on Get a Specific Invoice endpoint:
state - represents status of the invoice. More info about possible states in documentation:
