Node.js SDK

@tapayadot/checkout je serverové TypeScript SDK pro Tapaya Checkout. Tato reference popisuje verzi 0.3.0.

npm install @tapayadot/checkout

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

const tapaya = new Tapaya();

Klient načítá TAPAYA_SECRET_KEY z prostředí serveru. Balíček obsahuje také loader pro prohlížeč a React hook pro Embedded Checkout. Loader stahuje Tapaya.js 0.2.0 z https://js.tapaya.com/checkout/0.2.0/checkout.js; verze skriptu pro prohlížeč je na verzi tohoto balíčku nezávislá. Soubory .env nenačítá. Klíč i klienta držte pouze v kódu běžícím na serveru. Průvodce Hosted Checkout popisuje vytvoření objednávky, přesměrování zákazníka a ověření platby.

Konfigurace

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

Chcete-li použít vlastní API endpoint, nastavte na svém serveru TAPAYA_BASE_URL=https://api.example.com. Explicitně zadaná baseUrl má přednost před TAPAYA_BASE_URL; obě přepisují volbu podle prostředí.

Klient určí API klíč a URL API jednou, při svém vytvoření. Použijte klíč, který odpovídá zvolenému prostředí. URL API, návratové URL a URL hostovaného Checkoutu musí používat HTTPS, s výjimkou HTTP pro localhost, 127.0.0.1 a [::1] mimo NODE_ENV=production. SDK kontroluje aktuální NODE_ENV při každém ověření lokální URL s HTTP.

timeoutMs musí být celé číslo od 1 do 2 147 483 647. maxRetries musí být nezáporné bezpečné celé číslo. Výchozí počet opakování umožňuje až tři pokusy na jedno volání, každý s vlastním časovým limitem.

Každá metoda přijímá také signal, timeoutMs a maxRetries pro jednotlivý požadavek:

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

Když je signál přerušen, metoda okamžitě skončí bez opakování a vrácený promise se odmítne s důvodem (reason) signálu.

Relace Checkoutu

Výběr obchodníka

V režimu obchodníka určuje obchodníka jeho Checkout klíč. Použijte new Tapaya() bez merchantToken.

V režimu platformy obsluhuje jeden Secret key organizace mnoho obchodníků. Každý požadavek potřebuje token obchodníka; žádný výchozí obchodník neexistuje a požadavek bez tokenu selže s chybou TapayaAuthenticationError. Tokeny zkopírujte z tabulky obchodníků v nastavení Checkoutu a token dané objednávky předávejte jak při vytvoření, tak při načtení:

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,
})

Výchozí token můžete nastavit také pomocí new Tapaya(key, { merchantToken }). Token platí pro volání Hosted i Embedded Checkoutu. Tapaya odmítá tokeny mimo organizaci daného klíče. S klíčem obchodníka je token volitelný a musí označovat obchodníka, kterému klíč patří. Viz Autentizace Checkoutu.

Vytvoření relace

tapaya.checkout.sessions.create(params, options?) vyžaduje merchantOrderId, amount a currency. merchantOrderId je vaše označení objednávky o délce 1 až 200 znaků. Objednávku lze zaplatit pouze jednou; nová relace pro nezaplacenou objednávku nahradí tu předchozí. Viz Jedna platba na objednávku. amount je konečná celková částka včetně daně a dopravy, celé číslo od 1 do 2 147 483 647 v nejmenších jednotkách měny. currency je třípísmenný kód podle ISO 4217. Tapaya jej ukládá a vrací velkými písmeny.

Volitelná pole:

Před odesláním SDK kontroluje typy, povinná pole, celočíselné částky, formát měny a maximální délku e-mailu 254 znaků. Návratové URL musí být absolutní URL s HTTPS, s výjimkou pro lokální HTTP popsanou v části Konfigurace. Tapaya ověřuje obchodní pravidla, jako je formát e-mailu, limity adresy a kódy zemí, a problémy hlásí jako TapayaInvalidRequestError. Pravidla polí, součty daní a limity adresy zákazníka najdete v části Relace Checkoutu.

Načtení relace

tapaya.checkout.sessions.get(id, options?) vrací aktuální stav relace. ID musí být neprázdný řetězec o délce nejvýše 200 znaků; . a .. jsou neplatné. SDK ID kóduje do URL.

Vytvoření a načtení hostované relace vrací HostedCheckoutSession. Metody Embedded Checkoutu prepare(), verify() a configuration() popisuje stránka Embedded Checkout.

Pole hostované relace:

Ošetřete neznámé hodnoty status a paymentStatus, například tak, že s nimi budete zacházet jako s dosud nezaplacenými. Platbu prokazuje pouze paymentStatus: 'successful'.

Zamítnutá karta je výsledek platby, ne chyba. Relace zůstane open s paymentStatus: 'failed' a zákazník to může zkusit znovu. Zatímco Tapaya potvrzuje nejistý výsledek, relace zůstává open a unpaid. Webhooky zatím nejsou k dispozici; z úlohy pro odsouhlasení pravidelně volejte get().

Idempotence a opakování požadavků

Každý požadavek na vytvoření odesílá Idempotency-Key. Explicitně zadaný klíč musí být neprázdný řetězec z tisknutelných znaků ASCII. Tapaya přijímá nejvýše 250 znaků. Pokud idempotencyKey vynecháte, SDK pro každé volání vygeneruje náhodný klíč. V rámci tohoto volání opakování klíč znovu používají, takže opakování nikdy nevytvoří druhou relaci.

Aby bylo vytváření bezpečné i napříč samostatnými voláními a restarty procesu, uložte klíč spolu s objednávkou a předávejte jej pokaždé, když pro daný pokus vytváříte relaci, se stejnými parametry. Tapaya vrátí původní relaci, místo aby vytvořila novou. Nový klíč použijte pouze pro nový pokus o zaplacení, nikdy k opakování nejistého výsledku.

Opakované vytvoření hostované relace vrátí stejnou relaci s jejími aktuálními hodnotami status a paymentStatus. Před vyřízením objednávky zavolejte tapaya.checkout.sessions.get(session.id) a stav znovu ověřte.

Pro stejného obchodníka musí opakování hostovaných požadavků používat stejné tělo požadavku a stejný režim přihlašovacích údajů: Checkout klíč obchodníka, nebo Secret key organizace. Změna kteréhokoli z nich vrátí HTTP 409 s kódem API-0025. Přepnutí režimu přihlašovacích údajů vede ke konfliktu i při shodném těle, protože každý režim používá vlastní nastavení přesměrování.

SDK opakuje obě metody po chybách sítě, vypršení časového limitu a HTTP 429, 502, 503 a 504. Opakuje také vytvoření, které selže s HTTP 409 API-0024. Opakování odesílají stejný klíč a tělo, takže vrátí původní relaci. SDK mezi pokusy čeká s exponenciálně se prodlužující prodlevou (exponential backoff) a náhodným rozptylem (jitter) a respektuje Retry-After až do 10 sekund. Když Tapaya požádá o delší čekání, SDK přestane opakovat a vyvolá chybu odpovídající danému stavu HTTP: TapayaRateLimitError pro 429, TapayaServerError pro 502, 503 nebo 504, nebo TapayaConflictError pro 409. Požadovanou prodlevu jako retryAfterMs zpřístupňuje pouze TapayaRateLimitError; ostatní chyby HTTP uchovávají hlavičku Retry-After v headers. Všechna opakování sdílejí limit maxRetries. Nastavením maxRetries: 0 opakování vypnete.

Nikdy nepřecházejte na nový klíč, abyste obešli nejistý výsledek. Původní požadavek už mohl vytvořit relaci; s novým klíčem a stejnou nezaplacenou objednávkou ji nová relace nahradí.

Chyby

Třídy chyb SDK rozšiřují TapayaError. Přerušený požadavek se odmítne s důvodem uvedeným v signálu.

Chyby HTTP nesou status, chybový code Tapaya, fieldErrors ({ field, message, code? }[]), headers odpovědi a requestId z hlavičky X-Request-Id, pokud je přítomna. Backend tuto hlavičku v současnosti nenastavuje. Do požadavků na podporu uveďte ID relace nebo označení objednávky a čas požadavku, a také requestId, je-li k dispozici. TapayaResponseError nese rovněž status, headers a requestId. TapayaValidationError nese rovněž fieldErrors, kde field obsahuje cestu k parametru, napří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íček exportuje TapayaEnvironment, TapayaOptions, RequestOptions, CreateSessionOptions, CreateCheckoutSessionParams, CheckoutSessions, CheckoutSession, CheckoutSessionStatus, CheckoutPaymentStatus, CheckoutItem, TaxBreakdownEntry, CheckoutCustomer, CheckoutContactAddress a TapayaFieldError.

VERSION obsahuje verzi SDK. Typy importujte jako pojmenované importy pomocí import type:

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

Přechod z verze 0.2.x

• Loader pro prohlížeč načítá Tapaya.js 0.2.0, který podporuje Apple Pay a Google Pay. Již načtený skript 0.1.x odmítne. Každou značku script, kterou spravujete, aktualizujte na https://js.tapaya.com/checkout/0.2.0/checkout.js.
• environment: 'production' podporuje hostované i vložené platby. configuration() vrací environment: 'production' s klíči ostré platební brány.
• Bez explicitně zadaného prostředí nebo TAPAYA_ENVIRONMENT volí klíč tapaya_live_ produkci. Přihlašovací údaje, které neodpovídají zvolenému prostředí, selžou při vytváření klienta. baseUrl stále přepisuje URL API.