Meeg Pay System API (1.3.0)

Token-based authentication is used for endpoints that require authorization.

The server provides a bearer token, which must be included in the Authorization HTTP header:

Authorization: Bearer <YOUR_TOKEN>

The token is obtained after logging in and remains valid until logging out.

Endpoints requiring authorization are intended for backend-to-backend integration only.

Endpoints under the public section do not require authorization and are intended for frontend-to-backend communication.

To receive cryptocurrency payments, a temporary address is generated for each invoice in the selected blockchain network. This address is used exclusively to identify the purpose of incoming payments.

Note: In some blockchain networks (e.g., TON, or when interacting with certain centralized exchanges), a unique address is not generated per invoice. Instead, a shared address is used along with a unique identifier such as a memo, tag, or destination ID to distinguish between payments. Make sure to always display the memo/tag to the user when required, and ensure they include it in the transaction. Failure to do so may result in an untracked or lost payment.

Creating invoices

Invoices can be created in either one-step or multi-step mode, depending on your business logic:

• One-step: Provide the invoice currency and the customer's payment currency/network in a single request.
• Multi-step: First, create the invoice with a currency and amount; then, in a separate request, specify the currency and network the user will use to pay.

Users can only pay invoices using cryptocurrencies that are allowed in the merchant’s settings, which are a subset of all supported tokens and networks.

Once the currency and network are selected, the payable amount is calculated using current exchange rates and fixed for a limited time (see expires_at).

Paying the Invoice

The customer must send funds to the generated pay_address.

• If the payment is less than the required amount, the invoice enters status [2 - Partially Paid] and awaits additional transactions.
• If the payment is equal to or greater, the invoice is marked as paid and:
  • Funds are transferred to the merchant’s wallet, or
  • AML checks are initiated, depending on the merchant's configuration.

⚠️ Important: If the user sends an unsupported token or uses the wrong blockchain network, the transaction will not be recognized as a payment! In some cases, such funds might be forwarded to the merchant’s wallet as unlinked external deposits. In other cases, the transaction may be completely ignored.

💡 Memo/Tag Requirement: For some networks, the pay_address must be accompanied by a memo, tag, or destination ID. This additional identifier is essential to correctly associate the transaction with the invoice. Always ensure the user is instructed to include the memo/tag where applicable.

If the invoice is not paid within a certain time, it will be marked [98 - Cancelled]. Any funds received after cancellation are likely to be lost.

The final status of the invoice is [99 - Successful]. It informs that the funds have been successfully transferred to merchant's wallet.

Invoice lifecycle

[0 New] -> [1 Awaiting payment] -> [2 Partially Paid] -> [3 Paid]
                   |                       |
                   +------ expired --------+--> [98 Cancelled]

[3 Paid] -- AML OFF --> [21 Transfer in progress] ----------------> [99 Successful]
[3 Paid] -- AML ON  --> [11 AML in progress] -> [12 AML finished]
                              low risk  -> [21 Transfer in progress] -> [99 Successful]
                              high risk -> [13 Awaiting AML decision]
                                               approve -> [21 Transfer in progress] -> [99 Successful]
                                               refund  -> [31 Refund in progress] -> [39 Refunded] / [38 Partially Refunded]

When can you treat the invoice as accepted?

Status [3 - Paid] means funds reached the temporary address but the invoice is not yet settled — it still has to be moved to your merchant wallet.

• If AML is disabled for your account (the network/wallet has no AML action), [3 - Paid] is reliable: there is no AML hold and no refund branch in the normal flow, so the invoice is guaranteed to proceed to [99 - Successful]. You may safely accept the order on [3 - Paid] to speed up fulfilment, without waiting for [99 - Successful].
• If AML is enabled, do not rely on [3 - Paid]: the invoice may go through an AML check and can stop at [13 - Awaiting AML decision] or be refunded. Use [21 - Transfer in progress] as the early "accepted" signal instead — it is only reached after the AML check has passed (or you approved a held invoice), so the payment will not be refunded by AML from this point. [99 - Successful] remains the final settlement confirmation, and you may still handle [13 - Awaiting AML decision] explicitly.

⚠️ Withdrawals must be made to addresses on the same network as the source wallet. Sending to incorrect or non-existent addresses may result in permanent loss of funds.

💡 Security Tip: Do not store large balances on merchant wallets. Withdraw funds regularly to secure external wallets.

Withdrawals can be executed in:

• Single-step mode (via skipConfirmation flag)
• Multi-step mode: First, a withdrawal request is created and validated, then confirmed in a second request.

🔐 Request Signature (required)

All withdrawal requests must be signed using the merchant's secret key.

The following HTTP headers are required:

The server will reject requests if:

• Timestamp is too far from current time (±30 seconds)
• Signature is missing or invalid

📋 Parameters to sign

🧮 Signature Algorithm (PHP)

$params = [
    'timestamp'   => $timestamp,
    'amount'      => $amount,
    'token'       => $currency,
    'network'     => $network,
    'to_address'  => $to_address,
];

ksort($params);
$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
$signature = hash_hmac('sha256', $query, $merchant_secret);

The resulting signature must be sent in the X-Merchant-Signature header.

✅ Example

X-Timestamp: 1712990000000
X-Merchant-Signature: 3b2a1b7d9a8bdf12...

Payload:

{
  "amount": "100.00",
  "token": "USDT",
  "network": "TRON",
  "to_address": "TXYZabc..."
}

String to sign:

amount=100.00&network=TRON&timestamp=1712990000000&to_address=TXYZabc...&token=USDT

Service fee

A service fee is charged when funds are transferred from the temporary address to the merchant wallet. The amount depends on your subscription plan and is charged in the same token used for payment.

Fees can be accumulated in the merchant wallet (frozen_amount) and periodically transferred to the service when economically reasonable.

Blockchain Network Fees (BNF)

BNF is charged in the main coin of the blockchain (e.g., ETH for Ethereum).

It applies to:

• Transfers from temporary to merchant wallets
• Withdrawals
• Refunds

Normally, BNF is deducted from the source wallet. If the source wallet lacks the required main coin, the service pays the fee and deducts its equivalent in the token used.

If a webhook_url is set in the merchant's settings, the service will notify your server about updates to invoice and withdrawal statuses.

• A webhook is considered delivered if your server responds with an HTTP status code 2xx.
• Otherwise, it will retry using exponential backoff (up to 3 attempts).
• The request timeout is 3 seconds.

Signature Verification

Each IPN includes a Sig header, which is an HMAC SHA256 signature of the payload, signed with the merchant's secret key.

To verify the signature, you need to:

1. Extract the Sig header from the request.
2. Sort the payload parameters by key in ascending order.
3. Concatenate them as key=value pairs, separated by &.
4. Calculate hash code for string from step3 using the SHA256 algorithm in hexadecimal encoding in lowercase with the NMAS method, signed with a secret key from your merchant's settings
5. Compare hash code with the signature from step 1.

example (PHP)

// $payload - array of parameters from ipn
// $signFromSigHeader - server signature value from Sig header
// $secret - merchant's secret key

// Sorting the array by keys
ksort($payload);

// Combining key=value pairs with an ampersand as a separator
$sign_params_query = http_build_query($payload);

$calculatedSign = hash_hmac('sha256', $sign_params_query, $secret);

return $signFromSigHeader === $calculatedSign;

Invoice webhook payload

An invoice notification is sent whenever the invoice status changes and whenever paid_amount changes (so top-ups to a still Partially Paid invoice are delivered as separate notifications).

All amount fields are decimal strings, status is an integer. Optional string fields (e.g. order_num) are sent as an empty string "" when absent — the payload never contains null.

status is one of the following values (other internal statuses are not delivered): 2 Partially Paid, 3 Paid, 13 Awaiting AML decision, 21 Transfer in progress, 38 Partially Refunded, 39 Refunded, 97 Error, 98 Cancelled, 99 Successful.

Note on 21 Transfer in progress — the payment is confirmed and (if AML is enabled) has passed the AML check; the funds are being swept to your wallet. It is not a terminal status: a successful sweep is followed by 99 Successful. Use it as an early "payment accepted" signal, but treat 99 as the final confirmation.