Get started

Authentication

OAuth 2.0 client credentials. Your identity comes from the token, never from the request.

Get a token

Send your client_id and client_secret to POST /oauth2/token with grant_type=client_credentials. The token is valid for one hour. Request a new one shortly before it expires rather than on every call.

curl https://api.sandbox.paylumia.com/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=$PAYLUMIA_CLIENT_ID \
  -d client_secret=$PAYLUMIA_CLIENT_SECRET

Response

{
  "access_token": "eyJ0eXAiOi…",
  "token_type": "bearer",
  "expires_in": 3600
}

Call the API

Send the token as a Bearer on every /v1 request:

Header

Authorization: Bearer eyJ0eXAiOi…

The token identifies your application and its environment. Requests carry no application, partner or environment field: anything you send to that effect is ignored. Each route also checks that your application holds the matching capability (payments, capabilities, subscriptions).

Headers

Header	Direction	Required	Notes
`Authorization: Bearer`	Request	Always	Token from /oauth2/token
`Idempotency-Key`	Request	On POST /v1/payments	8–255 characters. Replays within 24 h return the original result.
`PayLumia-Signature`	Webhook	Always	HMAC of the webhook body. See Webhooks.

No URL signatures

PayLumia never asks you to sign query strings or the checkout URL. The Bearer token authenticates your server; the webhook signature authenticates ours.

Keep secrets secret

Call PayLumia from your server only. Never ship a client secret in a mobile app or a web page.
The client secret is shown once when the environment is created. Store it in a secret manager.
Rotating a secret affects one environment only: sandbox and production are independent.