Calypso Pay supports the following products:

• Customers this functionality is a convenient and effective tool for managing users and their multi-deposit addresses. With it you can create users and edit information about them. Each user will receive their own multi-deposit address for replenishment with several currencies available within the same blockchain and supported by our service.

• Limited Invoice is a commercial document issued by a merchant to a client relating to a sale transaction. It includes provided products and services, their quantities and agreed costs.

• Unlimited Invoice is an invoice without a fixed amount. Payments to the invoice of this type can be accepted in unlimited quantities for any amount for an unlimited time. Funds are transferred to the hot wallet if necessary.

• Payment Link is a link to a one-time invoice. Payment links can be sent by email, messenger or in any other way.

• Payment Widget is an out of the box solution for accepting crypto currencies from your clients. It is versatile, easy to set up and adjust for you and easy to use for your clients. While being based on our invoice product under the hood, it also gives your client the possibility to choose the currency and different ways to pay - by just copying the needed address, scanning the QR code or connecting via Metamask or Walletconnect in just a few clicks.

• Exchange is the process of exchanging one cryptocurrency for another within the same account.

• Single Payout is a payment of a reward, dividend, insurance compensation, etc. (i.e. you may need to pay dividends to partners).

• Mass payout is a method of paying multiple recipients simultaneously. Since mass payouts are submitted online, they are processed instantly which helps organizations to save time, money and resources.

Do you want to see how our payment products look like?

A real example of our products you can find on the page with implemented payment products.

The entire payment flow of Payment Link, Payment Widget or Embedded Payment Link you can watch on the page with payment flows examples.

All requests must contain the following headers:

Every request must be signed and the sign must be provided to the request header.

Sign — POST data (in the same format in which you want to send) encrypted with method HMAC-SHA512 using secret key and the result object is converted to a HEX string.

The body is the request body string (in all cases this is JSON stringified request params object).

All the requests should also include the obligatory POST parameter timestamp with current unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past and not greater than 3 minutes in the future.

After registering your company in Calypso, you will gain access to your company's personal account.

Sandbox mode

For newly registered companies, we offer a test mode that allows you to get acquainted with the functionality of our service using live funds, within the established limits.

In test mode you will have access to:

• Top-ups

• Invoices

• Customer wallets

• Exchange

• Payouts

Please note that in the test mode, a limit is set on the withdrawal of funds from the personal account. This is done to ensure security and control over processes at the initial stage of working with our service.

Limits

For new companies, the withdrawal limit is set at 1000 USDT.

The image shows the scale of withdrawal limits, shown below the list of our services:

Request full access

To use the full functionality of Сalypso, you need to get full access to the product, for this you need to click on the "Request full access" button and fill in your contact information for communication. Our managers will contact you for further cooperation.

The "Request full access" button is on the scale with limits in the picture below:

After clicking the button, a form will appear to fill in your contact information:

The table below shows the full list of blockchains and currencies available on Calypso Pay. We're constantly adding new ones, so please check this page from time to time to be up to date.

You can generate API keys directly within the Calypso Pay interface. Simply navigate to the Integration section, where you can monitor the status of your keys and create new ones as needed. With API keys, you gain seamless access to Calypso Pay's functionality, enabling smoother integration with your existing systems and applications.

To create a new key, click on the "Generate API key" button and assign a name to your key. Please note that at this stage, both the public and secret keys will be displayed. They will only be shown at this point, so be sure to store them in a secure location.

Calypso Pay - is a crypto and fiat processing platform that lets merchants receive payments in crypto or fiat from their clients and pay their partners and workers almost instantly with minimal commissions.

Users can create invoices and use the payment widget to accept payments or charge subscriptions with advanced analytics on top.

Calypso Pay even provides a dedicated management module for crypto treasuries to cover their specific needs.

The Calypso API is a powerful tool that provides programmatic access to a wide range of cryptocurrency payment services. The API is built on top of a robust infrastructure and utilizes state-of-the-art security measures to ensure the safe and secure transfer of sensitive financial data.

The API provides a simple and secure way for merchants to accept and make payments in multiple cryptocurrencies such as Bitcoin, Ethereum, Tron and more.

Calypso API provides powerful and flexible access to cryptocurrency payment functionality. With this API, developers can quickly and easily build custom crypto-based financial applications that meet the specific needs of their business or projects.

You can use this API to access Calypso API endpoints, which can give you access to our products.

The base URL with access to the Calypso API looks like this: https://api.calypso.finance

Welcome to Calypso Pay, the premier crypto processing platform that is revolutionizing the way merchants and businesses handle their cryptocurrency transactions. Calypso Pay allows merchants to easily receive payments in a variety of cryptocurrency options, and make instant payments to partners and workers with minimal commission fees. This platform is designed to provide a seamless and user-friendly experience for all users, whether you are new to the world of cryptocurrency or a seasoned pro.

With Calypso Pay, you have access to a wide range of powerful tools and features to manage your transactions. You can create invoices, use a payment widget to accept payments, subscriptions, and access advanced analytics to track your transactions in real-time. Additionally, you can make payments and mass payments in various types of cryptocurrency, and even exchange one crypto token for another, all in one place.

In this section you will find all actual ENUM's used in Calypso API.

Currency

All possible crypto currencies:

All possible fiat currencies:

Blockchain

Invoice state

Invoice type

Payment widget type

Payment widget state

Payout state

Payout withdrawal state

Withdrawal error state

notificationServiceTypes

sort

To add an extra layer of security to your financial operations, you may want to use the system of multiple signatures for the payouts. In short - it will require more than one user to successfully create a payout.

There are two available roles for this action - payout user and payout manager. The first one can only create a payout, and will need a signature from a user with payout manager role to proceed with the transaction. At the same time payout manager can create a payout himself, but will need another payout manager to sign it. Therefore there will always be needed at least 2 people to make a payout - but maybe more, the system is flexible and can be adjusted to your needs.

This functionality applies both to single and mass payouts. At the moment it only applies to payouts created from UI and is not used in API.

To set the number of needed confirmations for your account and get more details - please contact our support.

Below you can find an instruction on how to assign needed roles to the members of your team.

1. Navigate to the individual teammate settings page

1. Open "Advanced options" dropdown menu and choose the roles you want to assign.

1. Go to the assets tab and click the "top-up" button or 3 vertical dots on the right side of the chosen currency.

1. Select "Top-up with your own crypto"

1. Select currency if you need

2. You will see the blockchain address for the deposit. The address can be copied or you can easily use the QR code.

The speed of replenishment of the wallet depends on the selected currency and also on which network was used. Be sure to check the wallet address, the amount of funds, and the network through which the transaction is made before sending.

In order to separate the space for different projects or for your convenience, you can create additional accounts.

They will use different identifiers and keys for API requests authentication.

Just click in the upper left corner and enter a name for your new account.

Setting up payout confirmations for your company account allows you to increase security and introduce additional control over these transactions.

To set up the payout confirmations, you need to navigate to the settings.

After that, go to the "Security" section, where you can enable the standard number of confirmations, which is 1, or set an additional number of confirmations for withdrawals from your account.

Example when confirmations are disabled:

Example when the standard number of confirmations equal to 1 is enabled:

Example of setting an additional number of confirmations:

If there is a situation when you want to change the address you use for top-ups of your assets, you can easily do it through our UI. To do it please choose in your left menu "Assets", choose the individual asset you need and on the page of the individual asset page in the right corner there is a three-dot menu, where you can choose an option to change your top-up address.

How to add a new asset to account

Manual is under development

To add a new asset you just need to follow a few easy steps.

1. In the left part of your account, click on the assets tab

2. Click on "Add new asset" or on the plus icon in the upper right corner

1. Choose the currency as well as the desired blockchain network

1. After you click on "Add a new asset", a new currency will be displayed in the lists and you can use it for further deposits or payments

Webhooks are a mechanism that allows your web application to automatically receive notifications about events happening in other applications or systems. They are particularly useful for integrating different services and automating processes.

To create a webhook, navigate to the "Integration" section and switch to "Webhooks".

Then follow the simple creation process provided by the interface:

Enter the URL for the webhook.

Subscribe to the types of events you wish to receive notifications for.

Be sure to save the webhook keys.

The interface provides an option to test the webhook's functionality.

However, webhooks can also pose certain risks, such as the potential for malicious actors to use them for attacks on your system. Therefore, it's important to prioritize security and use reliable authentication and authorization methods when working with webhooks.

To make the payments more convenient and safer you can save the needed addresses and use them when you make a payout.

To start using the address book, click on your profile icon in the top right corner and choose "Settings".

On the settings page click the tab "Address Management".

There you will see the list of the existing addresses in the order book, and you may add the new addresses as well.

Once the address added to the book, you will be able to choose it when creating a payout.

Also you will be able to see the name of the recipient in the payout info and the name o the sender in the top-up info - if these addresses are in the address book.

You can take advantage of lower transaction costs by transferring funds to clients who are also Calypso Pay users.

To easily identify whether a user is registered with Calypso Pay, you can add their address to your address book within the platform. This streamlined process ensures seamless transactions between Calypso Pay users.

If a Calypso logo appears next to the address upon addition, it signifies that this address is a Calypso Pay client. This feature simplifies the process of identifying Calypso Pay users, ensuring efficient and secure transactions within the platform.

To initiate a transfer, navigate to the "Payout" section. Choose the payout type and enter the amount you wish to transfer.

Enter the description and select the recipient from your address book. A distinctive banner will indicate that you're transferring funds to another Calypso Pay user, ensuring a seamless and secure transaction experience.

Is there a minimal sum with which an invoice can be created?

We recommend to not set the invoice amount below 10 USD equivalent in chosen currency

Do the invoices have expiration?

By default an invoice will expire in 1 day after its creation. When creating an invoice you can set a custom expiration date

What happens if money is deposited on an invoice after it expires? Including the situation when the transaction has already been initiated but is taking long?

The invoice will be in state "ARCHIVED". Our system doesn't monitor these addresses after the invoice is moved to that state, so the merchant won't be able to know about the deposits. It can be checked only manually, and money from that address can be withdrawn only manually by our team as well.

Can the merchant check the actual sum that was deposited to the invoice address?

Yes, at the moment you can do it via UI - on any invoice card you can click "More info" and you will see more information about the given invoice, including the field "Money received" - the amount deposited to the invoice address and "Invoice wallet balance" - the actual balance on the invoice address at the moment.

Can you change the language to be used on the invoice payment page(the one that the end client sees)?

At the moment it is done automatically based on the client's browser language.

How long does it take for invoice to be processed? (From client's funds being deposited to the invoice address till the callback on successful invoice completion)

Approximate time on the whole invoice processing depends on the blockchain:

Polygon, Tron, BSC, Doge - around 5 min

Ethereum - up to 10 min

Bitcoin takes longer - up to several hours.

By creating an invoice and sending it for payment to your client, the funds get to your wallet. This is convenient when you want to issue an invoice to pay for a product or service. Please follow several steps to create it from your account.

1. Go to the "Invoices" tab and click "Create invoice" or select the "Top-up" button from the "Assets" tab and select "Get funds from a customer".

1. Select the currency in which the invoice will be created. The number of currency options depends on which assets you have added to your account

1. Choose the correct payment information. Specify the amount to pay the invoice in cryptocurrency. To specify the amount in fiat, check the box next to "Invoice in fiat". Also, you can create an invoice without fixed payment amount using the "Without amount" slider.

1. Select the life duration of the invoice. Use our presets or select a desired custom one. If the funds have not been received during the lifetime of the invoice, it will switch to the Archived status.

1. If you need you can specify "External ID". It's not mandatory but it can be helpful if you need to compare the identification of invoices in an external service or program.

1. "Description" is a required field. As the name implies, it is used for convenience and to understand the purpose of the invoice. Please keep in mind that the client will see this text when they make payment

1. After creating an invoice, you will be taken to a page with general information about it

1. You can send the invoice manually by copying the link from the previous paragraph or send it to your client by email

At the moment the language of the invoice is based on the client's browser language.

Then you can check all your created invoices, their status, and other information in the "Invoices" tab. Using status filters or the search field you can easily find the invoice that you need.

Select the invoice you need and in the next window, you can find additional information about the invoice like status lifetime changes.

Currency auto-conversion is a feature that automatically converts all incoming payments from your clients into stablecoins, thereby mitigating volatility.

To set up the auto-conversion process, you need to navigate to the settings.

Afterward, proceed to the Currency Auto Conversion section, allowing you to specify the currencies you wish to convert into the desired final currency.

When the toggle is enabled, all incoming payments will automatically convert into the currency you've selected. This allows your users to deposit funds using various methods, while all funds on your account will accumulate solely in the chosen currency.

In this scenario, all incoming payments from your clients in BTC currency will automatically convert to USDT (ETH or TRX).

You can always disable currency auto-conversion by simply toggling it off.

Payouts are used to send funds to other wallets or create payments to customers. In this article, we will tell you how to create a single Payout.

1. First, go to the "Payouts" tab and click on the "Create a payout" button.

1. Select "Single payout" and specify an amount that you want to transfer.

1. You can send payment instantly or select the later date for the payment. Use our presets or select a desired custom one.

1. "Description" is a required field. As the name implies, it is used for convenience and to understand the purpose of the payment. Please note that it is only shown internally and not displayed to the receiver of the payment.

1. Add a new wallet address and save it to presets or chose one from previously saved.

1. After creating a payout, you will be taken to a page with general information about it

Then you can check all your created payments, their status, and other information in the "Payments" tab. Using status filters or additional filters you can easily find the payout that you need.

Select the payment you need and in the next window, you can find additional information about payment like transaction hash, customer address, and status lifetime changes.

Exchanges are used to swap one asset in your account for another asset.

1. First, go to the "Crypto to Crypto" tab, you will be go to the exchange page.

1. Select the asset "You sell" from the list of available ones.

1. Select the asset "You buy" from the list of available ones.

1. Enter the amount of the asset in the "You sell" field, or by clicking the MAX button the field will be filled with the maximum available amount of this asset on your account. In the form below you can see the calculation for your exchange.

1. If several minutes have passed since you selected the assets, you can update the exchange rate data to correctly display the amounts before the exchange in the calculation form by clicking on the "Update" button.

Below we see an example where the amounts changed after the update because the exchange rate changed during this time.

1. Click to "Exchange".

1. You go to the exchange confirmation page, where you see the exchange calculation and also have the opportunity to update the calculation data by clicking the "Update" button. Next step click to the "Confirm" button.

1. To go to the exchange page and the list of your exchanges, click "Done", if you click on the "Go to Assets" button, you will be taken to the page with assets.

1. On the exchange page in the list you will see the new exchange that you created appear, while the exchange is being processed you will see the status "In progress".

When the exchange is completed you will see the status "Completed"

Payouts are used to send funds to other wallets or create payments to customers. In this article, we will tell you how to create a single Payout.

1. First, go to the "Payouts" tab and click on the "Create a payout" button.

1. Select "Mass payout" and specify the currency you want to use.

1. Please read about additional limits and restrictions on mass payouts.

• You can’t create more than 100 transactions within one mass payment.

• All transactions must be in the same currency.

• If you want to create less than 5 payouts, use regular payouts, it will be cheaper.

• The speed of transaction execution depends on the blockchain, transactions in the network will be executed sequentially one after another. You can learn more about blockchain.

2. Upload your CSV file.

1. Check provided information, payment amount, and fees. If validation is not successful, fix errors and upload the correct CSV file.

1. Your payout has been created and now you can check the state of its transactions.

Where is the payout shown if there was not enough funds to make it?

Page Payouts → In Progress

Is there any limit on number of transactions in mass payouts?

• ETH 1000

• Tokens on ETH 1000

• BTC 100

• DOGE 100

• TRON 100

Approved payout is being processed for very long time, is there any problem?

In most cases there are no issues with the payouts, but there can be several reasons for slower processing:

1. You have set too low blockchain fee

2. The network is congested at the moment and all the transactions are taking longer

3. There have been other transactions from that address and they haven't been finished yet - transactions are processed following the order

What is the transaction speed in payout creation menu?

It is the sum that the user wants to spend on the network fee for that transaction. The higher the sum is - the faster the transaction will be processed and vice versa.

Can you cancel the payout?

The created payout can be cancelled only before it gets approved by all the responsible supervisors. If all the approvals were given and the payout has been created it is impossible to cancel or alter it as if the transaction has been translated to the blockchain it becomes immutable.

You can easily get detailed reports on your transactions in Calypso Pay.

In the left side menu choose Reporting and you will get to the menu where you can choose the type of report - Incoming, Outgoing or exchange transactions.

Once you choose the type of the report you need, you will get to the next page where you will be able to choose the dates, timezone and currencies you wish to include in the report:

When you choose everything and click "Create report" you will be able to choose the preferred format of the report - .csv or .docx

Just click the needed format and the report will be automatically downloaded.

Incoming transactions report

Outgoing transactions report

Exchange reports

Create a customer

To create a new customer use the following endpoint: customer (**POST** https://api.calypso.finance/api/v1/customer-purse/customer/create)

You can find the detailed description of all the parameters in the documentation:

Create a customer

Here we consider the most important ones.

To create a new user, you need to pass this parameter in the request:

• account (required) - your product/service account id.

• timestamp (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

• payload (required) - Request data for creating a new Customer

  • email

  • description

So to create new customer you just have to send request:

curl

curl --request POST \
     --url https://api.calypso.finance/api/v1/customer-purse/customer/create \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "email": "string",
    "description": "string"
  }
}

If the creation was successful you receive the response:

curl

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "description": "string",
  "blocked": false
}

Update a customer

To update a customer use the following endpoint: customer (**POST** https://api.calypso.finance/api/v1/customer-purse/customer/update)

You can find the detailed description of all the parameters in the documentation:

Here we consider the most important ones.

To create a new user, you need to pass this parameter in the request:

• account (required) - your product/service account id.

• timestamp (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

• payload (required) - Request data for creating a new Customer

  • id (required) - Customer ID

  • email

  • description

So to update customer you just have to send request:

curl

curl --request POST \
     --url https://api.calypso.finance/api/v1/customer-purse/customer/update \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "string",
    "description": "string"
  }
}
'

If the update was successful you receive the response:

curl

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "email": "string",
  "description": "string",
  "blocked": false
}

Signing requests

First of all to use Calypso Public API you’ll need to contact Technical Support to generate a new pair of API keys (public and secret keys):

secret key example:
b823a6b9ea72408583cef9ec8d67fa52
public key example:
c529e14832b34b74972365cf7bf02430

API keys are used for authorization in requests to the Calypso API. After receiving API keys from our Technical Support team you can start sending requests to Calypso Public API.

All requests must contain the following headers:

Sign — POST data (in the same format in which you want to send) encrypted with the method HMAC-SHA512 using secret key and the result object is converted to a HEX string.

The body is the request body string (in all cases this is JSON stringified request params object).

All the requests should also include the obligatory POST parameter timestamp with current unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past and not greater than 3 minutes in the future.

To create the sign:

1. Build the body of the request with correct timestamp

2. Encrypt the request body with method HMAC-SHA512 using the body as a message and the secret key as a key.

3. Convert bytes to string of hexadecimal digits.

Examples of sign building:

• Javascript

  JSX

  Copy

  const crypto = require("crypto-js");
  
  signature = function (body, secretKey) {
          return crypto.HmacSHA512(body, secretKey).toString(crypto.enc.hex);
      };

• Python

  Python

  Copy

  import hmac
  import hashlib
  
  def signature(body, secret_key):
      return hmac.new(secret_key.encode(), body.encode(), hashlib.sha512).hexdigest()

Example of api keys, body and correct sign for request:

Python

api_key = 'c529e14832b34b74972365cf7bf02430'
secret_key = 'b823a6b9ea72408583cef9ec8d67fa52'

data = '{"timestamp":1}'
sign = 'b16e9d45f49f2069becbc4f108b237bee588cfc353fe9501df103e692acbc68d482a10d34c12bea22fedde7e28e1b8e57a6a0a373b0e9a27c5257bd8b36e13b9'

Examples of timestamp building:

• Javascript

JavaScript

var timestamp = new Date().getTime();

• Python

Python

import time

timestamp = round(time.time() * 1000)

Getting information about a new deposit

When Calypso receives information from the blockchain about a new deposit from your customer, you will receive webhooks about the processes and statuses associated with this deposit:

CUSTOMER_PURSE_MEMPOOL_FOUND

• The transaction pending in the mempool.

CUSTOMER_PURSE_PENDING_COMLIANCE

• Transaction under compliance check.

CUSTOMER_PURSE_COMLIANCE_DECLINED

• The transaction failed compliance check.

CUSTOMER_PURSE_FUNDS_RECEIVED_FOR_PURSE

• Transaction received successfully.

After receiving the final successful deposit status, you need to send a request with the transaction ID and get the transaction data.

Get Customer Purse Transaction

To get a transaction data from transactionID, use the following endpoint: customer (POST https://api.calypso.finance/api/v1/customer-purse/transaction/get)

You can find the detailed description of all the parameters in the documentation:

Here we consider the most important ones.

To get transaction data, you need to pass this parameter in the request:

• account (required) - your product/service account id.

• timestamp (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

• payload (required) - Request data for get a deposit address

  • transactionId (required)

So to get a transaction data, you just have to send request:

JSON

If the transaction successfully received, you receive the response:

JSON

Get a deposit address

To get an address for deposits use the following endpoint: customer (POST https://api.calypso.finance/api/v1/customer-purse/address/get)

You can find the detailed description of all the parameters in the documentation:

Here we consider the most important ones.

To get an address for deposits in a specific currency, you need to pass this parameter in the request:

• account (required) - your product/service account id.

• timestamp (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

• payload (required) - Request data for get a deposit address

  • customerId (required)

  • currency (required)

So to get a depost address, you just have to send request:

JSON

curl --request POST \
     --url https://api.calypso.finance/api/v1/customer-purse/address/get \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "currency": "string"
  }
}
'

If the address is successfully given, you receive the response:

JSON

{
  "address": "string"
}

If a deposit address has not received any deposits within 30 days of its receipt, it will expired.

• And you will receive a webhook - CUSTOMER_PURSE_EXPIRED

General API integration rules

Limited Invoice API Integration

An invoice is a document given to the buyer by the seller to collect payment. It includes the cost of the products purchased or services rendered to the buyer as well as lists products/services.

To accept a single payment for a product with a fixed price when price specified in crypto currency you can use single invoice. Single Invoice is an instrument that allows you to receive a fixed amount of funds for your product.

Creating single invoice

To create a new Invoice use the following endpoint: New Single Invoice (POST https://api.calypso.finance/api/v1/invoice/single/create)

Here we consider the most important ones.

• amount (required) - the amount of money merchant want to receive for a product/service.

• currency (required) - the crypto currency of payment.

• description (required) - the description of product/service.

• idempotencyKey - a specific UUID for the payment link which guarantees uniqueness of the request. It’s possible to check the status of the invoice by this parameter after creation.

So to create invoice without additional options you just have to send request:

cURL

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/single/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "amount": 0.001,
    "currency": "ETH",
    "description": "invoice for client 1",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce"
  }
}'

Some additional options:

• By default the invoice is available 3hours for TRON base currencies 1day for others . You can set custom expiration time of an invoice by transmitting expiration field in request body but the expiration date may only be less than 1 day from the current moment. After this time the invoice will be unavailable for payment.

• You can customise interface of your invoice by transmitting returnUrl, supportUrl and logoUrl fields.

If the creation was successful you receive the response:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "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
  }

To complete the payment the client must pay the amount of money from amount field to address specified in invoiceAddress field.

Now after you’ve successfully created Invoice you can send link for payment to your client. Link format: https://pay.calypso.finance/invoice/{idempotencyKey}

Invoice Payment link view

Or you can build your own invoice interface using data from the response.

For example, you can use the following HTML template:

  <div class="invoice">
    <h4 class="fullCurrency">Tether USD (TRC-20)</h4>
    <h4 class="rate"><span class="amount">1800</span> <span class="currency">USDT</span> = <span class="fiatAmount">1801.1</span> <span class="fiatCurrency">USD</span></h4>
    <p class="amount"><span id="amount">1800</span> <span class="currency">USDT</span></p>
    <button onclick="copyText('amount')">Copy Amount</button>
    <p class="wallet-address" id="wallet-address">TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX</p>
    <button onclick="copyText('wallet-address')">Copy Address</button>
    <br>
    <hr>
    <p>or scan QR code</p>
    <img class="qr-code" src="https://api.qrserver.com/v1/create-qr-code/?data=TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX&size=150x150"
      alt="QR Code">
  </div>
  <script>
    function copyText(elementId) {
      var copyText = document.getElementById(elementId);
      var textArea = document.createElement("textarea");
      textArea.value = copyText.innerText;
      document.body.appendChild(textArea);
      textArea.select();
      document.execCommand("copy");
      textArea.remove();
    }
  </script>

Tracking invoice state

After creating Invoice you can receive information about it from the system. There are two options to track changes in invoice state:

1. Get invoice data via request by ID.

2. Set webhooks for invoices

Get data about specific invoice

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 id, externalId or idempotencyKey.

Example of the request by id:

Bash

curl --location --request POST 'https://api.calypso.finance/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": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive invoice data:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "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
  }

The most important fields you need to pay attention to:

• totalDebitAmount - received amount of money to this invoice.

Receive information about your payments via Webhooks

To track state of your created Invoice you can use Calypso Payment 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.

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:

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

curl --location --request POST 'https://api.calypso.finance/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",
      "INVOICE_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "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:

JSON

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
      "INVOICE_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

1. After successful creation of subscription for Payment events and providing your client with Payment Link you can wait for your client to make payment.

Successful Invoice payment scenario

When money are received to invoice address you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE. It means that money delivered to invoice but it doesn't inform whether the right amount was received. You can compare amount from the webhook payload on your side or wait for the next webhook.

• The example of webhook payload:

JSON

{
  "requestId": "535b0c92-32b8-4679-9d9e-56ebda031ff7",
  "id": 16579,
  "createdDate": "2022-08-25T12:54:48.645795",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
  "data": {
    "type": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
    "amount": 0.001043,
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "invoice for client 1",
    "currency": "ETH",
    "externalId": null,
    "fiatAmount": {},
    "createdDate": "2022-08-25T12:47:28.200475",
    "description": "invoice for client 1",
    "paymentDate": "2022-08-25T12:54:48.605098",
    "senderAddress": "0xf127e5b7666f51aa346f374213113298014f5969",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "transactionHash": "0xa76b638428b0702b6d6721f89f4806b9853fae65315dd1f6f34ce71deae0380b",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

If client successfully paid the invoice (he sent the right amount of money) you will receive webhook with type INVOICE_PAID. Receiving this type of webhook guarantees that the invoice was fully paid.

• The example of webhook payload:

{
  "id":9677,
  "viewed":false,
  "createdDate":"2023-03-13T11:16:53.274743",
  "level":"INFO","service":"INVOICE",
  "data":{
    "type":"INVOICE_PAID",
    "amount":0.001043,
    "currency":"ETH",
    "realAmount":0.001043,
    "description":"test",
    "idempotencyKey":"1be6a518-6dcd-477d-96af-dd914b1300ce",
    "parentExternalId":"d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

To avoid errors related to receiving webhooks, it is necessary to request information about the invoice in Calypso Pay after receiving the webhook. To get detailed information about invoice you can use Get a Specific Invoice endpoint (POST https://api.calypso.finance/api/v1/invoice using idempotencyKey, externalId 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.

• The value of fee shows the amount of service fee charged from the deposit amount of the invoice.

That means that the money were sent by client and they were received to invoice wallet 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.

When money successfully credited to the balance you will receive webhook with type INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED.

The example of webhook payload:

JSON

{
  "requestId": "e505bbf7-0dcd-4097-b0c7-70372a5c68d3",
  "id": 9974,
  "createdDate": "2022-09-05T07:39:18.929518",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
  "data": {
    "type": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
    "amount": 0.01,
    "message": "unlimited invoice for client 2",
    "currency": "ETH",
    "externalId": "1234",
    "fiatAmount": {
      "EUR": 0.919371150133309,
      "USD": 1.0
    },
    "serviceFee": 0.0001,
    "createdDate": "2022-09-05T07:39:18.929518",
    "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

The most important fields in the event payload:

• parentExternalId - system ID of invoice.

• externalId - custom merchant ID, that could be set when the invoice was created.

• amount - amount of money paid for this invoice.

• serviceFee - service fee for the invoice deposit. This amount will be charged from the deposit amount.

In order to calculate exact amount of money credited to the merchant balance you should deduct serviceFee from amount.

You will see changes in the fields:

• The value of state is COMPLETED.

Interventions

For advanced invoice usage scenarios and error handling please check our How to manage interventions via API? page.

General API integration rules

Limited Fiat Invoice API Integration

To accept a single payment for a product with a fixed price when initial price specified in fiat currency you can use Single Fiat invoice type. Single Fiat Invoice is an instrument that allows you to receive a fixed amount of funds for your product.

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 invoice creation.

You can find more information about other features of Public API integration in our documentation.

Creating Single Fiat Invoice

To create a new Invoice use the following endpoint: New Single Fiat Invoice (POST https://api.calypso.finance/api/v1/invoice/single-fiat/create)

Here we consider the most important ones.

• amount - the amount of money merchant want to receive for a product/service in crypto. Recalculates every 15 minutes from fiatAmount value.

• currency (required) - the crypto currency of payment.

• fiatAmount (required) - the fiat amount of the invoice. The crypto amount is being calculated according to this value.

• fiatCurrency (required) - the fiat currency of the invoice.

• description (required) - the description of product/service.

• idempotencyKey - a specific UUID for the payment link which guarantees uniqueness of the request. It’s possible to check the status of the invoice by this parameter after creation.

So to create an invoice without additional options you just have to send request:

Bash

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/single-fiat/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
        "currency": "USDC",
        "description": "invoice for client 1",
        "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
        "fiatAmount": 1000,
        "fiatCurrency": "EUR"
    }
}'

Some additional options:

• By default the invoice is available 3hours for TRON base currencies 1day for others . You can set custom expiration time of an invoice by transmitting expiration field in request body but the expiration date may only be less than 1 day from the current moment. After this time the invoice will be unavailable for payment.

• You can customise interface of your invoice by transmitting return_url, support_url and logo_url fields.

If the creation was successful you receive the response:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "invoiceAddress": "0xc23670524181205cdddef7a7e471674779b20797",
      "type": "SINGLE_FIAT",
      "totalDebitAmount": 0,
      "amount": 980,
      "currency": "USDC",
      "state": "PENDING_PAYMENT",
      "description": "invoice for client 1",
      "createdDate": "2022-09-05T06:54:41.421731",
      "idempotencyKey": "d7067648-cf1f-4d95-afd1-3f7228992671",
      "expiration": "2022-10-05T06:54:41.421458",
      "fiatAmount": 1000,
      "fiatCurrency": "EUR",
      "isInterventionResolved": true,
      "subscriptionEnabled": false
  }

To complete the payment the client must pay the amount of money from amount field to the address specified in invoiceAddress field.

Now after you’ve successfully created an Invoice you can send link for payment to your client. Link format: https://pay.calypso.finance/invoice/{idempotencyKey}

Invoice Payment link view

The invoice amount for payment will recalculate every time you open the Payment Link according to fiatAmount that you set earlier.

Or you can build your own invoice interface using data from the response.

For example, you can use the following HTML template:

  <div class="invoice">
    <h4 class="fullCurrency">Tether USD (TRC-20)</h4>
    <h4 class="rate"><span class="amount">1800</span> <span class="currency">USDT</span> = <span class="fiatAmount">1801.1</span> <span class="fiatCurrency">USD</span></h4>
    <p class="amount"><span id="amount">1800</span> <span class="currency">USDT</span></p>
    <button onclick="copyText('amount')">Copy Amount</button>
    <p class="wallet-address" id="wallet-address">TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX</p>
    <button onclick="copyText('wallet-address')">Copy Address</button>
    <br>
    <hr>
    <p>or scan QR code</p>
    <img class="qr-code" src="https://api.qrserver.com/v1/create-qr-code/?data=TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX&size=150x150"
      alt="QR Code">
  </div>
  <script>
    function copyText(elementId) {
      var copyText = document.getElementById(elementId);
      var textArea = document.createElement("textarea");
      textArea.value = copyText.innerText;
      document.body.appendChild(textArea);
      textArea.select();
      document.execCommand("copy");
      textArea.remove();
    }
  </script>

Tracking invoice state

After creating Single Fiat Invoice you can receive information about it from the system. There are two options to track changes in invoice state:

1. Get invoice data via request by ID.

2. Set webhooks for invoices

Get data about specific invoice

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 id, externalId or idempotencyKey.

Example of the request by id:

Bash

curl --location --request POST 'https://api.calypso.finance/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": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive invoice data:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "invoiceAddress": "0xc23670524181205cdddef7a7e471674779b20797",
      "type": "SINGLE_FIAT",
      "totalDebitAmount": 0,
    	"amount": 980,
      "currency": "USDC",
      "state": "PENDING_PAYMENT",
      "description": "invoice for client 1",
      "createdDate": "2022-09-05T06:54:41.421731",
      "idempotencyKey": "d7067648-cf1f-4d95-afd1-3f7228992671",
      "expiration": "2022-10-05T06:54:41.421458",
      "fiatAmount": 1000,
      "fiatCurrency": "EUR",
      "isInterventionResolved": true,
      "subscriptionEnabled": false
  }

The most important fields you need to pay attention to:

• totalDebitAmount - received amount of money to this invoice.

Receive information about your payments via Webhooks

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.

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:

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

curl --location --request POST 'https://api.calypso.finance/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",
      "INVOICE_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "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:

JSON

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
      "INVOICE_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

1. After successful creation of subscription for Payment events and providing your client with Payment Link you can wait for your client to make payment.

Successful Single Fiat Invoice payment scenario

When money are received to invoice address you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE. It means that money delivered to invoice but it doesn't inform whether the right amount was received. You can compare amount from the webhook payload on your side or wait for the next webhook.

• The example of webhook payload:

JSON

{
  "requestId": "535b0c92-32b8-4679-9d9e-56ebda031ff7",
  "id": 16579,
  "createdDate": "2022-08-25T12:54:48.645795",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
  "data": {
    "type": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
    "amount": 0.001043,
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "invoice for client 1",
    "currency": "ETH",
    "externalId": null,
    "fiatAmount": {},
    "createdDate": "2022-08-25T12:47:28.200475",
    "description": "invoice for client 1",
    "paymentDate": "2022-08-25T12:54:48.605098",
    "senderAddress": "0xf127e5b7666f51aa346f374213113298014f5969",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "transactionHash": "0xa76b638428b0702b6d6721f89f4806b9853fae65315dd1f6f34ce71deae0380b",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

If client successfully paid the invoice (he sent the right amount of money) you will receive webhook with type INVOICE_PAID. Receiving this type of webhook guarantees that the invoice was fully paid.

• The example of webhook payload:

{
  "id":9677,
  "viewed":false,
  "createdDate":"2023-03-13T11:16:53.274743",
  "level":"INFO","service":"INVOICE",
  "data":{
    "type":"INVOICE_PAID",
    "amount":0.001043,
    "currency":"ETH",
    "realAmount":0.001043,
    "description":"test",
    "idempotencyKey":"1be6a518-6dcd-477d-96af-dd914b1300ce",
    "parentExternalId":"d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

To avoid errors related to receiving webhooks, it is necessary to request information about the invoice in Calypso Pay after receiving the webhook. To get detailed information about invoice you can use Get a Specific Invoice endpoint (POST https://api.calypso.finance/api/v1/invoice using idempotencyKey, externalId 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.

• The value of fee shows the amount of service fee charged from the deposit amount of the invoice.

That means that the money were sent by client and they were received to invoice wallet 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.

When money successfully credited to the balance you will receive webhook with type INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED.

The example of webhook payload:

JSON

{
  "requestId": "e505bbf7-0dcd-4097-b0c7-70372a5c68d3",
  "id": 9974,
  "createdDate": "2022-09-05T07:39:18.929518",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
  "data": {
    "type": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
    "amount": 0.01,
    "message": "unlimited invoice for client 2",
    "currency": "ETH",
    "externalId": "1234",
    "fiatAmount": {
      "EUR": 0.919371150133309,
      "USD": 1.0
    },
    "serviceFee": 0.0001,
    "createdDate": "2022-09-05T07:39:18.929518",
    "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

The most important fields in the event payload:

• parentExternalId - system ID of invoice.

• externalId - custom merchant ID, that could be set when the invoice was created.

• amount - amount of money paid for this invoice.

• serviceFee - service fee for the invoice deposit. This amount will be charged from the deposit amount.

In order to calculate exact amount of money credited to the merchant balance you should deduct serviceFee from amount.

You will see changes in the fields:

• The value of state is COMPLETED.

Interventions

For advanced invoice usage scenarios and error handling please check our How to manage interventions via API? page.

Interventions

This section is only relevant to SINGLE and SINGLE_FIAT invoice types.

There are several scenarios when something can go wrong during your client Invoice payment. Calypso Payment supports following scenarios when you need to intervene into Invoice payment process and manually decide how to proceed.

There are two main types of interventions in Calypso Payment system:

1. Underpay

If client payed less money than required in the Invoice.

1. Overpay

If client payed more money than Invoice requires.

1. To real-time track these scenarios and react to them you can use Calypso Webhook INVOICE_PENDING_INTERVENTION event type.

You can subscribe for this event type using Create Webhook endpoint: POST https://api.calypso.finance/api/v1/subscription/webhook/create

Bash

curl --location --request POST 'https://api.calypso.finance/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_PENDING_INTERVENTION"
    ],
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "url": "Your App URL"
  }
}'

After creating a Webhook for INVOICE_PENDING_INTERVENTION event you’ll start receiving incoming requests of a following format in case of an event appearing:

JSON

{
  "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
  "id": 3,
  "createdDate": "2022-06-17T12:13:05.909616",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_PENDING_INTERVENTION",
  "data": {
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
    "message": "Invoice example",
    "type": "INVOICE_PENDING_INTERVENTION",
    "idempotencyKey": "5b0ca8da-6af4-4a1c-9efd-5cbfc19ace09"
  }
}

1. In case of receiving an incoming request about pending intervention you’ll need to use Get a Specific Invoice endpoint in order to receive detailed information about Invoice and understand your next steps: Get a Specific Invoice (POST https://api.calypso.finance/api/v1/invoice)

You will see changes in the fields:

• The value of state is PENDING_INTERVENTION

• The value of interventionType is either OVERPAY or UNDERPAY depending on received amount of money bigger or lower than amount.

• The value of isInterventionResolved is false.

To resolve this intervention you can withdraw the money to the merchant’s wallet by sending Resolve intervention and receive money to the wallet request (POST https://api.calypso.finance/api/v1/invoice/return-to-paid).

The invoice state changes to PAID and invoice will be completed then.

After invoice became COMPLETED you can mark that intervention was resolved with the client by sending Mark that intervention is resolved in invoice request (POST https://api.calypso.finance/api/v1/invoice/close-intervention).

This request changes the value of field isInterventionResolved to “true”.

Introduction

If you already have a checkout page in your application it's can be useful to embed invoice data to checkout page with all needed for client payment data. Embedding invoice data on your checkout page can provide several benefits for your business and your customers:

• By including all the necessary information for payment on one page, it makes the process of making a payment in cryptocurrency more streamlined and efficient.

• Customers will not need to leave your website to complete their payment and this can increase payment conversion.

• Additionally, it can also improve the overall user experience by making the payment process more user-friendly and intuitive.

We also have some detailed guides on how to create and track limited fiat invoices via API:

Limited Fiat invoice - the amount to pay is issued in fiat currency but converted to crypto currency at current exchange rate.

For detailed information about managing invoices read these guides first. Here we will go through the general flow.

Steps to embed invoice

To embed Calypso invoice data to your web page, you can follow these steps:

1. Place the HTML code in your web page's code, wherever you want the invoice to appear:

HTML

  <div class="invoice">
    <h4 class="full-currency">Tether USD (TRC-20)</h4>
    <h4 class="rate"><span class="amount">1800</span> <span class="currency">USDT</span> = <span class="fiat-amount">1801.1</span> <span class="fiat-currency">USD</span></h4>
    <p><span class="amount" id="amount">1800</span> <span class="currency">USDT</span></p>
    <button onclick="copyText('amount')">Copy Amount</button>
    <p class="wallet-address" id="wallet-address">TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX</p>
    <button onclick="copyText('wallet-address')">Copy Address</button>
    <br>
    <hr>
    <p>or scan QR code</p>
    <img class="qr-code" src="https://api.qrserver.com/v1/create-qr-code/?data=TEoZ53apYcxrJspfCCb7PGh5CJKMiRrAMX&size=150x150"
      alt="QR Code">
  </div>

cURL

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "timestamp": 13292792792,
    "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
    "payload": {
        "type": "SINGLE_FIAT",
        "currency": "USDC",
        "description": "invoice for client 1",
        "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
        "fiatAmount": 1000,
        "fiatCurrency": "EUR"
    }
}'

1. Get invoice data in response

JSON

{
    "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
    "invoiceAddress": "0xc23670524181205cdddef7a7e471674779b20797",
    "type": "SINGLE_FIAT",
    "totalDebitAmount": 0,
    "amount": 980,
    "currency": "USDC",
    "state": "PENDING_PAYMENT",
    "description": "invoice for client 1",
    "createdDate": "2022-09-05T06:54:41.421731",
    "idempotencyKey": "d7067648-cf1f-4d95-afd1-3f7228992671",
    "expiration": "2022-10-05T06:54:41.421458",
    "fiatAmount": 1000,
    "fiatCurrency": "EUR",
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

1. Replace the placeholder data within the code (such as the currency, amount, and wallet address) with the actual invoice data that you receive in response:

1. If you have a CSS file in your web page, you can add the CSS styles for the HTML code.

2. Add the copyText() function to your Javascript file and make sure it is correctly referenced in the HTML code.

HTML

  <script>
    function copyText(elementId) {
      var copyText = document.getElementById(elementId);
      var textArea = document.createElement("textarea");
      textArea.value = copyText.innerText;
      document.body.appendChild(textArea);
      textArea.select();
      document.execCommand("copy");
      textArea.remove();
    }
  </script>

1. Test the invoice on your web page, to make sure that it looks good and that all the data is correct. Your ready invoice form with CSS styles can be looked like this:

General API integration rules

Unlimited Invoice API Integration

An invoice is a document given to the buyer by the seller to collect payment. It includes the cost of the products purchased or services rendered to the buyer as well as lists products/services.

Unlimited Invoice is an invoice without a fixed pay amount. Payments to the invoice of this type can be accepted in unlimited quantities for any amount for an unlimited time. Funds are transferred to the merchant account automatically. It can be archived by merchant or after 3 months automatically if no deposit is received during this period.

You can find more information about other features of Public API integration in our documentation.

Restrictions and limits

Calypso charges a one-time commission for creating any unlimited invoice. Further, only a percentage will be charged from any deposits to the invoice.

Important: there are no minimum and maximum replenishment amounts.

Creating an Unlimited Invoice

To create a new Unlimited Invoice use the following endpoint: New Invoice (POST https://api.calypso.finance/api/v1/invoice/unlimited/create)

Here we consider the most important ones.

• currency (required) - the crypto currency of payment.

• idempotencyKey - a specific UUID for the payment link which guarantees uniqueness of the request. It’s possible to check the status of the invoice by this parameter after creation. As well, externalId is returned in all types of events in webhooks.

• description (required) - the description of product/service.

So to create an invoice without additional options you just have to send request:

cURL

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/unlimited/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "currency": "ETH",
    "description": "invoice for client 1",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce"
  }
}'

Some additional options:

• You can customise interface of your invoice by transmitting return_url, support_url and logo_url fields.

In order to create a mapping between merchant's clients and invoices on the Calypso Pay side, you can use 2 ways: 1 - pass the client ID to the externalId 2 - on the merchant's side, create mapping between the client ID and idempotencyKey on the Calypso Pay side (the most optimal way, since it will be possible to immediately request all extended information using idempotencyKey).

If the creation was successful you would receive the response:

• Response example

To complete the payment the client must pay any amount of money to the address specified in invoiceAddress field. The client may create as many payments as he needs while invoice is not expired.

Now after you’ve successfully created Invoice you can send link for payment to your client. Link format: https://pay.calypso.finance/invoice/{idempotencyKey}

Invoice Payment link view

Or you can build your own invoice interface using data from the response.

Tracking Unlimited Invoice state

After creating Invoice you can receive information about it from the system. There are two options to track changes in invoice state:

1. Get invoice data via request by ID.

2. Set webhooks for invoices

Get data about specific invoice

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 id, externalId or idempotencyKey.

Example of the request by id:

Bash

curl --location --request POST 'https://api.calypso.finance/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": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive invoice data:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "invoiceAddress": "0x1a8201e316e5012cf3608c65b6f9d428ca4544ef",
      "type": "UNLIMITED",
      "totalDebitAmount": 0,
      "currency": "ETH",
      "state": "PENDING_PAYMENT",
      "description": "invoice for client 1",
      "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:

• state - the status of invoice processing. There are 2 possible states for unlimited invoices: PENDING_PAYMENT и ARCHIVED. PENDING_PAYMENT - invoice is active, it can accept deposits. ARCHIVED - invoice is archived, deposits can not be accepted.

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

Get data about deposits

Also you can get detailed information about deposit.

Get all deposits

To receive information about all deposits for invoice you can use Get all Deposits for the Invoice endpoint (POST https://api.calypso.finance/api/v1/invoice/deposit-history)

You can request deposits by id or idempotencyKey.

Example of the request by id:

cURL

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/deposit-history' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive deposit data:

JSON

{
  "result": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 0.01,
      "currency": "ETH",
      "transactionHash": "0x10c2eba81f0acc458a5c02c40ef709ede784240f0f5701e5cbb4454e30c7f3a1",
      "createdDate": "2023-04-03T13:34:57.783Z"
    },
    {
      "id": "9d71b4c3-b158-489e-ac96-5a73a90c423c",
      "amount": 0.01,
      "currency": "ETH",
      "transactionHash": "0x9c6d1f02e042a08c9f5cef9a0af7a9bc8f6ceac9152f37cd2ee9fec442703060",
      "createdDate": "2023-04-02T13:34:57.783Z"
    },
  ],
  "page": 1,
  "size": 10,
  "total": 1,
  "totalElements": 2
}

Get specific deposit

If you want to get information about specific or last deposit you can use Get Deposit for the Invoice endpoint (POST https://api.calypso.finance/api/v1/invoice/deposit)

In the payload of the event INVOICE_FUNDS_RECEIVED_FOR_INVOICE there is the field transactionId which can be used in this request. In addition, you have to specify the invoice for which deposit is requested by passing parameters id or idempotencyKey of the invoice.

Example of the request by id:

cURL

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/deposit-history' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}'

In response you will receive deposit data:

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": 0.01,
  "currency": "ETH",
  "transactionHash": "0x10c2eba81f0acc458a5c02c40ef709ede784240f0f5701e5cbb4454e30c7f3a1",
  "createdDate": "2023-04-03T13:31:53.601Z"
}

Receive information about your payments via Webhooks

To track state of your created Invoice you can use Calypso Payment 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.

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:

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

curl --location --request POST 'https://api.calypso.finance/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",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "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:

JSON

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

After successful creation of subscription for Payment events and providing your client with Payment Link you can wait for your client to make payment.

Successful Unlimited Invoice payment scenario

If client paid the invoice you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE.

• The example of webhook payload:JSON

  Copy

  {
    "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,
      "transactionIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ],
      "message": "unlimited invoice for client 2",
      "currency": "ETH",
      "externalId": "1234",
      "fiatAmount": {},
      "createdDate": "2022-09-05T07:14:43.673181",
      "description": "unlimited invoice for client 2",
      "paymentDate": "2022-09-05T07:39:18.904215",
      "senderAddress": "0xf17366cf1aa135acfe6b2b91aacd3c95610fad12",
      "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
      "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
    }
  }

The most important fields in the event payload:

• parentExternalId - system ID of invoice.

• externalId - custom merchant ID, that could be set when the invoice was created.

• amount - amount of money paid for this invoice.

• transactionIds - system IDs of deposits.

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.

When money successfully credited to the balance you will receive webhook with type INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED.

The example of webhook payload:

JSON

{
  "requestId": "e505bbf7-0dcd-4097-b0c7-70372a5c68d3",
  "id": 9974,
  "createdDate": "2022-09-05T07:39:18.929518",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
  "data": {
    "type": "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
    "amount": 0.01,
    "message": "unlimited invoice for client 2",
    "currency": "ETH",
    "externalId": "1234",
    "fiatAmount": {
      "EUR": 0.919371150133309,
      "USD": 1.0
    },
    "serviceFee": 0.0001,
    "createdDate": "2022-09-05T07:39:18.929518",
    "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

The most important fields in the event payload:

• parentExternalId - system ID of invoice.

• externalId - custom merchant ID, that could be set when the invoice was created.

• amount - amount of money paid for this invoice.

• serviceFee - service fee for the invoice deposit. This amount will be charged from the deposit amount.

In order to calculate exact amount of money credited to the merchant balance you should deduct serviceFee from amount.

To avoid errors related to receiving webhooks, it is necessary to request information about the incoming transaction in Calypso Pay after receiving the webhook. You can request additional information about this particular deposit by transactionId using Get Deposit for the Invoice endpoint (POST https://api.calypso.finance/api/v1/invoice/deposit).

In the scenario with an unlimited invoice, there are no interventions, the amount of replenishment is not important. It is important to understand that the money that gets on the unlimited invoice is not moved to the available balance instantly. First, INVOICE_FUNDS_RECEIVED_FOR_INVOICE webhook event will be received, then after crediting funds to the balance INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED will be received. The system guarantees that the money will be transferred from the invoice wallet to the account balance (in negative scenarios, a delay may be due to our fault, but the funds will be given). It follows from this that at the moment when the funds have arrived on the invoice balance, the merchant can already fully verify the transfer of funds from the client on his side.

Converting amount in crypto currency to amount in fiat currency

At the moment when the merchant synchronizes a new deposit in his system you can use Get exchange rate endpoint (POST https://api.calypso.finance/api/v1/rate) to calculate the fiat amount equivalent of the crypto amount of the deposit.

More info on Get exchange rates endpoint: Get exchange rates.

Payment widget is an out of the box solution for accepting crypto currencies from your clients. It is versatile, easy to set up and adjust for you and easy to use for your clients.

While being based on our invoice product under the hood, it also gives your client the possibility to choose the currency and different ways to pay - by just copying the needed address, scanning the QR code or connecting via Metamask or Walletconnect in just a few clicks.

To find detailed instructions on how to install the widget on your site please check the following links:

And also the API documentation for setting a Payment Widget:

General API integration rules

Payment Widget

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.

Limited Fiat Payment widget API integration

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.

Create Single Fiat Payment widget

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:

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

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.

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:

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

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 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:

• widgetState - represents status of the Payment widget. 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.

Successful Single Fiat 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: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

Before creating payouts you will probably want to check whether you have enough funds on your wallets or not.

• In the response you get the following data:JSON

  Copy

  {
    "account": "string",
    "name": "string",
    "ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "balances": [
      {
        "currency": "BTC",
        "amount": 0
      }
    ]
  }

Information by currency is contained in balances field. Here you can find total available balance amount by currency currency.

Before you create an exchange, you may want to check if you have enough assets in your account.

• In the response you get the following data:JSON

  Copy

  {
    "account": "string",
    "name": "string",
    "ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "balances": [
      {
        "currency": "BTC",
        "amount": 0
      }
    ]
  }

Information by currency is contained in balances field. Here you can find total available balance amount by currency currency.

Create exchange

You can find the detailed description of all the parameters in the documentation:

Here we consider the most important ones:

• account - Merchant account ID

• payload - Request for exchange

  • sourceCurrency - You sell currency

  • destinationCurrency - You buy currency

  • amount - Amount of the selling asset.

So, to create an exchange without additional commands, you just need to send a request:

Request

curl --request POST \
     --url https://api.calypso.finance/api/v1/exchange/create \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "sourceCurrency": "string",
    "destinationCurrency": "string",
    "amount": 0
  }
}
'

If the creation was successful you receive the response:

Response 200

{
  "id": 0,
  "account": "string",
  "sourceCurrency": "string",
  "sourceAmount": 0,
  "destinationCurrency": "string",
  "destinationAmount": 0,
  "state": "IN_PROGRESS",
  "createdDate": "2024-08-22T10:48:54.980Z"
}

After that, you will be able to track the status changes until the exchange is completed using the method below.

Get exchange

Here we consider the most important ones:

• account - Merchant account ID

• timestamp - 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

• payload - Request for exchange

  • id - Exchange ID

To get information about the exchange, you need to send a request:

Request

curl --request POST \
     --url https://api.calypso.finance/api/v1/exchange/get \
     --header 'accept: */*' \
     --header 'content-type: application/json' \
     --data '
{
  "account": "string",
  "timestamp": 0,
  "payload": {
    "id": 0
  }
}
'

You receive the response with exchange data and state:

IN PROGRESSCOMPLETEDFAILED

{
  "id": 0,
  "account": "string",
  "sourceCurrency": "string",
  "sourceAmount": 0,
  "destinationCurrency": "string",
  "destinationAmount": 0,
  "state": "IN_PROGRESS",
  "createdDate": "2024-08-22T10:48:54.980Z"
}

You need to check the exchange details until you get the final exchange status.

Introduction

There are two options you can use in Calypso to embed on your web page:

1. Payment widget - if you want to provide possibility to pay by several crypto currencies.

2. Payment link - if you want to provide possibility to pay by particular crypto currency.

First of all you need to create a payment widget or payment link.

How to create payment widget?

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:

Bash

curl --location --request POST 'https://api.calypso.finance/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"
    }
}'

You can customize interface of your Payment widget by transmitting returnUrl, supportUrl and logoUrl fields.

If the creation was successful you will receive the response:

• Response example

  JSON

  Copy

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

Now after you’ve successfully created a Payment widget you can build a link for payment. Link format: https://pay.calypso.finance/pay?widgetKey={idempotencyKey}.

Payment widget view:

How to create payment link?

Here we will consider the simplest example - single payment where the price defined in crypto currency.

To create a payment link you need to create Invoice using the following endpoint: New Invoice (POST https://api.calypso.finance/api/v1/invoice/create)

Here we consider the most important ones.

• amount - the amount of money merchant want to receive for a product/service.

• currency - the crypto currency of payment.

• description - the description of product/service.

• idempotencyKey - a specific UUID for the payment link which guarantees uniqueness of the request. It’s possible to check the status of the invoice by this parameter after creation.

• type - the type of invoice. As we want to create invoice for one fixed payment, we put here “SINGLE”.

So to create invoice without additional options you just have to send request:

Bash

curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/single/create>' \\
--header 'Key: <your_api_key>' \\
--header 'Sign: <your_sign>' \\
--header 'Content-Type: application/json' \\
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "amount": 0.001,
    "currency": "ETH",
    "description": "invoice for client 1",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "type": "SINGLE"
  }
}'

If the creation was successful you receive the response:

• Response example

  JSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "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
  }
  

To complete the payment the client must pay the amount of money from payAmount field to address specified in invoiceAddress field.

Now after you’ve successfully created an invoice you can build a link for payment. Link format: https://pay.calypso.finance/invoice/{idempotencyKey}

Invoice Payment link view:

How embed payment widget / link on a web page using IFrame?

In order to embed payment widget or payment link on your web page you can use html tag <iframe>.

The <iframe> tag specifies an inline frame. An inline frame is used to embed another document within the current HTML document.

Just add this code to your web page replacing url in src attribute by url created by yourself:

HTML

<iframe src="https://pay.calypso.finance/invoice/{idempotencyKey}" width="800" height="800" style="border: none;"></iframe>

Full html code example:

HTML

<html>
<head>
    <title>Pyament button</title>
</head>
<body style="background-color: grey">
<iframe src="https://pay.calypso.finance/invoice/{idempotencyKey}" width="800" height="800" style="border: none;"></iframe>  
</body>

</html>

Specifying attributes width and height you can adjust size of the widget on your page.

Here is the example with attributes width="800" height="800":

Here is the example with attributes width="370" height="600":

You also can customize your widget by specifying logoUrl, supportUrl and returnUrl parameters during creating payment widget or invoice:

General API integration rules

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.

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 https://api.calypso.finance/api/v1/payment-widget/unlimited-linked/create)

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:

Bash

curl --location --request POST 'https://api.calypso.finance/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 exampleJSON

  Copy

  {
      "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: https://pay.calypso.finance/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.

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:

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 https://api.calypso.finance/api/v1/subscription/webhook/create

Bash

curl --location --request POST 'https://api.calypso.finance/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:

JSON

{
    "requestId": "bf9348b7-2c14-46d7-868c-b597852da319",
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

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 https://api.calypso.finance/api/v1/payment-widget/unlimited-linked/find)

You can request widget by idempotencyKey.

Example of the request by id:

Bash

curl --location --request POST 'https://api.calypso.finance/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 exampleJSON

  Copy

  {
      "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": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
              "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 https://api.calypso.finance/api/v1/invoice).

You can request invoice by idor idempotencyKey.

Example of the request by id:

Bash

curl --location --request POST 'https://api.calypso.finance/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": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}'

In response you will receive invoice data:

• Response exampleJSON

  Copy

  {
      "id": "d9732536-acdd-41bd-87c3-ec40aeeb6a37",
      "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:JSON

  Copy

  {
    "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",
      "invoiceAddress": "0xg18966c0yaa175acfe6b2b89kbcd3c95610fad45",
      "idempotencyKey": "9a995722-6dc1-4536-9d0a-8965914b45d3",
      "transactionHash": "0x9c1dda28b45d61d74015166fb7ec0e728f02824917ab3697402e65edb7af44ff",
      "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
    }
  }