SyncPay API Documentation

Welcome to the SyncPay API documentation. This guide will help you integrate payments into your application.

Base URL

All API requests should be made to:

https://api.usesyncpay.com

Quick Start

1. Get Your API Key

Follow this guide to obtain your API key from the dashboard.

2. Make Your First Request

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

3. Create a Checkout

curl -X POST https://api.usesyncpay.com/api/v1/payments/checkouts \
  -H "Authorization: Bearer sk_test_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "pricing": {
      "base_currency": "USD",
      "amount": "50.00"
    },
    "customer_email": "customer@example.com"
  }'

Documentation Structure

Authentication

Overview - API keys, security, environments
Getting Started - Get your first API key

Payments

Accept payments from customers:

List Payment Methods
List Supported Currencies
Create Checkout - Main integration endpoint
Create Quote - Get pricing before checkout
Create Whitelabel Checkout - Custom UI integration
Get Charge Status - Check payment status
List Payins - View all payments
Notes & Clarifications - Important details

Accounts

Manage your balances:

Get Balances - View available funds

Payouts

Withdraw funds to external accounts:

Create Withdrawal - Initiate payout
Create Payout Destination - Add withdrawal destination

Organizations

Manage your organization settings:

Get Organization - View organization details

Webhooks

Receive real-time notifications:

Payment Events - Payment status updates

Common Integration Patterns

Standard Checkout Flow

Create Checkout with amount and customer email
Redirect customer to checkout URL
Customer completes payment
Receive webhook notification
Fulfill order

Recommended for: Most integrations, e-commerce, SaaS, digital products

Custom Checkout Flow (Whitelabel)

List Payment Methods to show options
Create Quote to get pricing
Collect payment details in your UI
Create Whitelabel Checkout
Display payment instructions
Monitor via webhooks

Recommended for: Mobile apps, embedded payments, custom UI requirements

Payout Flow

Check Balances
Create Payout Destination (one-time)
Create Withdrawal
Monitor status via polling or webhooks

Recommended for: Marketplace payouts, affiliate payments, vendor payments

Test vs Live Mode

SyncPay provides two environments:

Environment	API Key Prefix	Purpose
Test	`sk_test_...`	Development & testing
Live	`sk_live_...`	Production

Test mode uses simulated payments
No real money moves in test mode
All features work the same in both modes
Data is completely isolated between modes

Learn more about environments

Rate Limits

Standard: 100 requests per minute per API key
Exceeded limit returns 429 Too Many Requests
Contact support for higher limits

Error Handling

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {
      // Additional context
    }
  }
}

Common error codes:

400 - Bad Request (validation error)
401 - Unauthorized (invalid API key)
403 - Forbidden (no permission)
404 - Not Found
429 - Too Many Requests (rate limit)
500 - Internal Server Error

Best Practices

1. Always Use HTTPS

Never send API keys over HTTP in production.

2. Use Webhooks

Webhooks are more reliable than polling for payment status updates.

3. Implement Idempotency

Use idempotency keys for critical operations like withdrawals.

4. Validate Webhook Signatures

Always verify webhooks came from SyncPay to prevent fraud.

5. Handle Errors Gracefully

Implement retry logic with exponential backoff for transient errors.

6. Store Settlement Amounts

Use settlement_amount, not amount, for revenue calculations.

Support

Need help?

📧 Email: support@usesyncpay.com
💬 Dashboard: Live chat (business hours)
📚 Documentation: https://docs.usesyncpay.com
🐛 Report issues: Include your organization ID (never your API key!)

Changelog

Check the dashboard or contact support for API updates and new features.

SDKs and Libraries

Official SDKs coming soon. For now, use standard HTTP clients:

Node.js: fetch, axios
Python: requests, httpx
PHP: curl, guzzle
Ruby: httparty, faraday