Direct API

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

1. Έλεγχος BIN

   Μόλις ο πληρωτής εισαγάγει έξι ψηφία, καλέστε το GET /api/payments/bin/{bin6}. Το payment_mode υποδεικνύει αν πρέπει να συλλέξετε τα πλήρη στοιχεία της κάρτας στη φόρμα σας ή να παραπέμψετε τον πληρωτή στη σελίδα πληρωμής.

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

   Καλέστε το POST /api/payments/direct με τα στοιχεία της κάρτας ή, για BIN τύπου hosted, μόνο με bin6.

3. Ολοκλήρωση του 3-D Secure

   Αν η κατάσταση είναι requires_action, ανακατευθύνετε το πρόγραμμα περιήγησης στο next_action.url. Στη συνέχεια, το πρόγραμμα περιήγησης επιστρέφει στο success_url ή στο fail_url σας με υπογεγραμμένες παραμέτρους.

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

   Περιμένετε την ειδοποίηση webhook payment.succeeded ή payment.failed ή καλέστε το GET /api/payments/{payment_id}. Εκτελέστε την παραγγελία μόνο σε κατάσταση succeeded.

Your server                          Payniko                        Payer's browser
 1  GET /api/payments/bin/{bin6} ───►  payment_mode: direct | hosted
 2  POST /api/payments/direct  ─────►  200  requires_action + next_action.url
                                            (or processing / succeeded / failed)
 3  redirect to next_action.url ──────────────────────────────────►  3-D Secure page
                                       ───────────────────────────►  success_url / fail_url
 4  webhook  ◄───────────────────────  payment.succeeded / payment.failed
    GET /api/payments/{payment_id} ──►  current status

Προαπαιτούμενα

• Το Direct API ενεργοποιείται ανά λογαριασμό. Χωρίς αυτή την πρόσβαση, τα αιτήματα απορρίπτονται με 403 0055502.
• Τα κλειδιά, οι κεφαλίδες και η υπογραφή είναι ίδια με του Hosted API· δείτε Έλεγχος ταυτότητας. Τα παραδείγματα χρησιμοποιούν τις βοηθητικές συναρτήσεις αιτημάτων.

3. 3-D Secure και πρόγραμμα περιήγησης

Όταν η κατάσταση είναι requires_action, το πρόγραμμα περιήγησης του πληρωτή πρέπει να ανοίξει το next_action.url, όπου η τράπεζα εκτελεί τον έλεγχο 3-D Secure ή ο πληρωτής συνεχίζει στη σελίδα πληρωμής.

• Ανακατευθύνετε ολόκληρη τη σελίδα στο next_action.url ή ανοίξτε το σε νέα καρτέλα· και οι δύο μέθοδοι υποστηρίζονται πάντα.
• Η σελίδα δεν ζητά ξανά τα στοιχεία της κάρτας· συλλέγει μόνο τα δεδομένα του προγράμματος περιήγησης που απαιτεί η τράπεζα.
• Χρησιμοποιείτε πάντα το πιο πρόσφατο next_action.url πριν από το next_action.expires_at του (το τέλος του βήματος 3-D Secure). Μην ανοίγετε ποτέ ξανά προηγούμενο URL.
• Στη συνέχεια, το πρόγραμμα περιήγησης ανακατευθύνεται στο success_url (μόνο σε succeeded) ή στο fail_url με υπογεγραμμένες παραμέτρους (δείτε URL επιστροφής). Έπειτα, ανακτήστε την πληρωμή.

Ενσωμάτωση σε πλαίσιο

Η σελίδα 3-D Secure δεν μπορεί να εμφανιστεί μέσα σε πλαίσιο· ανακατευθύνετε ολόκληρη τη σελίδα ή ανοίξτε νέα καρτέλα. Μόνο η σελίδα πληρωμής ενός BIN τύπου hosted επιτρέπεται να ενσωματωθεί σε πλαίσιο, μόνο με κλειδιά παραγωγής και μόνο στην ακριβή προέλευση (origin) του success_url της πληρωμής. Η σελίδα πληρωμής του Hosted API δεν μπορεί ποτέ να ενσωματωθεί σε πλαίσιο.

Η σελίδα πληρωμής ενός BIN τύπου hosted ενσωματώνει την ασφαλή οθόνη πληρωμής και 3-D Secure του ίδιου του παρόχου πληρωμών και μπορεί να εμφανιστεί ως iframe μέσα στη δική σας φόρμα πληρωμής.

Αν ενσωματώσετε σε πλαίσιο τη σελίδα πληρωμής ενός BIN τύπου hosted, τα μηνύματα που αποστέλλει στο παράθυρό σας χρησιμεύουν μόνο ως σήμα για να ελέγξετε την πληρωμή. Αποδεχτείτε τα μόνο από την προέλευση του next_action.url και από το δικό σας πλαίσιο, αγνοήστε το περιεχόμενό τους και αναθέστε την ανάκτηση της πληρωμής στον διακομιστή σας.

// Only if you show the payment page of a hosted BIN in a frame on the exact origin of success_url.
// nextActionUrl: next_action.url from your server.
const pageOrigin = new URL(nextActionUrl).origin;
window.addEventListener('message', (event) => {
  if (event.origin !== pageOrigin || event.source !== frame.contentWindow) return;
  // A wake-up call only: ignore event.data. Ask your server to read the payment.
  fetch('/checkout/ORDER-2026-002/refresh', {method: 'POST', credentials: 'same-origin'});
});

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

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

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

Τα στοιχεία customer που στάλθηκαν κατά τη δημιουργία της πληρωμής δεν αποτελούν μέρος αυτού του αντικειμένου και δεν εμφανίζονται στα webhooks.

{
  "data": {
    "payment_id": "3c2d7a4e-5b1f-4e8a-9d06-7f2b1c9e4a35",
    "merchant_order_id": "ORDER-2026-002",
    "flow": "direct",
    "status": "requires_action",
    "amount": "100.00",
    "currency": "USD",
    "environment": "sandbox",
    "next_action": {
      "type": "redirect",
      "url": "https://payniko.com/example-authentication-step",
      "expires_at": "2026-11-01T12:30:00.000Z"
    },
    "card": {
      "bin6": "435509",
      "last_four": "4242",
      "network": "visa",
      "bank": "Test Bank"
    },
    "failure": null,
    "created_at": "2026-11-01T12:00:00.000Z",
    "expires_at": "2026-11-01T12:30:00.000Z",
    "completed_at": null
  }
}

Καταστάσεις πληρωμής Direct API

Αντιμετωπίστε κάθε κατάσταση που δεν αναφέρεται εδώ ως processing και ανακτήστε ξανά την πληρωμή.

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

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

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

URL επιστροφής

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

Direct API: αν το αποτέλεσμα δεν είναι ακόμη τελικό όταν ο πληρωτής επιστρέφει από το 3-D Secure, το πρόγραμμα περιήγησης δεν ανακατευθύνεται στο fail_url· ο πληρωτής παραμένει σε μια ουδέτερη σελίδα αποτελέσματος της Payniko. Βασιστείτε στο webhook ή σε ένα GET για το αποτέλεσμα.

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.

Σφάλματα

Τα σφάλματα του Direct API περιλαμβάνουν επίσης το metadata.retry_class (no_retry, retry_same_request, retry_after, read_order). Ένα κλειστό παράθυρο του προγράμματος περιήγησης ή μια λήξη χρονικού ορίου από την πλευρά σας δεν σημαίνει ότι η πληρωμή απέτυχε· ανακτήστε την πληρωμή. Για τον πλήρη κατάλογο, δείτε Κωδικοί σφαλμάτων.

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

Με κλειδί sandbox, ο έλεγχος BIN και η πληρωμή χρησιμοποιούν σταθερά δοκιμαστικά δεδομένα: τα 435509 και 400000 είναι BIN τύπου direct και το 540061 είναι BIN τύπου hosted. Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε τριψήφιο CVV. Για λεπτομέρειες, δείτε Sandbox και δοκιμαστικές κάρτες.

Με το Direct API, μια απορριφθείσα δοκιμαστική κάρτα επιστρέφει failed απευθείας στην απάντηση δημιουργίας· ενδιάμεσο requires_action εμφανίζεται μόνο στη σελίδα πληρωμής ενός hosted BIN. Βασίστε τις αποφάσεις σας στο webhook ή σε ένα GET.

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

Ένας ελάχιστος διακομιστής Node.js που καλύπτει τον έλεγχο BIN, τη δημιουργία πληρωμής, την ανακατεύθυνση για 3-D Secure, το URL επιστροφής και την ειδοποίηση webhook. Χρησιμοποιεί τη βοηθητική συνάρτηση αιτημάτων και τις συναρτήσεις επαλήθευσης από τις ενότητες Ειδοποιήσεις webhook και URL επιστροφής.

// server.mjs: Direct 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); };

const reply = (res, data) => {
  res.writeHead(200, {'Content-Type': 'application/json'});
  res.end(JSON.stringify(data.status === 'requires_action' && data.next_action
    ? {redirect: data.next_action.url} : {status: data.status, failure: data.failure}));
};

http.createServer(async (req, res) => {
  const url = new URL(req.url, site);
  // 1. BIN check, 2. create the payment. Your own HTTPS form posts the card here.
  if (req.method === 'POST' && url.pathname === '/pay') {
    const form = JSON.parse((await readBody(req)).toString('utf8'));
    const bin6 = form.number.slice(0, 6);
    let mode = null;
    try {
      mode = (await api('GET', `/api/payments/bin/${bin6}?amount=100.00&currency=USD`)).data.payment_mode;
    } catch (error) {
      if (error.status === undefined || error.status >= 500 || error.status === 429) throw error;
    }
    if (mode !== 'direct' && mode !== 'hosted') { res.writeHead(422).end('Please use another card.'); return; }
    const orderId = 'ORDER-' + Date.now();
    const key = randomUUID();
    orders.set(orderId, {key, status: 'new'});
    const body = {
      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`,
    };
    if (mode === 'direct') {
      body.card = {number: form.number, holder_name: form.holder_name,
        expiry_month: form.expiry_month, expiry_year: form.expiry_year, cvv: form.cvv};
    } else {
      body.bin6 = bin6;                               // payer enters the card on the payment page
    }
    const {data} = await api('POST', '/api/payments/direct', body, key);
    Object.assign(orders.get(orderId), {paymentId: data.payment_id, status: data.status});
    reply(res, data);                                 // 3. browser goes to next_action.url
    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);