Integrazione tramite API

Il Suo backend crea una sessione di Checkout per ogni ordine e la recupera per verificare il pagamento.

Per Node.js, l'SDK @tapayadot/checkout fornisce per questi endpoint i metodi tipizzati create() e get(). Per impostazione predefinita legge TAPAYA_SECRET_KEY. Gli esempi HTTP in questa pagina passano TAPAYA_CHECKOUT_API_KEY in modo esplicito.

Autenticazione

Ogni chiamata a Checkout avviene da server a server e invia una chiave come bearer token:

Authorization: Bearer <key>

Scelga la modalità in base a chi gestisce il backend. In entrambi i casi conservi la chiave sul Suo server; si veda Sicurezza di Checkout.

Modalità esercente

Usi questa modalità quando il backend serve un solo negozio. Crei una chiave checkout dell'esercente nelle impostazioni di Checkout: apra l'esercente e selezioni Create merchant key. La chiave inizia con tapaya_test_ in sandbox o con tapaya_live_ in produzione e corrisponde esattamente a quell'esercente.

Authorization: Bearer <merchant-checkout-key>

In questa modalità X-Tapaya-Merchant-Token è facoltativo. Se lo invia, deve indicare lo stesso esercente.

La Platform mostra la chiave una sola volta e ne salva solo un hash. Per ruotare una chiave, crei quella sostitutiva prima di revocare la vecchia. La revoca di una chiave non influisce sulle altre chiavi dell'esercente, sulle chiavi dell'organizzazione né sui client secret già emessi ai browser.

Modalità piattaforma

Usi questa modalità quando un unico backend agisce per molti esercenti, ad esempio un marketplace o una piattaforma di consegna di cibo a domicilio. Invii in ogni richiesta la Secret key dell'organizzazione dalla pagina API Keys e il token dell'esercente:

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

Non esiste un esercente predefinito. Una richiesta senza l'intestazione restituisce HTTP 401. L'esercente deve appartenere all'organizzazione della chiave. Copi i token degli esercenti dalla tabella degli esercenti nelle impostazioni di Checkout. Il token identifica l'esercente; non è un segreto.

La Secret key dell'organizzazione è la stessa credenziale che la documentazione della Platform API chiama Server Secret Token. Checkout richiede il prefisso Bearer. Gli altri endpoint della Platform API accettano il token direttamente. L'onboarding degli esercenti e la gestione dell'organizzazione usano la Platform API.

I corpi delle richieste non accettano un merchantId.

Ambienti

Imposti TAPAYA_CHECKOUT_API_URL sull'origine dell'API del Suo ambiente. In produzione sono disponibili sia i pagamenti ospitati sia quelli incorporati. Ogni esercente deve completare l'onboarding, ottenere l'approvazione del processore di pagamento per i pagamenti online e avere un gateway di pagamento configurato. Verifichi la preparazione dell'esercente nelle impostazioni di Checkout. Usi invariato l'URL della sessione ospitata restituito.

Sessioni di Checkout

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"

Responsabilità di ordine e pagamento

L'ID di una sessione di checkout identifica un Hosted Checkout. Il suo merchantOrderId la collega al Suo ordine, mentre paymentReference identifica l'ultimo tentativo di conferma. Salvi l'ID della sessione insieme all'ordine, così da poter recuperare l'esito anche se il cliente chiude il browser.

La pagina ospitata usa endpoint pubblici separati per caricare e confermare la sessione. Il suo ID di sessione è una credenziale di accesso per quegli endpoint. Un'integrazione dell'esercente verifica il pagamento tramite l'endpoint autenticato per gli esercenti.

Un pagamento per ordine

Hosted ed Embedded Checkout condividono un unico motore di pagamento. Un esercente può avere al massimo un pagamento riuscito per merchantOrderId. Gli ID degli ordini valgono a livello di esercente, quindi esercenti diversi, anche all'interno della stessa organizzazione, possono usare gli stessi ID.

• La creazione di una sessione per un ordine non pagato sostituisce la sessione non pagata precedente. Il vecchio URL riporta expired e non può più accettare pagamenti.
• La creazione di una sessione per un ordine già pagato, o con un pagamento in corso, restituisce HTTP 409.
• Dopo un rifiuto, il cliente può provare un'altra carta o un altro wallet nella stessa sessione. Inviare di nuovo lo stesso token della carta non comporta mai un doppio addebito.
• Tapaya definisce la policy 3-D Secure e tenta sempre l'autenticazione.

Idempotenza ed errori

La creazione richiede un Idempotency-Key non vuoto di al massimo 250 caratteri. Per lo stesso esercente:

Il rifiuto di una carta è un esito del pagamento, non la prova che una richiesta HTTP non sia riuscita.