Platform, Auth, and Tenant

Platform Model

PekoPay uses a tenant-based API model.

• Every merchant account is a tenant.
• Most endpoints are tenant-scoped using /tenants/:tenantId/....
• External server-to-server calls use Basic auth with clientId:clientSecret.

Typical flow:

1. Obtain tenantId and API credentials (clientId, clientSecret).
2. Generate a payment token.
3. Use embedded checkout to capture card details.
4. Use the payment token in transaction or subscription APIs.
5. Consume async lifecycle updates through webhooks.

Environments and Base URLs

• Production: https://gateway.peko-pay.com
• Sandbox: https://sandbox-api.peko-pay.com

Recommended external onboarding path:

1. Create a sandbox account in the PekoPay portal.
2. Configure sandbox business credentials and webhooks.
3. Build and validate integration in sandbox.
4. Switch to production credentials and base URL.

Authentication and tenantId

Basic auth

• Header: Authorization: Basic <base64(clientId:clientSecret)>

AUTH=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64)
 
curl -X GET "${BASE_URL}/tenants/${TENANT_ID}/customers" \
  -H "Authorization: Basic ${AUTH}"

tenantId

tenantId is the business id shown in the API Credentials page in the PekoPay portal.

tenantId is required in URL paths for tenant-scoped resources:

• /tenants/:tenantId/customers
• /tenants/:tenantId/products
• /tenants/:tenantId/plans
• /tenants/:tenantId/subscriptions
• /tenants/:tenantId/transactions
• /payment-token/:tenantId/generate

API Credentials (clientId/clientSecret)

From API Credentials in the PekoPay portal, copy and securely store:

• id as clientId
• clientSecret

Important:

• clientSecret is returned only at creation time.
• Store it in a secret manager.
• Rotate by creating a new client if it is lost or compromised.