Orders

Orders represent a payment request for a specific USDT amount. When created, the API assigns a blockchain address and returns a hosted payment_url to redirect your customer to.

The Order object

Field	Type	Description
`id`	`string`	Unique order ID (UUID)
`order_number`	`string`	Human-readable ID with ord_ prefix
`status`	`string`	PENDING · OPEN · CONFIRMING · PAID · EXPIRED · EXPIRED_PAID · UNDERPAID · FROZEN
`order_amount`	`string`	Requested payment amount in USDT
`received_amount`	`string`	Amount received on-chain
`credited_amount`	`string`	Amount credited to your balance after fees
`currency`	`string`	Always USDT
`network`	`string`	TRC20 or ERC20
`payment_url`	`string`	Hosted checkout page URL — redirect your customer here
`expire_at`	`string`	ISO 8601 timestamp when the order expires
`paid_at`	`string`	ISO 8601 timestamp when payment was confirmed (null if unpaid)
`metadata`	`object`	Arbitrary key-value data you attached when creating the order
`created_at`	`string`	ISO 8601 creation timestamp

Create an order

POST

/v1/orders

Create a new payment order and receive a hosted checkout URL

💡Redirect the customer to payment_url immediately after creation. The order expires in 30 minutes by default.

Body parameters

amountstringrequired

Payment amount in USDT as a decimal string. Must be positive. Example: "99.99".

currencystringrequired

Must be "USDT".One of: USDT

networkstringrequired

Blockchain network. TRC20 (TRON) has lower fees.One of: TRC20, ERC20

descriptionstringoptional

Human-readable description shown on the hosted checkout page.

metadataobjectoptional

Arbitrary key-value pairs (JSON object). Returned in webhook events.

return_urlstringoptional

HTTPS URL to redirect the customer after payment. Never use this as payment proof — verify server-side.

webhook_urlstringoptional

HTTPS URL to receive payment event POSTs for this order. Overrides your default webhook.

idempotency_keystringoptional

Unique key for safe retries. Passing the same key returns the original order without creating a duplicate. Scoped per merchant, expires after 24h.

tolerance_percentnumberoptionaldefault: 0.01

Acceptable underpayment as a decimal (0.01 = 1%). Orders paid within this tolerance are marked PAID.

Returns Returns the Order object with a payment_url. Redirect your customer to this URL.

Request

bash

curl -X POST https://api.mpchat.com/v1/orders \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "99.99",
    "currency": "USDT",
    "network": "TRC20",
    "description": "Pro Plan - 1 month",
    "metadata": {"customer_id": "cust_123"},
    "return_url": "https://acme.com/payment/return",
    "webhook_url": "https://acme.com/webhooks/mp",
    "idempotency_key": "checkout_session_xyz"
  }'

Response 201

JSON

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "merchant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "order_number": "ord_6f8a2b",
  "status": "OPEN",
  "order_amount": "99.99",
  "received_amount": "0.00",
  "credited_amount": "0.00",
  "currency": "USDT",
  "network": "TRC20",
  "description": "Pro Plan - 1 month",
  "metadata": {"customer_id": "cust_123"},
  "payment_url": "https://pay.mpchat.com/pay/ord_6f8a2b",
  "return_url": "https://acme.com/payment/return",
  "webhook_url": "https://acme.com/webhooks/mp",
  "expire_at": "2024-01-15T10:31:00Z",
  "paid_at": null,
  "environment": "live",
  "tolerance_percent": "0.01",
  "created_at": "2024-01-15T10:01:00Z",
  "updated_at": "2024-01-15T10:01:00Z"
}

List orders

GET

/v1/orders

Return a paginated list of orders for your merchant account

Query parameters

limitintegeroptionaldefault: 20

Maximum number of orders to return. Max 100.

offsetintegeroptionaldefault: 0

Number of orders to skip (for pagination).

Returns Returns an object with an orders array and total count.

Request

bash

curl "https://api.mpchat.com/v1/orders?limit=20&offset=0" \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}"

Response 200

JSON

{
  "orders": [
    {
      "id": "c3d4e5f6-...",
      "order_number": "ord_6f8a2b",
      "status": "PAID",
      "order_amount": "99.99",
      "currency": "USDT",
      "network": "TRC20",
      "payment_url": "https://pay.mpchat.com/pay/ord_6f8a2b",
      "paid_at": "2024-01-15T10:05:00Z",
      "created_at": "2024-01-15T10:01:00Z"
    }
  ],
  "total": 42
}

Retrieve an order

GET

/v1/orders/{id}

Retrieve a single order by its ID

Path parameters

idstringrequired

The order UUID (e.g. c3d4e5f6-a7b8-...).

Returns Returns the Order object. Returns 404 if not found or belongs to another merchant.

Request

bash

curl https://api.mpchat.com/v1/orders/c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer mk_live_abc:{ts}:{sig}"

Response 200

JSON

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "order_number": "ord_6f8a2b",
  "status": "PAID",
  "order_amount": "99.99",
  "received_amount": "99.99",
  "credited_amount": "98.99",
  "currency": "USDT",
  "network": "TRC20",
  "payment_url": "https://pay.mpchat.com/pay/ord_6f8a2b",
  "expire_at": "2024-01-15T10:31:00Z",
  "paid_at": "2024-01-15T10:05:12Z",
  "environment": "live",
  "created_at": "2024-01-15T10:01:00Z",
  "updated_at": "2024-01-15T10:05:12Z"
}

Stream order events (SSE)

GET

/v1/orders/{id}/events

Subscribe to real-time status updates via Server-Sent Events

💡Use SSE instead of polling for a better customer experience. The first event sent contains the current order state so you don't need a separate GET request.

Path parameters

idstringrequired

The order UUID to subscribe to.

Returns Returns a text/event-stream. The connection closes automatically when the order reaches a terminal state (PAID, EXPIRED, UNDERPAID, FROZEN).

Subscribe (JavaScript)

JavaScript

const es = new EventSource(
  `https://api.mpchat.com/v1/orders/${orderId}/events`,
  { headers: { Authorization: `Bearer ${buildAuthHeader()}` } }
);

es.onmessage = (event) => {
  const order = JSON.parse(event.data);
  console.log('Status:', order.status);

  // Close on terminal states
  if (['PAID', 'EXPIRED', 'UNDERPAID', 'FROZEN'].includes(order.status)) {
    es.close();
  }
};

Response

JSON

// First event: current order state
data: {"id":"c3d4e5f6-...","status":"OPEN","order_amount":"99.99",...}

// Subsequent events: pushed on each status change
data: {"id":"c3d4e5f6-...","status":"CONFIRMING",...}

data: {"id":"c3d4e5f6-...","status":"PAID","paid_at":"2024-01-15T10:05:12Z",...}

Next: Webhooks API