Authentication

QRPay uses API keys for authentication on all server-side API calls.

API Keys

Key Format

Secret keys follow this format:

sec1-{env}-{kid}-{secret}-{checksum}

Example:

sec1-prd-ABC123DEF456G-Xy9Kl3pQ7mN2vB8wR5tZ6aH4cF1jD0sG9eY-42

Obtaining API Keys

Once obtained, you can use the API keys to authenticate your requests. Keys can be regenerated at any time using the API.

Using Keys in Requests

Include your secret key in the X-API-Key header:

POST /api/v1/payments/init HTTP/1.1
Host: api.qrpay2.com
Content-Type: application/json
X-API-Key: sec1-prd-ABC123DEF456G-Xy9Kl3pQ7mN2vB8wR5tZ6aH4cF1jD0sG9eY-42

Regenerating API Keys

Endpoint: POST /api/v1/merchant/api-keys/secret/regenerate

curl -X POST "https://api.qrpay2.com/api/v1/merchant/api-keys/secret/regenerate" \
  -H "X-API-Key: $CURRENT_API_KEY"

Response (201 Created):

{
  "status": "success",
  "data": {
    "api_key": {
      "id": "uuid",
      "kid": "ABC123DEF456G",
      "env": "prd",
      "type": "secret",
      "status": "active",
      "created_at": "2025-01-07T12:00:00Z",
      "display_mask": "sec1-prd-ABC...42"
    },
    "full_key": "sec1-prd-ABC123DEF456G-Xy9Kl3pQ7mN2vB8wR5tZ6aH4cF1jD0sG9eY-42"
  }
}

Webhook Secrets

Webhook secrets sign outbound webhooks from QRPay to your endpoint, ensuring authenticity and preventing spoofing.

Secret Format

whsec_{base64url-encoded-32-bytes}

Example:

whsec_Xy9Kl3pQ7mN2vB8wR5tZ6aH4cF1jD0sG9eY8fH2kJ7

Creating Webhook Secrets

Endpoint: POST /api/v1/merchant/webhooks/secret

curl -X POST "https://api.qrpay2.com/api/v1/merchant/webhooks/secret" \
  -H "X-API-Key: $API_KEY"

Response (201 Created):

{
  "status": "success",
  "data": {
    "id": "uuid",
    "secret": "whsec_Xy9Kl3pQ7mN2vB8wR5tZ6aH4cF1jD0sG9eY8fH2kJ7",
    "kid": "abc123def456"
  }
}

Rotating Webhook Secrets

Endpoint: POST /api/v1/merchant/webhooks/secret/rotate

curl -X POST "https://api.qrpay2.com/api/v1/merchant/webhooks/secret/rotate" \
  -H "X-API-Key: $API_KEY"

Rotation Window:

Old secret marked as rotating (valid for 24 hours)
New secret marked as active (used for new webhooks)
After 24 hours, old secret is disabled
During rotation, verify webhooks against both secrets

Error Cases

Scenario	HTTP Status	Action
Invalid API key	401	Check key format and value
Expired API key	403	Regenerate API key
Revoked API key	403	Contact account manager
Missing header	401	Add X-API-Key header

All requests must use HTTPS. Requests with missing or malformed headers will be rejected.