Quick start

Use this quick start to create a SINGLE static invoice with Postman and run the fastest webhook smoke test through webhook.site.

This guide is for the first merchant integration test. It helps you check API keys, create a static invoice, get the payment address, and confirm that invoice webhooks can reach your test endpoint.

Open JSON files

Open both JSON files and copy their contents. You will paste each JSON into Postman import in the next step.

File	Description
Calypso Static Invoice Postman Collection	Ready-to-use requests for checking access, creating a SINGLE invoice, and getting invoice status.
Calypso Static Invoice Postman Environment	Environment template with variables for API keys, account, currency, and invoice amount.

Before you start

You need:

• access to Calypso UI;
• a company and account created in Calypso. If you need a separate integration account, use How to create an additional account;
• API keys with Full access for the selected account. Use How to create new API key if the keys are not created yet;
• Postman installed.

API keys are account-scoped. Use keys created for the same account that will receive invoice payments.

1. Prepare API keys

1. Sign in to Calypso UI.
2. Open the required company and account. If needed, create a dedicated account for integration testing by following How to create an additional account.
3. Go to API keys.
4. Create API keys with Full access by following How to create new API key.
5. Save the public key and secret key.

Make sure you are working in the same account that you will pass in the account environment variable.

2. Import JSON into Postman

1. Open Postman.
2. Open the Calypso Static Invoice Postman Collection link from this guide.
3. Copy the full JSON content from the browser page.
4. In Postman, click Import.
5. Select Raw text.
6. Paste the copied collection JSON and confirm the import.
7. Open the Calypso Static Invoice Postman Environment link from this guide.
8. Copy the full JSON content from the browser page.
9. In Postman, click Import again.
10. Select Raw text.
11. Paste the copied environment JSON and confirm the import.
12. Select Calypso Static Invoice Environment as the active environment.

3. Fill environment variables

Set these variables in the imported environment:

Variable	Value
publicApiKey	Public API key from Calypso UI.
secretApiKey	Secret API key from Calypso UI.
account	Account ID that will receive invoice payments.
currency	Example: USDT_TRX.
invoiceAmount	Example: 10.
externalId	Merchant order ID, for example order-100042.

The collection automatically adds timestamp, calculates the Sign header, and saves invoice data from responses.

4. Check API access

Run:

1. 01. Setup / Get current user
2. 01. Setup / Get available currencies

If both requests are successful, the API keys and environment are configured correctly.

5. Set up webhook.site smoke test

Use this step only for the first integration test. Do not use webhook.site as a live webhook endpoint.

1. Open https://webhook.site.
2. Copy the unique URL generated for your session.
3. In Calypso UI, create or update a webhook subscription by following Create a webhook.
4. Use the copied webhook.site URL as the webhook endpoint.
5. Enable invoice webhook events needed for a static invoice test.

Recommended events:

Event	Purpose
INVOICE_CREATE_INVOICE	Invoice was created.
INVOICE_MEM_POOL_FOUND	Optional. Transaction was detected in the blockchain mempool. Can be skipped on fast blockchains.
INVOICE_PENDING_COMPLIANCE	Optional. Transaction was routed to compliance review. Skipped if compliance passes automatically.
INVOICE_COMPLIANCE_DECLINED	Terminal negative compliance result. Do not mark the order as paid.
INVOICE_FUNDS_RECEIVED_FOR_INVOICE	Funds were received on the invoice address.
INVOICE_PENDING_INTERVENTION	Conditional. Merchant action is required, for example underpay or overpay.
INVOICE_PAID	Customer-facing payment is successful.
INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED	Funds were credited to the merchant account balance. Use for reconciliation.
INVOICE_EXPIRED	Invoice expired without successful payment.
INVOICE_FAILED	Invoice processing failed.

6. Create a static invoice

Run:

02. Static invoice / Create SINGLE invoice

The response should contain:

• id
• invoiceAddress
• type = SINGLE
• amount
• currency
• state

The collection saves:

• invoiceId
• invoiceAddress
• invoiceState
• invoiceIdempotencyKey

Show the customer the invoice address, amount, and currency.

7. Receive webhook events

After the customer sends funds, return to webhook.site.

Check:

• request headers;
• JSON body;
• event name;
• invoice ID or idempotency key;
• invoice state;
• external ID, if present.

For the first smoke test, the goal is to confirm that Calypso can send invoice webhooks to the configured endpoint.

8. Verify invoice status through API

Run one of these requests:

• 02. Static invoice / Get invoice by ID
• 02. Static invoice / Get invoice by idempotency key

Use API status verification as a fallback or support tool. In a live integration, webhook events should be the main source of status changes.

9. Go-live notes

Before going live:

• replace webhook.site with your own HTTPS backend endpoint;
• verify webhook signatures if configured;
• process webhook events idempotently;
• return 2xx only after successful processing;
• treat INVOICE_PAID as the customer-facing successful payment event;
• use INVOICE_TRANSLATION_TO_ACCOUNT_COMPLETED for reconciliation;
• do not mark an order as paid after INVOICE_EXPIRED, INVOICE_FAILED, or INVOICE_COMPLIANCE_DECLINED.

Related docs

Document	Link
API Authentication	API Authentication
Create invoice via API	How to create an invoice via API
Invoice webhooks	Invoice webhooks
Create account in UI	How to create an additional account
Create API keys in UI	How to create new API key
Create webhook in UI	Create a webhook