Guides

Unlimited Invoice changes

API General changes

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

Unlimited Invoice API Integration changes

Creating unlimited invoice

The endpoint for an Unlimited invoice creation itself differs from v1.0: 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

The request body for invoice creation has also been changed. Now to create 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"
  }
}'

List of new request parameters:

-

List of deprecated parameters:

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

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

List of new response parameters:

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

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.
  • payAmount- in Calypso 2.0 this parameter is equal to amount , so, use amount instead.
  • invoicePayments
  • amountInInvoiceWallet
  • cartItems

Tracking invoice state

The number of options to track changes in invoice state did not change. 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,
    "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 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.

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

Funds Withdrawal

The Funds Withdrawal endpoint has been deprecated.

Withdrawal of funds is now performed automatically when you receive funds on your Unlimited Invoice.

Funds are automatically transferred to account on which Unlimited Invoice has been created.

Successful Unlimited Invoice payment scenario

The successful Invoice payment scenario has not changed in its essence apart from Funds Withdrawal deprecation. You can find its description in Unlimited Invoice integration guide for Calypso 2.0.

Updated 7 months ago