Invoice Statuses

General provisions

Invoice status shows what is currently happening with the payment.

The merchant should rely on status, not only on invoice creation or checkout page opening.

An order is considered paid only after the paid status.

Status list

Weelay uses the main statuses:

• pending;
• paid;
• expired;
• failed.

These statuses are returned by the API and used in webhook events.

pending

pending means the invoice was created and is waiting for payment.

This is the initial status of a new invoice.

While the invoice is pending, the merchant must not fulfill the order.

The buyer can open payment_url, see the amount, network, recipient address and make the payment.

What the merchant should do with pending

When status is pending, the merchant should:

• show the checkout page to the buyer;
• wait for status change;
• not issue goods, services or access;
• not treat the order as completed.

If the buyer closed the checkout page, the merchant may show the same payment_url again while the invoice is still valid.

paid

paid means payment was found and the invoice was marked as paid.

This is the main successful status.

After paid, the merchant may fulfill the order.

What the merchant should do with paid

When status is paid, the merchant should:

• mark the order as paid in their system;
• issue goods, services or access;
• save paid_at, if needed for accounting;
• save tx_hash, if it is present in the response;
• not treat a repeated notification as a new payment.

Webhook may be delivered more than once, so paid handling must be idempotent.

expired

expired means the invoice payment time has expired.

After expiration, the buyer should usually create a new invoice or contact the merchant.

Payment after expiration may require manual review.

What the merchant should do with expired

When status is expired, the merchant should:

• not fulfill the order automatically;
• offer the buyer to create a new payment;
• manually review the situation if the buyer says they already paid;
• request tx_hash from the buyer if review is needed.

failed

failed means the invoice cannot be completed successfully in the normal scenario.

This is not a successful payment.

The merchant must not fulfill an order for an invoice with failed status.

What the merchant should do with failed

When status is failed, the merchant should:

• not fulfill the order automatically;
• review the order and payment manually;
• ask the buyer for tx_hash if they claim payment was made;
• create a new invoice if the buyer needs to repeat payment.

When to fulfill the order

The order may be fulfilled only when the status is paid.

Do not fulfill the order with statuses:

• pending;
• expired;
• failed.

Also, do not fulfill the order only because of buyer words, a screenshot or checkout page opening.

Repeated notifications

Webhook or API checks may report an invoice that was already processed.

The merchant system should check whether the order was already marked as paid.

If the order was already processed, a repeated event must not issue goods, services or access again.

Relation to order_id

It is recommended to send order_id when creating an invoice.

This helps the merchant quickly find the related order when receiving status through API or webhook.

order_id connects the merchant internal order and the Weelay invoice.

Relation to tx_hash

tx_hash is useful for payment reconciliation.

If the buyer says they paid but the invoice did not become paid, the merchant may request tx_hash and review the situation.

tx_hash does not replace the paid status.

For automatic order fulfillment, rely on status.

Disputes

If a dispute occurs, check:

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

If the data is not enough, the buyer should provide tx_hash.

Summary

pending — waiting for payment.

paid — payment is confirmed, the order may be fulfilled.

expired — payment time has expired, automatic fulfillment is forbidden.

failed — invoice was not completed successfully, manual review or a new invoice is needed.

Main rule: the order is fulfilled only after paid.