SyncPaySyncPay API DocumentationAPI Reference

Getting Started with API Keys

Overview

This guide walks you through obtaining your first API key and making your first authenticated request to the SyncPay API.

Prerequisites

Before you begin, you need:

  1. A SyncPay account (sign up at https://dashboard.usesyncpay.com)
  2. Access to your organization's dashboard

Step 1: Log In to Your Dashboard

  1. Go to https://dashboard.usesyncpay.com
  2. Log in with your email and password
  3. You'll be taken to your organization's dashboard

Step 2: Navigate to API Keys

In your dashboard:

  1. Click on Settings or API Keys in the navigation menu
  2. You'll see the API Keys management page

Step 3: Create Your First API Key

Important: You can only have one active API key per environment (test or live) at a time.

Creating a Test Mode Key

  1. Ensure you're in Test Mode (check the environment toggle in your dashboard)
  2. Click Create API Key or Generate New Key
  3. Enter a descriptive name for your key (e.g., "Development Key", "Staging Server")
  4. Click Create

Your API Key is Shown Once

After creation, your API key will be displayed once.

Critical: Copy and store your API key securely immediately. You won't be able to see it again.

If you lose your key:

  • You'll need to revoke the old key
  • Generate a new key
  • Update your application with the new key

Step 4: Store Your API Key Securely

Recommended: Use Environment Variables

Never hardcode API keys in your source code. Use environment variables instead:

Node.js / JavaScript:

# .env file (add to .gitignore!)
SYNCPAY_API_KEY=sk_test_abc123xyz...

// In your code
const apiKey = process.env.SYNCPAY_API_KEY;

Python:

# .env file (add to .gitignore!)
SYNCPAY_API_KEY=sk_test_abc123xyz...

# In your code
import os
api_key = os.environ.get('SYNCPAY_API_KEY')

PHP:

# .env file (add to .gitignore!)
SYNCPAY_API_KEY=sk_test_abc123xyz...

// In your code
$apiKey = getenv('SYNCPAY_API_KEY');

Step 5: Make Your First API Request

Let's verify your API key works by fetching your account balances.

Using cURL 

curl https://api.usesyncpay.com/api/v1/accounts/balances \
  -H "Authorization: Bearer sk_test_abc123xyz..."

Using Node.js (JavaScript) 

const fetch = require('node-fetch');

const apiKey = process.env.SYNCPAY_API_KEY;

async function getBalances() {
  const response = await fetch('https://api.usesyncpay.com/api/v1/accounts/balances', {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  const data = await response.json();
  console.log('Account balances:', data);
}

getBalances();

Using Python 

import os
import requests

api_key = os.environ.get('SYNCPAY_API_KEY')

response = requests.get(
    'https://api.usesyncpay.com/api/v1/accounts/balances',
    headers={'Authorization': f'Bearer {api_key}'}
)

data = response.json()
print('Account balances:', data)

Using PHP 

<?php
$apiKey = getenv('SYNCPAY_API_KEY');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.usesyncpay.com/api/v1/accounts/balances');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

print_r($data);
?>

Expected Response 

{
  "success": true,
  "account_id": "org_abc123",
  "balances": [
    {
      "currency": "USD",
      "available_balance": "0.00",
      "pending_balance": "0.00"
    }
  ],
  "total_balance_usd": "0.00"
}

If you see this response, congratulations! Your API key is working correctly.

Step 6: Test in Test Mode

Before processing real transactions:

  1. Use your test mode API key (sk_test_...)
  2. Create test checkouts and payments
  3. Verify your integration handles all scenarios correctly
  4. Test error cases (expired checkouts, failed payments, etc.)

Step 7: Go Live

When you're ready to process real transactions:

  1. Complete your business verification in the dashboard
  2. Wait for approval (usually 1-3 business days)
  3. Generate a live mode API key (sk_live_...)
  4. Replace your test key with the live key in your production environment
  5. Monitor your first transactions carefully

Common Issues

"Invalid or missing Authorization header"

Problem: API key not included in request

Solution:

  • Ensure you're sending the Authorization header
  • Format must be: Authorization: Bearer sk_test_...
  • Check for typos in "Authorization" or "Bearer"

"Invalid API key"

Problem: API key is incorrect or has been revoked

Solution:

  • Verify you copied the entire key (they're long!)
  • Check you're using the right environment (test vs live)
  • Generate a new key if the old one was revoked

"API key configuration error"

Problem: Rare configuration issue

Solution:

  • Log out and log back in to your dashboard
  • Try generating a new API key
  • Contact support if the issue persists

Managing API Keys

Viewing Your Keys

In your dashboard:

  • You can see when each key was created
  • View the last time each key was used
  • See key names you assigned

Note: You cannot view the actual key value after creation. Only the metadata.

Revoking Keys

To revoke an API key:

  1. Go to API Keys in your dashboard
  2. Find the key you want to revoke
  3. Click Revoke or Delete
  4. Confirm the action

Warning: Once revoked, any requests using that key will immediately fail with a 401 error.

Creating a New Key

To create a new key (if you already have one):

  1. First, revoke your existing key (you can only have one active key per environment)
  2. Then click Create API Key
  3. Enter a name and confirm

Best Practices

Development Workflow

  1. Local Development: Use test mode keys
  2. Staging Environment: Use test mode keys (separate from local)
  3. Production: Use live mode keys only

Key Rotation

If you need to rotate keys without downtime:

  1. This requires having multiple systems/servers
  2. SyncPay allows only one active key at a time per environment
  3. Plan a maintenance window for key rotation
  4. Or design your system to handle API key updates without restarting

Monitoring

  • Check the "last used" timestamp in your dashboard regularly
  • If you see unexpected usage, revoke the key immediately
  • Set up alerts for failed authentication attempts

Next Steps

Now that you have your API key working, you're ready to:

Need Help?

If you're having trouble getting started:

  1. Check the Authentication Overview for conceptual information
  2. Review error messages carefully - they usually indicate the exact issue
  3. Verify your API key is active in your dashboard
  4. Contact support with your organization ID (never share your API key!)