Merchant Checkout Flow

This document illustrates the merchant checkout flow with a step-by-step description and the expected API schemas for each step.

Description of Steps

1. Checkout Creation

   1.1 User initiates a checkout (e.g., by clicking “Pay” on the frontend).

   1.2 The frontend sends a POST request to /merchant/checkout/create on the backend.

   1.3 Backend creates a new checkout entry and responds with the generated id and externalId.

2. Get Checkout Status

   2.1 The frontend polls (or queries) the backend with GET /merchant/checkout/get?id=checkout_abcdef123456 to retrieve the status and details of the checkout.

   2.2 Backend returns the status and details.

3. Webhook Transaction Status Update

   3.1 The payment provider sends a webhook POST to /merchant/checkout/webhook with the new status (e.g., completed, failed).

   3.2 Backend updates the checkout status in the database accordingly.

4. (Optional) Frontend Polling for Updated Status

   4.1 The frontend may continue polling /merchant/checkout/get to check for status changes after the webhook is processed.

   4.2 Backend responds with the updated status and details

{
    "id": 9,
    "externalId": "k8O4SVRkbgxqyqW3SX9F"
}

---

API Schemas

1. POST /merchant/checkout/create

Request Example:

{
  "amount": "100.00",
  "metadata": { "orderId": "ORDER123" }
}

Response Example:

{
  "id": 123,
  "externalId": "checkout_abcdef123456"
}

---

2. GET /merchant/checkout/get?id=checkout_abcdef123456

Request:
Query parameter: id=checkout_abcdef123456

Response Example:

{
  "id": 123,
  "userUid": "user_abc123",
  "createdTime": "2025-07-07T05:54:15.000Z",
  "amount": "100.00",
  "externalId": "checkout_abcdef123456",
  "metadata": { "orderId": "ORDER123" },
  "paymentId": null,
  "payments": {
    "id": "pay_001",
    "createdTime": "2025-07-07T05:54:15.000Z",
    "totalAmount": "100.00",
    "txnFee": "1.00",
    "networkFee": "0.50",
    "discount": "0.00",
    "subPayments": [
      {
        "status": "pending",
        "amount": "100.00",
        "chain": "ETH",
        "currency": "USDT",
        "withTxnFee": true,
        "networkFee": "0.50",
        "discount": "0.00"
      }
    ]
  }
}

---

3. POST /merchant/checkout/webhook

Request Example:

{
  "externalId": "checkout_abcdef123456",
  "status": "completed"
}

Response:
HTTP 200 OK, usually empty or with a confirmation message.

---

For more details, visit our project repository for more information at:
https://github.com/MoonLabLtd/velox-checkout-example