Node.js SDK

@tapayadot/checkout є серверним TypeScript SDK для Tapaya Checkout. Цей довідник описує версію 0.3.0.

npm install @tapayadot/checkout

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

const tapaya = new Tapaya();

Клієнт зчитує TAPAYA_SECRET_KEY із серверного середовища. Пакет також містить браузерний завантажувач і React-хук для Embedded Checkout. Завантажувач отримує Tapaya.js 0.2.0 з https://js.tapaya.com/checkout/0.2.0/checkout.js; версія браузерного скрипта не залежить від версії цього пакета. Файли .env він не завантажує. Тримайте ключ і клієнт лише в серверному коді. Посібник з Hosted Checkout описує створення замовлення, переспрямування клієнта та перевірку платежу.

Конфігурація

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

Щоб використовувати власний ендпоінт API, задайте на своєму сервері TAPAYA_BASE_URL=https://api.example.com. Явно заданий baseUrl має пріоритет над TAPAYA_BASE_URL; обидва перевизначають вибір середовища.

Клієнт визначає API-ключ і URL API один раз, під час створення. Використовуйте ключ, що відповідає вибраному середовищу. URL API, повернення та Hosted Checkout мають використовувати HTTPS, за винятком того, що HTTP дозволено для localhost, 127.0.0.1 і [::1] поза NODE_ENV=production. SDK перевіряє поточне значення NODE_ENV щоразу, коли валідує локальний HTTP URL.

timeoutMs має бути цілим числом від 1 до 2 147 483 647. maxRetries має бути невід'ємним безпечним цілим числом. Типова кількість повторних спроб дає до трьох спроб на виклик, кожна з власним тайм-аутом.

Кожен метод також приймає signal, timeoutMs і maxRetries для окремого запиту:

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

Коли сигнал перериває запит, метод одразу зупиняється без повторних спроб, а проміс відхиляється з причиною сигналу.

Сесії Checkout

Вибір мерчанта

У режимі мерчанта checkout-ключ мерчанта сам визначає свого мерчанта. Використовуйте new Tapaya() без merchantToken.

У режимі платформи один Secret key організації обслуговує багатьох мерчантів. Кожному запиту потрібен токен мерчанта; типового мерчанта немає, і запит без токена завершується помилкою TapayaAuthenticationError. Скопіюйте токени з таблиці мерчантів у налаштуваннях Checkout і передавайте токен замовлення як під час створення, так і під час отримання:

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

Типове значення також можна задати через new Tapaya(key, { merchantToken }). Токен застосовується до викликів Hosted і Embedded Checkout. Tapaya відхиляє токени, що не належать до організації ключа. З ключем мерчанта токен необов'язковий і має вказувати на власного мерчанта цього ключа. Див. автентифікацію Checkout.

Створення сесії

tapaya.checkout.sessions.create(params, options?) потребує merchantOrderId, amount і currency. merchantOrderId є вашим референсом замовлення довжиною від 1 до 200 символів. Замовлення можна оплатити лише один раз; нова сесія для неоплаченого замовлення замінює попередню. Див. Один платіж на замовлення. amount є остаточною сумою, включно з податком і доставкою, цілим числом від 1 до 2 147 483 647 мінімальних одиниць. currency є тризначним кодом ISO 4217. Tapaya зберігає та повертає його у верхньому регістрі.

Необов'язкові поля:

Перед надсиланням SDK перевіряє типи, обов'язкові поля, цілочисельні суми, формат валюти та максимальну довжину email у 254 символи. URL повернення мають бути абсолютними HTTPS URL, з винятком для локального HTTP, описаним у розділі Конфігурація. Tapaya валідує бізнес-правила, як-от формат email, обмеження адрес і коди країн, і повідомляє про проблеми як TapayaInvalidRequestError. Правила полів, суми податків і обмеження адрес клієнта див. у розділі Сесії Checkout.

Отримання сесії

tapaya.checkout.sessions.get(id, options?) повертає поточний стан сесії. ID має бути непорожнім рядком довжиною не більше 200 символів; . і .. недійсні. SDK кодує ID для URL.

Створення та отримання сесії Hosted Checkout повертають HostedCheckoutSession. Про методи вбудованої оплати prepare(), verify() і configuration() див. Embedded Checkout.

Поля сесії Hosted Checkout:

Обробляйте невідомі значення status і paymentStatus, наприклад вважаючи їх ще не оплаченими. Лише paymentStatus: 'successful' доводить оплату.

Відхилена картка є результатом платежу, а не помилкою. Сесія залишається open з paymentStatus: 'failed', і клієнт може спробувати знову. Поки Tapaya підтверджує невизначений результат, сесія залишається open і unpaid. Вебхуків поки немає; опитуйте get() із завдання звірки.

Ідемпотентність і повторні спроби

Кожен запит на створення надсилає Idempotency-Key. Явно заданий ключ має бути непорожнім рядком із друкованих символів ASCII. Tapaya приймає щонайбільше 250 символів. Якщо ви не вкажете idempotencyKey, SDK генерує випадковий ключ для кожного виклику. У межах цього виклику повторні спроби використовують той самий ключ, тому повторна спроба ніколи не створює другу сесію.

Щоб залишатися в безпеці між окремими викликами та перезапусками процесу, зберігайте ключ разом із замовленням і передавайте його щоразу, коли створюєте сесію для цієї спроби, з тими самими параметрами. Tapaya повертає початкову сесію замість створення нової. Використовуйте новий ключ лише для нової спроби оформлення замовлення, ніколи для повторення запиту з невизначеним результатом.

Повторне створення сесії Hosted Checkout повертає ту саму сесію з її поточними status і paymentStatus. Викличте tapaya.checkout.sessions.get(session.id), щоб ще раз перевірити статус перед виконанням замовлення.

Для того самого мерчанта повторні запити Hosted Checkout мають використовувати те саме тіло запиту та той самий режим облікових даних: checkout-ключ мерчанта або Secret key організації. Зміна будь-чого з цього повертає HTTP 409 з кодом API-0025. Перемикання режиму облікових даних спричиняє конфлікт навіть за ідентичного тіла, оскільки кожен режим використовує власні налаштування переспрямування.

SDK повторює обидва методи після мережевих помилок, тайм-аутів і HTTP 429, 502, 503 та 504. Він також повторює створення, яке завершилося помилкою HTTP 409 API-0024. Повторні спроби надсилають той самий ключ і тіло, тому повертають початкову сесію. SDK чекає між спробами з експоненційною затримкою та випадковим розкидом (jitter) і враховує Retry-After до 10 секунд. Коли Tapaya просить чекати довше, SDK припиняє повторні спроби та викидає помилку для відповідного HTTP-статусу: TapayaRateLimitError для 429, TapayaServerError для 502, 503 або 504 чи TapayaConflictError для 409. Лише TapayaRateLimitError надає запитану затримку як retryAfterMs; інші HTTP-помилки зберігають заголовок Retry-After у headers. Усі повторні спроби мають спільний ліміт maxRetries. Задайте maxRetries: 0, щоб вимкнути повторні спроби.

Ніколи не переходьте на новий ключ, щоб обійти невизначений результат. Початковий запит міг уже створити сесію; з новим ключем і тим самим неоплаченим замовленням нова сесія її замінить.

Помилки

Класи помилок SDK розширюють TapayaError. Для перерваного запиту проміс відхиляється з причиною сигналу.

HTTP-помилки містять status, code помилки Tapaya, fieldErrors ({ field, message, code? }[]), headers відповіді та requestId із заголовка X-Request-Id, якщо він є. Наразі бекенд не встановлює цей заголовок. У запитах до підтримки вказуйте ID сесії або референс замовлення та час запиту, а також requestId, якщо він доступний. TapayaResponseError також містить status, headers і requestId. TapayaValidationError також містить fieldErrors, де field містить шлях до параметра, наприклад 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
}

Експортовані типи

Пакет експортує TapayaEnvironment, TapayaOptions, RequestOptions, CreateSessionOptions, CreateCheckoutSessionParams, CheckoutSessions, CheckoutSession, CheckoutSessionStatus, CheckoutPaymentStatus, CheckoutItem, TaxBreakdownEntry, CheckoutCustomer, CheckoutContactAddress і TapayaFieldError.

VERSION містить версію SDK. Типи імпортуються іменованим імпортом з import type:

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

Оновлення з 0.2.x

• Браузерний завантажувач завантажує Tapaya.js 0.2.0, який підтримує Apple Pay і Google Pay. Він відхиляє вже завантажений скрипт 0.1.x. Оновіть усі теги script, якими ви керуєте, на https://js.tapaya.com/checkout/0.2.0/checkout.js.
• environment: 'production' підтримує як платежі Hosted Checkout, так і вбудовані платежі. configuration() повертає environment: 'production' з ключами шлюзу робочого середовища.
• Без явно заданого середовища чи TAPAYA_ENVIRONMENT ключ tapaya_live_ вибирає робоче середовище. Облікові дані, які не відповідають вибраному середовищу, спричиняють помилку під час створення клієнта. baseUrl і далі перевизначає URL API.