Secret keys
Every request must include your secret key as a Bearer token:The customer-id header
Many routes act on behalf of a specific merchant customer (a buyer or seller you
manage). These require a customer-id header alongside your secret key:
customer-id include wallet, confirm-payment, milestone
confirm, disputes (per-customer), payments, cards, and the crypto whitelist.
Payluk checks that the customer belongs to your merchant account and is active
before the request runs.
On the escrow and category routes the header is optional: send it to act as
one of your customers (the seller when creating), or omit it to act as your own
business account. Only a business-type account can sell on its own behalf.
Merchant-wide routes must not include a
customer-id header and refuse one
with customer-id is not allowed in request header:
List all customers’ disputes,
Get escrow feeds,
Resolve dispute & disburse,
Update additional fee,
every vault route, and the
merchant account routes.Merchant super-admin routes
Two kinds of key can call this API:
A non-super-admin key calling a super-admin route gets
401 Access denied, and
any customer-id it sends is ignored.
Rate limits
Each secret key may make 10 requests per minute across all/v1 routes,
wherever the calls come from. Beyond that the API answers
429 Too many request until the window resets. Every response carries the
IETF RateLimit and RateLimit-Policy headers, so read them and back off
before you are cut off rather than retrying on 429.
IP allowlist
On production you can restrict a key to known servers by adding their IP addresses to the allowlist in your dashboard. Once at least one address is listed, requests from any other address are refused with403 Unauthorized IP address. An empty allowlist admits every address. Staging
never checks the caller’s IP.