Skip to main content

​
Overview

The Waypay API uses API keys to authenticate requests. You can view and manage your API keys in the Waypay Dashboard.
Your API keys carry many privileges, so keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, or anywhere else that could expose them.

​
API Keys

Waypay provides two types of API keys:

Test Keys

Use these keys during development and testing. They start with pk_test_

Live Keys

Use these keys in production. They start with pk_live_

​
Key Characteristics

  • Test keys process transactions in test mode - no real money is moved
  • Live keys process real transactions and charge actual payment methods
  • Both environments have separate databases and don’t share data
  • API behavior is identical in both environments

​
Authentication Method

Include your API key in the SWICH-API-Key header: 
SWICH-API-Key: YOUR_API_KEY

​
Example Request

curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TXN123456 \
  --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx'

​
Storing API Keys Securely

Store your API keys in environment variables: 
export WAYPAY_API_KEY="pk_live_xxxxxxxxxxxxx"

​
Best Practices

1

Use Environment Variables

Never hardcode API keys in your source code. Use environment variables or secure configuration management.
2

Separate Keys by Environment

Use different API keys for development, staging, and production environments.
3

Restrict Key Permissions

Create separate keys with limited permissions for different services or applications.
4

Rotate Keys Regularly

Periodically rotate your API keys and immediately revoke compromised keys.
5

Use Server-Side Only

Never include API keys in client-side code (JavaScript, mobile apps) where they can be extracted.

​
Authentication Errors

​
401 Unauthorized

This error occurs when:
  • No SWICH-API-Key header is provided
  • The API key is invalid or has been revoked
  • The API key format is incorrect
Example Error Response: 
{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token"
}
Solutions:
  1. Verify your API key is correct and active
  2. Ensure the header format is exactly: SWICH-API-Key: YOUR_API_KEY
  3. Check that you’re using the correct key for the environment (test vs live)
  4. Confirm the key hasn’t been revoked in the dashboard

​
403 Forbidden

This error occurs when:
  • The API key doesn’t have permission for the requested resource
  • The account is suspended or restricted
Example Error Response: 
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions to access this resource"
}

​
API Key Management

​
Creating API Keys

  1. Log in to your Waypay Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Choose the environment (Test or Live)
  5. Set permissions and restrictions
  6. Save the key securely - it will only be shown once

​
Revoking API Keys

If you suspect a key has been compromised:
  1. Go to Settings → API Keys in your dashboard
  2. Find the compromised key
  3. Click Revoke
  4. Create a new key to replace it
  5. Update your application with the new key
Revoking a key will immediately stop all API requests using that key. Ensure you have a rollover plan before revoking keys used in production.

​
Testing Authentication

Test your authentication setup with a simple API call: 
curl --request GET \
  --url https://gateway.dev.waypay.live/Gateway/v1/Settlements/schedule \
  --header 'SWICH-API-Key: YOUR_API_KEY'

​
Security Recommendations

Always use HTTPS for API requests. Never send API keys over unencrypted HTTP connections.
Rotate API keys every 90 days or immediately after team member departures.
Regularly review API logs in your dashboard for unusual activity.
Grant each API key only the permissions it needs to perform its function.
Use secure key management services (AWS KMS, Azure Key Vault, HashiCorp Vault) in production.

​
Additional Headers

While the SWICH-API-Key header is required, you may also include optional headers:

​
Content-Type

Content-Type: application/json
Required for POST, PUT, and PATCH requests with JSON bodies.

​
Idempotency-Key

Idempotency-Key: unique-operation-id-123
Optional header to safely retry requests without duplicate processing.

​
User-Agent

User-Agent: MyApp/1.0.0
Optional header to identify your application in logs and support tickets.

​
Next Steps

Make Your First Payment

Learn how to create a payment checkout session

Handle Webhooks

Set up webhook endpoints for event notifications

Error Handling

Learn about API error codes and handling

Quickstart Guide

Complete integration tutorial