Integration Guide

General flow

This guide shows the basic steps for connecting Weelay to a merchant website or backend.

Weelay works as a non-custodial checkout for USDT TRC20: the merchant creates an invoice, the buyer pays it on the Weelay checkout page, and the merchant backend receives the payment status through API or webhook.

The secret API key must be stored only on the backend. It must not be placed in frontend code, public JavaScript, a mobile app without a protected backend or a public repository.

What is needed before starting

Before integration, prepare a Weelay account, verified email, project in dashboard, merchant USDT TRC20 wallet address, project secret API key and webhook endpoint if automatic event delivery is needed.

Step 1. Create an account

Register in Weelay and verify your email.

After logging in to the dashboard, you can create projects, API keys, invoices and configure webhook.

Step 2. Create a project

A project connects merchant settings with future invoices.

A project usually contains name, USDT TRC20 wallet address, webhook URL and project status.

The project must be active so the secret API key can be used for Merchant API.

Step 3. Set USDT TRC20 wallet address

Wallet address is the merchant address where buyers will send payment.

Check the address carefully.

Weelay does not hold funds, does not control the wallet and cannot return a payment if the address is wrong.

Step 4. Create a secret API key

Create a secret API key in the project dashboard.

Secret key has the format weelay_secret_....

The full secret key is shown only once at creation. Store it securely on the backend.

Step 5. Configure backend variables

On the merchant backend, it is convenient to store settings in environment variables.

Use base URL https://api.weelay.com/v1.

Store the secret key in a private backend variable such as WEELAY_SECRET_KEY.

Do not store the secret key in frontend code.

Step 6. Check the API key

To check the connection, the backend can call GET /merchant/me.

The request should go to https://api.weelay.com/v1/merchant/me.

The request must include the header Authorization: Bearer weelay_secret_....

If the key is active, the project is active and the user is not blocked, the API returns current merchant context data.

Step 7. Create an invoice

To create an invoice, the merchant backend sends POST /merchant/invoices.

The request should go to https://api.weelay.com/v1/merchant/invoices.

Minimum fields:

• amount — amount as string, for example 10.55;
• order_id — internal merchant order number, optional.

For production integration, it is recommended to send the Idempotency-Key header so a retried request does not create a duplicate invoice.

Step 8. Save the Weelay response

After invoice creation, the merchant backend should save the main response fields:

• id;
• status;
• amount;
• currency;
• order_id;
• payment_url;
• payment_expires_at;
• tx_hash, if it appears later.

The main field for redirecting the buyer is payment_url.

Step 9. Redirect the buyer to payment

After creating the order and invoice, the merchant redirects the buyer to payment_url.

The Weelay checkout page shows amount, currency, network, merchant wallet address, invoice expiration time and payment status.

The buyer sends USDT TRC20 directly to the merchant address.

Step 10. Wait for paid status

After creation, the invoice has status pending.

While the status is pending, the order must not be treated as paid.

After successful payment check, the invoice receives status paid.

The merchant should fulfill the order only after paid.

Step 11. Retrieve invoice status through API

The merchant backend can retrieve one invoice through GET /merchant/invoices/{invoice}.

It can also retrieve invoice list through GET /merchant/invoices.

This is useful for manual review, order synchronization and dispute handling.

Step 12. Configure webhook

Webhook is used so Weelay can automatically send a notification to the merchant backend after an important event.

The current main event is invoice.paid.

When the invoice is paid, Weelay creates webhook delivery and sends a POST request to the project webhook URL.

The merchant backend should accept the webhook, verify the signature, find the order by order_id or invoice id, ensure the event has not been processed yet, mark the order as paid and quickly return a successful HTTP response.

Step 13. Handle webhook idempotently

Webhook may be delivered more than once. This is normal for reliable delivery.

The merchant backend must not issue goods, services or access again if the invoice.paid event was already processed earlier.

Use invoice id, tx_hash or your own order_id to protect against duplicate processing.

Step 14. Handle API errors

The API may return an error if the secret key is missing, secret key is invalid, project is inactive, request data is invalid, limits are exceeded, invoice is not found or an internal error occurs.

Save the trace_id from the response. It is needed for diagnostics and support.

Step 15. Test the full scenario

Before real usage, test the full flow:

1. Create an order in your system.
2. Create an invoice through Weelay API.
3. Open payment_url.
4. Check amount, network and address.
5. Make a test payment.
6. Wait for paid status.
7. Check webhook delivery.
8. Ensure the order is updated once.
9. Ensure repeated webhook does not break the order.
10. Check the error with invalid API key.

Minimal production checklist

Before launch, make sure the secret API key is stored only on the backend, amount is sent as string, order_id is stored by the merchant, Idempotency-Key is used for invoice creation, payment_url is saved in the order, the order is fulfilled only after paid, webhook signature is verified, webhook is handled idempotently, API errors are logged without secret key and trace_id is saved for diagnostics.

Where to go next

After this guide, read Merchant API, Invoices, Invoice Statuses, Idempotency-Key, Webhooks, API Errors and Non-Custodial Payment Notice.