# How to create an Unlimited Invoice via API ## General API integration rules Before starting an integration please check our [Get started with API](https://docs.calypso.finance/guides/integration-guides-and-questions/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](https://docs.calypso.finance/api-reference/invoice-api#post-api-v1-invoice-unlimited-create) 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 curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/unlimited/create' \ --header 'Key: ' \ --header '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](https://docs.calypso.finance/api-reference/invoice-api#post-api-v1-invoice-external) 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](https://docs.calypso.finance/api-reference/invoice-api#post-api-v1-invoice) Example of the request by `id`: Bash ```shell curl --location --request POST 'https://api.calypso.finance/api/v1/invoice' \ --header 'Key: ' \ --header '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 ```json { "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`. More info on **Get all Deposits for the Invoice** endpoint: [Get all Deposits for the Invoice](https://docs.calypso.finance/api-reference/invoice-api#post-api-v1-invoice-deposit-history) Example of the request by `id`: cURL ```curl curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/deposit-history' \ --header 'Key: ' \ --header '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 ```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. More info on **Get Deposit for the Invoice** endpoint: [Get Deposit for the Invoice](https://docs.calypso.finance/api-reference/invoice-api#post-api-v1-invoice-deposit) Example of the request by `id`: cURL ```curl curl --location --request POST 'https://api.calypso.finance/api/v1/invoice/deposit-history' \ --header 'Key: ' \ --header '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 ```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. More detailed information about Calypso Webhooks functionality: [Webhooks](https://docs.calypso.finance/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: | 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](https://docs.calypso.finance/webhooks/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 ```shell curl --location --request POST 'https://api.calypso.finance/api/v1/subscription/webhook/create' \ --header 'Key: ' \ --header '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 ```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" } ``` More info on Webhooks management in Calypso Payment system: [Webhook API](https://docs.calypso.finance/api-reference/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:JSON ```json { "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 ```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.