Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lyelpay.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Lyel Pay uses two authentication mechanisms depending on the context: API Keys and Bearer tokens (JWT). In most flows, both are used together.

​
API Keys

An API key identifies your merchant account. Every request must carry it.

​
Where to get your key

Go to your dashboard → Settings → API Keys. You can generate multiple keys and rotate them independently.

​
How to send it

x-api-key: YOUR_API_KEY
API keys are sent as a request header, not in the URL or query string.
Never expose your API key in client-side JavaScript or a public repository. Use environment variables.

​
Bearer tokens (JWT)

Some endpoints — particularly those that act on behalf of a specific user (e.g., initiating a payment from a user’s wallet) — require a short-lived JWT in addition to the API key. The token is obtained by authenticating the user via the /auth/web endpoint: 
POST /auth/web
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "phoneNumber": "+242XXXXXXXX",
  "password": "user_web_password"
}
Response: 
{
  "id": "user_abc123",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "phoneNumber": "+242XXXXXXXX",
  "roles": ["USER"]
}
Then pass both headers on subsequent requests: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-api-key: YOUR_API_KEY

​
OTP tokens

The four-step payment flow adds a third layer: an OTP-derived token that authorizes the specific transaction.
StepWhat happens
initOtp()Lyel Pay sends an OTP to the user via SMS or email
verifyOtp()You send the OTP back; Lyel Pay validates it and stores an authorization token in the SDK instance
charge()The token is automatically included; the transaction executes
In the browser SDK, the token is held in memory in the LyelPay instance (not persisted). It is scoped to one transaction.

​
Authentication by SDK

SDKMechanism
@lyel/lyel-pay (browser)apiKey in constructor + JWT from initOtp/verifyOtp flow
@lyel/lyel-pay-nodesecretKey in constructor (Bearer token sent as Authorization header)
react-lyel-pay-jsapiKey + clientSecret in loadLyelPay()

​
Security checklist

  • Store API keys in environment variables, never in source code
  • Use HTTPS for all requests (enforced by the API)
  • Validate webhook signatures on your server before processing events (see Webhooks)
  • Rotate API keys periodically from the dashboard