Your website. Your products.
Orders through a phone call.

Connect your store

Any ecommerce website can use this common API. Your developer connects the five endpoints below to your existing catalogue, Cash on Delivery checkout and order records. No payment gateway or SMS/WhatsApp provider is required. A Shopify or WooCommerce website can use an adapter; ready-made platform plugins are not included in this release.

1. Sign in to HeyCall BusinessUse Business Login in your browser, or Business → Setup → Ecommerce website in the app. Verify the same phone number in both. Each business uses its own store connection.
2. Generate integration keysChoose Generate secure keys in the browser or Generate integration keys in the app. HeyCall generates your Store API key and a separate Webhook signing secret. Copy the one-time values and install both in your website's private server configuration. Existing saved keys remain unchanged unless you explicitly confirm replacement.
3. Ask your developer for the API URLGive your developer this guide and OpenAPI file. After implementing the five endpoints in your website, they provide its actual public HTTPS API base URL. Example only: https://shop.example.com/heycall/v1. Your storefront homepage, HeyCall login URL and HeyCall webhook URL are different addresses.
4. Confirm Cash on Delivery supportYour website must support COD for the intended address. Digital Payment is Coming soon; no payment gateway or messaging setup is required.
5. Save connection → Test connection → AI store accessEnable after the latest saved connection passes. Copy the webhook URL to your adapter; its final segment is the connection UUID. Use Check a product → Search products to check your live catalogue.

Which value goes where?

Private keys and controlled access

Generate credentials in your signed-in Business account on browser or in the HeyCall app → Business → Setup → Ecommerce website. This public guide contains documentation and placeholder examples. Saved keys are never returned by settings; freshly generated values are displayed once.

• Use two separate credentials. A dedicated API key authorizes your store's endpoints. A different random webhook secret signs events. Restrict keys to the intended store and operations.
• Saved credentials are encrypted server-side. Settings show whether each key is configured; they do not return saved key or secret values.
• Keep credentials out of URLs and public code. The API key goes to your configured store in the HTTPS Authorization header. The connection UUID in a webhook URL is an identifier, not a secret or authorization.
• Payment updates need verified evidence. Your adapter verifies actual cash collection/refund first (gateway evidence for historical digital orders). HeyCall then validates the HMAC, current timestamp and matching order/amount, and handles replayed event IDs.

API key ও webhook secret আলাদা রাখুন। Login করা app-এ keys save হবে; public landing page বা guide-এ secret বসাতে হবে না। Save করা secret settings থেকে ফেরত পাওয়া যাবে না।

Protect your account, server, logs and backups too. Encryption protects stored values; authorized server code still decrypts keys to connect your store. These controls do not guarantee that a website or account cannot be compromised.

During setup or credential rotation, webhook updates return 401 until a fresh health check verifies the pinned merchant ID. Keep events in your outbox, verify the connection, then retry the same event ID and raw body with a fresh signature. Turning off access after a successful identity check can still allow legitimate historical order updates.

From conversation to confirmed order

AI collects the selected variant, quantity and customer details, then reads back the website's quoted total, delivery charges and Cash on Delivery terms. After the caller agrees, the request appears as Needs review. Review it and tap Submit to website to create the order on your website.

The order uses Cash on Delivery and stays Unpaid until the merchant verifies actual cash collection. Digital Payment · Coming soon is shown for new orders. No payment link or message is sent.

You can decline a pending draft before any website operation begins. This cancels the local draft only. Uncertain/submitted orders need cancellation through the website. Historical digital records remain visible; reconcile any existing uncertain dispatch directly on the merchant website using the original evidence.

The API your website provides

Use a public HTTPS API base URL with a public IPv4 DNS record (A record), and no URL credentials, query string, fragment or explicit port. IPv6-only API hosts are not supported by the current connector. These endpoint paths are relative to that base. Return direct JSON objects without a data wrapper.

Authorization: Bearer YOUR_DEDICATED_API_KEY
X-HeyCall-Connection: YOUR_CONNECTION_UUID
Accept: application/json
Content-Type: application/json

Your adapter must validate the API key and connection UUID together, and bind that UUID to one store account. A rotated key must authorize the same store, including on platforms where several stores share an API hostname.

Keep API keys server-side. IDs use ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,254}$. Amounts are integer minor units from 0 to 99999999: 129900 with currency: "INR" and currency_exponent: 2 means ₹1,299.00. Exponent is 0–3. A quote supports up to 30 variants and quantities 1–100.

Return application/json with HTTP 200 (201 is accepted for successful creation), under 512 KiB. Endpoint timeout is 8 seconds; connection timeout is 3 seconds. Redirects are not followed. Report actual cash collection later through order status or a signed event.

{
  "status": "ok",
  "merchant_id": "store-104",
  "capabilities": ["products.search", "quotes", "orders.create",
                   "orders.status"],
  "payment_methods": ["cod"]
}

{"query": "blue cotton shirt size M", "limit": 8}

{
  "products": [{
    "product_id": "shirt-104",
    "variant_id": "shirt-104-blue-m",
    "name": "Cotton shirt",
    "description": "Blue cotton shirt, size M",
    "variant": "Blue / M",
    "price_minor": 129900,
    "currency": "INR", "currency_exponent": 2,
    "stock_quantity": 5, "available": true
  }]
}

{
  "payment_method": "cod",
  "items": [{"product_id":"shirt-104",
             "variant_id":"shirt-104-blue-m", "quantity":2}],
  "customer": {
    "name": "Example Customer", "phone": "+919000000000",
    "address": "Example delivery address, Kolkata",
    "postal_code": "700001", "fulfillment": "delivery"
  }
}

{
  "quote_id": "quote-203", "payment_method": "cod",
  "items": [{"product_id":"shirt-104", "variant_id":"shirt-104-blue-m",
             "name":"Cotton shirt — Blue / M", "quantity":2,
             "unit_price_minor":129900, "line_total_minor":259800}],
  "subtotal_minor": 259800, "shipping_minor": 5000,
  "tax_minor": 0, "discount_minor": 0, "total_minor": 264800,
  "currency": "INR", "currency_exponent": 2,
  "expires_at": "2030-01-01T12:10:00Z", "available": true
}

Idempotency-Key: hc-order-CONNECTION_UUID-42

{
  "idempotency_key": "hc-order-CONNECTION_UUID-42",
  "client_order_id": "heycall-42", "quote_id": "quote-203",
  "payment_method": "cod",
  "items": [{"product_id":"shirt-104", "variant_id":"shirt-104-blue-m",
             "name":"Cotton shirt — Blue / M", "quantity":2,
             "unit_price_minor":129900, "line_total_minor":259800}],
  "customer": {
    "name":"Example Customer", "phone":"+919000000000",
    "address":"Example delivery address, Kolkata",
    "postal_code":"700001", "fulfillment":"delivery"
  },
  "total_minor":264800, "currency":"INR", "currency_exponent":2
}

{
  "order_id": "store-order-901", "client_order_id": "heycall-42",
  "status": "confirmed", "payment_method": "cod",
  "total_minor": 264800, "currency": "INR", "currency_exponent": 2,
  "payment_status": "unpaid"
}

{
  "order_id": "store-order-901", "client_order_id": "heycall-42",
  "status": "delivered", "payment_method": "cod",
  "total_minor": 264800, "currency": "INR", "currency_exponent": 2,
  "payment_status": "paid", "payment_id": "cash-collection-808"
}

Send signed order and cash collection updates

Copy the webhook URL from your connection. Sign the exact JSON bytes with that connection's webhook secret, using a current Unix timestamp in seconds.

POST https://heycall.rinvo.in/api/webhooks/ecommerce/YOUR_CONNECTION_UUID
Content-Type: application/json
X-HeyCall-Timestamp: CURRENT_UNIX_SECONDS
X-HeyCall-Signature: LOWERCASE_HEX_SIGNATURE

signature = HMAC-SHA256(webhook_secret, timestamp + "." + raw_json_body)

{
  "event_id": "event-unique-701", "type": "payment.paid",
  "payment_method": "cod",
  "order_id": "store-order-901", "total_minor": 264800,
  "currency": "INR", "currency_exponent": 2,
  "payment_id": "cash-collection-808"
}

Supported event types: order.updated, payment.paid, payment.failed, payment.refunded. Every COD event must include payment_method: "cod", matching the order. Add status for an order update. Paid and refunded events require a payment ID. Historical digital orders may omit the payment-method field.

Verify actual cash collection or refund in the merchant records first; keep a stable receipt ID as payment_id. COD delivery alone must not mark an order paid. Historical digital orders require gateway evidence. Amount, currency and order must match. Keep clock difference within 300 seconds. Retry using the same event ID and exact raw body with a fresh timestamp/signature; do not reformat the body after signing or reuse an event ID for changed content. Persist events in an outbox and preserve order per order.

$body = json_encode($event, JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
$timestamp = (string) time();
$signature = hash_hmac(
    'sha256', $timestamp.'.'.$body, getenv('HEYCALL_WEBHOOK_SECRET')
);
// Send exactly $body, with the timestamp and signature headers.

Check before accepting live orders

• Search the correct variant and check an out-of-stock item.
• Check shipping, taxes, exact cart totals and quote expiry.
• Send the same order request twice with one key: only one website order should exist.
• Check genuine COD support in health and reject addresses where COD is unavailable. Quotes and orders must echo payment_method: "cod".
• Verify webhook rejection for wrong signatures, stale timestamps and mismatched amounts; duplicate events must not apply twice.
• Make a real phone call, approve its draft, and verify the matching website order.
• Confirm and deliver a COD order: it stays unpaid until actual cash collection is verified with a matching receipt.
• Check Digital Payment shows Coming soon; its action must return 409 without sending a link or message.

Disconnecting disables the integration and clears its keys while retaining order history. After changing credentials, check the connection again before enabling it.

Troubleshooting

Return non-success HTTP statuses for failures: 401/403 access, 404 missing order, 409 quote or idempotency conflict, 422 invalid fields, 429 rate limit and 5xx temporary failure. Never include secrets or card details in errors.

Download the complete request/response schema for your developer or contact support with the endpoint, HTTP status and sanitized error.