Βασικό URL και μορφές δεδομένων

Βασικό URL

https://payniko.com/api. Η διαδρομή δεν περιλαμβάνει αριθμό έκδοσης.

Μορφή

JSON με κωδικοποίηση UTF-8. Τα σφάλματα χρησιμοποιούν τη μορφή application/problem+json.

Ποσά

Συμβολοσειρές με δύο δεκαδικά ψηφία, για παράδειγμα "100.00". Μη στέλνετε ποτέ ποσά ως αριθμούς JSON.

Νόμισμα

USD, EUR, AED ή TRY. Αν το currency παραλειφθεί, ισχύει το κύριο νόμισμα του συστήματος.

Ημερομηνία και ώρα

ISO 8601 σε UTC με χιλιοστά του δευτερολέπτου, για παράδειγμα 2026-11-01T12:00:00.000Z.

Αναγνωριστικά

Τα αναγνωριστικά πληρωμών, επιστροφών, αναλήψεων και αμφισβητήσεων έχουν τη μορφή LUVEI-ABCD-123456. Αποθηκεύστε ολόκληρο το αναγνωριστικό.

Γλώσσα

Τα μηνύματα επιστρέφονται στη γλώσσα που ορίζει η κεφαλίδα Accept-Language (en, tr, de, ar, es, el)· προεπιλογή είναι το en. Οι κωδικοί και τα ονόματα πεδίων δεν μεταφράζονται ποτέ.

Απόκτηση κλειδιών API

Οι νέοι λογαριασμοί λαμβάνουν αυτόματα κλειδιά Sandbox και Live. Αν έχετε λογαριασμό, συνδεθείτε και ανοίξτε Κλειδιά πρόσβασης. Αν λάβατε αρχείο λογαριασμού, συνδεθείτε με το όνομα χρήστη και τον κωδικό του· δεν χρειάζεται νέα εγγραφή.

1. Δημιουργήστε τον λογαριασμό σας

1. Δημιουργήστε λογαριασμό. Γράψτε το email που χρησιμοποιείτε και πατήστε Αποστολή κωδικού. Εισαγάγετε στη σελίδα εγγραφής τον εξαψήφιο κωδικό του email και πατήστε Επαλήθευση. Αν δεν έρθει, ελέγξτε τη διεύθυνση και τα ανεπιθύμητα· ζητήστε νέο κωδικό μετά την αντίστροφη μέτρηση.

2. Μετά την επιβεβαίωση email, επιλέξτε κωδικό χώρας και γράψτε τον αριθμό που συνδέεται με τον δικό σας λογαριασμό Telegram. Πατήστε Επαλήθευση. Η επιβεβαίωση γίνεται στο Telegram, όχι με SMS.

3. Ανοίξτε τον σύνδεσμο Telegram της σελίδας ή σαρώστε το QR με το τηλέφωνό σας αν είστε σε υπολογιστή. Πατήστε Έναρξη / Start στο bot και μοιραστείτε τον δικό σας αριθμό με το κουμπί του. Η πληκτρολόγηση αριθμού ως μήνυμα ή η αποστολή ξένης επαφής δεν αρκεί. Επιστρέψτε στην εγγραφή και περιμένετε την επιβεβαίωση.

4. Πατήστε Συνέχεια στα στοιχεία λογαριασμού. Δημιουργήστε όνομα χρήστη και κωδικό πρόσβασης, επαναλάβετε τον κωδικό και ολοκληρώστε τις επιβεβαιώσεις. Πατήστε Δημιουργία λογαριασμού. Όνομα χρήστη: 4–32 χαρακτήρες, πεζά λατινικά γράμματα, ψηφία, τελεία, κάτω παύλα ή παύλα. Κωδικός: τουλάχιστον 12 χαρακτήρες.

5. Αποθηκεύστε με ασφάλεια τον κωδικό ανάκτησης που εμφανίζεται μετά τη δημιουργία λογαριασμού. Εμφανίζεται μόνο σε αυτή την οθόνη και δεν είναι το μυστικό API. Επιβεβαιώστε την αποθήκευση και πατήστε Αποθήκευσα τον κωδικό, μετάβαση στον πίνακα.

2. Λάβετε κλειδιά Sandbox και κωδικό εμπόρου

1. Ανοίξτε Κλειδιά πρόσβασης και βρείτε την κάρτα Sandbox. Οι νέοι λογαριασμοί έχουν ήδη κλειδιά. Αν παλιότερος λογαριασμός δεν έχει ενεργό κλειδί, προσθέστε προαιρετική ετικέτα και πατήστε Δημιουργία κλειδιού. Δεν απαιτείται καταχώριση IP.

2. Πάρτε τις τρεις τιμές του πίνακα. Το εικονίδιο ματιού εμφανίζει το μυστικό και το εικονίδιο αντιγραφής το αντιγράφει. Ο κάτοχος μπορεί να δει ξανά ένα ενεργό μυστικό· δεν χρειάζεται ανανέωση κλειδιού μόνο για την προβολή.

3. Δώστε τις τιμές με ασφαλή τρόπο στον προγραμματιστή σας ή αποθηκεύστε τις στις ιδιωτικές ρυθμίσεις του διακομιστή. Κλειδί και μυστικό πρέπει να προέρχονται από την ίδια κάρτα Sandbox. Μην βάλετε το μυστικό σε JavaScript του browser, δημόσια αρχεία ή URL.

Δημιουργία δοκιμαστικής πληρωμής

Δοκιμάστε την ενσωμάτωση στο Sandbox χωρίς πραγματική κίνηση χρημάτων. Η επιτυχής δοκιμή δεν αποτελεί προϋπόθεση για κλειδιά Live· συνιστάται για έλεγχο υπογραφών, ανακατευθύνσεων και webhooks.

1. Χρησιμοποιήστε παράδειγμα διακομιστή από Βοηθητικές συναρτήσεις αιτημάτων με κλειδί Sandbox, μυστικό Sandbox και κωδικό εμπόρου. Δεν υπάρχει διαφορετικό domain API Sandbox: χρησιμοποιήστε τη βασική URL της τεκμηρίωσης. Το κλειδί καθορίζει το περιβάλλον.

2. Ελέγξτε τα όρια ποσών και νομίσματα Sandbox στο Εμπειρία πληρωμής. Επιλέξτε επιτρεπτό ποσό που δεν τελειώνει σε .77: αυτή η κατάληξη ενεργοποιεί σενάριο εκκρεμούς αποτελέσματος.

3. Συμπληρώστε το παράδειγμα POST /api/payments/hosted: μοναδικό merchant_order_id, ποσό, νόμισμα, customer.email / customer.phone και τρεις URL ειδοποίησης/επιστροφής. Χρησιμοποιήστε προσβάσιμα στοιχεία και τηλέφωνο με κωδικό χώρας. Το webhook_url πρέπει να είναι δημόσιο HTTPS ακόμη και στο Sandbox· localhost και ιδιωτικά δίκτυα δεν επιτρέπονται. Τα success_url / fail_url είναι οι URL επιστροφής του browser.

4. Στείλτε το υπογεγραμμένο POST /api/payments/hosted από τον διακομιστή. Για νέα δοκιμή χρησιμοποιήστε νέα αναφορά παραγγελίας και νέο Idempotency-Key· για επανάληψη ίδιου αιτήματος μετά από σφάλμα σύνδεσης κρατήστε το ίδιο. Το HTTP 201 σημαίνει δημιουργία πληρωμής, όχι επιτυχή πληρωμή.

5. Ανοίξτε ολόκληρο το next_action.url της απάντησης σε browser. Στη φόρμα Sandbox χρησιμοποιήστε τη δοκιμαστική κάρτα 4000000000000002, μελλοντική λήξη και τριψήφιο CVV, π.χ. 12/30 και 123. Ολοκληρώστε επιτυχώς τη δοκιμαστική οθόνη 3D Secure. Μην χρησιμοποιήσετε πραγματική κάρτα. Άλλα σενάρια: Δοκιμαστικές κάρτες.

6. Μετά την επιστροφή, ελέγξτε με GET /api/payments/{payment_id} ή επεξεργαστείτε ένα webhook αφού επαληθεύσετε την υπογραφή του. Η κατάσταση API πρέπει να είναι succeeded. Τα requires_action / processing είναι ενδιάμεσα· το failed δεν μετρά ως επιτυχία. Η σελίδα επιτυχίας μόνη της δεν αποδεικνύει πληρωμή.

7. Ελέγξτε το αποτέλεσμα στο Αρχείο αιτημάτων. Μια επιτυχής εγγραφή ολοκληρώνει αυτό το σενάριο δοκιμής. Το Live χρησιμοποιεί ξεχωριστό ζεύγος κλειδιών.

Απόκτηση κλειδιών Live

Το Sandbox και το Live χρησιμοποιούν ξεχωριστά ζεύγη κλειδιών. Τα κλειδιά Live δεν απαιτούν IP ή επιτυχή πληρωμή Sandbox. Η αλλαγή περιβάλλοντος στον πίνακα δεν αλλάζει τη ρύθμιση του διακομιστή.

1. Ανοίξτε Πρόσβαση Live και την κάρτα Παραγωγή. Οι νέοι λογαριασμοί έχουν ήδη κλειδιά Live· αν παλιότερος λογαριασμός δεν έχει, πατήστε Δημιουργία κλειδιού.

2. Πάρτε το κλειδί API και το μυστικό από την ίδια κάρτα Live. Ο κωδικός εμπόρου παραμένει ίδιος. Αποθηκεύστε το μυστικό μόνο στην ιδιωτική ρύθμιση του διακομιστή.

3. Βάλτε αυτό το ζεύγος Live στις ρυθμίσεις του παραγωγικού διακομιστή. Η URL API παραμένει ίδια και τα Sandbox κλειδιά εξακολουθούν να λειτουργούν για δοκιμές. Η προβολή κάρτας στο panel δεν αλλάζει τις ρυθμίσεις του διακομιστή.

4. Ελέγξτε τα όρια και νομίσματα Live στο Εμπειρία πληρωμής. Τα κλειδιά είναι έτοιμα. Τα αιτήματα Live μπαίνουν στην πραγματική ροή χρέωσης· συνεχίστε τις δοκιμές καρτών με Sandbox κλειδιά.

Αν κολλήσετε σε κάποιο βήμα

Επισκόπηση endpoint

Όλα τα endpoint χρησιμοποιούν τον ίδιο έλεγχο ταυτότητας και κάθε POST απαιτεί επιπλέον Idempotency-Key.

Κλειδί API και μυστικό κλειδί

Κάθε κλειδί API ανήκει σε ένα μόνο περιβάλλον, sandbox ή παραγωγής, και το κλειδί καθορίζει το περιβάλλον στο οποίο εκτελείται ένα αίτημα: χρησιμοποιήστε το κλειδί sandbox για δοκιμές και το κλειδί παραγωγής για πραγματικές πληρωμές. Η κεφαλίδα X-Environment είναι προαιρετική· αν παραλειφθεί, το αίτημα εκτελείται στο περιβάλλον του κλειδιού. Αν αποσταλεί, η τιμή της πρέπει να είναι sandbox ή live (χωρίς διάκριση πεζών-κεφαλαίων) και να αντιστοιχεί στο περιβάλλον του κλειδιού· διαφορετικά, το αίτημα απορρίπτεται με HTTP 401 και κωδικό 0055502 και δεν εκτελείται καμία επεξεργασία. Οι υποχρεωτικές κεφαλίδες ελέγχου ταυτότητας είναι οι X-Api-Key, X-Merchant-Code, X-Timestamp και X-Signature, καθώς και η Idempotency-Key σε κάθε αίτημα εγγραφής. Το περιβάλλον δεν αποτελεί μέρος της συμβολοσειράς προς υπογραφή. Κάθε σώμα απάντησης που περιέχει το πεδίο environment (πληρωμές, υπόλοιπα, επιστροφές χρημάτων και άλλοι πόροι) αναφέρει το περιβάλλον που χρησιμοποιήθηκε.

Ανανέωση κλειδιού

• Δημιουργήστε νέο κλειδί αν το μυστικό κλειδί ενδέχεται να έχει εκτεθεί ή όταν αποχωρεί κάποιο πρόσωπο που είχε πρόσβαση σε αυτό. Το προηγούμενο κλειδί παύει να λειτουργεί αμέσως.
• Οι ειδοποιήσεις webhook και οι σύνδεσμοι επιστροφής μιας πληρωμής υπογράφονται με το μυστικό κλειδί που αντιστοιχεί στο κλειδί API με το οποίο δημιουργήθηκε η πληρωμή· αυτό ισχύει και για ειδοποιήσεις επιστροφών χρημάτων και αμφισβητήσεων που αποστέλλονται πολύ μετά την πληρωμή. Διατηρήστε το προηγούμενο μυστικό κλειδί για όσο διάστημα ενδέχεται να φτάσουν ακόμη τέτοια συμβάντα.

Κεφαλίδες αιτήματος

Στείλτε κάθε κεφαλίδα X- ακριβώς μία φορά. Οι τιμές των κεφαλίδων δεν πρέπει να περιέχουν κόμματα, αλλαγές γραμμής ή κενά.

Υπογραφή αιτημάτων

Η συμβολοσειρά προς υπογραφή αποτελείται από τέσσερις τιμές που ενώνονται με χαρακτήρα αλλαγής γραμμής (line feed): τη χρονική σήμανση, τη μέθοδο HTTP, τη διαδρομή και την τιμή κατακερματισμού SHA-256 του σώματος.

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. Κωδικοποιήστε το σώμα σε JSON μία φορά και υπολογίστε την τιμή κατακερματισμού SHA-256 ακριβώς αυτών των byte (δεκαεξαδική μορφή με πεζά). Για αίτημα χωρίς σώμα, υπολογίστε την τιμή κατακερματισμού της κενής συμβολοσειράς (e3b0c442…b855).

2. Χρησιμοποιήστε τη διαδρομή ακριβώς όπως εμφανίζεται στο URL, ξεκινώντας από /api/ και χωρίς τη συμβολοσειρά ερωτήματος (query string). Για παράδειγμα, για το GET /api/payments/bin/540061?amount=100.00 υπογράφεται το /api/payments/bin/540061.

3. Υπολογίστε το HMAC-SHA256 με κλειδί το μυστικό κλειδί API. Χρησιμοποιήστε τη συμβολοσειρά του μυστικού κλειδιού ως έχει· μην την αποκωδικοποιείτε.

4. Στείλτε το αποτέλεσμα στην κεφαλίδα X-Signature και, ως σώμα του αιτήματος, ακριβώς τα byte για τα οποία υπολογίσατε την τιμή κατακερματισμού.

Ανοχή χρονικής σήμανσης

Η τιμή X-Timestamp πρέπει να απέχει έως 300 δευτερόλεπτα από την ώρα διακομιστή του Payniko, προς οποιαδήποτε κατεύθυνση. Διατηρείτε το ρολόι του διακομιστή σας συγχρονισμένο μέσω NTP. Αν η απόκλιση είναι μεγαλύτερη, το αίτημα απορρίπτεται με 401 0055504 και το detail περιέχει την ώρα διακομιστή του Payniko.

Παράδειγμα υπογραφής

Χρησιμοποιήστε αυτές τις ενδεικτικές τιμές για να ελέγξετε την υλοποίησή σας. Με αυτό το μυστικό κλειδί, αυτή τη χρονική σήμανση και αυτό το σώμα, ο κώδικάς σας πρέπει να παράγει ακριβώς αυτή την υπογραφή.

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

Βοηθητικές συναρτήσεις αιτημάτων

Προσθέστε μία από αυτές τις βοηθητικές συναρτήσεις στον διακομιστή σας. Η συνάρτηση διαβάζει τα API_KEY, API_SECRET και MERCHANT_CODE από μεταβλητές περιβάλλοντος, υπογράφει το αίτημα και το αποστέλλει. Τα υπόλοιπα παραδείγματα κώδικα χρησιμοποιούν αυτή τη βοηθητική συνάρτηση.

#!/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

Επαλήθευση της ρύθμισης

Η ανάκτηση του υπολοίπου είναι ασφαλής πρώτη κλήση, επειδή δεν δημιουργεί τίποτα.

./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)

Οι επαναλαμβανόμενες μη έγκυρες υπογραφές κλειδώνουν προσωρινά το κλειδί: 20 αποτυχίες από την ίδια διεύθυνση μέσα σε 15 λεπτά το κλειδώνουν για 15 λεπτά και 300 αποτυχίες μέσα σε μία ώρα το κλειδώνουν για μία ώρα (429 1000005 με Retry-After). Διορθώστε τη λογική υπογραφής πριν δοκιμάσετε ξανά.

Idempotency-Key

Κάθε POST απαιτεί Idempotency-Key. Ένα αίτημα που αποστέλλεται ξανά με το ίδιο κλειδί εκτελείται μόνο μία φορά και επιστρέφει το αρχικό αποτέλεσμα· έτσι, η επανάληψη μετά από λήξη χρονικού ορίου είναι ασφαλής.

• Δημιουργήστε νέο τυχαίο κλειδί, για παράδειγμα ένα UUID, για κάθε νέα λειτουργία και αποθηκεύστε το μαζί με την παραγγελία σας πριν στείλετε το αίτημα.
• Μετά από λήξη χρονικού ορίου ή σφάλμα δικτύου, στείλτε ξανά το ίδιο σώμα με το ίδιο κλειδί.
• Μην επαναχρησιμοποιείτε ποτέ ένα κλειδί με διαφορετικό σώμα· ένα τέτοιο αίτημα απορρίπτεται με 409 (9000010 ή 0055503 στο Direct API).
• Αν το αρχικό αίτημα βρίσκεται ακόμη σε εξέλιξη, η απάντηση είναι 409: 9000039 στο Hosted API (με integration.retryable: true) ή 0055503 με metadata.retry_class: retry_same_request στο Direct API. Στείλτε ξανά το ίδιο αίτημα μετά από σύντομη αναμονή.
• Μορφή: 8–128 χαρακτήρες από το σύνολο A-Z a-z 0-9 _ -. Αν το κλειδί λείπει ή δεν είναι έγκυρο, επιστρέφεται 422 1000009.
• Ένα υπογεγραμμένο αίτημα (X-Timestamp και X-Signature) δεσμεύεται για 10 λεπτά στο πρώτο Idempotency-Key με το οποίο στάλθηκε· η ίδια υπογραφή με διαφορετικό κλειδί απορρίπτεται με 409 9000010. Δημιουργήστε νέα χρονοσφραγίδα και υπογραφή για κάθε νέα ενέργεια. Αν αυτός ο έλεγχος δεν είναι προσωρινά διαθέσιμος, η απάντηση είναι 503 1000011.

Απαιτήσεις αιτημάτων

• Στέλνετε μόνο τα πεδία που περιγράφονται στην τεκμηρίωση. Τα άγνωστα πεδία απορρίπτονται με 422 1000001.
• Τα αιτήματα POST δεν πρέπει να περιέχουν συμβολοσειρά ερωτήματος. Τα αιτήματα GET δεν πρέπει να περιέχουν σώμα και δέχονται μόνο τις παραμέτρους ερωτήματος που περιγράφονται στην τεκμηρίωση.
• Το σώμα πρέπει να είναι ένα μόνο αντικείμενο JSON με βάθος ένθεσης έως 7 επίπεδα, συμπεριλαμβανομένου του αντικειμένου ανώτατου επιπέδου.
• Τα όρια ρυθμού ισχύουν ανά διεύθυνση IP (600 αιτήματα ανά λεπτό πριν από την ταυτοποίηση) και ανά κλειδί (300 αιτήματα ανά λεπτό). Σε 429 (1000005), περιμένετε το διάστημα Retry-After και δοκιμάστε ξανά με αυξανόμενη αναμονή. Κάθε απάντηση περιέχει X-RateLimit-Limit και X-RateLimit-Remaining.

Σφάλματα ελέγχου ταυτότητας

Βήματα ενσωμάτωσης

1. Δημιουργία της πληρωμής

   Ο διακομιστής σας καλεί το POST /api/payments/hosted. Αποθηκεύστε το payment_id που επιστρέφεται μαζί με την παραγγελία σας.

2. Ανακατεύθυνση του πληρωτή

   Ανακατευθύνετε το πρόγραμμα περιήγησης στο next_action.url ή ανοίξτε το σε νέα καρτέλα· μην το φορτώνετε ποτέ μέσα σε iframe.

3. Ολοκλήρωση της πληρωμής από τον πληρωτή

   Ο πληρωτής εισάγει τα στοιχεία της κάρτας. Αν η τράπεζα απαιτεί 3-D Secure, η σελίδα το εμφανίζει. Μια ενδιάμεση απόρριψη σε αυτό το στάδιο δεν είναι οριστική· η πληρωμή καταλήγει σε τελική κατάσταση χωρίς καμία ενέργεια από την πλευρά σας.

4. Επιστροφή του πληρωτή

   Η σελίδα εμφανίζει το αποτέλεσμα με σύντομη αντίστροφη μέτρηση και, στη συνέχεια, ανακατευθύνει το πρόγραμμα περιήγησης με υπογεγραμμένες παραμέτρους στο success_url (μόνο αν η πληρωμή είναι succeeded) ή στο fail_url. Δείτε URL επιστροφής.

5. Επιβεβαίωση του αποτελέσματος

   Περιμένετε την ειδοποίηση webhook ή καλέστε το GET /api/payments/{payment_id}. Εκτελέστε την παραγγελία μόνο όταν η κατάσταση είναι 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

Αντικείμενο πληρωμής

Οι κλήσεις δημιουργίας και ανάκτησης επιστρέφουν αυτό το αντικείμενο μέσα στο data, και κάθε ειδοποίηση webhook πληρωμής το περιέχει. Η δομή του είναι ίδια στο Hosted API και στο Direct API.

Το next_action μπορεί για σύντομο διάστημα να είναι null ακόμη και σε requires_action· σε αυτή την περίπτωση, ανακτήστε ξανά την πληρωμή. Ο πλήρης αριθμός κάρτας, το CVV, η ημερομηνία λήξης και το όνομα του κατόχου δεν επιστρέφονται ποτέ. Τα card.network και card.bank μπορεί να είναι null όταν δεν είναι γνωστά.

Τα στοιχεία customer που στάλθηκαν κατά τη δημιουργία της πληρωμής δεν αποτελούν μέρος αυτού του αντικειμένου και δεν εμφανίζονται στα 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 API

• Μια ενδιάμεση απόρριψη στη σελίδα πληρωμής δεν είναι οριστική: η πληρωμή μπορεί να παραμείνει σε requires_action και ενδέχεται να λάβετε payment.updated. Τελικά λαμβάνετε ένα οριστικό αποτέλεσμα.
• Οι καταστάσεις succeeded, failed, expired και cancelled είναι τελικές. Μια πληρωμή σε processing μπορεί να ολοκληρωθεί επιτυχώς ακόμη και μετά το expires_at.
• Αντιμετωπίστε κάθε κατάσταση που δεν αναφέρεται εδώ ως processing και ανακτήστε ξανά την πληρωμή.

Κωδικοί αποτυχίας

Μια πληρωμή σε failed περιέχει τα failure.code και failure.message. Χρησιμοποιήστε τον κωδικό στη λογική της εφαρμογής σας και εμφανίστε το μήνυμα στον πληρωτή ως απλό κείμενο.

Ενδέχεται να προστεθούν νέοι κωδικοί· χειριστείτε κάθε άγνωστο κωδικό ως payment_declined. Το failure.message μπορεί να περιέχει το κείμενο της ίδιας της τράπεζας· διαφορετικά, είναι στα αγγλικά στις ειδοποιήσεις webhook και ακολουθεί το Accept-Language στο GET.

Απαιτήσεις ανακατεύθυνσης

• Ανακατευθύνετε ολόκληρη τη σελίδα (303 ή window.location) στο next_action.url ή ανοίξτε το σε νέα καρτέλα. Μην το ενσωματώνετε σε iframe· η σελίδα αποκλείει τη φόρτωση σε πλαίσιο.
• Χρησιμοποιήστε το URL πριν από το next_action.expires_at. Μετά τη λήξη του, ανακτήστε την πληρωμή.
• Η γλώσσα της σελίδας ακολουθεί τις ρυθμίσεις του προγράμματος περιήγησης του πληρωτή· δεν απαιτείται καμία παράμετρος.

URL επιστροφής

Κατά την επιστροφή του πληρωτή, το πρόγραμμα περιήγησης ανακατευθύνεται στο success_url μόνο αν η πληρωμή είναι succeeded και στο fail_url σε κάθε άλλη περίπτωση. Στο URL προστίθενται υπογεγραμμένες παράμετροι. Επαληθεύστε τις για να εμφανίσετε τη σωστή σελίδα και εκτελέστε την παραγγελία μόνο αφού η ειδοποίηση webhook ή ένα GET επιβεβαιώσει την κατάσταση succeeded.

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

1. Επιλέξτε το μυστικό κλειδί που αντιστοιχεί στο κλειδί το οποίο προσδιορίζει το key_version. Πρόκειται για το κλειδί με το οποίο δημιουργήθηκε η πληρωμή, ακόμη και αν τα κλειδιά έχουν αντικατασταθεί στο μεταξύ.

2. Συνθέστε τη συμβολοσειρά από τις τιμές μετά την αποκωδικοποίηση URL. Αν δεν υπάρχει failure_code, διατηρήστε την τελική τελεία.

3. Υπολογίστε το HMAC-SHA256 και συγκρίνετέ το με το sig σε σταθερό χρόνο. Βεβαιωθείτε ότι το payment_id αντιστοιχεί σε μία από τις πληρωμές σας.

4. Ανακτήστε την πληρωμή με GET /api/payments/{payment_id} (ή περιμένετε την ειδοποίηση webhook) πριν εκτελέσετε την παραγγελία.

• Οι δικές σας παράμετροι ερωτήματος διατηρούνται. Αν το URL περιέχει ήδη παράμετρο με ένα από τα παραπάνω ονόματα, αυτή αντικαθίσταται.
• Αν ο σύνδεσμος δεν ήταν δυνατό να υπογραφεί λόγω προσωρινού σφάλματος, το URL δεν περιέχει καμία από αυτές τις παραμέτρους. Θεωρήστε το αποτέλεσμα άγνωστο και ανακτήστε την πληρωμή.

// 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

Ειδοποιήσεις webhook πληρωμής

Τα παρακάτω συμβάντα αποστέλλονται στο webhook_url της πληρωμής. Κάθε συμβάν πληρωμής αποστέλλεται το πολύ μία φορά ανά πληρωμή.

{
  "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"
  }
}

Επαληθεύετε κάθε ειδοποίηση webhook: το HMAC-SHA256 του X-Timestamp + "." + raw body, υπολογισμένο με το μυστικό κλειδί που αντιστοιχεί στο κλειδί API με το οποίο δημιουργήθηκε η πληρωμή, πρέπει να ισούται με το X-Signature και το X-Timestamp πρέπει να βρίσκεται εντός 300 δευτερολέπτων. Αποθηκεύστε κάθε event_id μία φορά και απαντήστε άμεσα με 2xx. Για παραδείγματα κώδικα και τη συμπεριφορά των επαναλήψεων, δείτε Ειδοποιήσεις webhook.

Σφάλματα

Η απόρριψη κάρτας δεν αποτελεί σφάλμα HTTP· η πληρωμή καταλήγει σε failed με failure.code. Για τον πλήρη κατάλογο, δείτε Κωδικοί σφαλμάτων.

Δοκιμές με κάρτες sandbox

Δημιουργήστε την πληρωμή με το κλειδί sandbox, ανοίξτε το next_action.url και πληρώστε με μία από τις παρακάτω κάρτες, με οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε τριψήφιο CVV. Για λεπτομέρειες, δείτε Sandbox και δοκιμαστικές κάρτες.

Ολοκληρωμένο παράδειγμα

Ένας ελάχιστος διακομιστής Node.js που δημιουργεί πληρωμή, ανακατευθύνει τον πληρωτή και χειρίζεται την επιστροφή και την ειδοποίηση webhook. Χρησιμοποιεί τη βοηθητική συνάρτηση αιτημάτων και τις συναρτήσεις επαλήθευσης από τις ενότητες Ειδοποιήσεις webhook και 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);

Συμβάντα

Τα συμβάντα πληρωμών, επιστροφών χρημάτων και αμφισβητήσεων αποστέλλονται στο webhook_url της πληρωμής, ενώ τα συμβάντα αναλήψεων στο webhook_url της ανάληψης. Κάθε συμβάν πληρωμής αποστέλλεται το πολύ μία φορά ανά πληρωμή· κάθε συμβάν επιστροφής χρημάτων, αμφισβήτησης ή ανάληψης το πολύ μία φορά ανά επιστροφή χρημάτων, αμφισβήτηση ή ανάληψη και ανά κατάσταση.

Περιεχόμενο ειδοποίησης

{
  "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"
  }
}

Συμβάντα επιστροφών χρημάτων, αμφισβητήσεων και αναλήψεων

• Τα συμβάντα επιστροφών χρημάτων και αμφισβητήσεων περιέχουν μία μόνο αναφορά πληρωμής: payment_id ή, σε ορισμένα συμβάντα, payment_code. Το refund.completed περιλαμβάνει πάντα payment_id. Όταν ένα συμβάν περιέχει payment_code, αντιστοιχίστε την παραγγελία με βάση το merchant_order_id.
• Πριν ενεργήσετε βάσει ενός συμβάντος, ανακτήστε την επιστροφή χρημάτων, την αμφισβήτηση ή την ανάληψη με GET για να επιβεβαιώσετε την τρέχουσα κατάστασή της.

{
  "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"
  }
}

Επαλήθευση υπογραφής

1. Διαβάστε τα byte του ακατέργαστου σώματος πριν αναλύσετε το JSON.

2. Επαληθεύστε ότι το X-Timestamp έχει 10 ψηφία και απέχει έως 300 δευτερόλεπτα από την ώρα του διακομιστή σας.

3. Υπολογίστε το HMAC-SHA256 του X-Timestamp + "." + raw body με το μυστικό κλειδί API σας και συγκρίνετε το αποτέλεσμα με το X-Signature σε σταθερό χρόνο.

4. Αν η επαλήθευση αποτύχει, απορρίψτε το αίτημα με 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

Επεξεργασία κάθε συμβάντος μία φορά

1. Αποθηκεύστε το event_id σε πίνακα με μοναδικό ευρετήριο. Αν υπάρχει ήδη, απαντήστε με 2xx και διακόψτε την επεξεργασία.

2. Απαντήστε με 2xx μέσα σε λίγα δευτερόλεπτα και εκτελέστε τις χρονοβόρες εργασίες (μηνύματα ηλεκτρονικού ταχυδρομείου, ενημερώσεις αποθέματος) στη συνέχεια, μέσω ουράς.

3. Τα συμβάντα μπορεί να φτάσουν με καθυστέρηση, περισσότερες από μία φορές ή εκτός σειράς. Μια πληρωμή που ολοκληρώνεται λόγω λήξης χρονικού ορίου μπορεί να αναφερθεί ένα λεπτό ή και αργότερα. Βασίζετε τις αποφάσεις σας στην κατάσταση που περιέχει το data ή ανακτήστε ξανά το αντικείμενο με GET.

4. Μην εκτελείτε ποτέ μια παραγγελία μόνο επειδή το πρόγραμμα περιήγησης επέστρεψε στο success_url.

Επαναλήψεις αποστολής

• Κάθε απάντηση 2xx εντός περίπου 10 δευτερολέπτων θεωρείται επιτυχής αποστολή. Οι ανακατευθύνσεις δεν ακολουθούνται και θεωρούνται αποτυχίες.
• Οι αποτυχημένες αποστολές επαναλαμβάνονται μετά από περίπου 1 λεπτό, 5 λεπτά, 15 λεπτά, 1 ώρα και 6 ώρες. Το σώμα και το X-Event-Id παραμένουν αμετάβλητα· τα X-Timestamp και X-Signature δημιουργούνται εκ νέου σε κάθε προσπάθεια.
• Μετά την τελευταία προσπάθεια, η αποστολή επισημαίνεται ως failed. Ορισμένα σφάλματα (ιδιωτική IP ως προορισμός, κλειδί υπογραφής που λείπει) δεν επαναλαμβάνονται και η αποστολή επισημαίνεται αμέσως ως failed. Οι αποτυχημένες αποστολές μπορούν να σταλούν ξανά μέσω του API αποστολών.
• Το webhook_url σας πρέπει να επιλύεται σε δημόσια διεύθυνση IP σε κάθε προσπάθεια.

Αποστολές webhook

Κάθε ειδοποίηση webhook που αποστέλλεται καταχωρίζεται ως αποστολή. Χρησιμοποιήστε αυτό το API για να εντοπίσετε τις αποτυχημένες αποστολές και να τις στείλετε ξανά.

./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)

Λειτουργία του sandbox

• Δεν υπάρχει διακόπτης περιβάλλοντος: τα αιτήματα που υπογράφονται με κλειδί sandbox εκτελούνται στο sandbox και τα αιτήματα που υπογράφονται με κλειδί παραγωγής εκτελούνται στο περιβάλλον παραγωγής.
• Οι παρακάτω κάρτες λειτουργούν τόσο στη σελίδα πληρωμής όσο και στη δική σας φόρμα πληρωμής· οι πραγματικές κάρτες απορρίπτονται. Η δική σας φόρμα δέχεται επίσης οποιονδήποτε άλλο έγκυρο αριθμό κάρτας με BIN 435509 ή 400000· στη συνέχεια, μια δοκιμαστική σελίδα σάς επιτρέπει να επιλέξετε επιτυχία, αποτυχία ή απουσία απάντησης.
• Οι οθόνες 3-D Secure είναι δοκιμαστικές και οι αριθμοί κάρτας πρέπει να έχουν έγκυρο ψηφίο ελέγχου.
• Οι ειδοποιήσεις webhook αποστέλλονται ως πραγματικά αιτήματα HTTPS στο webhook_url σας και υπογράφονται με το μυστικό κλειδί sandbox.

Δοκιμαστικές κάρτες

Οι κάρτες συμπεριφέρονται το ίδιο στο Hosted API και στο Direct API, εκτός αν ο πίνακας αναφέρει κάτι διαφορετικό. Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε τριψήφιο CVV.

• Με οποιαδήποτε δοκιμαστική κάρτα, ένα ποσό που λήγει σε .77 (για παράδειγμα 100.77) διατηρεί την πληρωμή σε processing (χειροκίνητος έλεγχος).
• Μια δοκιμαστική πληρωμή που δεν λαμβάνει ποτέ απάντηση κλείνει τελικά ως failed με service_unavailable.
• Μια πληρωμή με δοκιμαστική κάρτα που απορρίπτεται (για παράδειγμα 4000000000000051) μπορεί να παραμείνει σε requires_action για κάποιο διάστημα πριν περιέλθει σε τελική κατάσταση. Βασίζετε τις αποφάσεις σας στην ειδοποίηση webhook ή σε ένα GET, όχι σε μια ενδιάμεση απόρριψη.

Δοκιμαστικά BIN

Στο sandbox, ο έλεγχος BIN επιστρέφει τα ακόλουθα αποτελέσματα:

Επιστροφές χρημάτων και αναλήψεις

Στο sandbox, οι επιστροφές χρημάτων και οι αναλήψεις ολοκληρώνονται αμέσως έναντι ενός δοκιμαστικού υπολοίπου. Επιλέξτε το αποτέλεσμα με την κεφαλίδα X-Sandbox-Scenario, η οποία δεν αποτελεί μέρος της υπογραφής. Χρησιμοποιήστε νέο Idempotency-Key για κάθε σενάριο: η κεφαλίδα αποτελεί μέρος του αποτυπώματος idempotency και το ίδιο κλειδί με διαφορετικό σενάριο απορρίπτεται με 409 9000010. Άγνωστη τιμή, ή η κεφαλίδα με κλειδί live, επιστρέφει 422 1000001· το τελικό σημείο αποδεικτικών στοιχείων δεν δέχεται την κεφαλίδα. Το σενάριο που εφαρμόστηκε επιστρέφεται στην κεφαλίδα απάντησης X-Sandbox-Scenario.

Πριν εφαρμοστεί το σενάριο, το sandbox επιβάλλει τους ίδιους κανόνες με το live: ελάχιστα και ημερήσια όρια ανάληψης, συναλλαγματικές ισοτιμίες (503 3000001 όταν δεν είναι διαθέσιμες) και επαλήθευση διεύθυνσης. Κάθε διεύθυνση TRC20 με έγκυρο άθροισμα ελέγχου γίνεται δεκτή στο sandbox, συμπεριλαμβανομένης της μηδενικής διεύθυνσης TRON, και δεν πραγματοποιείται μεταφορά· το 1000030 (διεύθυνση που δεν μπορεί να λάβει πληρωμές) δεν αναπαράγεται στο 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)

Το tx_hash στο sandbox είναι προσομοιωμένο και δεν αντιστοιχεί σε πραγματική συναλλαγή blockchain.

Αρχείο αιτημάτων

Η σελίδα Αρχείο αιτημάτων παραθέτει τα πρόσφατα αιτήματα API σας με την κατάσταση, τον κωδικό σφάλματος και το correlation_id. Τα αιτήματα που απορρίπτονται πριν από την αναγνώριση του κλειδιού (μη έγκυρο κλειδί, υπογραφή ή κωδικός εμπόρου) δεν εμφανίζονται. Οι πληρωμές sandbox εμφανίζονται στην ενότητα Παραγγελίες API Sandbox.

Μορφή απάντησης σφάλματος

{
  "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_class υπάρχει μόνο σε απαντήσεις που περιέχουν metadata (Direct API, σφάλματα ταυτοποίησης και ορίου ρυθμού). Τα υπόλοιπα σφάλματα περιέχουν αντ' αυτού integration.retryable.
• Μετά από λήξη χρονικού ορίου ή 5xx, μη δημιουργείτε ποτέ νέα πληρωμή· ανακτήστε την πληρωμή ή στείλτε ξανά το αίτημα με το ίδιο κλειδί.
• Η απόρριψη κάρτας δεν αποτελεί σφάλμα HTTP: η πληρωμή επιστρέφεται με 200, status: failed και failure.
• Το developer_detail ενδέχεται να αλλάξει· μη βασίζετε τη λογική της ενσωμάτωσης σε αυτό.

Όλοι οι κωδικοί σφαλμάτων

Έλεγχος ταυτότητας και πρόσβαση

Idempotency-Key και συγκρούσεις

Επικύρωση δεδομένων

Ποσό, κάρτα και BIN

Δεν βρέθηκε

Όρια και διαθεσιμότητα

Λειτουργίες λογαριασμού

Αποκλειστικά στο sandbox

Γλώσσα μηνυμάτων

Τα title και detail ακολουθούν την κεφαλίδα Accept-Language (en, tr, de, ar, es, el· το de-AT αντιμετωπίζεται ως de). Για οποιαδήποτε άλλη τιμή επιστρέφονται αγγλικά. Η κεφαλίδα Content-Language δηλώνει τη γλώσσα που χρησιμοποιήθηκε.