# PayTide Integration Guide

PayTide is a crypto payment gateway for overseas hosting/server-rental platforms.

## Flow

1. Merchant platform creates a payment order via PayTide API.
2. PayTide returns `paymentId`, `paymentUrl`, amount, chain and receiving address.
3. User opens `paymentUrl` and pays USDT on TRC20.
4. PayTide detects the on-chain transfer and confirms it.
5. PayTide sends an HTTP POST callback to the merchant `notifyUrl`.
6. Merchant verifies callback signature and activates service.

## Create Payment

`POST /api/v1/payments`

Headers:

```http
Content-Type: application/json
x-api-key: <merchant apiKey>
x-timestamp: <unix milliseconds>
x-signature: <HMAC-SHA256 signature>
```

Body:

```json
{
  "merchantUserId": "user_1001",
  "merchantOrderId": "order_202605130001",
  "amount": "19.90",
  "currency": "USDT",
  "chain": "TRC20",
  "notifyUrl": "https://merchant.example.com/paytide/callback",
  "returnUrl": "https://merchant.example.com/orders/success",
  "expireMinutes": 30
}
```

Signature:

```text
signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
```

Important: sign the exact raw JSON string you send as the HTTP request body.

Response:

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "paymentId": "PAY_xxx",
    "merchantId": "M_xxx",
    "merchantUserId": "user_1001",
    "merchantOrderId": "order_202605130001",
    "amount": "19.90",
    "currency": "USDT",
    "chain": "TRC20",
    "receiveAddress": "T...",
    "status": "PENDING",
    "paymentUrl": "http://82.47.34.79:31030/pay/PAY_xxx",
    "expireAt": "2026-05-13T01:00:00.000Z"
  }
}
```

## Query Payment

`GET /api/v1/payments/{paymentId}`

Returns current payment status.

Statuses:

- `PENDING` — waiting for transfer
- `PAID` — transaction seen but confirmations not enough
- `CONFIRMED` — confirmations reached; callback being sent
- `NOTIFIED` — merchant callback succeeded
- `EXPIRED` — order expired
- `CANCELLED` — cancelled manually

## Callback

PayTide sends an HTTP POST request to the `notifyUrl` after confirmation.

Headers:

```http
Content-Type: application/json
X-PaymentId: PAY_xxx
X-Timestamp: <unix milliseconds>
X-Signature: <HMAC-SHA256 signature>
```

Body:

```json
{
  "paymentId": "PAY_xxx",
  "merchantId": "M_xxx",
  "merchantUserId": "user_1001",
  "merchantOrderId": "order_202605130001",
  "status": "CONFIRMED",
  "amount": "19.90",
  "currency": "USDT",
  "chain": "TRC20",
  "txHash": "...",
  "fromAddress": "T_user_wallet",
  "toAddress": "T_receive_wallet",
  "confirmations": 20,
  "paidAt": "...",
  "confirmedAt": "..."
}
```

Callback signature verification:

```text
expected = HMAC_SHA256(secret, timestamp + "." + rawBody)
```

Merchant server should:

1. Verify signature.
2. Check timestamp freshness, recommended <= 5 minutes.
3. Check `merchantOrderId` exists and amount matches.
4. Ensure idempotency: repeated callbacks for the same `paymentId` must not double-credit.
5. Return HTTP 2xx if processed successfully.