Skip to content

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

  1. 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 text undefined.
  2. Concatenate with no separators: bodyString + applicationId + applicationSecret + apiKeyId + apiKeySecret.
  3. 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, not 10.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.