Invoices

What an invoice is

An invoice is the main payment entity in Weelay.

An invoice connects a merchant order with a buyer payment in USDT TRC20.

Through an invoice, the merchant receives payment_url, the buyer opens the checkout page and Weelay returns the payment status to the merchant.

An invoice is not a Weelay balance. Funds are sent directly to the merchant wallet address.

When an invoice is created

Usually an invoice is created after the buyer places an order on the merchant website.

The merchant backend sends POST /merchant/invoices, receives invoice data and redirects the buyer to payment_url.

Minimum data for creation

To create an invoice, send amount.

amount is a required positive amount string.

Example: 10.55.

You may also send order_id.

order_id is the internal merchant order number. It helps connect the Weelay invoice with the order in the merchant system.

Why amount must be a string

Money should not be passed as a float.

That is why amount is sent as a string, for example 10.55, not as a number.

This reduces the risk of rounding errors between different systems.

Main invoice fields

The invoice API response contains public fields needed for merchant integration.

Main fields:

• id;
• project_id;
• status;
• amount;
• currency;
• network;
• order_id;
• payment_url;
• payment_expires_at;
• paid_at;
• tx_hash;
• created_at;
• updated_at.

id

id is the public invoice identifier.

It has the inv_... format.

Use this id to retrieve the invoice through API, support the buyer and connect webhook events.

status

status shows the current invoice state.

Main statuses:

• pending — invoice is created and waiting for payment;
• paid — payment was found and confirmed;
• expired — payment time has expired;
• failed — invoice cannot be completed successfully.

The merchant order should be fulfilled only after the status becomes paid.

amount

amount shows the invoice amount.

When creating an invoice, the merchant sends the amount as a string.

The buyer should send the amount shown on the checkout page.

currency and network

Weelay supports payments in USDT TRC20.

In the API response:

• currency — invoice currency;
• network — payment network.

The buyer must send payment through the specified network.

Payment through another network may not be detected automatically.

order_id

order_id is the internal merchant order number.

Weelay does not create order_id for the merchant.

It is recommended to send order_id so the order can be quickly found in the merchant system.

payment_url

payment_url is the Weelay checkout page link.

After creating an invoice, the merchant should show this link to the buyer or redirect the buyer to it.

The checkout page shows amount, network, recipient address, invoice expiration time and payment status.

payment_expires_at

payment_expires_at shows the invoice expiration time.

The buyer should pay the invoice before this time.

If the buyer sends payment after expiration, the situation may require manual review with the merchant.

paid_at

paid_at shows the time when the invoice was marked as paid.

If the invoice is not paid yet, the field is empty.

tx_hash

tx_hash is the blockchain transaction hash if payment was found and linked to the invoice.

This field is useful for payment reconciliation, buyer support and dispute handling.

created_at and updated_at

created_at shows invoice creation time.

updated_at shows the last invoice update time.

Dates are returned in ISO 8601 format.

Create invoice

An invoice is created through POST /merchant/invoices.

Minimal body:

{"amount":"10.55","order_id":"ORDER-1001"}

order_id is optional, but recommended.

Use Idempotency-Key to protect against duplicates.

Retrieve invoice list

Invoice list can be retrieved through GET /merchant/invoices.

Available query parameters:

• status;
• limit;
• page.

This is useful for merchant panels, support, reconciliation and manual order review.

Retrieve one invoice

One invoice can be retrieved through GET /merchant/invoices/{invoice}.

{invoice} must be a public id in the inv_... format.

The merchant can retrieve only an invoice of the current project.

When to fulfill the order

The order is considered paid only after the invoice status becomes paid.

The order must not be fulfilled only because the invoice was created or the buyer opened the checkout page.

pending means payment has not yet been confirmed.

Disputes

In a disputed situation, check:

• id;
• order_id;
• status;
• amount;
• payment_url;
• payment_expires_at;
• paid_at;
• tx_hash.

If the buyer says they paid, ask them to provide tx_hash.

Summary

A Weelay invoice connects a merchant order with a buyer payment in USDT TRC20.

Main integration fields are id, order_id, status, amount, payment_url, payment_expires_at, paid_at and tx_hash.

The order is fulfilled only after the invoice status becomes paid.