Authentication

Your API key tells SavaPay which merchant account is making a request. Treat it like a password.

Use your key on the server only

Send your key from your server using the Authorization header or X-API-Key header. Never include it in browser JavaScript or a mobile app.

Authorization: Bearer sp_live_...
# or equivalently:
X-API-Key: sp_live_...

You only see a new key once

When SavaPay creates an API key, copy it and store it in a secure environment variable immediately. SavaPay stores only a protected version, so it cannot show the key again.

Use the smallest permission needed

• Scoped: keys carry specific scopes, such as webhooks:write. A webhook-management key should not automatically access unrelated actions.
• Revocable: revoke an exposed or unused key with DELETE /v1/api-keys/{keyHash}.
• Never administrator: merchant keys never grant administrator access. Administrator endpoints require SavaPay administrator authentication.

Avoid duplicate actions

Add an Idempotency-Key header whenever a request changes data. Retrying the same request will not accidentally charge, refund, or create something twice.

Idempotency-Key: checkout-order-123

Getting ready to accept payments

1. Create your merchant account with POST /v1/merchants. It is public and returns your first API key once.

{
  "merchant": { "id": "m_1abc", "businessName": "Acme", "status": "pending" },
  "apiKey": "sp_live_..."
}

2. Submit the required business information and documents through POST /v1/merchants/{id}/kyc and the document upload endpoint.
3. Wait for SavaPay to approve the account.
4. Confirm that your merchant status is active.
5. Start accepting production payments.

Key management

Issue additional scoped keys with POST /v1/api-keys and revoke them with DELETE /v1/api-keys/{keyHash}.