Transition from Single Invoice to Unlimited Invoice

API General changes

Before moving from Calypso 1.0 to Calypso 2.0 please check our General API changes page for more info.

The difference between Single and Unlimited invoice types

The Single or Single Fiat Invoice represents itself a single payment for a product with a fixed price. So it is a functionality that allows you to receive a fixed amount of funds for your product once.

The 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 when the payment is received on invoice.

So if you want to receive a single payment for your product with a fixed predetermined price you should use:

  • a Single Invoice (if the initial price for the product is determined in cryptocurrency)
  • a Single Fiat Invoce (if the initial price for the product is determined in FIAT currency)

If you want to receive several payments with a customer-defined price you should use:

  • an Unlimited Invoice

Transition from Calypso 1.0 Single and Single Fiat invoice types to Calypso 2.0 Unlimited Invoice

Creating unlimited invoice

The endpoint for Unlimited invoice creation is as follows: New Unlimited Invoice (POST <<baseUrl2>>/api/v1/invoice/unlimited/create)

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

To create invoice without additional options you'll have to send the following 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"
  }
}'

List of new request parameters different from Single or Single Fiat invoice creation:

-

List of unused parameters for an Unlimited invoice type:

  • expiration - the Unlimited Invoice never expires. It can only be archived using the Archive Invoice endpoint.
  • amount - This field is only viable for Single Invoice creation since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • fiatAmount - This field is only viable for Single Fiat Invoice creation since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • fiatCurrency - This field is only viable for Single Invoice creation since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.

List of deprecated parameters:

  • hotWalletAddress - there is no Hot Wallets in Calypso 2.0, there are Accounts instead.
  • upperCommission - has been removed to simplify the invoice creation flow.
  • useLiquidity - the liquidity logic is by default always used in Calypso 2.0 to simplify the user experience.
  • type - you do not need to translate the invoice type inside of the request body. Now you should use different request for each invoice type instead.

If the creation was successful you now receive the response:

  • Response example 
    {
    "id": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
    "invoiceAddress": "0xc7721217b3e919eeb618c5155df278da58521aef",
    "type": "UNLIMITED",
    "fee": 0.000042026017236,
    "amountInInvoiceWallet": 0,
    "totalDebitAmount": 0,
    "currency": "ETH",
    "state": "PENDING_PAYMENT",
    "description": "invoice for client 1",
    "createdDate": "2022-08-25T12:47:28.200475",
    "cartItems": [],
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "expiration": "2022-09-24T12:47:28.171538",
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

List of new response parameters:

  • invoicePayments.serviceFee - the Calypso fee for each invoice transaction is now returned in response.

List of unused response parameters:

  • amount - The payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • payAmount - The payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • expiration - the Unlimited Invoice never expires. It can only be archived using the Archive Invoice endpoint.
  • fiatAmount - This field is only viable for Single Fiat Invoice since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • fiatCurrency - This field is only viable for Single Fiat Invoice since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • lastFiatUpdated - This field is only viable for Single Fiat Invoice since the payment amount for an Unlimited Invoice is determined by the customer directly at the time of payment.
  • interventionType - the need for an intervention may never occur for an Unlimited Invoice since the pay amount is not predetermined.

List of deprecated response parameters:

  • fiat
  • fiatInInvoiceWallet
  • useLiquidity - the liquidity logic is by default always used in Calypso 2.0 to simplify the user experience.
  • Most of invoicePayments data has been deprecated and simplified in Calypso 2.0:
    • invoicePayments.blockchainTransactionFee
    • invoicePayments.feeCurrency
    • invoicePayments.hotWallet
    • invoicePayments.notEnoughFundsForTokenFee
    • invoicePayments.notEnoughFundsForTokenFeeAmount
    • invoicePayments.payAmount
    • invoicePayments.toHotWalletHash
    • invoicePayments.tokenFeeRequestHash
    • invoicePayments.tokenTransactionFee

Tracking invoice state

The number of options to track changes in invoice state did not change from Single or Single Fiat invoice types. You can:

  1. Get invoice data via request by ID.
  2. Set webhooks for invoices

Get data about specific invoice

The endpoint itself differs from Calypso 1.0: Get a Specific Invoice (POST <<baseUrl2>>/api/v1/invoice). Although the requested data remains the same apart from General API changes.

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": "75867d4d-764c-4dd2-94a5-3e07a41c22ea"
  }
}'

In response you will receive invoice data:

{
    "id": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
    "invoiceAddress": "0xc7721217b3e919eeb618c5155df278da58521aef",
    "type": "UNLIMITED",
    "fee": 0.000042026017236,
  	"amountInInvoiceWallet": 0,
    "totalDebitAmount": 0,
    "currency": "ETH",
    "state": "PENDING_PAYMENT",
    "description": "invoice for client 1",
    "createdDate": "2022-08-25T12:47:28.200475",
    "cartItems": [],
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "expiration": "2022-09-24T12:47:28.171538",
    "isInterventionResolved": true,
    "subscriptionEnabled": false
}

The list of changes corresponds to the list of changes in the New Unlimited Invoice response.

Receive information about your payments via Webhooks

The Webhooks API didn't change apart from General API changes.

The main difference in INVOICE_FUNDS_RECEIVED_FOR_INVOICE webhook response type is in the fields you'll need to track.

For Single or Single Fiat Invoices you needed to track changes in the both fields:

  • state - is being changed to PAID at the time of payment.
  • totalDebitAmount - the value is changed to received payment amount.

For an Unlimited Invoice the state field never changes unless you previously archived an invoice using Archive Invoice endpoint.

So you will see changes only in:

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

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

You can find a detailed Webhooks integration guide in Unlimited Invoice integration guide for Calypso 2.0..

Successful Unlimited Invoice payment scenario

The successful Unlimited Invoice payment scenario and other integration info for Calypso 2.0 can be found in Unlimited Invoice integration guide for Calypso 2.0.

Updated 1 day ago