Skip to main content

​
Overview

Zupy uses API key authentication for all partner API access. Each restaurant (company) you integrate with gets its own API key, provisioned by the Zupy team during onboarding.
  • One key per restaurant — if you integrate with 3 restaurants, you receive 3 API keys
  • No OAuth flows — authenticate once per request with a single header
  • No self-service — keys are provisioned by Zupy ops, not generated in a dashboard

​
API Key Format

All partner API keys follow this format: 
zupy_pk_ + 32 alphanumeric characters
Example: 
zupy_pk_abc123def456ghi789jkl012mno345pq
API keys are generated by the Zupy team and delivered to you during onboarding. You cannot create or rotate keys yourself.

​
Authentication Flow

1

Zupy provisions your key

During onboarding, the Zupy team creates your API key and assigns it to a specific restaurant (company). You also receive your webhook URL.
2

You receive credentials

You receive your zupy_pk_* API key, the company ID, and your integration slug (e.g., repediu).
3

Include X-API-Key in every request

Add the X-API-Key header to all API requests. No Authorization: Bearer — just the header and the key.

​
Making Authenticated Requests

Include your API key in the X-API-Key header on every request: 
curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511987654321" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

​
Access Levels

API keys have two access levels, configured by Zupy during onboarding:
LevelCan DoCannot Do
Read-onlySearch customers, view points/rewards/coupons, list programsAward points, redeem rewards, validate coupons
Read-writeEverything above + award points, redeem rewards, validate couponsN/A
If you attempt a write operation with a read-only key, you receive a 403 Forbidden error.

​
Error Handling

All authentication errors follow the RFC 7807 Problem Details format. 
{
  "type": "https://api.zupy.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Invalid API key"
}

​
Rate Limits

API requests are rate-limited per API key. Your tier is assigned during onboarding.
TierRequests/minAssigned To
Free60Default for new integrations
Standard300Active partners (e.g., Repediu, Saipos)
Enterprise3,000High-volume partners
Every response includes rate limit headers: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1711108800
The Retry-After header (seconds to wait) is only included in 429 responses. When you receive a 429, wait for the Retry-After duration before retrying.

​
OTP — Optional Per-Integration

OTP (One-Time Password) provides extra customer verification. OTP is NOT required for all partners — it depends on your integration’s trust level, configured by Zupy during onboarding.
ActionOTP Possible?Depends On
Search customersNever—
View points balance/historyNever—
Award pointsNeverB2B operation
List rewards/couponsNever—
Redeem rewardPer configrequire_otp_for_redemption
Validate/use couponPer configrequire_otp_for_coupon_usage
Send webhookNever—
PartnerEnrollment OTPRedemption OTPCoupon OTPTrust PartnerRationale
RepediuNoNoNoYesiFood/Rappi already verify customer identity
GoomerNoYesYesNoOpen tablet — customer types phone, no prior verification
SaiposNoYesYesYesPOS identifies customer, but coupon usage needs confirmation
If your integration requires OTP for certain actions, see the OTP Flow guide for the complete 3-step verification process.

​
Security Best Practices

Never expose API keys in frontend or client-side code. All API calls must go through your backend server.
  • Always use HTTPS — HTTP requests are rejected
  • Store keys in environment variables — never hardcode in source code
ZUPY_API_KEY=zupy_pk_your_api_key_here
ZUPY_BASE_URL=https://api.zupy.com/api/v2
  • One key per restaurant — do not share keys between companies
  • Contact Zupy immediately if you suspect a key has been compromised

​
Next Steps

Quick Start

Get your first API call working in under 15 minutes

Webhook Setup

Send order data to Zupy for automatic loyalty processing

OTP Flow

Implement customer identity verification when required