Authentication

All Merchant API endpoints are authenticated using API Keys. Every request must include your secret key in the Authorization header.

---

API Keys

IvoryPay issues two keys per environment:

Key Type	Prefix	Use
Secret Key	sk_	Server-side API calls. Never expose this publicly.
Public Key	pk_	Client-side, read-only contexts.

Use the Secret Key for all Merchant API requests.

---

Environments

Each key is scoped to a single environment at generation time. There is no environment header to pass — the key itself determines which environment the request runs in.

Environment	Key Example	Behaviour
TEST	sk_test_xxxx...	Sandbox. No real money moves.
LIVE	sk_live_xxxx...	Production. Real transactions.

Always use your TEST key during development and integration testing.

---

Generating API Keys

API keys are generated from the IvoryPay Dashboard:

Dashboard → Settings → API Keys → Generate Keys

Generating new keys immediately invalidates the previous key pair for that environment. Store your keys securely — they are only shown once.

---

Sending the API Key

Pass your secret key directly in the Authorization header — no Bearer prefix:

Authorization: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Example

BASE_URL="https://api.ivorypay.io/api"

curl $BASE_URL/crypto-transfer \
  -H "Authorization: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

---

What Happens on Each Request

Your API key is your secure identifier — it tells IvoryPay who you are, which business you belong to, and which environment you're operating in. Every request to the Merchant API must carry it. Requests without a valid key will be rejected immediately.

---

Security Best Practices

• Never expose your secret key in frontend code, mobile apps, or public repositories.

• Store keys in environment variables (e.g. process.env.IVORYPAY_SECRET_KEY).

• Rotate your keys immediately if you suspect a compromise — generate a new pair from the Dashboard.

• Use TEST keys in staging and CI environments; never use LIVE keys outside production.

• Restrict access to the server or service that holds the key using firewall rules where possible.

---

Error Responses

Status	Message	Cause
401	Unauthorized	Authorization header is missing
400	Invalid key	Key does not exist or has been rotated
400	Account not found	The user tied to the key was deleted
400	Your account is inactive. Please contact support	Business or user account suspended