SyncPaySyncPay API DocumentationAPI Reference

Authentication Overview

What is API Key Authentication?

SyncPay uses API keys to authenticate requests to the API. API keys allow you to securely integrate payments into your application without requiring your users to log in to SyncPay.

Live Mode vs Test Mode

SyncPay provides two environments for your API keys:

Test Mode (sk_test_...)

  • For development and testing
  • Transactions are simulated and never processed by real payment providers
  • No real money is moved
  • Available immediately when you sign up
  • Free to use with no limits

Live Mode (sk_live_...)

  • For production use with real transactions
  • Real money is processed through payment providers
  • Requires business verification and approval
  • Available after completing onboarding and verification

Important: Your test mode and live mode data are completely separate. Transactions, customers, and balances in test mode do not affect your live mode environment.

API Key Format

API keys follow this format:

  • Test keys: sk_test_abc123... (starts with sk_test_)
  • Live keys: sk_live_abc123... (starts with sk_live_)

The prefix determines which environment your requests will use.

Security Best Practices

Keep Your API Keys Secret

API keys carry significant privileges and should be treated like passwords:

  • Never commit API keys to version control (Git, GitHub, etc.)
  • Never expose API keys in client-side code (JavaScript, mobile apps)
  • Never share API keys in public forums or support tickets
  • Always use environment variables or secure secret management systems

Use Test Keys During Development

  • Develop and test your integration using test mode keys
  • Only switch to live mode keys when you're ready to process real transactions
  • Use separate API keys for different environments (development, staging, production)

Rotate Keys Regularly

  • If you suspect a key has been compromised, revoke it immediately from your dashboard
  • Consider rotating keys periodically as part of your security practices
  • You can only have one active API key per environment at a time

How API Keys Work

When you make a request to the SyncPay API:

  1. You include your API key in the Authorization header as a Bearer token
  2. SyncPay validates the key and identifies your organization
  3. The request is processed in the environment matching your key (test or live)
  4. All transactions, balances, and data are scoped to your organization and environment

Rate Limits

API keys are subject to rate limits to ensure system stability:

  • Standard tier: 100 requests per minute
  • Higher limits: Available on request for high-volume merchants

If you exceed your rate limit, you'll receive a 429 Too Many Requests error. Wait a few seconds before retrying.

Getting Your First API Key

Ready to start integrating? See Getting Started to obtain your first API key.

Common Authentication Errors

401 Unauthorized

Cause: Invalid or missing API key

Solution:

  • Verify your API key is correctly formatted
  • Ensure you're including the Authorization: Bearer sk_test_... header
  • Check that your key hasn't been revoked

403 Forbidden

Cause: API key doesn't have permission for the requested resource

Solution:

  • Verify you're using the correct organization's API key
  • Check that you're not trying to access another organization's data

Next Steps