Partner Onboarding

This guide walks you through the complete onboarding process — from receiving your credentials to going live in production.

What Zupy Provides

When your partnership is activated, the Zupy team provides:

Item	Format	Description
API Key(s)	`zupy_pk_*`	One key per restaurant (company) you integrate with
Integration Slug	e.g., `repediu`	Your unique identifier for webhook URLs
Webhook URL	`https://api.zupy.com/api/v2/webhooks/integrations/{slug}/`	Endpoint for sending order data
Company ID(s)	KSUID strings	IDs for each restaurant in the Zupy system
OTP Policy	strict / relaxed / trusted	Which actions require customer OTP verification
Rate Limit Tier	Free / Standard / Enterprise	Your request quota (60 / 300 / 3,000 req/min)
Documentation	This portal	Full API reference and integration guides

Credentials are shared via a secure channel (encrypted email or password manager). Never share API keys via plain text chat (Slack, WhatsApp, etc.).

Your API key is shown only once, at creation. Zupy stores only a hash of it — we cannot retrieve the full key later, so save it immediately in your secrets manager. If it is lost or compromised, it can be rotated (the old key stops working instantly and a new one is issued). Each company has exactly one active zupy_pk_ key.

Your key reaches only the endpoints in this documentation (the partner contract). Every other v2 endpoint returns 403 for a partner key — see Authentication → Endpoint allowlist.

What You Configure

After receiving your credentials, set up your integration:

Store API Keys Securely

Store your API keys as environment variables or in a secrets manager. Never hardcode keys in source code or expose them in client-side code.

# .env (add to .gitignore!)
ZUPY_API_KEY=zupy_pk_your_api_key_here
ZUPY_BASE_URL=https://api.zupy.com/api/v2
ZUPY_INTEGRATION_SLUG=your-partner-slug

import os

API_KEY = os.environ["ZUPY_API_KEY"]
BASE_URL = os.environ.get("ZUPY_BASE_URL", "https://api.zupy.com/api/v2")
HEADERS = {"X-API-Key": API_KEY}

const API_KEY = process.env.ZUPY_API_KEY;
const BASE_URL = process.env.ZUPY_BASE_URL || "https://api.zupy.com/api/v2";

Configure Webhook Sending

Set up your system to send order data to Zupy’s webhook endpoint. See the Webhook Setup guide for payload format and examples.Your webhook URL:

POST https://api.zupy.com/api/v2/webhooks/integrations/{your-slug}/

Implement Customer Lookup

Use the Customer Search API to look up customers by phone, email, or name:

GET /api/v2/customers/?phone=5511987654321

See the Getting Started guide for code examples.

Implement Points Flow

If your integration needs to display points or award them directly (beyond webhooks):

View balance: GET /api/v2/customers/{id}/points/
Award points: POST /api/v2/customers/{id}/points/add/
View history: GET /api/v2/customers/{id}/points/history/

Implement OTP Flow (If Required)

If your OTP policy requires verification for redemption or coupon usage, implement the OTP Flow in your customer-facing UI.

Trusted partners (e.g., Repediu) can skip this step — OTP is not required for any action.

Implement Error Handling

Handle RFC 7807 error responses from the API:

Status	Action
401	Check your API key
403	Complete OTP flow or check access level
429	Wait for `Retry-After` header, then retry
400/422	Fix request body based on `detail` field

Testing Checklist

Before going live, verify each integration point works correctly:

Verify API Key

Send a simple customer search to confirm your key is valid:

curl -s -o /dev/null -w "%{http_code}" \
  -X GET "https://api.zupy.com/api/v2/customers/?phone=0000000000" \
  -H "X-API-Key: zupy_pk_your_api_key_here"
# Expected: 200

curl -s -o /dev/null -w "%{http_code}" \
  -X GET "https://api.zupy.com/api/v2/customers/?phone=0000000000"
# Expected: 401

Send Test Webhook

Send a test order payload and verify a 200 response. The payload format is partner-specific — the example below uses Repediu’s format. Replace the fields with your own payload structure:

curl -X POST "https://api.zupy.com/api/v2/webhooks/integrations/{your-slug}/" \
  -H "X-API-Key: zupy_pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[{"cliente":"Test Customer","Celular":"+5511999888777","Valor":"50.00","id_venda":999999,"DataVenda":"2026-03-23T12:00:00.000Z","loja_cnpj":"00.000.000/0001-00","loja_nome":"Test Store","Email":null,"CpfCnpj":null}]'

The webhook accepts any JSON payload. Zupy processes it using your partner-specific adapter. See the Webhook Setup guide for your payload format.

Expected response:

{"data": {"status": "received", "id": "..."}, "meta": {}}

Verify Customer Created

After the webhook processes (wait a few seconds), search for the test customer:

curl -X GET "https://api.zupy.com/api/v2/customers/?phone=5511999888777" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

Verify the customer exists and has the expected points balance.

Verify Points Awarded

Check the customer’s points balance matches the order value:

curl -X GET "https://api.zupy.com/api/v2/customers/{customer_id}/points/" \
  -H "X-API-Key: zupy_pk_your_api_key_here"

Test OTP Flow (If Applicable)

If your policy requires OTP for redemption or coupon usage:

Request OTP: POST /api/v2/auth/request-otp/
Verify OTP: POST /api/v2/auth/verify-otp/
Redeem with session: Include X-OTP-Session header

See the OTP Flow guide for full examples.

Test Error Handling

Verify your integration handles errors gracefully:

Send a request without X-API-Key → expect 401
Send invalid JSON → expect 400
Send the same webhook twice → expect 200 with "status": "duplicate"

Go-Live Checklist

Before declaring your integration production-ready:

Infrastructure

API key stored securely (environment variable or secrets manager)
All API calls use HTTPS (HTTP is rejected)
All API calls go through your backend server (never client-side)
Retry logic implemented for 429 rate limit responses
Error logging configured for API failures

Integration

Webhook sending configured with correct URL and API key
Customer lookup working for phone, email, and/or name search
Points display integrated (if showing points to customers)
OTP flow implemented (if required by your policy)
Idempotency tested — duplicate webhooks return "status": "duplicate"

Monitoring

API error rates tracked (401, 403, 429, 5xx)
Webhook delivery success rate monitored
Support contact established with Zupy team

Communication

Production API key received and deployed
Rate limit tier confirmed with Zupy
OTP policy confirmed with Zupy
Support escalation path established (both sides)

Do not go live without completing the testing checklist. Untested integrations risk awarding incorrect points, failing silently on errors, or creating duplicate customer records.

Rate Limit Tiers

Tier	Requests/min	Assigned To
Free	60	Default for new integrations
Standard	300	Active partners (Repediu, Saipos)
Enterprise	3,000	High-volume partners

Your tier is assigned during onboarding. Contact Zupy to request a tier upgrade.

Webhook batching reduces API calls. A single webhook with 100 orders counts as 1 request. Batch your orders to stay well within limits.

Support

Channel	Contact
Technical support	webmaster@zupy.com.br
Documentation	This portal

Next Steps

Getting Started

Make your first API call in under 15 minutes

Webhook Setup

Configure webhooks for automatic order processing

OTP Flow

Implement customer identity verification

API Reference

Browse all endpoints with request/response schemas

Introduction

Guides

What Zupy Provides

What You Configure

Testing Checklist

Go-Live Checklist

Infrastructure

Integration

Monitoring

Communication

Rate Limit Tiers

Support

Next Steps

Getting Started

Webhook Setup

OTP Flow

API Reference

​What Zupy Provides

​What You Configure

​Testing Checklist

​Go-Live Checklist

​Infrastructure

​Integration

​Monitoring

​Communication

​Rate Limit Tiers

​Support

​Next Steps

Getting Started

Webhook Setup

OTP Flow

API Reference

What Zupy Provides

What You Configure

Testing Checklist

Go-Live Checklist

Infrastructure

Integration

Monitoring

Communication

Rate Limit Tiers

Support

Next Steps