Integration Guide

Authentication

You will need API keys for both the test and live environments. You can generate these keys from your SureGifts Merchant Dashboard under Developer → API Keys

Public Key → Username in Basic Auth.
Secret Key → Password in Basic Auth.
Combine as PUBLIC_KEY:SECRET, Base64 encode, and include in the header:
```
Authorization: Basic BASE64(PUBLIC_KEY:SECRET)
```
Never expose keys in version control or client-side code. Store them securely in environment variables or a secrets manager.

Environments

The API provides two environments. Configure your application to use the correct base URL and API keys based on the active environment.

1. Test Environment

Purpose: Development and integration testing.

Base URL:

https://staging-onlinemerchants.suregifts.com

Use Case: Test API calls without affecting production data.

2. Live Environment

Purpose: Production use.
Base URL:
```
https://onlinemerchants.suregifts.com
```
Use Case: Only use after thorough testing in the test environment; all actions affect real data.

.env Template:

# Test
SG_ENV=test
SG_BASE_URL=https://staging-onlinemerchants.suregifts.com
SG_PUBLIC_KEY=pk_test_********************************
SG_SECRET=sk_test_********************************

# Live
# SG_ENV=live
# SG_BASE_URL=https://onlinemerchants.suregifts.com
# SG_PUBLIC_KEY=pk_live_********************************
# SG_SECRET=sk_live_********************************

Allowed IPs

The SureGifts API requires requests to come from approved outbound IP addresses.

Steps to Configure:

Log in to your SureGifts Business Dashboard.
Go to Developer → Allowed IPs.
Enter your outbound public IP(s) or CIDR ranges.
Click Save.

Accepted Formats:

# Single IP
203.0.113.10

# CIDR Range
198.51.100.0/25

# Multiple IPs/ranges
203.0.113.10, 198.51.100.0/25

Tips:

Prefer static egress IPs.
Avoid 0.0.0.0/0 or ::/0 except for temporary troubleshooting.
Include all outbound IPs if using multiple data centers or regions.

Security Best Practices

Rotate keys quarterly or if compromised.
Restrict dashboard access (least privilege + MFA).
Redact sensitive data from logs.
Always use HTTPS.

Go-Live Checklist ✅

Test all API endpoints in staging (both success and error cases).
Confirm Base URL and API keys are loaded from environment variables.
Ensure Allowed IPs match your actual outbound IPs.
Implement retries (exponential backoff with jitter) and timeouts.
Centralize structured logging (requestId, endpoint, latency, status).
Add health checks and alerting for elevated error rates.
Document runbooks for key rotation and IP updates.

Resilience Recommendations

Timeouts: 10–30s (shorter for GETs).
Retry Policy: Exponential backoff with jitter.
Idempotency: Use unique request IDs for safe retries on writes.

Governance & Ops

Track changes to URLs, keys, and IPs with timestamps.
Emit metrics for requests, latency, and errors.
Securely back up non-secret configuration.
Maintain disaster recovery plans.