DoorPay Merchant API

Accept protected payments on your website or app. Create orders via API, let your customers pay through DoorPay, and get notified via webhooks when things happen.

Protected Payments

Funds are held securely until delivery is confirmed. Buyers trust it, you get paid.

Simple REST API

Six endpoints to manage the entire order lifecycle. JSON in, JSON out.

Auto-Confirm

Orders auto-complete 24 hours after delivery if no dispute is raised.

Real-time Webhooks

Get notified instantly when payments succeed, disputes are raised, or orders complete.

Base URL

All API requests go to one of these base URLs depending on your environment. Use the toggle in the sidebar to switch between Sandbox and Production.

SANDBOXhttps://api.thedoorpay.com/sandbox/api/merchant/v1

Quick Start

Here's how to create your first order in 30 seconds. You'll need your API key and secret from the Dashboard → API Keys page.

Create an order (sandbox)

curl -X POST https://api.thedoorpay.com/sandbox/api/merchant/v1/orders \
  -H "X-API-Key: dp_test_your_api_key" \
  -H "X-API-Secret: sk_test_your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "description": "Premium Logo Design",
    "buyer_email": "customer@example.com",
    "buyer_phone": "+919876543210",
    "buyer_first_name": "Rahul",
    "buyer_last_name": "Sharma",
    "merchant_order_id": "MY-ORDER-001"
  }'

You'll get back a response with the order details and a payment link for your customer:

Response (201 Created)

{
  "success": true,
  "message": "Order created",
  "data": {
    "order_number": "DP-20260313-A7X9K2",
    "merchant_order_id": "MY-ORDER-001",
    "amount": 500.00,
    "description": "Premium Logo Design",
    "status": "ACCEPTED",
    "payment_status": "UNPAID",
    "environment": "sandbox",
    "buyer": {
      "first_name": "Rahul",
      "last_name": "Sharma",
      "email": "customer@example.com",
      "phone": "+919876543210",
      "is_new_account": true
    },
    "payment_link": "https://user.thedoorpay.com/order/DP-20260313-A7X9K2",
    "payment_expires_at": "2026-03-15T10:00:00Z",
    "idempotency_key": "auto-generated-uuid",
    "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"
}

Order Lifecycle

Every order goes through a predictable series of steps. Here's how it works from start to finish:

You create an order

ACCEPTED

Call POST /orders with amount, description, and buyer details. The order starts in ACCEPTED status. The buyer gets an email with a payment link.

Buyer pays

PAID

The buyer clicks the payment link and pays directly on a secure checkout page — no login or OTP required. You receive a PAYMENT_SUCCESS webhook.

You mark as delivered

DELIVERED

Call PUT /orders/{id}/deliver after fulfilling the order. A 24-hour auto-confirm timer starts. The buyer can raise a dispute during this window.

Auto-confirmed or disputed

COMPLETED

If the buyer doesn't raise a dispute within 24 hours, the order auto-completes and funds are released to you. If they dispute, you have 24 hours to resolve it.

Sandbox vs Production

Aspect	Sandbox	Production
API Key prefix	dp_test_...	dp_live_...
Secret prefix	sk_test_...	sk_live_...
Payments	Simulated (no real money)	Real payments (UPI, etc.)
Buyer accounts	Dummy accounts	Real DoorPay accounts
Webhooks	Sent to sandbox webhook URL	Sent to production webhook URL

Start with Sandbox to test your integration. When everything works, switch to Production keys. Your code stays exactly the same — only the keys and base URL change.

What's Next?

Authentication

How to authenticate your API requests

Orders

Create, list, deliver, and cancel orders

Webhooks

Receive real-time notifications