API Keys

API Keys Overview

PayOrc API keys authenticate your requests to the payment gateway. You need both a merchant-key and a merchant-secret for every API call. Keys are environment-specific — separate keys exist for live (production) and test (sandbox) environments.

Generating API Keys

To generate your API keys:

1. Log in to the PayOrc Merchant Dashboard.
2. Navigate to Developers → API Keys.
3. Click Add new API key.
4. Select the channel for this key.
5. Copy and securely store both the key and secret immediately — the secret is only shown once.

API Key Channels

Each channel serves a specific integration type:

Live vs Test Keys

PayOrc provides two environments with separate credentials:

When to Use Test Keys

• During development and integration testing
• QA and staging environment validation
• Demo and proof-of-concept implementations
• Training new team members on the API

When to Use Live Keys

• Production deployments only
• After completing thorough testing in the sandbox
• When processing real customer payments

Using API Keys in Requests

Include both keys in the request headers for every API call:

curl -X POST "https://api.payorc.com/orders/v1/create" \
  -H "merchant-key: live-XXXXXXXXXX" \
  -H "merchant-secret: sec-XXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "AED"}'

Key Rotation

Key rotation is the practice of periodically generating new API keys and retiring old ones. This limits the impact of compromised credentials.

Rotation Schedule

Rotation Steps

1. Generate a new key pair in the Merchant Dashboard under Developers → API Keys.
2. Update your application to use the new key pair.
3. Test thoroughly in the sandbox environment with test keys first.
4. Deploy the changes to production.
5. Delete the old key from the Dashboard once you confirm the new key works.

Environment Variables

Store your API keys in environment variables — never hardcode them in source code.

Recommended Environment Variable Names

export PAYORC_MERCHANT_KEY="live-XXXXXXXXXX"
export PAYORC_MERCHANT_SECRET="sec-XXXXXXXXXX"
export PAYORC_ENV="live"  # or "test"

Security Best Practices

Follow these guidelines to keep your API credentials secure:

Do's

• ✅ Store keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault)
• ✅ Use test keys during development and CI/CD pipelines
• ✅ Rotate keys periodically
• ✅ Restrict key permissions by channel (only generate keys for channels you use)
• ✅ Monitor API usage for unusual patterns
• ✅ Use HTTPS for all API calls (never HTTP)

Don'ts

• ❌ Never hardcode keys in source code
• ❌ Never commit keys to Git repositories
• ❌ Never expose keys in client-side JavaScript or mobile apps
• ❌ Never share keys over unencrypted channels (email, Slack DMs)
• ❌ Never use live keys for testing
• ❌ Never reuse keys across multiple applications without isolation

Using a Secrets Manager

import boto3
import json

client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='payorc/api-keys')
keys = json.loads(secret['SecretString'])

# Use keys['merchant_key'] and keys['merchant_secret']