Node.js SDK

@tapayadot/checkout je serverové TypeScript SDK pre Tapaya Checkout. Táto referencia opisuje verziu 0.3.0.

npm install @tapayadot/checkout

import { Tapaya } from '@tapayadot/checkout';

const tapaya = new Tapaya();

Klient načítava TAPAYA_SECRET_KEY z prostredia servera. Balík obsahuje aj loader pre prehliadač a React hook pre Embedded Checkout. Loader sťahuje Tapaya.js 0.2.0 z https://js.tapaya.com/checkout/0.2.0/checkout.js; verzia skriptu pre prehliadač je od verzie tohto balíka nezávislá. Súbory .env nenačítava. Kľúč aj klienta držte iba v kóde, ktorý beží na serveri. Sprievodca Hosted Checkout opisuje vytvorenie objednávky, presmerovanie zákazníka a overenie platby.

Konfigurácia

const tapaya = new Tapaya(apiKey, {
	environment: 'sandbox',
	timeoutMs: 30_000,
	maxRetries: 2,
})

Ak chcete použiť vlastný API endpoint, nastavte na svojom serveri TAPAYA_BASE_URL=https://api.example.com. Explicitne zadaná baseUrl má prednosť pred TAPAYA_BASE_URL; obe prepisujú voľbu podľa prostredia.

Klient určí API kľúč a URL API raz, pri svojom vytvorení. Použite kľúč, ktorý zodpovedá zvolenému prostrediu. URL API, návratové URL a URL hostovaného Checkoutu musia používať HTTPS, s výnimkou HTTP pre localhost, 127.0.0.1 a [::1] mimo NODE_ENV=production. SDK kontroluje aktuálne NODE_ENV pri každom overení lokálnej URL s HTTP.

timeoutMs musí byť celé číslo od 1 do 2 147 483 647. maxRetries musí byť nezáporné bezpečné celé číslo. Predvolený počet opakovaní umožňuje až tri pokusy na jedno volanie, každý s vlastným časovým limitom.

Každá metóda prijíma aj signal, timeoutMs a maxRetries pre jednotlivú požiadavku:

const current = await tapaya.checkout.sessions.get(sessionId, {
	signal: request.signal,
	timeoutMs: 5_000,
})

Keď sa signál preruší, metóda okamžite skončí bez opakovania a jej promise sa odmietne s dôvodom (reason) signálu.

Relácie Checkoutu

Výber obchodníka

V režime obchodníka určuje obchodníka jeho checkout kľúč. Použite new Tapaya() bez merchantToken.

V režime platformy obsluhuje jeden Secret key organizácie mnoho obchodníkov. Každá požiadavka potrebuje token obchodníka; neexistuje žiadny predvolený obchodník a požiadavka bez tokenu zlyhá s chybou TapayaAuthenticationError. Tokeny skopírujte z tabuľky obchodníkov v nastaveniach Checkoutu a token danej objednávky odovzdávajte pri vytvorení aj pri načítaní:

const tapaya = new Tapaya(process.env.TAPAYA_SECRET_KEY)
const session = await tapaya.checkout.sessions.create(params, {
	merchantToken: order.merchantToken,
	idempotencyKey: order.checkoutAttemptKey,
})
const current = await tapaya.checkout.sessions.get(session.id, {
	merchantToken: order.merchantToken,
})

Predvolený token môžete nastaviť aj pomocou new Tapaya(key, { merchantToken }). Token platí pre hostované aj vložené volania. Tapaya odmieta tokeny mimo organizácie daného kľúča. S kľúčom obchodníka je token voliteľný a musí označovať obchodníka, ktorému kľúč patrí. Pozrite si Autentifikácia Checkoutu.

Vytvorenie relácie

tapaya.checkout.sessions.create(params, options?) vyžaduje merchantOrderId, amount a currency. merchantOrderId je vaša referencia objednávky s dĺžkou 1 až 200 znakov. Objednávku možno zaplatiť iba raz; nová relácia pre nezaplatenú objednávku nahradí tú predchádzajúcu. Pozrite si Jedna platba na objednávku. amount je konečná celková suma vrátane dane a dopravy, celé číslo od 1 do 2 147 483 647 v najmenších jednotkách meny. currency je trojpísmenový kód podľa ISO 4217. Tapaya ho ukladá a vracia veľkými písmenami.

Voliteľné polia:

Pred odoslaním SDK kontroluje typy, povinné polia, celočíselné sumy, formát meny a maximálnu dĺžku e-mailu 254 znakov. Návratové URL musia byť absolútne URL s HTTPS, s výnimkou pre lokálne HTTP opísanou v časti Konfigurácia. Tapaya overuje obchodné pravidlá, ako je formát e-mailu, limity adresy a kódy krajín, a problémy hlási ako TapayaInvalidRequestError. Pravidlá polí, súčty daní a limity adresy zákazníka nájdete v časti Relácie Checkoutu.

Načítanie relácie

tapaya.checkout.sessions.get(id, options?) vracia aktuálny stav relácie. ID musí byť neprázdny reťazec s dĺžkou najviac 200 znakov; . a .. sú neplatné. SDK ID zakóduje do URL.

Vytvorenie a načítanie hostovanej relácie vracia HostedCheckoutSession. Metódy pre vložené platby prepare(), verify() a configuration() opisuje stránka Embedded Checkout.

Polia hostovanej relácie:

Ošetrite neznáme hodnoty status a paymentStatus, napríklad tak, že s nimi budete zaobchádzať ako s ešte nezaplatenými. Platbu dokazuje iba paymentStatus: 'successful'.

Zamietnutá karta je výsledok platby, nie chyba. Relácia zostane open s paymentStatus: 'failed' a zákazník to môže skúsiť znova. Kým Tapaya potvrdzuje neistý výsledok, relácia zostáva open a unpaid. Webhooky zatiaľ nie sú k dispozícii; z úlohy na odsúhlasenie pravidelne volajte get().

Idempotencia a opakovanie požiadaviek

Každá požiadavka na vytvorenie posiela Idempotency-Key. Explicitne zadaný kľúč musí byť neprázdny reťazec z tlačiteľných znakov ASCII. Tapaya prijíma najviac 250 znakov. Ak idempotencyKey vynecháte, SDK pre každé volanie vygeneruje náhodný kľúč. V rámci tohto volania opakovania kľúč znova používajú, takže opakovanie nikdy nevytvorí druhú reláciu.

Aby bolo vytváranie bezpečné aj naprieč samostatnými volaniami a reštartmi procesu, uložte kľúč spolu s objednávkou a odovzdávajte ho zakaždým, keď pre daný pokus vytvárate reláciu, s rovnakými parametrami. Tapaya vráti pôvodnú reláciu namiesto toho, aby vytvorila novú. Nový kľúč použite iba pre nový pokus o zaplatenie, nikdy na opakovanie neistého výsledku.

Opakované vytvorenie hostovanej relácie vráti tú istú reláciu s jej aktuálnymi hodnotami status a paymentStatus. Pred vybavením objednávky zavolajte tapaya.checkout.sessions.get(session.id) a stav znova overte.

Pre toho istého obchodníka musia opakovania hostovaných požiadaviek používať rovnaké telo požiadavky a rovnaký režim prihlasovacích údajov: checkout kľúč obchodníka alebo Secret key organizácie. Zmena ktoréhokoľvek z nich vráti HTTP 409 s kódom API-0025. Prepnutie režimu prihlasovacích údajov vedie ku konfliktu aj pri zhodnom tele, pretože každý režim používa vlastné nastavenia presmerovania.

SDK opakuje obe metódy po chybách siete, vypršaní časového limitu a HTTP 429, 502, 503 a 504. Opakuje aj vytvorenie, ktoré zlyhá s HTTP 409 API-0024. Opakovania posielajú rovnaký kľúč a telo, takže vrátia pôvodnú reláciu. SDK medzi pokusmi čaká s exponenciálne sa predlžujúcim odstupom (exponential backoff) a náhodným rozptylom (jitter) a rešpektuje Retry-After až do 10 sekúnd. Keď Tapaya požiada o dlhšie čakanie, SDK prestane opakovať a vyvolá chybu zodpovedajúcu danému stavu HTTP: TapayaRateLimitError pre 429, TapayaServerError pre 502, 503 alebo 504, alebo TapayaConflictError pre 409. Požadované oneskorenie ako retryAfterMs sprístupňuje iba TapayaRateLimitError; ostatné chyby HTTP uchovávajú hlavičku Retry-After v headers. Všetky opakovania zdieľajú limit maxRetries. Nastavením maxRetries: 0 opakovanie vypnete.

Nikdy neprechádzajte na nový kľúč, aby ste obišli neistý výsledok. Pôvodná požiadavka už mohla vytvoriť reláciu; s novým kľúčom a tou istou nezaplatenou objednávkou ju nová relácia nahradí.

Chyby

Triedy chýb SDK rozširujú TapayaError. Promise prerušenej požiadavky sa odmietne s dôvodom uvedeným v signáli.

Chyby HTTP nesú status, chybový code Tapaya, fieldErrors ({ field, message, code? }[]), headers odpovede a requestId z hlavičky X-Request-Id, ak je prítomná. Backend túto hlavičku v súčasnosti nenastavuje. Do požiadaviek na podporu uveďte ID relácie alebo referenciu objednávky a čas požiadavky, a tiež requestId, ak je k dispozícii. TapayaResponseError nesie tiež status, headers a requestId. TapayaValidationError nesie tiež fieldErrors, kde field obsahuje cestu k parametru, napríklad customer.email.

import { TapayaConnectionError, TapayaError, TapayaValidationError } from '@tapayadot/checkout'

try {
	const session = await tapaya.checkout.sessions.create(params, { idempotencyKey })
	return Response.redirect(session.url, 303)
} catch (error) {
	if (error instanceof TapayaValidationError) {
		console.error(error.fieldErrors)
	} else if (error instanceof TapayaConnectionError) {
		// The outcome is unknown. Retry later with the same idempotency key.
	} else if (error instanceof TapayaError) {
		console.error(error.message)
	}
	throw error
}

Exportované typy

Balík exportuje TapayaEnvironment, TapayaOptions, RequestOptions, CreateSessionOptions, CreateCheckoutSessionParams, CheckoutSessions, CheckoutSession, CheckoutSessionStatus, CheckoutPaymentStatus, CheckoutItem, TaxBreakdownEntry, CheckoutCustomer, CheckoutContactAddress a TapayaFieldError.

VERSION obsahuje verziu SDK. Typy importujte ako pomenované importy pomocou import type:

import type { CheckoutSession, CreateCheckoutSessionParams } from '@tapayadot/checkout';

Prechod z verzie 0.2.x

• Loader pre prehliadač načítava Tapaya.js 0.2.0, ktorý podporuje Apple Pay a Google Pay. Už načítaný skript 0.1.x odmietne. Každú značku script, ktorú spravujete, aktualizujte na https://js.tapaya.com/checkout/0.2.0/checkout.js.
• environment: 'production' podporuje hostované aj vložené platby. configuration() vracia environment: 'production' s kľúčmi ostrej platobnej brány.
• Bez explicitne zadaného prostredia alebo TAPAYA_ENVIRONMENT volí kľúč tapaya_live_ produkciu. Prihlasovacie údaje, ktoré nezodpovedajú zvolenému prostrediu, zlyhajú pri vytváraní klienta. baseUrl stále prepisuje URL API.