Authentication¶
Every call carries an API key id and a SHA-1 request signature, comes from an IP address Payard has confirmed, and needs a valid licence for the selected environment. All four must pass, or the call is refused with 403 ACCESS_DENIED.
Credentials¶
| Credential | What it is | Sent? |
|---|---|---|
| Merchant application ID | UUID of your application | No, only signed |
| Merchant application secret | Shared secret of the application | No, only signed |
| API key ID | UUID of the key | Yes, x-api-key header |
| API key secret | 40-character lowercase hex, shown once at key creation | No, only signed |
| API key type | PAYMENT_ONLY, CLIENT_ACCESS, ADVANCED_ACCESS or FULL_ACCESS |
— |
Keep both secrets on your servers only. Never log signed requests together with their headers.
Request headers¶
| Header | Required | Value |
|---|---|---|
x-api-key |
yes | API key ID |
signature |
yes | Lowercase hex SHA-1, see below |
Content-Type |
with a body | application/json |
x-env |
no | PROD for production; anything else, or absent, means SANDBOX |
Do not send an Authorization header: it is reserved for dashboard sessions.
Signing a request¶
- Take the body string: the exact compact JSON you send. If there is no body, or the body is
{}or[], use the literal 9-character textundefined. - Concatenate with no separators:
bodyString + applicationId + applicationSecret + apiKeyId + apiKeySecret. - Hash the UTF-8 bytes with SHA-1 and send the lowercase hex digest in
signature.
The method, path, query string and other headers are not signed. The server re-serialises your body the way JavaScript's JSON.stringify does, so serialise once, compactly, and send that exact string:
- no whitespace between tokens; keep key order; no duplicate keys;
- do not escape non-ASCII characters or
/; - numbers in shortest form (
10, not10.0); prefer integers; - avoid object keys that look like integers (
"0","42"): JavaScript reorders them.
Test vectors (fake credentials): application 3f6c1d2e-8b4a-4f0e-9c7d-2a1b5e6f7a80 / app-secret-example, key 9b2e7c4d-1f3a-4e5b-8c6d-7e8f9a0b1c2d / 5f1d7c0e9a3b2c4d6e8f0a1b2c3d4e5f6a7b8c9d.
| Body | Signature |
|---|---|
{"types":["PAYMENT_ONLY"]} |
7f7bddb6e3eb249c1ee62134766d7dcd7aa56694 |
| (no body) | 73fbe4e67ec3a9f9143467a8f079e5c3fbd441ce |
// Node.js
const crypto = require('crypto');
function sign(bodyString) {
const data = `${bodyString}${APP_ID}${APP_SECRET}${API_KEY_ID}${API_KEY_SECRET}`;
return crypto.createHash('sha1').update(data, 'utf8').digest('hex');
}
async function payard(method, path, body, env = 'SANDBOX') {
const empty = body == null || (typeof body === 'object' && Object.keys(body).length === 0);
const bodyString = empty ? undefined : JSON.stringify(body); // serialise once
const headers = { 'x-api-key': API_KEY_ID, signature: sign(empty ? 'undefined' : bodyString), 'x-env': env };
if (bodyString) headers['Content-Type'] = 'application/json';
const res = await fetch(`${BASE_URL}${path}`, { method, headers, body: bodyString });
const text = await res.text();
return { status: res.status, body: text ? JSON.parse(text) : null };
}
# Python: send data=, never json= (requests re-serialises json= with spaces)
import hashlib, json, requests
def payard(method, path, body=None, env="SANDBOX"):
empty = body is None or (isinstance(body, (dict, list)) and len(body) == 0)
body_string = None if empty else json.dumps(body, separators=(",", ":"), ensure_ascii=False)
data = f"{'undefined' if empty else body_string}{APP_ID}{APP_SECRET}{API_KEY_ID}{API_KEY_SECRET}"
headers = {"x-api-key": API_KEY_ID, "signature": hashlib.sha1(data.encode()).hexdigest(), "x-env": env}
if body_string:
headers["Content-Type"] = "application/json"
return requests.request(method, BASE_URL + path, headers=headers,
data=body_string.encode() if body_string else None)
In PHP, encode with JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE. In shell, hash with printf '%s', not echo, which adds a newline.
IP allow-list¶
Send Payard the public egress IP addresses of your servers (test and production). Payard registers and confirms them; there is no self-service endpoint. The match is an exact string, the address must be public, and traffic through a proxy or NAT is seen with the proxy's address.
Licence and environment¶
The x-env header picks which licence must be valid: PROD (case-insensitive) or, for anything else, SANDBOX. A typo such as PRODUCTION silently selects sandbox. The licence must be ACTIVE, inside its dates and current billing period, paid or on trial, and not OVERDUE.
API key types¶
Types form a hierarchy: PAYMENT_ONLY < CLIENT_ACCESS < ADVANCED_ACCESS < FULL_ACCESS. A key accepts every endpoint that requires its type or a lower one.
| Area | Minimum key type |
|---|---|
Transactions (payins), payment instructions, preauth, refunds, core/* helpers |
PAYMENT_ONLY |
| Payers (users) and their bank accounts | CLIENT_ACCESS |
| Webhook registrations | CLIENT_ACCESS |
| Reading payment systems, provider bindings, provider configurations | CLIENT_ACCESS |
| Payouts and payout destinations | ADVANCED_ACCESS |
| API key management | FULL_ACCESS |
You issue PAYMENT_ONLY, CLIENT_ACCESS and ADVANCED_ACCESS keys yourself in the dashboard; FULL_ACCESS keys only Payard issues. Give each system the lowest type that works: a checkout backend needs PAYMENT_ONLY, a payout service ADVANCED_ACCESS.
When authentication fails¶
Every failure is 403 with errorCode: ACCESS_DENIED. Only detailedMessage tells the stages apart.
detailedMessage |
Likely cause |
|---|---|
Unauthorized. Please check your credentials and try again. |
Missing header, unknown or disabled key, disabled application, wrong signature, or an IP address that is not registered and confirmed |
Merchant license check failed |
Key type too low for the endpoint, or no valid licence for the selected x-env |
Forbidden resource / Access denied |
The endpoint is internal or dashboard-only |
The authenticated API applies no request-rate limit today; throttle on your side anyway.