Authentication

Payylo uses API keys to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Don’t share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The interactive API Reference  lets you paste a key (Authorize button) and run authenticated requests against every endpoint right from the browser.

API Keys

Payylo provides two types of API keys:

Publishable Keys

• Safe to use in client-side code
• Used for collecting payment information
• Cannot complete payments or access sensitive data
• Format: pk_test_... (sandbox) or pk_live_... (live)

Secret Keys

• Must be kept confidential and only used on your servers
• Can perform any API operation
• Should never be exposed in client-side code
• Format: sk_test_... (sandbox) or sk_live_... (live)

Getting Your API Keys

1. Log in to your Payylo Dashboard 
2. Navigate to Settings → API Keys
3. Copy your keys for the appropriate environment

Warning: Sandbox vs Live. For creating sandbox keys, you need to use a sandbox merchant account.

Authentication Methods

Bearer Token (Recommended)

Include your secret key in the Authorization header:

curl https://api.payylo.com/v1/group-payments \
  -H "Authorization: Bearer sk_test_your_secret_key_here" \
  -H "Content-Type: application/json"

Basic Authentication

Alternatively, use HTTP Basic auth with your secret key as the username:

curl https://api.payylo.com/v1/group-payments \
  -u sk_test_your_secret_key_here: \
  -H "Content-Type: application/json"

Using an environment variable

export PAYYLO_SECRET_KEY="sk_test_your_secret_key_here"
 
curl https://api.payylo.com/v1/group-payments \
  -H "Authorization: Bearer $PAYYLO_SECRET_KEY" \
  -H "Content-Type: application/json"

Error Responses

When authentication fails, Payylo returns an HTTP 401 status code:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "request_id": "req_123456789"
  }
}

Common authentication errors:

Security Best Practices

Keep Secret Keys Secure

• Never expose secret keys in client-side code
• Store keys in environment variables or secure configuration
• Use different keys for different environments
• Rotate keys regularly

Use Environment Variables

# .env file
PAYYLO_SECRET_KEY=sk_test_your_secret_key_here
PAYYLO_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

Read the key from the environment and send it as the Authorization header on every request — never hard-code it.

IP Allowlisting

For additional security, you can restrict API key usage to specific IP addresses:

1. Go to Settings → API Keys in your dashboard
2. Click on the key you want to restrict
3. Add allowed IP addresses or CIDR blocks
4. Save your changes

Webhook Endpoints

Secure your webhook endpoints using the webhook signature verification:

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Testing Authentication

Test your authentication setup with a simple, read-only API call:

curl "https://api.payylo.com/v1/group-payments?limit=1" \
  -H "Authorization: Bearer sk_test_your_secret_key_here"

A 200 with a group_payments array (possibly empty) confirms your key works. A 401 means the key is missing, malformed, or for the wrong environment.

Need Help?

If you’re having trouble with authentication:

1. Check that you’re using the correct API key format
2. Verify you’re using the right environment (sandbox vs live)
3. Ensure your API key has the necessary permissions
4. Contact support