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)

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

If the creation was successful you receive the response:

curl

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

If the update was successful you receive the response:

curl

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:

Get Customer Purse Address

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

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:

Get Customer Purse Transaction

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

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

If the transaction successfully received, you receive the response:

JSON

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerBlocked": "false",
  "amount": 100,
  "currency": "string",
  "transactionHash": "string",
  "transactionState": "COMPLETED",
  "complianceState": "CHECKED",
  "translationToAccountCompleted": true,
  "createdDate": "2024-10-16T14:12:20.898Z"
}

General API integration rules

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

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)

You can find the detailed description of all the parameters in the documentation: New Single Fiat Invoice

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:

• You can set a specific custom ID to your Invoice by transmitting externalId field in request body. It’s possible to check the status of the invoice by this parameter after creation. Here, for example, you can pass a unique client ID and then use this method Get Invoices by External ID get them all. As well, externalId is returned in all types of events in webhooks, if it is set.

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

See in details: How to embed invoice data to your payment page

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.

More info on Get a Specific Invoice endpoint: Get a specific Invoice

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:

• state - represents the status of the invoice. More info about possible states in documentation: Limited Invoice

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

More detailed information about Calypso Webhooks functionality: Webhooks

1. First of all, to receive information about Invoice state change you need to create a subscription for system events which you want to track.

There are several types of events which you need to track in order to understand what is happening to your Invoices.

The main events are:

More info on Calypso Webhooks event types: Types of events

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

More info on Webhooks management in Calypso Pay system: Webhook API

1. After successful creation of subscription for Payment events and providing your client with Payment 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.

General API integration rules

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

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)

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

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 set a specific custom ID to your Invoice by transmitting externalId field in request body. It’s possible to check the status of the invoice by this parameter after creation. Here, for example, you can pass a unique client ID and then use this method Get Invoices by External ID get them all. As well, externalId is returned in all types of events in webhooks, if it is set.

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

More info on Get a Specific Invoice endpoint: Get a specific Invoice

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.

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

cURL

1. Get invoice data in response

JSON

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

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:

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.

More details about the functions and design of the Payment Widget can be found here .

Following this link you will be able to see and interact with a real payment widget - click here.

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

How to create limited fiat payment widget via API?

How to embed a payment widget on a web page?

And also the API documentation for setting a Payment Widget:

Payment Widget