Integrácia API

Váš backend vytvorí pre každú objednávku reláciu Checkoutu a načíta ju, aby overil platbu.

Pre Node.js poskytuje SDK @tapayadot/checkout pre tieto endpointy typované metódy create() a get(). Predvolene načítava TAPAYA_SECRET_KEY. Príklady HTTP na tejto stránke odovzdávajú TAPAYA_CHECKOUT_API_KEY explicitne.

Autentifikácia

Každé volanie Checkoutu prebieha medzi servermi a posiela kľúč ako bearer token:

Authorization: Bearer <key>

Zvoľte režim podľa toho, kto backend prevádzkuje. Oba typy kľúčov uchovávajte na svojom serveri; pozrite si Zabezpečenie Checkoutu.

Režim obchodníka

Tento režim použite, keď backend obsluhuje jeden obchod. V nastaveniach Checkoutu vytvorte checkout kľúč obchodníka: otvorte obchodníka a zvoľte Create merchant key. Kľúč začína na tapaya_test_ v sandboxe alebo tapaya_live_ v produkcii a zodpovedá práve tomuto obchodníkovi.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token je v tomto režime voliteľný. Ak ho pošlete, musí označovať toho istého obchodníka.

Tapaya Platform zobrazí kľúč iba raz a ukladá len jeho hash. Pri rotácii kľúča najprv vytvorte náhradný kľúč a až potom zneplatnite starý. Zneplatnenie kľúča neovplyvní ostatné kľúče obchodníkov, kľúče organizácie ani client secrets, ktoré už boli vydané prehliadačom.

Režim platformy

Tento režim použite, keď jeden backend koná za mnoho obchodníkov, napríklad marketplace alebo platforma na rozvoz jedla. V každej požiadavke pošlite Secret key organizácie zo stránky API Keys a token obchodníka:

Authorization: Bearer <secret-key>
X-Tapaya-Merchant-Token: <merchant-token>

Neexistuje žiadny predvolený obchodník. Požiadavka bez tejto hlavičky vráti HTTP 401. Obchodník musí patriť do organizácie daného kľúča. Tokeny obchodníkov skopírujte z tabuľky obchodníkov v nastaveniach Checkoutu. Token identifikuje obchodníka; nie je tajný.

Secret key organizácie je ten istý prihlasovací údaj, ktorý dokumentácia Platform API nazýva Server Secret Token. Checkout vyžaduje predponu Bearer. Ostatné endpointy Platform API prijímajú token priamo. Onboarding obchodníkov a správa organizácie prebiehajú cez Platform API.

Telá požiadaviek neprijímajú merchantId.

Prostredia

Nastavte TAPAYA_CHECKOUT_API_URL na origin API pre vaše prostredie. V produkcii sú k dispozícii hostované aj vložené platby. Každý obchodník musí prejsť onboardingom, získať od spracovateľa schválenie pre online platby a mať nakonfigurovanú platobnú bránu. Pripravenosť obchodníka skontrolujete v nastaveniach Checkoutu. Vrátenú URL hostovanej relácie používajte bez zmeny.

Relácie Checkoutu

curl -X 'POST' "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN" \
-H 'Idempotency-Key: order-1001-checkout-1' \
-d '{
        "merchantOrderId": "order-1001",
        "amount": 12100,
        "currency": "EUR",
        "tax": 2100,
        "shipping": 605,
        "taxRate": 21,
        "successUrl": "https://shop.example/checkout/return",
        "cancelUrl": "https://shop.example/checkout/cancel"
    }'

{
    "id": "cs_7Hq2x9LmR4",
    "merchantOrderId": "order-1001",
    "url": "https://checkout.sandbox.tapaya.com/c/cs_7Hq2x9LmR4",
    "status": "open",
    "paymentStatus": "unpaid",
    "amount": 12100,
    "currency": "EUR",
    "tax": 2100,
    "shipping": 605,
    "taxRate": 21,
    "taxBreakdown": [],
    "items": [],
    "expiresAt": "2026-07-15T12:30:00Z",
    "createdAt": "2026-07-15T12:00:00Z"
}

curl "$TAPAYA_CHECKOUT_API_URL/merchant/checkout-sessions/cs_7Hq2x9LmR4" \
-H "Authorization: Bearer $TAPAYA_CHECKOUT_API_KEY" \
-H "X-Tapaya-Merchant-Token: $TAPAYA_MERCHANT_TOKEN"

Vlastníctvo objednávky a platby

ID relácie Checkoutu identifikuje hostovaný Checkout. Pole merchantOrderId relácie ju prepája s vašou objednávkou, zatiaľ čo paymentReference identifikuje posledný pokus o potvrdenie. Ukladajte ID relácie k objednávke, aby ste mohli výsledok načítať, aj keď zákazník zatvorí prehliadač.

Hostovaná stránka používa na načítanie a potvrdenie relácie samostatné verejné endpointy. ID relácie slúži pre tieto endpointy ako prístupový údaj. Integrácia obchodníka overuje platbu cez autentifikovaný endpoint pre obchodníkov.

Jedna platba na objednávku

Hosted a Embedded Checkout zdieľajú jeden platobný systém. Obchodník môže mať na jedno merchantOrderId najviac jednu úspešnú platbu. ID objednávok platia v rámci obchodníka, takže rôzni obchodníci, aj v rámci jednej organizácie, môžu používať rovnaké ID.

• Vytvorenie relácie pre nezaplatenú objednávku nahradí predchádzajúcu nezaplatenú reláciu. Stará URL hlási expired a už nemôže prijať platbu.
• Vytvorenie relácie pre objednávku, ktorá je už zaplatená alebo pri ktorej prebieha platba, vráti HTTP 409.
• Po zamietnutí môže zákazník v tej istej relácii skúsiť inú kartu alebo peňaženku. Opätovné odoslanie toho istého tokenu karty nikdy nezaťaží kartu dvakrát.
• Tapaya určuje pravidlá pre 3-D Secure a vždy sa pokúsi o autentifikáciu.

Idempotencia a chyby

Vytvorenie vyžaduje neprázdny Idempotency-Key s dĺžkou najviac 250 znakov. Pre toho istého obchodníka platí:

Zamietnutie karty je výsledok platby, nie dôkaz, že požiadavka HTTP zlyhala.