Authentication & Security

API Key Authentication

All API calls require the apikey header.

const client = axios.create({
  baseURL: 'https://pay.3pa-y.com/api/v1',
  headers: {
    'apikey': process.env.THREEPAY_API_KEY,
    'x-api-secret': process.env.THREEPAY_API_SECRET, // optional but recommended
  },
});

x-api-secret is required for:

Error responses: 401 for missing/invalid API key or invalid API secret.

Dashboard Authentication

• JWT in httpOnly cookies (secure: true, sameSite: strict in production)
• OTP required for payouts and password changes
• Optional TOTP 2FA in Dashboard > Settings > Security

Webhook HMAC Verification

Every webhook includes X-Webhook-Signature: sha256=<hex-digest> computed from the raw body using your webhookSecret.

const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const received = signatureHeader?.replace('sha256=', '') || '';
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Full verification examples (Node.js, Python, PHP): Webhook Handling

Rate Limits

All endpoints are rate-limited per IP (sliding window).

Exceeding returns 429 with RateLimit-* headers. Implement exponential backoff.

Pagination

• limit capped at 100 server-side on all list endpoints
• sortBy validated against allowlist: createdAt, updatedAt, amount, status, confirmedAt
• Invalid sortBy values fall back to createdAt

SSRF Protection

Webhook URLs and callback URLs are validated — private IPs, localhost, and cloud metadata endpoints are rejected. Use public, internet-routable HTTPS URLs only.

Best Practices

1. HTTPS webhook URLs — HTTP works but exposes payload data
2. Rotate webhook secrets periodically — POST /webhook/secret/rotate
3. Send x-api-secret on every call — adds a second credential layer
4. IP whitelisting — Dashboard > Settings
5. API keys server-side only — never in client code
6. Enable 2FA — Dashboard > Settings > Security
7. Verify webhook signatures — never skip HMAC verification
8. Idempotency — webhooks may arrive more than once (5 auto-retries)