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 <<baseUrl2>>/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 --location --request POST '<<baseUrl2>>/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: <<widgetUrl>>/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:

Get invoice data via request by ID.
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 <<baseUrl2>>/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:

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

In response you will receive invoice data:

Response example

{
    "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 <<baseUrl2>>/api/v1/invoice/deposit-history)

You can request deposits by id or idempotencyKey.

More info on Get all Deposits for the Invoice endpoint: Get all Deposits for the Invoice

Example of the request by id:

curl --location --request POST '<<baseUrl2>>/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:

{
  "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 <<baseUrl2>>/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.

More info on Get Deposit for the Invoice endpoint: Get Deposit for the Invoice

Example of the request by id:

curl --location --request POST '<<baseUrl2>>/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:

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

More detailed information about Calypso Webhooks functionality: Webhooks

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

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

The main events are:

Event type	Description
INVOICE_FUNDS_RECEIVED_FOR_INVOICE	The event shows if funds have been received to invoice wallet
INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED	Funds have been received from invoice wallet to the merchant balance

More info on Calypso Webhooks event types: Types of events

We’ll look at more scenarios of using Webhooks in Successful Unlimited Invoice payment scenario section.

To create a subscription for those events you can use the Create Webhook Public API endpoint: POST <<baseUrl2>>/api/v1/subscription/webhook/create

curl --location --request POST '<<baseUrl2>>/api/v1/subscription/webhook/create' \
--header 'Key: <your_api_key>' \
--header 'Sign: <your_sign>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "timestamp": 13292792792,
  "account": "0xc195df92dd9db2a8f28e597981f113d6e7582f8b",
  "payload": {
    "notificationEventTypes": [
      "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
      "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:

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

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

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:

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

{
  "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 <<baseUrl2>>/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 <<baseUrl2>>/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.