General API integration rules

Before starting an integration please check our Get started with API page for more info.

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

To accept a single payment for a product without fixed price you can use bound invoice. Bound Invoice is an instrument that allows you to receive funds for your product.

You can find more information about other features of Public API integration in our documentation: Limited Invoice

Creating single invoice

To create a new Invoice use the following endpoint: New Single Invoice (POST <<baseUrl2>>/api/v1/invoice/bound/create)

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

Here we consider the most important ones.

lowerBorder (required) - minimum amount ro recieve from your client
currency (required) - the crypto currency of payment.
description (required) - the description of product/service.
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.

So 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": {
    "currency": "USDT",
    "lowerBound": 10,
    "description": "test bound fiat 10USD from pg",
    "fiatAvailable": true,
    "returnUrl": "https://arabiskmedia.com/wp-content/uploads/2020/02/success.png"
  }
}'

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.
By default the invoice is available 3hours for TRON base currencies 1day for others . You can set custom expiration time of an invoice by transmitting expiration field in request body but the expiration date may only be less than 1 day from the current moment. After this time the invoice will be unavailable for payment.
You can customise interface of your invoice by transmitting returnUrl, supportUrl and logoUrl fields.

If the creation was successful you receive the response:

Response example

{
    "id": "4c27250d-0b9a-4cf5-8644-2f8cd9132691",
    "invoiceAddress": "0x9da67114ac789bedc554575b2c0de81d1d398eef",
    "type": "BOUND",
    "fee": 0,
    "totalDebitAmount": 0,
    "currency": "USDT",
    "state": "PENDING_PAYMENT",
    "description": "test bound fiat 10USD from pg",
    "createdDate": "2024-07-08T09:25:45.938992167",
    "idempotencyKey": "b4b1d098-643f-444c-9567-fd0fb7f2cbcd",
    "expiration": "2024-07-09T09:25:45.896590228",
    "isInterventionResolved": true,
    "subscriptionEnabled": false,
    "returnUrl": "https://arabiskmedia.com/wp-content/uploads/2020/02/success.png",
    "lowerBound": 10,
    "fiatAvailable": false
}

To complete the payment the client must pay the amount of money from amount field to address specified in invoiceAddress field.

Tracking 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": "4c27250d-0b9a-4cf5-8644-2f8cd9132691",
    "invoiceAddress": "0x9da67114ac789bedc554575b2c0de81d1d398eef",
    "type": "BOUND",
    "fee": 0,
    "totalDebitAmount": 0,
    "currency": "USDT",
    "state": "PENDING_PAYMENT",
    "description": "test bound fiat 10USD from pg",
    "createdDate": "2024-07-08T09:25:45.938992167",
    "idempotencyKey": "b4b1d098-643f-444c-9567-fd0fb7f2cbcd",
    "expiration": "2024-07-09T09:25:45.896590228",
    "isInterventionResolved": true,
    "subscriptionEnabled": false,
    "returnUrl": "https://arabiskmedia.com/wp-content/uploads/2020/02/success.png",
    "lowerBound": 10,
    "fiatAvailable": false
}

The most important fields you need to pay attention to:

state - represents status of the invoice. More info about possible states in documentation: Limited Invoice
totalDebitAmount - received amount of money to this invoice.

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_PAID	Invoice successfully paid. All required amount has been received to invoice wallet.
INVOICE_PENDING_INTERVENTION	Invoice has changed state to INVOICE_PENDING_INTERVENTION. Either more or less funds was received to the invoice wallet than required
INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED	Funds have been received from invoice wallet to the merchant balance.
INVOICE_EXPIRED	Invoice has been archived because of expiration

More info on Calypso Webhooks event types: Types of events

We’ll look at more scenarios of using Webhooks in Successful Invoice payment scenario and How to manage interventions via API? sections.

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_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
      "INVOICE_EXPIRED"
    ],
    "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_PAID",
      "INVOICE_PENDING_INTERVENTION",
      "INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED",
      "INVOICE_EXPIRED"
    ],
    "url": "Your App URL",
    "createdDate": "2022-08-22T08:24:00.307535"
}

More info on Webhooks management in Calypso Pay 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 Invoice payment scenario

When money are received to invoice address you will receive webhook with type INVOICE_FUNDS_RECEIVED_FOR_INVOICE. It means that money delivered to invoice but it doesn't inform whether the right amount was received. You can compare amount from the webhook payload on your side or wait for the next webhook.

The example of webhook payload:

{
  "requestId": "535b0c92-32b8-4679-9d9e-56ebda031ff7",
  "id": 16579,
  "createdDate": "2022-08-25T12:54:48.645795",
  "level": "SUCCESS",
  "service": "INVOICE",
  "eventType": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
  "data": {
    "type": "INVOICE_FUNDS_RECEIVED_FOR_INVOICE",
    "amount": 0.001043,
    "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "message": "invoice for client 1",
    "currency": "ETH",
    "externalId": null,
    "fiatAmount": {},
    "createdDate": "2022-08-25T12:47:28.200475",
    "description": "invoice for client 1",
    "paymentDate": "2022-08-25T12:54:48.605098",
    "senderAddress": "0xf127e5b7666f51aa346f374213113298014f5969",
    "idempotencyKey": "1be6a518-6dcd-477d-96af-dd914b1300ce",
    "transactionHash": "0xa76b638428b0702b6d6721f89f4806b9853fae65315dd1f6f34ce71deae0380b",
    "parentExternalId": "d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

If client successfully paid the invoice (he sent the right amount of money) you will receive webhook with type INVOICE_PAID. Receiving this type of webhook guarantees that the invoice was fully paid.

The example of webhook payload:

{
  "id":9677,
  "viewed":false,
  "createdDate":"2023-03-13T11:16:53.274743",
  "level":"INFO","service":"INVOICE",
  "data":{
    "type":"INVOICE_PAID",
    "amount":0.001043,
    "currency":"ETH",
    "realAmount":0.001043,
    "description":"test",
    "idempotencyKey":"1be6a518-6dcd-477d-96af-dd914b1300ce",
    "parentExternalId":"d9732536-acdd-41bd-87c3-ec40aeeb6a37"
  }
}

To avoid errors related to receiving webhooks, it is necessary to request information about the invoice in Calypso Pay after receiving the webhook. To get detailed information about invoice you can use Get a Specific Invoice endpoint (POST <<baseUrl2>>/api/v1/invoice using idempotencyKey, externalId or parentExternalId (id in request).

You will see changes in the fields:

The value of state is PAID.
The value of totalDebitAmount is changed to received payment amount.
The value of fee shows the amount of service fee charged from the deposit amount of the invoice.

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

After receiving the correct amount of money to the invoice address in Calypso system the money will be automatically credited to the merchant 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.

You will see changes in the fields:

The value of state is COMPLETED.

Interventions

For advanced invoice usage scenarios and error handling please check our How to manage interventions via API? page.