Orders

Orders are the core of the DoorPay Merchant API. Create an order, let the buyer pay, mark it delivered, and funds are released to you automatically.

Create Order

Creates a new payment-protected order. The buyer receives an email with a payment link. The order is auto-accepted (no manual acceptance needed). If the buyer doesn't pay within 48 hours, the order is automatically cancelled.

POSThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders

Request Body (JSON)

Field	Type	Required	Description
`amount`	number	Required	Order amount in INR. Minimum 5.00, maximum 10,000.00.
`description`	string	Required	What the buyer is paying for. Max 500 characters. Shown to the buyer on the payment page.
`buyer_email`	string	Required	Buyer's email address. Payment link will be sent here.
`buyer_phone`	string	Required	Buyer's phone number in +91XXXXXXXXXX format. Used for OTP verification.
`buyer_first_name`	string	Required	Buyer's first name. Max 100 characters.
`buyer_last_name`	string	Required	Buyer's last name. Max 100 characters.
`merchant_order_id`	string	Optional	Your internal order reference ID. Max 255 characters. Echoed back in all responses and webhooks for easy correlation.
`delivery_deadline`	string (ISO-8601)	Optional	Expected delivery date in UTC. Example: "2026-03-20T00:00:00Z". Informational only — not enforced.

Request Headers

Field	Type	Required	Description
`X-API-Key`	string	Required	Your merchant API key.
`X-API-Secret`	string	Required	Your merchant API secret.
`Content-Type`	string	Required	Must be application/json.
`Idempotency-Key`	string	Optional	Unique key to prevent duplicate orders. If omitted, auto-generated.

Request (sandbox)

curl -X POST https://api.thedoorpay.com/sandbox/api/merchant/v1/orders \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-abc-123" \
  -d '{
    "amount": 2500.00,
    "description": "Premium Logo Design Package",
    "buyer_email": "rahul@example.com",
    "buyer_phone": "+919876543210",
    "buyer_first_name": "Rahul",
    "buyer_last_name": "Sharma",
    "merchant_order_id": "SHOP-456",
    "delivery_deadline": "2026-03-20T00:00:00Z"
  }'

Response (201 Created)

{
  "success": true,
  "message": "Order created",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "merchant_order_id": "SHOP-456",
    "amount": 2500.00,
    "description": "Premium Logo Design Package",
    "status": "ACCEPTED",
    "payment_status": "UNPAID",
    "environment": "sandbox",
    "buyer": {
      "first_name": "Rahul",
      "last_name": "Sharma",
      "email": "rahul@example.com",
      "phone": "+919876543210",
      "is_new_account": true
    },
    "payment_link": "https://user.thedoorpay.com/pay/DP-20260313-A7X9K2",
    "payment_expires_at": "2026-03-15T10:00:00Z",
    "delivery_deadline": "2026-03-20T00:00:00Z",
    "idempotency_key": "checkout-abc-123",
    "dispute_count": 0,
    "created_at": "2026-03-13T10:00:00Z",
    "audit_trail": [
      {
        "action_type": "MERCHANT_ORDER_CREATED",
        "actor_user_id": "merchant:42",
        "metadata": "Order created via merchant API",
        "timestamp": "2026-03-13T10:00:00Z"
      }
    ]
  },
  "timestamp": "2026-03-13T10:00:00Z"
}

What happens next?

The buyer receives an email with a direct payment link — no login or OTP required.
If the buyer doesn't have a DoorPay account, one is created automatically in the background.
The buyer clicks the link and lands on a secure checkout page showing the order details, amount, and a "Pay Now" button.
After payment, the buyer sees a confirmation screen. No app download needed.
You receive a PAYMENT_SUCCESS webhook when payment is complete.
If the buyer doesn't pay within 48 hours, the order is auto-cancelled and you receive an ORDER_CANCELLED webhook.

Buyer Payment Experience

The payment_link in the response points to a public checkout page atuser.thedoorpay.com/pay/{order_number}.

No authentication required — the buyer pays directly without creating an account or entering OTP.
The page shows your merchant name, order amount, description, and a secure payment button.
After payment, the buyer sees a success screen with order details and DoorPay protection info.
If the buyer has the DoorPay app installed, they can also view and manage the order there.
You can also redirect your users to this link from your own checkout flow.

Validation Errors

amount must be between 5.00 and 10,000.00
buyer_phone must match +91 followed by exactly 10 digits
buyer_email must be a valid email address
description max 500 characters
All buyer fields (email, phone, first name, last name) are required

List Orders

Returns all orders for your merchant account in the current environment (sandbox or production), sorted by newest first.

GEThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders

Request (sandbox)

curl -X GET https://api.thedoorpay.com/sandbox/api/merchant/v1/orders \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

Response (200 OK)

{
  "success": true,
  "message": "Orders retrieved",
  "data": [
    {
      "order_number": "DP-20260313-A7X9K2",
      "merchant_order_id": "SHOP-456",
      "amount": 2500.00,
      "status": "PAID",
      "payment_status": "PAID",
      "environment": "sandbox",
      "created_at": "2026-03-13T10:00:00Z"
    },
    {
      "order_number": "DP-20260312-B3M7P1",
      "merchant_order_id": "SHOP-455",
      "amount": 1200.00,
      "status": "COMPLETED",
      "payment_status": "PAID",
      "environment": "sandbox",
      "created_at": "2026-03-12T08:30:00Z"
    }
  ],
  "timestamp": "2026-03-13T12:00:00Z"
}

Get Order

Retrieves full details for a single order, including the complete audit trail. Replace {orderNumber} with the DoorPay order number (e.g., DP-20260313-A7X9K2).

GEThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders/{orderNumber}

Request (sandbox)

curl -X GET https://api.thedoorpay.com/sandbox/api/merchant/v1/orders/DP-20260313-A7X9K2 \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

Response (200 OK)

{
  "success": true,
  "message": "Order retrieved",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "merchant_order_id": "SHOP-456",
    "amount": 2500.00,
    "description": "Premium Logo Design Package",
    "status": "PAID",
    "payment_status": "PAID",
    "environment": "sandbox",
    "buyer": {
      "first_name": "Rahul",
      "last_name": "Sharma",
      "email": "rahul@example.com",
      "phone": "+919876543210"
    },
    "payment_link": "https://user.thedoorpay.com/pay/DP-20260313-A7X9K2",
    "payment_expires_at": null,
    "auto_confirm_at": null,
    "delivery_deadline": "2026-03-20T00:00:00Z",
    "idempotency_key": "checkout-abc-123",
    "dispute_count": 0,
    "created_at": "2026-03-13T10:00:00Z",
    "updated_at": "2026-03-13T10:05:00Z",
    "audit_trail": [
      {
        "action_type": "MERCHANT_ORDER_CREATED",
        "actor_user_id": "merchant:42",
        "metadata": "Order created via merchant API",
        "timestamp": "2026-03-13T10:00:00Z"
      },
      {
        "action_type": "PAID",
        "actor_user_id": "123",
        "metadata": null,
        "timestamp": "2026-03-13T10:05:00Z"
      }
    ]
  },
  "timestamp": "2026-03-13T12:00:00Z"
}

Error: Order not found

Returns 404 if the order doesn't exist or 403 if it belongs to another merchant.

{
  "success": false,
  "message": "Order not found: DP-INVALID",
  "data": null,
  "timestamp": "2026-03-13T12:00:00Z"
}

Mark as Delivered

Marks an order as delivered. This starts a 24-hour auto-confirm timer. During this window, the buyer can raise a dispute. If no dispute is raised, the order auto-completes and funds are released to you. Important: The order must be in PAID status. You cannot deliver an unpaid order.

PUThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders/{orderNumber}/deliver

Request (sandbox)

curl -X PUT https://api.thedoorpay.com/sandbox/api/merchant/v1/orders/DP-20260313-A7X9K2/deliver \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

Response (200 OK)

{
  "success": true,
  "message": "Order marked as delivered",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "status": "DELIVERED",
    "payment_status": "PAID",
    "auto_confirm_at": "2026-03-14T10:05:00Z",
    "audit_trail": [
      { "action_type": "MERCHANT_ORDER_CREATED", "timestamp": "2026-03-13T10:00:00Z" },
      { "action_type": "PAID", "timestamp": "2026-03-13T10:05:00Z" },
      { "action_type": "DELIVERED", "timestamp": "2026-03-13T10:05:00Z" }
    ]
  },
  "timestamp": "2026-03-13T10:05:00Z"
}

Error: Wrong status

Returns 400 if the order is not in PAID status.

{
  "success": false,
  "message": "Cannot mark as delivered. Order must be in PAID status. Current status: ACCEPTED",
  "data": null,
  "timestamp": "2026-03-13T10:05:00Z"
}

After marking delivered

A DELIVERY_CONFIRMED webhook is sent to your endpoint.
The buyer is notified and has 24 hours to raise a dispute.
auto_confirm_at shows when the order will auto-complete.
If the buyer raises a dispute, you'll receive a DISPUTE_RAISED webhook.
If no dispute is raised, the order auto-completes and you receive an ORDER_COMPLETED webhook.

Cancel Order

Cancels an order before the buyer has paid. You can only cancel orders in ACCEPTED status (i.e., before any payment is made). Once paid, you cannot cancel.

PUThttps://api.thedoorpay.com/sandbox/api/merchant/v1/orders/{orderNumber}/cancel

Request (sandbox)

curl -X PUT https://api.thedoorpay.com/sandbox/api/merchant/v1/orders/DP-20260313-A7X9K2/cancel \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

Response (200 OK)

{
  "success": true,
  "message": "Order cancelled",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "status": "CANCELLED",
    "payment_status": "UNPAID",
    "payment_expires_at": null
  },
  "timestamp": "2026-03-13T10:10:00Z"
}

Error: Already paid

{
  "success": false,
  "message": "Cannot cancel. Order must be in ACCEPTED status (before payment). Current status: PAID",
  "data": null,
  "timestamp": "2026-03-13T10:10:00Z"
}

Order Statuses

The status field in every order response will be one of these values:

Status	Meaning	What You Can Do
`ACCEPTED`	Order created, waiting for buyer to pay	Cancel the order
`PAID`	Buyer has paid. Funds are held securely.	Mark as delivered
`DELIVERED`	You marked it delivered. 24hr auto-confirm timer running.	Wait for auto-confirm or dispute
`COMPLETED`	Auto-confirmed. Funds released to you.	Nothing — done!
`CANCELLED`	Order was cancelled (by you or payment expired)	Nothing — terminal state
`DISPUTE_DELIVERY`	Buyer says they didn't receive the item	Resolve the dispute
`DISPUTE_QUALITY`	Buyer says the item quality is not as described	Resolve the dispute
`REFUNDED`	Buyer was refunded (dispute not resolved in 24hrs)	Nothing — terminal state

Payment Statuses

The payment_status field tracks the money side of the order:

Status	Meaning
`UNPAID`	No payment received yet
`PAID`	Payment received and held in DoorPay
`REFUNDED`	Full refund issued to buyer
`PARTIALLY_REFUNDED`	Partial refund issued to buyer