Guides

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

Limited Invoice API Integration changes

Creating single invoice

The endpoint for Limited invoice creation itself differs from v1.0: New Single Invoice (POST <<baseUrl2>>/api/v1/invoice/single/create)

You can find the detailed description of all the parameters in the documentation: New Single 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/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"
  }
}'

List of new request parameters:

-

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

If the creation was successful you now receive the response:

{
    "id": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
    "invoiceAddress": "0xc7721217b3e919eeb618c5155df278da58521aef",
    "type": "SINGLE",
    "amount": 0.00101,
    "payAmount": 0.00101,
    "upperCommission": true,
    "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:

-

List of deprecated response parameters:

  • hotWallet - there are no more Hot Wallets in Calypso 2.0. Account are used instead.
  • 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:

  • Response example 
    {
    "id": "75867d4d-764c-4dd2-94a5-3e07a41c22ea",
    "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 list of changes corresponds to the list of changes in the New Single 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 Limited Invoice integration guide for Calypso 2.0.

Successful Invoice payment scenario

The successful Invoice payment scenario has not changed in its essence. You can find its description in Limited Invoice integration guide for Calypso 2.0.

Interventions

The interventions management logic did not change apart from General API changes and request routes.

The Resolve intervention and receive money request now has the following route POST <<baseUrl2>>/api/v1/invoice/return-to-paid

The Mark that intervention is resolved in invoice request now has the following route POST <<baseUrl2>>/api/v1/invoice/close-intervention

For detailed information please check How to manage interventions via API? page.

Updated 7 months ago