Authentication

Every API request must include your API key and secret in the request headers. No tokens, no OAuth, no sessions — just two headers on every request.

How It Works

When you make a request to the DoorPay API, include these two headers:

Required Headers

Field	Type	Required	Description
`X-API-Key`	string	Required	Your API key. Starts with "dp_test_" for sandbox. Identifies your merchant account.
`X-API-Secret`	string	Required	Your API secret. Starts with "sk_test_" for sandbox. Proves you own the key. Keep this secret!

Example request (sandbox)

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

Getting Your API Keys

Complete onboarding. Register your business and submit KYC documents at merchants.thedoorpay.com/onboarding.

Wait for approval. DoorPay team reviews your documents. You'll get an email when approved.

Generate keys. Go to Dashboard → API Keys and generate Sandbox or Production keys. The secret is shown only once — save it somewhere safe.

Key Types

Sandbox Keys

Key: dp_test_...

Secret: sk_test_...

For testing. No real money moves.

Production Keys

Key: dp_live_...

Secret: sk_live_...

For real payments. Handle with care.

Rotating Secrets

If your secret is compromised, rotate it immediately from the Dashboard. Go to API Keys → Rotate Secret. The old secret stops working instantly, and you get a new one.

Security Warning

Never expose your API secret in frontend code, GitHub repos, or client-side JavaScript.
Always call the DoorPay API from your backend server.
Store secrets in environment variables, not in source code.

API Versioning

Every API response includes an X-API-Version header indicating the current API version (e.g. 2026-03-15). Use this to track compatibility. When breaking changes are introduced, the version will change and the previous version will be supported for a deprecation period.

Rate Limiting

The API allows 10 requests per second per IP address. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Rate limit exceeded response

{
  "error": "Too many requests"
}

Pagination

List endpoints (like GET /orders) support pagination via query parameters:

Pagination Parameters

Field	Type	Required	Description
`page`	integer	Optional	Page number (0-indexed). Default: 0
`size`	integer	Optional	Items per page. Default: 20, max: 100

Example: Paginated orders (sandbox)

curl -X GET "https://api.thedoorpay.com/sandbox/api/merchant/v1/orders?page=0&size=50" \
  -H "X-API-Key: dp_test_your_key" \
  -H "X-API-Secret: sk_test_your_secret"

The response includes standard Spring page metadata: totalElements, totalPages, number (current page), size.

Domain Whitelisting (Optional)

If you call the DoorPay API from a browser (e.g., a checkout widget), you can whitelist your domain for extra security. When configured, DoorPay will reject requests from non-whitelisted origins. Request whitelisting from Dashboard → Whitelist. Server-to-server calls (without an Origin header) are never blocked.

Idempotency

To prevent duplicate orders on network retries, send an Idempotency-Key header with your POST /orders request. If you send the same key twice, DoorPay returns the existing order instead of creating a duplicate.

Using an idempotency key

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 "Idempotency-Key: order-checkout-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If you don't provide an idempotency key, one is auto-generated. We recommend always sending your own key for order creation requests.