Integrace přes API

Váš backend vytvoří pro každou objednávku relaci Checkoutu a načte ji, aby ověřil platbu.

Pro Node.js poskytuje SDK @tapayadot/checkout pro tyto endpointy typované metody create() a get(). Ve výchozím nastavení načítá TAPAYA_SECRET_KEY. Příklady HTTP na této stránce předávají TAPAYA_CHECKOUT_API_KEY explicitně.

Autentizace

Každé volání Checkoutu probíhá mezi servery a odesílá klíč jako bearer token:

Authorization: Bearer <key>

Zvolte režim podle toho, kdo backend provozuje. Oba typy klíčů uchovávejte na svém serveru; viz Zabezpečení Checkoutu.

Režim obchodníka

Tento režim použijte, když backend obsluhuje jeden obchod. V Nastavení Checkoutu vytvořte Checkout klíč obchodníka: otevřete obchodníka a zvolte Create merchant key. Klíč začíná na tapaya_test_ v sandboxu nebo tapaya_live_ v produkci a odkazuje právě na tohoto obchodníka.

Authorization: Bearer <merchant-checkout-key>

X-Tapaya-Merchant-Token je v tomto režimu volitelný. Pokud jej odešlete, musí označovat stejného obchodníka.

Tapaya Platform zobrazí klíč jen jednou a ukládá pouze jeho hash. Při rotaci klíče nejprve vytvořte náhradní klíč a teprve potom zrušte starý. Zrušení klíče neovlivní ostatní klíče obchodníků, klíče organizace ani client secret, které už byly vydány prohlížečům.

Režim platformy

Tento režim použijte, když jeden backend jedná za mnoho obchodníků, například jako tržiště nebo platforma pro rozvoz jídla. V každém požadavku odešlete Secret key organizace ze stránky API Keys a token obchodníka:

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

Žádný výchozí obchodník neexistuje. Požadavek bez této hlavičky vrátí HTTP 401. Obchodník musí patřit do organizace daného klíče. Tokeny obchodníků zkopírujte z tabulky obchodníků v Nastavení Checkoutu. Token identifikuje obchodníka; není tajný.

Secret key organizace je tentýž přihlašovací údaj, který dokumentace Platform API nazývá Server Secret Token. Checkout vyžaduje předponu Bearer. Ostatní endpointy Platform API přijímají token přímo. Onboarding obchodníků a správa organizace probíhají přes Platform API.

Těla požadavků nepřijímají merchantId.

Prostředí

Nastavte TAPAYA_CHECKOUT_API_URL na origin API pro vaše prostředí. V produkci jsou k dispozici hostované i embedded platby. Každý obchodník musí projít onboardingem, získat od zpracovatele plateb schválení pro online platby a mít nakonfigurovanou platební bránu. Připravenost obchodníka zkontrolujete v Nastavení Checkoutu. Vrácenou URL hostované relace používejte beze změny.

Relace 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"

Vlastnictví objednávky a platby

ID relace Checkoutu identifikuje hostovaný Checkout. Pole merchantOrderId relace ji propojuje s vaší objednávkou, zatímco paymentReference identifikuje poslední pokus o potvrzení. Ukládejte ID relace k objednávce, abyste mohli výsledek načíst, i když zákazník zavře prohlížeč.

Hostovaná stránka používá k načtení a potvrzení relace samostatné veřejné endpointy. ID relace slouží pro tyto endpointy jako přístupový údaj. Integrace obchodníka ověřuje platbu přes autentizovaný endpoint pro obchodníky.

Jedna platba na objednávku

Hosted a Embedded Checkout sdílejí jeden platební systém. Obchodník může mít na jedno merchantOrderId nejvýše jednu úspěšnou platbu. ID objednávek platí v rámci obchodníka, takže různí obchodníci, i v rámci jedné organizace, mohou používat stejná ID.

• Vytvoření relace pro nezaplacenou objednávku nahradí předchozí nezaplacenou relaci. Stará URL hlásí expired a už nemůže přijmout platbu.
• Vytvoření relace pro objednávku, která je už zaplacená nebo u které probíhá platba, vrátí HTTP 409.
• Po zamítnutí může zákazník ve stejné relaci zkusit jinou kartu nebo peněženku. Opětovné odeslání stejného tokenu karty nikdy nezaúčtuje platbu dvakrát.
• Tapaya určuje pravidla pro 3-D Secure a vždy se pokusí o autentizaci.

Idempotence a chyby

Vytvoření vyžaduje neprázdný Idempotency-Key o délce nejvýše 250 znaků. Pro stejného obchodníka platí:

Zamítnutí karty je výsledek platby, nikoli důkaz, že požadavek HTTP selhal.