Base URL and formats

Base URL

https://payniko.com/api. The path does not include a version.

Format

JSON, UTF-8 encoded. Errors use application/problem+json.

Amounts

Strings with two decimal places, for example "100.00". Never send amounts as JSON numbers.

Currency

USD, EUR, AED or TRY. If currency is omitted, the system main currency applies.

Time

ISO 8601 in UTC with milliseconds, for example 2026-11-01T12:00:00.000Z.

IDs

Payment, refund, withdrawal and dispute IDs use LUVEI-ABCD-123456. Store the complete ID.

Language

Messages are returned in the language set by Accept-Language (en, tr, de, ar, es, el); the default is en. Codes and field names are never translated.

Getting your API keys

New accounts receive Sandbox and Live keys automatically. If you have an account, sign in and open Access keys. If you received an account file, sign in with its username and password; do not register again.

1. Create your account

1. Create an account. Enter an email address you use and press Send code. Enter the six-digit code from the email on the registration page, then press Verify. If it does not arrive, check the address and spam folder; request another code after the countdown ends.

2. After email verification, select your country code and enter the phone number linked to your own Telegram account. Press Verify beside it. Verification takes place in Telegram; no SMS is sent.

3. Open the Telegram link shown on the page, or scan its QR code with your phone if using a computer. Press Start in the bot, then use its share-phone-number button to share your own number. Typing a number as a message or sending someone else’s contact does not verify it. Return to registration and wait for the verified status.

4. Press Continue to account details. Choose a username and password, repeat the password, complete the confirmations on screen, then press Create account. A username has 4–32 characters: lowercase letters, digits, dots, underscores or hyphens. A password needs at least 12 characters.

5. Save the recovery code displayed after account creation in a safe place. It is shown only on this screen and is different from an API secret. Confirm you saved it and press I saved the code, continue.

2. Get Sandbox keys and your merchant code

1. Open Access keys and find the Sandbox card. New accounts already have keys. If an older account has no active key, enter an optional label and press Generate key. No IP registration is needed.

2. Collect the three values below from the Sandbox card. Use the eye icon in the Secret row to reveal it, or the copy icon to copy it. The account owner can view an active secret again; you do not need to rotate a key just to view it.

3. Share these values securely with your integration developer or store them in your server’s private configuration. The API key and secret must come from the same Sandbox card. Never put the secret in browser JavaScript, public files or a URL.

Creating a test payment

Test your integration in Sandbox without moving real funds. A successful test is not a requirement for Live keys; it is recommended to verify signing, redirects and webhooks.

1. Use a server example from Request helper functions. Configure it with your Sandbox API key, Sandbox secret and merchant code. Sandbox has no separate API hostname: use the documented base URL; the key determines the environment.

2. Check the Sandbox amount limits and available currencies under Payment experience. Choose an amount within those limits. For your first successful test, do not use an amount ending in .77: that triggers the pending test scenario.

3. Fill in the fields in the POST /api/payments/hosted example: a unique merchant_order_id, amount, currency, customer.email / customer.phone, and the three notification/return URLs. Use reachable contact details and a phone number with its country code. webhook_url must be a public HTTPS endpoint on your server; localhost and private network addresses are not accepted even in Sandbox. success_url / fail_url are your browser return URLs.

4. Send the signed POST /api/payments/hosted request from your server. Use a new order reference and Idempotency-Key for a new test. When retrying the identical request after a connection error, keep the same Idempotency-Key. A 201 response means the payment was created, not that it succeeded.

5. Open the full next_action.url returned in the response in a browser. On the Sandbox payment form, use test card 4000000000000002, a future expiry date and any three-digit CVV; for example 12/30 and 123. Complete the successful/approved outcome on the test 3D Secure screen. Do not use a real card. Other scenarios are listed under Test cards.

6. After the browser return, query the payment with GET /api/payments/{payment_id} or process a webhook after verifying its signature. The API status must be succeeded. requires_action / processing are intermediate states; failed does not count as success. Opening a success return page alone is not proof of payment.

7. Check the test result under Request activity. A successful record completes this integration scenario. Live access uses its own key pair.

Getting your Live keys

Sandbox and Live use separate ready key pairs. Live keys require neither an IP registration nor a successful Sandbox transaction. Changing the panel environment does not change your server configuration.

1. Open Live access page and find the Live card. A new account already has Live keys; if an older account has none, use Generate key.

2. Take the API key and secret from that same Live card. The merchant code is the same as in Sandbox. Store the secret only in your server’s private configuration.

3. Use this Live key pair in your production server configuration instead of the Sandbox pair. The API URL stays the same. Sandbox keys remain valid for testing; simply viewing a card in the panel does not change your server configuration.

4. Check Live limits and currencies under Payment experience. Your Live keys are now ready. Requests signed with Live keys enter the real payment flow; continue test-card testing with Sandbox keys.

If you get stuck

Endpoint overview

All endpoints use the same authentication, and every POST additionally requires an Idempotency-Key.

API key and secret

Every API key belongs to exactly one environment, sandbox or live, and the key determines the environment in which a request runs: use the sandbox key for testing and the live key for real payments. The X-Environment header is optional; if it is omitted, the request runs in the key's environment. If it is sent, its value must be sandbox or live (case-insensitive) and must match the key's environment; otherwise the request is rejected with HTTP 401 and code 0055502, and nothing is processed. The required authentication headers are X-Api-Key, X-Merchant-Code, X-Timestamp and X-Signature, plus Idempotency-Key on every write request. The environment is not part of the string to sign. Every response body that contains environment (payments, balances, refunds and other resources) reports the environment that was used.

Key rotation

• Create a new key if the secret may have been exposed or when someone with access to it leaves. The previous key stops working immediately.
• Webhooks and return links for a payment are signed with the secret of the key that created the payment; this also applies to refund and dispute webhooks sent long after the payment. Retain the previous secret for as long as such events can still arrive.

Request headers

Send each X- header exactly once. Header values must not contain commas, line breaks or spaces.

Request signing

The string to sign consists of four values joined by line feeds: the timestamp, the HTTP method, the path and the SHA-256 hash of the body.

canonical   = X-Timestamp + "\n" + METHOD + "\n" + path + "\n" + hex(sha256(raw body))
X-Signature = hex(HMAC-SHA256(key = API secret, message = canonical))   // 64 lowercase hex characters

1. Encode the body as JSON once and hash exactly those bytes with SHA-256 (lowercase hex). For a request without a body, hash the empty string (e3b0c442…b855).

2. Use the path exactly as it appears in the URL, starting with /api/ and excluding the query string. For example, GET /api/payments/bin/540061?amount=100.00 signs /api/payments/bin/540061.

3. Compute the HMAC-SHA256 with the API secret as the key. Use the secret string as is; do not decode it.

4. Send the result in X-Signature, and send exactly the hashed bytes as the request body.

Timestamp tolerance

X-Timestamp must be within 300 seconds of Payniko server time, in either direction. Keep your server clock synchronised with NTP. If the deviation is larger, the request is rejected with 401 0055504, and detail contains the Payniko server time.

Signing example

Use these sample values to test your implementation. With this secret, timestamp and body, your code must produce exactly this signature.

e3c4a5b6d7e8f90112233445566778899aabbccddeeff0011223344556677889

{"merchant_order_id":"ORDER-2026-001","amount":"100.00","currency":"USD","webhook_url":"https://merchant.example/webhooks/payments","success_url":"https://merchant.example/payment/success","fail_url":"https://merchant.example/payment/failure","customer":{"email":"[email protected]","phone":"+37061234567"}}

dca2bae6e50c13c26b22b57e3c31161ba3174147060fcbf22b2ba99cc13560ae

1793534400
POST
/api/payments/hosted
dca2bae6e50c13c26b22b57e3c31161ba3174147060fcbf22b2ba99cc13560ae

5522c27ff0b49ffa4c44712ed5db350c1c5a2cbfc0c568edbce39cff59ca620c

POST /api/payments/hosted
X-Api-Key: api_0123456789abcdef0123456789abcdef
X-Merchant-Code: 123456
X-Timestamp: 1793534400
X-Signature: 5522c27ff0b49ffa4c44712ed5db350c1c5a2cbfc0c568edbce39cff59ca620c
Idempotency-Key: 6f1c2a9e-1d2b-4c1a-9f0e-3b7d5a2c8e41
Content-Type: application/json
Accept: application/json

Request helpers

Add one of these helpers to your server. It reads API_KEY, API_SECRET and MERCHANT_CODE from environment variables, signs the request and sends it. The other code examples use this helper.

#!/usr/bin/env bash
# payniko.sh - signed request helper (bash, curl, openssl).
# Usage: ./payniko.sh METHOD PATH [JSON_BODY] [IDEMPOTENCY_KEY]
# Reads API_KEY, API_SECRET and MERCHANT_CODE. The key decides sandbox or live.
# Optional: SANDBOX_SCENARIO adds the X-Sandbox-Scenario header (sandbox keys only).
set -euo pipefail
: "${API_KEY:?set API_KEY}" "${API_SECRET:?set API_SECRET}" "${MERCHANT_CODE:?set MERCHANT_CODE}"
BASE_URL="https://payniko.com"
method="$(printf '%s' "${1:?METHOD}" | tr '[:lower:]' '[:upper:]')"
target="${2:?PATH}"            # may include a query string; only the path is signed
body="${3-}"                   # sent byte-for-byte as hashed
idempotency_key="${4-}"
path="${target%%\?*}"
timestamp="$(date +%s)"
body_hash="$(printf '%s' "$body" | openssl dgst -sha256 | sed 's/^.* //')"
signature="$(printf '%s\n%s\n%s\n%s' "$timestamp" "$method" "$path" "$body_hash" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')"
args=(-sS --fail-with-body -X "$method" "$BASE_URL$target"
  -H "X-Api-Key: $API_KEY" -H "X-Merchant-Code: $MERCHANT_CODE" -H "X-Timestamp: $timestamp"
  -H "X-Signature: $signature" -H "Accept: application/json" -H "Accept-Language: en")
if [ -n "$body" ]; then args+=(-H "Content-Type: application/json" --data-binary "$body"); fi
if [ -n "$idempotency_key" ]; then args+=(-H "Idempotency-Key: $idempotency_key"); fi
if [ -n "${SANDBOX_SCENARIO-}" ]; then args+=(-H "X-Sandbox-Scenario: $SANDBOX_SCENARIO"); fi
curl "${args[@]}"
echo

// payniko.mjs - signed request helper (Node.js 20+, no dependencies).
import {createHash, createHmac, randomUUID} from 'node:crypto';

const base = 'https://payniko.com';
const key = process.env.API_KEY ?? '';
const secret = process.env.API_SECRET ?? '';
const merchant = process.env.MERCHANT_CODE ?? '';
if (!/^api_[0-9a-f]{32}$/.test(key) || !/^[0-9a-f]{64}$/.test(secret) || !/^[0-9]{6}$/.test(merchant)) {
  throw new Error('Set API_KEY, API_SECRET and MERCHANT_CODE.');
}

export async function api(method, path, body, idempotencyKey, extraHeaders = {}) {
  const url = new URL(path, base);
  if (url.origin !== base || !url.pathname.startsWith('/api/')) throw new Error('Invalid API URL');
  method = method.toUpperCase();
  const raw = body === undefined ? '' : JSON.stringify(body);   // hash and send the same bytes
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const canonical = [timestamp, method, url.pathname,
    createHash('sha256').update(raw, 'utf8').digest('hex')].join('\n');
  const signature = createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');
  const response = await fetch(url, {
    method,
    redirect: 'error',
    headers: {
      ...extraHeaders,
      'X-Api-Key': key, 'X-Merchant-Code': merchant,
      'X-Timestamp': timestamp, 'X-Signature': signature,
      'Accept': 'application/json', 'Accept-Language': 'en',
      ...(raw ? {'Content-Type': 'application/json'} : {}),
      ...(idempotencyKey ? {'Idempotency-Key': idempotencyKey} : {}),
    },
    ...(raw ? {body: raw} : {}),
  });
  const text = await response.text();
  const data = text ? JSON.parse(text) : null;
  if (!response.ok) {
    throw Object.assign(new Error(`${response.status} ${data?.code ?? ''} ${data?.detail ?? ''}`.trim()),
      {status: response.status, problem: data, correlationId: response.headers.get('x-correlation-id')});
  }
  return data;
}
export {randomUUID};

<?php
// payniko.php - signed request helper (PHP 8.1+ with the curl extension).
function payniko_api(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null, array $extraHeaders = []): ?array
{
    $base = 'https://payniko.com';
    $key = getenv('API_KEY') ?: '';
    $secret = getenv('API_SECRET') ?: '';
    $merchant = getenv('MERCHANT_CODE') ?: '';
    if (!preg_match('/^api_[0-9a-f]{32}$/', $key) || !preg_match('/^[0-9a-f]{64}$/', $secret)
        || !preg_match('/^[0-9]{6}$/', $merchant)) {
        throw new RuntimeException('Set API_KEY, API_SECRET and MERCHANT_CODE.');
    }
    $method = strtoupper($method);
    // Hash and send the same bytes.
    $raw = $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    $timestamp = (string) time();
    $canonical = implode("\n", [$timestamp, $method, explode('?', $path, 2)[0], hash('sha256', $raw)]);
    $headers = array_merge($extraHeaders, [
        'X-Api-Key: ' . $key,
        'X-Merchant-Code: ' . $merchant,
        'X-Timestamp: ' . $timestamp,
        'X-Signature: ' . hash_hmac('sha256', $canonical, $secret),
        'Accept: application/json',
        'Accept-Language: en',
    ]);
    if ($raw !== '') $headers[] = 'Content-Type: application/json';
    if ($idempotencyKey !== null) $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => false,
        CURLOPT_TIMEOUT => 60,
    ]);
    if ($raw !== '') curl_setopt($ch, CURLOPT_POSTFIELDS, $raw);
    $response = curl_exec($ch);
    if ($response === false) throw new RuntimeException('Network error: ' . curl_error($ch));
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $data = $response === '' ? null : json_decode($response, true);
    if ($status >= 400) {
        throw new RuntimeException($status . ' ' . ($data['code'] ?? '') . ' ' . ($data['detail'] ?? ''), $status);
    }
    return $data;
}

# payniko.py - signed request helper (Python 3.9+, standard library only).
import hashlib, hmac, json, os, re, time, urllib.error, urllib.request

BASE_URL = "https://payniko.com"
KEY = os.environ.get("API_KEY", "")
SECRET = os.environ.get("API_SECRET", "")
MERCHANT = os.environ.get("MERCHANT_CODE", "")
if not (re.fullmatch(r"api_[0-9a-f]{32}", KEY) and re.fullmatch(r"[0-9a-f]{64}", SECRET)
        and re.fullmatch(r"[0-9]{6}", MERCHANT)):
    raise SystemExit("Set API_KEY, API_SECRET and MERCHANT_CODE.")


def api(method, path, body=None, idempotency_key=None, extra_headers=None):
    method = method.upper()
    # Hash and send the same bytes.
    raw = b"" if body is None else json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
    timestamp = str(int(time.time()))
    canonical = "\n".join([timestamp, method, path.split("?", 1)[0], hashlib.sha256(raw).hexdigest()])
    signature = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    headers = dict(extra_headers or {})
    headers.update({
        "X-Api-Key": KEY, "X-Merchant-Code": MERCHANT,
        "X-Timestamp": timestamp, "X-Signature": signature,
        "Accept": "application/json", "Accept-Language": "en",
    })
    if raw:
        headers["Content-Type"] = "application/json"
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    request = urllib.request.Request(BASE_URL + path, data=raw or None, method=method, headers=headers)
    try:
        with urllib.request.urlopen(request, timeout=60) as response:
            text = response.read()
            return json.loads(text) if text else None
    except urllib.error.HTTPError as error:
        problem = json.loads(error.read() or b"{}")
        raise RuntimeError(f"{error.code} {problem.get('code')} {problem.get('detail')}") from None

Verify your setup

Retrieving the balance is a safe first call because it does not create anything.

./payniko.sh GET '/api/account/balance'

import {api} from './payniko.mjs';

const result = await api('GET', '/api/account/balance');
console.log(result);

<?php
require __DIR__ . '/payniko.php';

$result = payniko_api('GET', '/api/account/balance');
print_r($result);

from payniko import api

result = api("GET", "/api/account/balance")
print(result)

Repeated invalid signatures temporarily lock the key: 20 failures from the same address within 15 minutes lock it for 15 minutes, and 300 failures within an hour lock it for an hour (429 1000005 with Retry-After). Correct the signing logic before you retry.

Idempotency-Key

Every POST requires an Idempotency-Key. A request resent with the same key is executed only once and returns the original result, which makes retries after a timeout safe.

• Generate a new random key, such as a UUID, for every new operation, and store it with your order before you send the request.
• After a timeout or a network error, resend the same body with the same key.
• Never reuse a key with a different body; such a request is rejected with 409 (9000010, or 0055503 on the Direct API).
• If the original request is still in progress, the response is 409: 9000039 on the Hosted API (with integration.retryable: true), or 0055503 with metadata.retry_class: retry_same_request on the Direct API. Resend the same request after a short delay.
• Format: 8–128 characters from A-Z a-z 0-9 _ -. A missing or invalid key returns 422 1000009.
• A signed request (X-Timestamp and X-Signature) is bound to the first Idempotency-Key it is sent with, for 10 minutes; the same signature with a different key is rejected with 409 9000010. Generate a new timestamp and signature for every new operation. If this check is temporarily unavailable, the response is 503 1000011.

Request requirements

• Send only documented fields. Unknown fields are rejected with 422 1000001.
• POST requests must not include a query string. GET requests must not include a body and accept only the documented query parameters.
• The body must be a single JSON object nested no more than 7 levels deep, including the top-level object.
• Rate limits apply per IP address (600 requests per minute before authentication) and per key (300 requests per minute). On 429 (1000005), wait for the Retry-After interval, then retry with backoff. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

Authentication errors

Integration steps

1. Create the payment

   Your server calls POST /api/payments/hosted. Store the returned payment_id with your order.

2. Redirect the payer

   Redirect the browser to next_action.url or open it in a new tab; never load it inside an iframe.

3. The payer completes the payment

   The payer enters the card details. If the bank requires 3-D Secure, the page presents it. An interim decline at this stage is not final; the payment reaches a final status without any action on your side.

4. The payer returns

   The page displays the result with a short countdown, then redirects the browser with signed parameters to success_url (only if the payment succeeded) or to fail_url. See Return URL.

5. Confirm the result

   Wait for the webhook or call GET /api/payments/{payment_id}. Fulfil the order only when the status is succeeded.

Your server                          Payniko                        Payer's browser
 1  POST /api/payments/hosted  ─────►  201  status: requires_action
                               ◄─────  next_action.url
 2  redirect (303) ───────────────────────────────────────────────►  payment page
 3                                     card + 3-D Secure  ◄────────  payer pays
 4                                     ───────────────────────────►  success_url / fail_url
                                                                     (signed parameters)
 5  webhook  ◄───────────────────────  payment.succeeded / payment.failed
    GET /api/payments/{payment_id} ──►  current status

Payment object

Create and retrieve calls return this object inside data, and every payment webhook contains it. Its structure is identical for the Hosted API and the Direct API.

next_action can briefly be null even in requires_action; in that case, retrieve the payment again. The full card number, CVV, expiry date and cardholder name are never returned. card.network and card.bank can be null when unknown.

The customer details sent when the payment was created are not part of this object and do not appear in webhooks.

{
  "data": {
    "payment_id": "LUVEI-PAYN-123456",
    "merchant_order_id": "ORDER-2026-001",
    "flow": "hosted",
    "status": "requires_action",
    "amount": "100.00",
    "currency": "USD",
    "environment": "sandbox",
    "next_action": {
      "type": "redirect",
      "url": "https://payniko.com/l/example-checkout",
      "expires_at": "2026-11-02T12:00:00.000Z"
    },
    "card": null,
    "failure": null,
    "created_at": "2026-11-01T12:00:00.000Z",
    "expires_at": "2026-11-02T12:00:00.000Z",
    "completed_at": null
  }
}

Hosted payment statuses

• An interim decline on the payment page is not final: the payment can remain requires_action, and you may receive payment.updated. You ultimately receive one final result.
• succeeded, failed, expired and cancelled are final statuses. A processing payment can still succeed after expires_at.
• Treat any status not listed here as processing and retrieve the payment again.

Failure codes

A failed payment contains failure.code and failure.message. Use the code in your logic and display the message to the payer as plain text.

New codes may be added; handle any unknown code as payment_declined. failure.message may contain the bank's own text; otherwise it is in English in webhooks and follows Accept-Language in GET.

Redirect requirements

• Redirect the full page (303 or window.location) to next_action.url or open it in a new tab. Do not embed it in an iframe; the page blocks framing.
• Use the URL before next_action.expires_at. Once it has expired, retrieve the payment.
• The page language follows the payer's browser settings; no parameter is required.

Return URL

When the payer returns, the browser is redirected to success_url only if the payment succeeded, and to fail_url in all other cases. Signed parameters are appended to the URL. Verify them to display the correct page, and fulfil the order only after the webhook or a GET confirms succeeded.

ts + "." + payment_id + "." + status + "." + failure_code   // failure_code empty: keep the last dot

1. Select the secret of the key identified by key_version. This is the key that created the payment, even if keys have since been replaced.

2. Build the string from the URL-decoded values. If failure_code is absent, keep the trailing dot.

3. Compute the HMAC-SHA256 and compare it with sig in constant time. Confirm that payment_id belongs to one of your payments.

4. Retrieve the payment with GET /api/payments/{payment_id} (or wait for the webhook) before you fulfil the order.

• Your own query parameters are preserved. If the URL already contains a parameter with one of the names above, it is replaced.
• If the link could not be signed due to a temporary error, the URL contains none of these parameters. Treat the result as unknown and retrieve the payment.

// Node.js 20+: check the signed parameters on success_url / fail_url.
import {createHmac, timingSafeEqual} from 'node:crypto';

// query: URLSearchParams of the return URL.
// secretFor(keyVersion): the API secret of that key, or undefined if you do not know it.
export function verifyReturn(query, secretFor) {
  const sig = query.get('sig') ?? '';
  const secret = secretFor(query.get('key_version'));
  if (!secret || !/^[0-9a-f]{64}$/.test(sig)) return false;
  const signed = [query.get('ts') ?? '', query.get('payment_id') ?? '',
    query.get('status') ?? '', query.get('failure_code') ?? ''].join('.');
  const expected = createHmac('sha256', secret).update(signed, 'utf8').digest();
  return timingSafeEqual(expected, Buffer.from(sig, 'hex'));
}
// Even a valid return is not proof of payment: read GET /api/payments/{payment_id} before you deliver.

<?php
// PHP 8.1+: check the signed parameters on success_url / fail_url.
// $secretFor(string $keyVersion): the API secret of that key, or null if you do not know it.
function payniko_verify_return(array $query, callable $secretFor): bool
{
    $sig = (string) ($query['sig'] ?? '');
    $secret = $secretFor((string) ($query['key_version'] ?? ''));
    if (!$secret || !preg_match('/^[0-9a-f]{64}$/', $sig)) return false;
    $signed = implode('.', [(string) ($query['ts'] ?? ''), (string) ($query['payment_id'] ?? ''),
        (string) ($query['status'] ?? ''), (string) ($query['failure_code'] ?? '')]);
    return hash_equals(hash_hmac('sha256', $signed, $secret), $sig);
}

// $ok = payniko_verify_return($_GET, fn (string $v) => $secretsByKeyVersion[$v] ?? null);
// Even a valid return is not proof of payment: read GET /api/payments/{payment_id} before you deliver.

# Python 3.9+: check the signed parameters on success_url / fail_url.
import hashlib, hmac, re


def verify_return(query, secret_for) -> bool:
    # query: dict-like (for example Flask request.args); secret_for(key_version) -> secret or None
    sig = query.get("sig", "")
    secret = secret_for(query.get("key_version"))
    if not secret or not re.fullmatch(r"[0-9a-f]{64}", sig):
        return False
    signed = ".".join([query.get("ts", ""), query.get("payment_id", ""),
                       query.get("status", ""), query.get("failure_code", "")])
    expected = hmac.new(secret.encode(), signed.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

# Even a valid return is not proof of payment: read GET /api/payments/{payment_id} before you deliver.

https://merchant.example/payment/success?payment_id=LUVEI-PAYN-654321&merchant_order_id=ORDER-2026-001&status=succeeded&ts=1793001234&key_version=1&sig=200e8a5d4a7a03ead362a2c076408f9d8764f8f636f58bd4c17d78a50d59eb8a
string to sign: 1793001234.LUVEI-PAYN-654321.succeeded.

https://merchant.example/payment/failure?payment_id=LUVEI-PAYN-654321&merchant_order_id=ORDER-2026-001&status=failed&failure_code=insufficient_funds&ts=1793001234&key_version=1&sig=1cd0a104ec4ec4f5b2933d48d14c0eb33d949dd7f27936a067ab8f68b413b70d
string to sign: 1793001234.LUVEI-PAYN-654321.failed.insufficient_funds

secret used in this example (fake): example_secret_not_real

Payment webhooks

The following events are sent to the webhook_url of the payment. Each payment event is sent at most once per payment.

{
  "event_id": "e0743f4c-a297-4bf0-8085-ceb7d9d5e181",
  "event_type": "payment.succeeded",
  "environment": "sandbox",
  "occurred_at": "2026-11-01T12:02:00.000Z",
  "data": {
    "payment_id": "LUVEI-PAYN-123456",
    "merchant_order_id": "ORDER-2026-001",
    "flow": "hosted",
    "status": "succeeded",
    "amount": "100.00",
    "currency": "USD",
    "environment": "sandbox",
    "next_action": null,
    "card": {
      "bin6": "400000",
      "last_four": "0002",
      "network": "visa",
      "bank": null
    },
    "failure": null,
    "created_at": "2026-11-01T12:00:00.000Z",
    "expires_at": "2026-11-02T12:00:00.000Z",
    "completed_at": "2026-11-01T12:02:00.000Z"
  }
}

Verify every webhook: the HMAC-SHA256 of X-Timestamp + "." + raw body, computed with the secret of the key that created the payment, must equal X-Signature, and X-Timestamp must be within 300 seconds. Store each event_id once and respond with 2xx promptly. For code samples and retry behaviour, see Webhooks.

Errors

A card decline is not an HTTP error; the payment ends as failed with failure.code. For the full list, see Error codes.

Testing with sandbox cards

Create the payment with your sandbox key, open next_action.url and pay with one of the cards below, using any future expiry date and any 3-digit CVV. For details, see Sandbox and test cards.

End-to-end example

A minimal Node.js server that creates a payment, redirects the payer, and handles the return and the webhook. It uses the request helper and the verification functions from Webhooks and Return URL.

// server.mjs: Hosted API from start to end (Node.js 20+, no dependencies).
import http from 'node:http';
import {randomUUID} from 'node:crypto';
import {api} from './payniko.mjs';                  // request helper (Authentication)
import {verifyWebhook} from './verify-webhook.mjs'; // webhook check (Webhooks)
import {verifyReturn} from './verify-return.mjs';   // return URL check (Return URL)

const site = 'https://merchant.example';
const orders = new Map();      // use your database
const seenEvents = new Set();  // use your database
const readBody = async (req) => { const parts = []; for await (const p of req) parts.push(p); return Buffer.concat(parts); };

http.createServer(async (req, res) => {
  const url = new URL(req.url, site);
  // 1. Create the payment, 2. redirect the payer.
  if (req.method === 'POST' && url.pathname === '/checkout') {
    const form = JSON.parse((await readBody(req)).toString('utf8')); // your checkout form: the payer's e-mail and phone
    const orderId = 'ORDER-' + Date.now();
    const key = randomUUID();
    orders.set(orderId, {key, status: 'new'});      // save the key before you call the API
    const {data} = await api('POST', '/api/payments/hosted', {
      merchant_order_id: orderId, amount: '100.00', currency: 'USD',
      customer: {email: form.email, phone: form.phone},
      webhook_url: `${site}/webhooks/payniko`,
      success_url: `${site}/payment/success`, fail_url: `${site}/payment/failure`,
    }, key);
    Object.assign(orders.get(orderId), {paymentId: data.payment_id, status: data.status});
    // next_action can be null for a moment: read the payment again before you redirect.
    res.writeHead(303, {Location: data.next_action ? data.next_action.url : `/orders/${orderId}`}).end();
    return;
  }
  // Return URL: show a page, but trust only the webhook or a GET.
  if (req.method === 'GET' && (url.pathname === '/payment/success' || url.pathname === '/payment/failure')) {
    const signed = verifyReturn(url.searchParams, () => process.env.API_SECRET);
    let status = 'unknown';
    if (signed) status = (await api('GET', `/api/payments/${url.searchParams.get('payment_id')}`)).data.status;
    res.writeHead(200, {'Content-Type': 'text/plain; charset=utf-8'});
    res.end(status === 'succeeded' ? 'Thank you, payment received.' : 'Payment not completed.');
    return;
  }
  // Webhook: verify, store event_id once, answer 2xx fast.
  if (req.method === 'POST' && url.pathname === '/webhooks/payniko') {
    const raw = await readBody(req);
    if (!verifyWebhook(raw, req.headers, process.env.API_SECRET)) { res.writeHead(401).end(); return; }
    const event = JSON.parse(raw.toString('utf8'));
    if (!seenEvents.has(event.event_id)) {          // use a unique index in your database
      seenEvents.add(event.event_id);
      const order = orders.get(event.data.merchant_order_id);
      if (order && event.event_type.startsWith('payment.')) order.status = event.data.status;
    }
    res.writeHead(204).end();
    return;
  }
  res.writeHead(404).end();
}).listen(8080);

Events

Payment, refund and dispute events are sent to the webhook_url of the payment, and withdrawal events to the webhook_url of the withdrawal. Each payment event is sent at most once per payment; each refund, dispute or withdrawal event at most once per refund, dispute or withdrawal and status.

Payload

{
  "event_id": "e0743f4c-a297-4bf0-8085-ceb7d9d5e181",
  "event_type": "payment.succeeded",
  "environment": "sandbox",
  "occurred_at": "2026-11-01T12:02:00.000Z",
  "data": {
    "payment_id": "LUVEI-PAYN-123456",
    "merchant_order_id": "ORDER-2026-001",
    "flow": "hosted",
    "status": "succeeded",
    "amount": "100.00",
    "currency": "USD",
    "environment": "sandbox",
    "next_action": null,
    "card": {
      "bin6": "400000",
      "last_four": "0002",
      "network": "visa",
      "bank": null
    },
    "failure": null,
    "created_at": "2026-11-01T12:00:00.000Z",
    "expires_at": "2026-11-02T12:00:00.000Z",
    "completed_at": "2026-11-01T12:02:00.000Z"
  }
}

Refund, dispute and withdrawal events

• Refund and dispute events carry a single payment reference: payment_id or, on some events, payment_code. refund.completed always includes payment_id. When an event carries payment_code, match the order by merchant_order_id.
• Before you act on an event, retrieve the refund, dispute or withdrawal with GET to confirm its current state.

{
  "event_id": "c4b2e7d1-8a3f-4e65-b0d9-5f1a2c3e4d70",
  "event_type": "refund.completed",
  "environment": "sandbox",
  "occurred_at": "2026-11-02T09:20:00.000Z",
  "subject": {
    "type": "refund",
    "id": "LUVEI-RFND-100001"
  },
  "data": {
    "id": "LUVEI-RFND-100001",
    "status": "completed",
    "operation_type": "refund",
    "amount": "100.00",
    "currency": "USD",
    "payment_id": "LUVEI-PAYN-123456",
    "merchant_order_id": "ORDER-2026-001"
  }
}

{
  "event_id": "b3e8f0a2-5c71-4d96-8e14-7a2c9d0f6b35",
  "event_type": "withdrawal.sent",
  "environment": "sandbox",
  "occurred_at": "2026-11-02T10:00:00.000Z",
  "subject": {
    "type": "withdrawal",
    "id": "LUVEI-WTHD-100002"
  },
  "data": {
    "id": "LUVEI-WTHD-100002",
    "status": "sent",
    "amount": "50.00",
    "currency": "USD",
    "usdt_amount": "49.950000",
    "asset": "USDT",
    "network": "TRC20",
    "tx_hash": "9f2b6c1d4e8a7f30b5c2d9e1a6f4b7c08d3e5a2f1b9c6d4e7a0f3b8c5d2e1f6a"
  }
}

Verify the signature

1. Read the raw body bytes before you parse the JSON.

2. Verify that X-Timestamp has 10 digits and is within 300 seconds of your server time.

3. Compute the HMAC-SHA256 of X-Timestamp + "." + raw body with your API secret, and compare the result with X-Signature in constant time.

4. If verification fails, reject the request with 401.

// Node.js 20+: verify a Payniko notification before parsing it.
import {createHmac, timingSafeEqual} from 'node:crypto';

export function verifyWebhook(rawBody, headers, apiSecret, now = Math.floor(Date.now() / 1000)) {
  const timestamp = headers['x-timestamp'];
  const signature = headers['x-signature'];
  if (typeof timestamp !== 'string' || !/^[0-9]{10}$/.test(timestamp) ||
      typeof signature !== 'string' || !/^[0-9a-f]{64}$/.test(signature) ||
      Math.abs(now - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', apiSecret).update(timestamp + '.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

// Example with node:http - read the raw bytes first, never re-serialise the JSON.
// import http from 'node:http';
// http.createServer((req, res) => {
//   const chunks = [];
//   req.on('data', (c) => chunks.push(c)).on('end', () => {
//     const raw = Buffer.concat(chunks);
//     const secret = req.headers['x-environment'] === 'live' ? process.env.LIVE_API_SECRET : process.env.SANDBOX_API_SECRET;
//     if (!verifyWebhook(raw, req.headers, secret)) { res.writeHead(401).end(); return; }
//     const event = JSON.parse(raw.toString('utf8'));
//     // Save event.event_id (unique) and the event, then answer quickly.
//     res.writeHead(204).end();
//   });
// }).listen(8080);

<?php
// PHP 8.1+: verify a Payniko notification before parsing it.
function payniko_verify_webhook(string $rawBody, string $timestamp, string $signature, string $apiSecret, ?int $now = null): bool
{
    $now ??= time();
    if (!preg_match('/^[0-9]{10}$/', $timestamp) || !preg_match('/^[0-9a-f]{64}$/', $signature)) return false;
    if (abs($now - (int) $timestamp) > 300) return false;
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $apiSecret);
    return hash_equals($expected, $signature);
}

$raw = file_get_contents('php://input');            // raw bytes, before json_decode
$environment = $_SERVER['HTTP_X_ENVIRONMENT'] ?? '';
$secret = $environment === 'live' ? getenv('LIVE_API_SECRET') : getenv('SANDBOX_API_SECRET');
if (!payniko_verify_webhook($raw, $_SERVER['HTTP_X_TIMESTAMP'] ?? '', $_SERVER['HTTP_X_SIGNATURE'] ?? '', (string) $secret)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
// Save $event['event_id'] (unique) and the event, then answer quickly.
http_response_code(204);

# Python 3.9+: verify a Payniko notification before parsing it.
import hashlib, hmac, re, time


def verify_webhook(raw_body: bytes, headers, api_secret: str, now=None) -> bool:
    timestamp = headers.get("X-Timestamp", "")
    signature = headers.get("X-Signature", "")
    if not re.fullmatch(r"[0-9]{10}", timestamp) or not re.fullmatch(r"[0-9a-f]{64}", signature):
        return False
    if abs(int(now or time.time()) - int(timestamp)) > 300:
        return False
    expected = hmac.new(api_secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask example:
# @app.post("/webhooks/payments")
# def payniko_webhook():
#     raw = request.get_data()                    # raw bytes, before JSON parsing
#     env = request.headers.get("X-Environment")
#     secret = os.environ["LIVE_API_SECRET" if env == "live" else "SANDBOX_API_SECRET"]
#     if not verify_webhook(raw, request.headers, secret):
#         return "", 401
#     event = json.loads(raw)
#     # Save event["event_id"] (unique) and the event, then answer quickly.
#     return "", 204

Process each event once

1. Store event_id in a table with a unique index. If it already exists, respond with 2xx and stop processing.

2. Respond with 2xx within a few seconds, and perform time-consuming work (e-mails, stock updates) afterwards in a queue.

3. Events can arrive late, more than once or out of order. A payment that ends by timeout can be reported a minute or more later. Base decisions on the status in data, or retrieve the object again with GET.

4. Never fulfil an order solely because the browser returned to success_url.

Retries

• Any 2xx response within approximately 10 seconds counts as a successful delivery. Redirects are not followed and count as failures.
• Failed deliveries are retried after approximately 1 minute, 5 minutes, 15 minutes, 1 hour and 6 hours. The body and X-Event-Id remain unchanged; X-Timestamp and X-Signature are regenerated for each attempt.
• After the final attempt, the delivery is marked failed. Some errors (a private IP target, a missing signing key) are not retried, and the delivery is marked failed immediately. Failed deliveries can be resent with the deliveries API.
• Your webhook_url must resolve to a public IP address on every attempt.

Webhook deliveries

Every webhook sent is stored as a delivery. Use this API to identify failed deliveries and resend them.

./payniko.sh GET '/api/webhooks/deliveries?status=failed&page=1&per_page=20'

import {api} from './payniko.mjs';

const deliveries = await api('GET', '/api/webhooks/deliveries?status=failed&page=1&per_page=20');
console.log(deliveries);

<?php
require __DIR__ . '/payniko.php';

$deliveries = payniko_api('GET', '/api/webhooks/deliveries?status=failed&page=1&per_page=20');
print_r($deliveries);

from payniko import api

deliveries = api("GET", "/api/webhooks/deliveries?status=failed&page=1&per_page=20")
print(deliveries)

{
  "id": "0a6f3c9e-2b7d-4e15-9c84-6d1f2a3b5e70",
  "event": "payment.succeeded",
  "status": "failed",
  "payment_id": "LUVEI-PAYN-123456",
  "subject_type": null,
  "subject_id": null,
  "attempt_count": 6,
  "last_status_code": 500,
  "last_error": "Bildirim adresi başarısız yanıt verdi.",
  "last_error_code": "webhook_response_unsuccessful",
  "last_error_message": "Webhook delivery failed.",
  "next_attempt_at": null,
  "delivered_at": null,
  "created_at": "2026-11-01T12:02:00.000Z"
}

KEY="$(openssl rand -hex 16)"  # store with the order before sending; reuse it after network errors
./payniko.sh POST '/api/webhooks/deliveries/0a6f3c9e-2b7d-4e15-9c84-6d1f2a3b5e70/retry' '' "$KEY"

import {api, randomUUID} from './payniko.mjs';

const key = randomUUID(); // Store this key with the order before sending; reuse it after network errors.
const delivery = await api('POST', '/api/webhooks/deliveries/0a6f3c9e-2b7d-4e15-9c84-6d1f2a3b5e70/retry', undefined, key);
console.log(delivery);

<?php
require __DIR__ . '/payniko.php';

$key = bin2hex(random_bytes(16)); // store with the order; reuse it after network errors
$delivery = payniko_api('POST', '/api/webhooks/deliveries/0a6f3c9e-2b7d-4e15-9c84-6d1f2a3b5e70/retry', null, $key);
print_r($delivery);

from payniko import api
import uuid

key = str(uuid.uuid4())  # store with the order; reuse it after network errors
delivery = api("POST", "/api/webhooks/deliveries/0a6f3c9e-2b7d-4e15-9c84-6d1f2a3b5e70/retry", None, key)
print(delivery)

How the sandbox works

• There is no environment switch: requests signed with a sandbox key run in sandbox, and requests signed with a live key run live.
• The cards below work both on the payment page and in your own payment form; real cards are rejected. Your own form also accepts any other valid card number with BIN 435509 or 400000; a test page then lets you choose success, failure or no response.
• The 3-D Secure screens are test screens, and card numbers must have a valid check digit.
• Webhooks are delivered as real HTTPS requests to your webhook_url and signed with your sandbox secret.

Test cards

The cards behave the same with the Hosted API and the Direct API unless the table says otherwise. Use any future expiry date and any 3-digit CVV.

• With any test card, an amount ending in .77 (for example 100.77) keeps the payment in processing (manual review).
• A test payment that never receives a response is eventually closed as failed with service_unavailable.
• A payment with a declined test card (for example 4000000000000051) can remain requires_action for some time before it reaches a final status. Base decisions on the webhook or a GET, not on an interim decline.

Test BINs

In sandbox, the BIN check returns the following results:

Refunds and withdrawals

In sandbox, refunds and withdrawals complete immediately against a test balance. Select the outcome with the X-Sandbox-Scenario header, which is not part of the signature. Use a new Idempotency-Key for every scenario: the header is part of the idempotency fingerprint, and the same key with a different scenario is rejected with 409 9000010. An unknown value, or the header sent with a live key, returns 422 1000001; the evidence endpoint does not accept the header. The applied scenario is echoed in the X-Sandbox-Scenario response header.

Before the scenario is applied, sandbox enforces the same rules as live: minimum and daily withdrawal limits, exchange rates (503 3000001 when unavailable) and address validation. Any TRC20 address with a valid checksum is accepted in sandbox, including the TRON zero address, and no transfer is made; 1000030 (an address that cannot receive payouts) cannot be reproduced in sandbox.

KEY="$(openssl rand -hex 16)"  # store with the order before sending; reuse it after network errors
SANDBOX_SCENARIO=rejected ./payniko.sh POST '/api/account/refunds' '{
  "payment_id": "LUVEI-PAYN-123456",
  "operation_type": "refund",
  "reason": "Test refund"
}' "$KEY"

import {api, randomUUID} from './payniko.mjs';

const key = randomUUID(); // Store this key with the order before sending; reuse it after network errors.
const refund = await api('POST', '/api/account/refunds', {
  "payment_id": "LUVEI-PAYN-123456",
  "operation_type": "refund",
  "reason": "Test refund"
}, key, {'X-Sandbox-Scenario': 'rejected'});
console.log(refund);

<?php
require __DIR__ . '/payniko.php';

$key = bin2hex(random_bytes(16)); // store with the order; reuse it after network errors
$refund = payniko_api('POST', '/api/account/refunds', [
    "payment_id" => 'LUVEI-PAYN-123456',
    "operation_type" => 'refund',
    "reason" => 'Test refund',
], $key, ['X-Sandbox-Scenario: rejected']);
print_r($refund);

from payniko import api
import uuid

key = str(uuid.uuid4())  # store with the order; reuse it after network errors
refund = api("POST", "/api/account/refunds", {
    "payment_id": "LUVEI-PAYN-123456",
    "operation_type": "refund",
    "reason": "Test refund"
}, key, {"X-Sandbox-Scenario": "rejected"})
print(refund)

A sandbox tx_hash is simulated and does not refer to a real blockchain transaction.

Request log

The Request activity page lists your recent API requests with status, error code and correlation_id. Requests rejected before the key is identified (invalid key, signature or merchant code) are not listed. Sandbox payments are listed under Sandbox API orders.

Error response format

{
  "type": "https://payniko.com/problems/1000001",
  "title": "Validation failed",
  "status": 422,
  "detail": "The submitted fields are not valid.",
  "code": "1000001",
  "correlation_id": "9b8c7d6e-5f40-4a3b-8c2d-1e0f9a8b7c6d",
  "errors": {
    "merchant_order_id": [
      "This field is required."
    ]
  },
  "integration": {
    "stage": "validation",
    "reason": "validation_failed",
    "violations": [
      {
        "location": "body",
        "path": "merchant_order_id",
        "expected": {
          "type": "string",
          "min_length": 1,
          "max_length": 64,
          "unique_within": "account_and_environment"
        },
        "hint": "Check this field against the documented format."
      }
    ],
    "docs_url": "/en/developers#errors",
    "retryable": false
  }
}

Retry guidance

• retry_class is present only in responses that carry metadata (Direct API, authentication and rate-limit errors). Other errors carry integration.retryable instead.
• After a timeout or a 5xx, never create a new payment; retrieve the payment or resend the request with the same key.
• A card decline is not an HTTP error: the payment is returned with 200, status: failed and failure.
• developer_detail may change; do not base integration logic on it.

All error codes

Authentication and access

Idempotency and conflicts

Validation

Amount, card and BIN

Not found

Limits and availability

Account operations

Sandbox only

Message language

title and detail follow Accept-Language (en, tr, de, ar, es, el; de-AT is treated as de). Any other value returns English. Content-Language indicates the language used.