Authentication

4pay.online supports two authentication methods for partner API access.

---

Method 1 — API Key (recommended)

Pass your API key in the x-api-key request header, together with x-organization-id. Two headers, not one: the key is resolved inside the organization the header names, and a request carrying the key alone is refused before the key is even read. Treat both 400 and 401 as "these credentials are not usable": some endpoints answer the missing organization header with a bare 400 Bad Request rather than 401. Your operator gives you both values together. This is the simplest and most common method for server-to-server integrations.

curl https://4pay.online/api/v1/transactions \
  -H "x-api-key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

Where to find your API key:

1. Log in to Partner Area
2. Go to Settings → API Keys
3. Click Create Key — copy the value immediately, it is shown only once

Keep your API key secret

Store API keys in environment variables. Never commit them to source control or include them in client-side code.

---

Method 2 — Bearer Token (session-based)

For interactive applications, you can authenticate with a login/password to obtain a Bearer token.

Create a session

curl -X POST https://4pay.online/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{
    "type": "partner",
    "login": "your-login",
    "password": "your-password"
  }'

Response:

{
  "token": "b7f0c9d2-1e4a-4c8b-9f31-2a5d6e7c8b90",
  "refresh_token": "1acdd2f3-299a-4213-a2df-39b6fae4d165",
  "inserted_at": 1788434490,
  "expire_at": 1789039290
}

The expiry field

It is expire_at — singular, and Unix seconds, not an ISO 8601 string. Code written against an expires_at timestamp reads undefined and treats the token as immortal, then starts failing a week later with no obvious cause. A session lasts seven days.

Use the token

curl https://4pay.online/api/v1/transactions \
  -H "Authorization: Bearer eyJhbGci..."

Refresh a session

curl -X PUT https://4pay.online/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "1acdd2f3-299a-4213-a2df-39b6fae4d165"
  }'

End a session

curl -X DELETE https://4pay.online/api/v1/session \
  -H "Authorization: Bearer eyJhbGci..."

---

Comparison

	API Key	Bearer Token
Setup	One-time, no expiry	Login required each session
Best for	Server-to-server integrations	Interactive / dashboard apps
Header	x-api-key: YOUR_KEY	Authorization: Bearer TOKEN
Revocation	Delete key in Partner Area	DELETE /session or key expiry

---

HTTP Response Codes

Code	Meaning
200	Success
201	Resource created — not proof the payment was accepted; read status
400	Bad Request — malformed body, or a missing x-organization-id
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid credentials but insufficient permissions
422	Validation error — check the errors field in the response
429	Rate limited — slow down requests
500	Internal server error — contact support