Merchant API

General provisions

Merchant API allows the merchant backend to work with Weelay programmatically: check the current API key, create an invoice, retrieve invoice list and retrieve one invoice.

Base URL:

https://api.weelay.com/v1

Merchant API must be called only from the merchant backend. The secret API key must not be placed in frontend code, public JavaScript, a mobile app without backend protection or a public repository.

Authentication

Merchant API uses the project secret API key.

Each protected request must include the header:

Authorization: Bearer weelay_secret_...

The secret key must start with weelay_secret_.

If the header is missing, the key is invalid, the key is revoked, the project is inactive or the account is inactive, the API returns an error.

Recommended headers

For JSON requests, use:

• Accept: application/json;
• Content-Type: application/json;
• Authorization: Bearer weelay_secret_....

Health endpoint

GET /health

Full URL:

https://api.weelay.com/v1/health

This endpoint checks whether the API responds. Merchant secret key is not required.

Check API key

GET /merchant/me

Full URL:

https://api.weelay.com/v1/merchant/me

This endpoint returns current project and API key data.

Use it to check that the secret API key works and belongs to an active project.

Create invoice

POST /merchant/invoices

Full URL:

https://api.weelay.com/v1/merchant/invoices

Minimal body:

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

Request fields:

• amount — required positive amount string, max 2 decimals;
• order_id — optional string up to 120 characters.

amount must be sent as a string, not a number.

Idempotency-Key

When creating an invoice, it is recommended to send the header:

Idempotency-Key: order-1001

If the merchant backend repeats the request with the same Idempotency-Key, Weelay returns the already created invoice instead of creating a duplicate.

This protects the merchant from duplicate invoice creation after timeout, network error or repeated request.

Create invoice response

On successful invoice creation, API returns status 201.

Main response fields:

• id — public invoice id;
• project_id — public project id;
• status — invoice status;
• amount — amount to pay;
• currency — currency;
• network — payment network;
• order_id — merchant order id, if provided;
• payment_url — checkout page link;
• payment_expires_at — payment expiration time;
• paid_at — payment time, if invoice is paid;
• tx_hash — transaction hash, if payment is found;
• created_at;
• updated_at.

Save id, order_id, payment_url and status in your system.

Invoice list

GET /merchant/invoices

Full URL:

https://api.weelay.com/v1/merchant/invoices

Query parameters:

• status — optional status filter;
• limit — number of records from 1 to 100;
• page — page number.

Example query:

GET /merchant/invoices?status=pending&limit=20&page=1

The response contains invoice list and pagination data.

Retrieve one invoice

GET /merchant/invoices/{invoice}

Full URL:

https://api.weelay.com/v1/merchant/invoices/{invoice}

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

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

Invoice statuses

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 invoice status becomes paid.

Success response format

A successful response contains:

• success;
• message;
• data;
• meta, if additional data exists;
• trace_id.

trace_id is needed for diagnostics and support.

Error response format

An error response contains:

• success;
• message;
• error.code;
• error.details;
• trace_id.

Save trace_id in your logs, but do not log the full secret API key.

Main errors

Possible authentication errors:

• API_KEY_REQUIRED;
• API_KEY_INVALID_FORMAT;
• API_KEY_INVALID;
• API_KEY_REVOKED;
• PROJECT_NOT_ACTIVE;
• ACCOUNT_NOT_ACTIVE.

Possible common errors:

• VALIDATION_ERROR;
• NOT_FOUND;
• METHOD_NOT_ALLOWED;
• RATE_LIMITED;
• INTERNAL_SERVER_ERROR.

Rate limits

Merchant API uses request limits.

If a limit is exceeded, the API returns RATE_LIMITED with status 429.

The merchant should handle this error safely and retry later if this is acceptable for the scenario.

Secret key security

Secret API key must be stored only on the backend.

Do not:

• send the secret key to the browser;
• place the secret key in frontend JavaScript;
• store the secret key in a public repository;
• write the full secret key to logs;
• send the secret key in chats, tickets or screenshots.

If the key is exposed, revoke it in dashboard and create a new one.

Production recommendations

For production integration:

• create invoices only from backend;
• use Idempotency-Key;
• save payment_url;
• connect the invoice with your order through order_id;
• fulfill the order only after paid;
• handle webhook idempotently;
• save error trace_id;
• do not log the secret API key.

Where to go next

After this page, read:

• Integration Guide;
• Invoices;
• Invoice Statuses;
• Idempotency-Key;
• Webhooks;
• API Errors.