@gopaycz/gopay-js-sdk 1.6.6

package/src/modules/payments/payments.module.ts

@@ -0,0 +1,244 @@
+import {
+    assertHttpsOrigin,
+    awaitCharge,
+    type AwaitChargeOptions as CoreAwaitChargeOptions,
+    type GoPaySDKError,
+    type HttpClient,
+    requireNonEmptyString,
+} from '@gopay-internal/core';
+import type { components } from '../../types/generated.js';
+
+type PaymentCreateRequest = components['schemas']['Payment-Create-Request'];
+type PaymentDetails = components['schemas']['Payment-Details'];
+type PaymentChargeRequest = components['schemas']['Payment-Charge-Input'];
+type PaymentChargeResponse = components['schemas']['Payment-Charge-Response'];
+type PaymentChargeStatusResponse =
+    components['schemas']['Payment-Charge-Status-Response'];
+
+/** Options for {@link awaitChargeState}. */
+export type AwaitChargeOptions =
+    CoreAwaitChargeOptions<PaymentChargeStatusResponse>;
+type GooglePayInfoResponse =
+    components['responses']['Google-Pay-Info-Response']['content']['application/json'];
+type ApplePayInfoResponse =
+    components['responses']['Apple-Pay-Info-Response']['content']['application/json'];
+type ValidateMerchantResponse =
+    components['schemas']['Validate-Merchant-Response'];
+type QRPaymentDetails = components['schemas']['QR-Payment-Details'];
+
+export function createPaymentsApi(client: HttpClient) {
+    return {
+        /**
+         * Retrieve the current status of an existing payment.
+         *
+         * GET /payments/{payment_id}
+         *
+         * @param paymentId - Payment session ID returned by {@link createPayment}
+         */
+        async getPaymentStatus(paymentId: string): Promise<PaymentDetails> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.get<PaymentDetails>(`/payments/${pid}`);
+        },
+
+        /**
+         * Create a new payment session.
+         *
+         * POST /eshops/{goid}/payments
+         *
+         * The response includes a `gw_url` field — **ignore it**. It exists only for
+         * backward compatibility with pre-SDK redirect-based integrations. This SDK's
+         * flow is always: create → charge (via card token, Apple Pay, or Google Pay).
+         *
+         * @param goid   - Merchant's GoPay ID (eshop identifier)
+         * @param params - Payment creation parameters
+         */
+        async createPayment(
+            goid: string,
+            params: PaymentCreateRequest,
+        ): Promise<PaymentDetails> {
+            return client.post<PaymentDetails>(
+                `/eshops/${goid}/payments`,
+                params,
+            );
+        },
+
+        /**
+         * Charge a payment using a payment instrument.
+         *
+         * POST /payments/{payment_id}/charge
+         *
+         * @param paymentId - Payment session ID returned by {@link createPayment}
+         * @param params    - Charge parameters including payment instrument details
+         */
+        async chargePayment(
+            paymentId: string,
+            params: PaymentChargeRequest,
+        ): Promise<PaymentChargeResponse> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.post<PaymentChargeResponse>(
+                `/payments/${pid}/charge`,
+                params,
+            );
+        },
+
+        /**
+         * Retrieve the current state of a payment charge.
+         *
+         * GET /payments/{payment_id}/charge
+         *
+         * @param paymentId - Payment session ID returned by {@link createPayment}
+         */
+        async getChargeState(
+            paymentId: string,
+        ): Promise<PaymentChargeStatusResponse> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.get<PaymentChargeStatusResponse>(
+                `/payments/${pid}/charge`,
+            );
+        },
+
+        /**
+         * Retrieve Google Pay configuration for this payment.
+         *
+         * GET /payments/{payment_id}/google-pay/info
+         *
+         * @param paymentId - Payment session ID
+         */
+        async getGooglePayInfo(
+            paymentId: string,
+        ): Promise<GooglePayInfoResponse> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.get<GooglePayInfoResponse>(
+                `/payments/${pid}/google-pay/info`,
+            );
+        },
+
+        /**
+         * Retrieve Apple Pay configuration for this payment.
+         *
+         * GET /payments/{payment_id}/apple-pay/info
+         *
+         * @param paymentId - Payment session ID
+         */
+        async getApplePayInfo(
+            paymentId: string,
+        ): Promise<ApplePayInfoResponse> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.get<ApplePayInfoResponse>(
+                `/payments/${pid}/apple-pay/info`,
+            );
+        },
+
+        /**
+         * Wire merchant validation onto an ApplePaySession and begin it.
+         * Handles the onvalidatemerchant callback via POST /payments/{payment_id}/apple-pay/validate.
+         *
+         * @param paymentId - Payment session ID
+         * @param session   - ApplePaySession instance
+         * @param origin    - Merchant origin (https:); defaults to current page origin
+         * @param callbacks - Optional lifecycle callbacks
+         */
+        startApplePaySession(
+            paymentId: string,
+            session: {
+                onvalidatemerchant: ((event: unknown) => void) | null;
+                oncancel: ((event: unknown) => void) | null;
+                completeMerchantValidation(merchantSession: unknown): void;
+                abort(): void;
+                begin(): void;
+            },
+            origin: string = globalThis.location?.origin ?? '',
+            callbacks?: { oncancel?: (event: unknown) => void },
+        ): void {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            if (origin) {
+                try {
+                    assertHttpsOrigin(
+                        origin,
+                        '[GoPaySDK] startApplePaySession',
+                    );
+                } catch (e) {
+                    throw client.emitError(e as GoPaySDKError);
+                }
+            }
+            session.onvalidatemerchant = (event: unknown) => {
+                const validationURL =
+                    event != null &&
+                    typeof event === 'object' &&
+                    'validationURL' in event &&
+                    typeof (event as Record<string, unknown>).validationURL ===
+                        'string'
+                        ? ((event as Record<string, unknown>)
+                              .validationURL as string)
+                        : undefined;
+                const headers: Record<string, string> = origin
+                    ? { Origin: origin }
+                    : {};
+                const body = validationURL
+                    ? { validationUrl: validationURL }
+                    : undefined;
+                client
+                    .post<ValidateMerchantResponse>(
+                        `/payments/${pid}/apple-pay/validate`,
+                        body,
+                        { headers },
+                    )
+                    .then((merchantSession) =>
+                        session.completeMerchantValidation(merchantSession),
+                    )
+                    .catch(() => session.abort());
+            };
+            session.oncancel = (event) => {
+                callbacks?.oncancel?.(event);
+            };
+            session.begin();
+        },
+
+        /**
+         * Retrieve QR payment info for this payment.
+         * Returns recipient details and base64-encoded QR code image(s).
+         *
+         * GET /payments/{payment_id}/qr-payment/info
+         *
+         * @param paymentId - Payment session ID
+         * @param format    - Image format of the QR code: 'png' (default) or 'svg'
+         */
+        async getQRPaymentInfo(
+            paymentId: string,
+            format?: 'png' | 'svg',
+        ): Promise<QRPaymentDetails> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            const path = format
+                ? `/payments/${pid}/qr-payment/info?format=${format}`
+                : `/payments/${pid}/qr-payment/info`;
+            return client.get<QRPaymentDetails>(path);
+        },
+
+        /**
+         * Poll the charge state until a terminal outcome.
+         *
+         * Resolves on `SUCCEEDED`. Rejects with `CHARGE_FAILED` on `FAILED`,
+         * or `CHARGE_TIMEOUT` if the charge does not leave `REQUESTED`/
+         * `PROCESSING` within `initialTimeoutMs` (default 30 s).
+         *
+         * Use `options.onActionRequired` to handle 3DS redirects
+         * (e.g. redirect the customer or open a popup).
+         *
+         * @param paymentId - Payment session ID
+         * @param options   - Polling configuration and callbacks
+         */
+        awaitChargeState(
+            paymentId: string,
+            options?: AwaitChargeOptions,
+        ): Promise<PaymentChargeStatusResponse> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return awaitCharge(
+                () =>
+                    client.get<PaymentChargeStatusResponse>(
+                        `/payments/${pid}/charge`,
+                    ),
+                options,
+            );
+        },
+    };
+}

package/src/modules/recurrences/recurrences.module.ts

@@ -0,0 +1,100 @@
+import { type HttpClient, requireNonEmptyString } from '@gopay-internal/core';
+
+import type { components } from '../../types/generated.js';
+
+type RecurrenceCreateRequest =
+    components['schemas']['Recurrence-Create-Request'];
+type RecurrenceDetails = components['schemas']['Recurrence-Details'];
+type RecurrenceNextBody = components['schemas']['Payment-Instance-Override'];
+type PaymentDetails = components['schemas']['Payment-Details'];
+
+export function createRecurrencesApi(client: HttpClient) {
+    return {
+        /**
+         * Create a recurrence.
+         * Requires the `payment:write` OAuth2 scope.
+         *
+         * POST /eshops/{goid}/recurrences
+         *
+         * @param goid   - Merchant's GoPay ID (eshop identifier)
+         * @param params - Recurrence creation parameters including type, schedule, and payment data
+         */
+        async createRecurrence(
+            goid: string,
+            params: RecurrenceCreateRequest,
+        ): Promise<RecurrenceDetails> {
+            return client.post<RecurrenceDetails>(
+                `/eshops/${goid}/recurrences`,
+                params,
+            );
+        },
+
+        /**
+         * Recurrence status.
+         * Requires the `payment:read` OAuth2 scope.
+         *
+         * GET /recurrences/{rec_id}
+         *
+         * @param recId - Recurrence ID returned by {@link createRecurrence}
+         */
+        async recurrenceStatus(recId: string): Promise<RecurrenceDetails> {
+            const rid = requireNonEmptyString(recId, 'recId');
+            return client.get<RecurrenceDetails>(`/recurrences/${rid}`);
+        },
+
+        /**
+         * Stop a recurrence.
+         * Requires the `payment:write` OAuth2 scope.
+         *
+         * DELETE /recurrences/{rec_id}
+         *
+         * @param recId - Recurrence ID returned by {@link createRecurrence}
+         */
+        async stopRecurrence(recId: string): Promise<void> {
+            const rid = requireNonEmptyString(recId, 'recId');
+            return client.delete(`/recurrences/${rid}`);
+        },
+
+        /**
+         * Start a recurrence.
+         * Triggers the first charge of a recurrence that is in the `NEW` state.
+         * Requires the `payment:write` OAuth2 scope.
+         *
+         * POST /recurrences/{rec_id}/start
+         *
+         * @param recId  - Recurrence ID returned by {@link createRecurrence}
+         * @param params - Optional payment overrides (amount, order_number, callback, etc.)
+         */
+        async startRecurrence(
+            recId: string,
+            params?: RecurrenceNextBody,
+        ): Promise<PaymentDetails> {
+            const rid = requireNonEmptyString(recId, 'recId');
+            return client.post<PaymentDetails>(
+                `/recurrences/${rid}/start`,
+                params,
+            );
+        },
+
+        /**
+         * Create a next payment for a recurrence.
+         * Charges the next instalment for a recurrence that is already `STARTED`.
+         * Requires the `payment:write` OAuth2 scope.
+         *
+         * POST /recurrences/{rec_id}/next
+         *
+         * @param recId  - Recurrence ID returned by {@link createRecurrence}
+         * @param params - Optional payment overrides (amount, order_number, callback, etc.)
+         */
+        async recurrenceNext(
+            recId: string,
+            params?: RecurrenceNextBody,
+        ): Promise<PaymentDetails> {
+            const rid = requireNonEmptyString(recId, 'recId');
+            return client.post<PaymentDetails>(
+                `/recurrences/${rid}/next`,
+                params,
+            );
+        },
+    };
+}

package/src/modules/refunds/refunds.module.ts

@@ -0,0 +1,55 @@
+import { type HttpClient, requireNonEmptyString } from '@gopay-internal/core';
+import type { components } from '../../types/generated.js';
+
+type RefundCreateRequest = components['schemas']['Refund-Create-Request'];
+type RefundDetails = components['schemas']['Refund-Details'];
+
+export function createRefundsApi(client: HttpClient) {
+    return {
+        /**
+         * Refund a payment (fully or partially).
+         * Requires the `payment:write` OAuth2 scope.
+         *
+         * POST /payments/{payment_id}/refunds
+         *
+         * @param paymentId - Payment session ID returned by {@link createPayment}
+         * @param params    - Refund parameters, including the amount in cents
+         */
+        async refundPayment(
+            paymentId: string,
+            params: RefundCreateRequest,
+        ): Promise<RefundDetails> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.post<RefundDetails>(
+                `/payments/${pid}/refunds`,
+                params,
+            );
+        },
+
+        /**
+         * List all refunds for a payment.
+         * Requires the `payment:read` OAuth2 scope.
+         *
+         * GET /payments/{payment_id}/refunds
+         *
+         * @param paymentId - Payment session ID returned by {@link createPayment}
+         */
+        async listRefunds(paymentId: string): Promise<RefundDetails[]> {
+            const pid = requireNonEmptyString(paymentId, 'paymentId');
+            return client.get<RefundDetails[]>(`/payments/${pid}/refunds`);
+        },
+
+        /**
+         * Retrieve details of a single refund.
+         * Requires the `payment:read` OAuth2 scope.
+         *
+         * GET /refunds/{refund_id}
+         *
+         * @param refundId - Refund ID returned by {@link refundPayment}
+         */
+        async getRefund(refundId: string): Promise<RefundDetails> {
+            const rid = requireNonEmptyString(refundId, 'refundId');
+            return client.get<RefundDetails>(`/refunds/${rid}`);
+        },
+    };
+}

package/src/types/generated.ts

@@ -0,0 +1 @@
+export type * from '@gopay-internal/core/types/generated.js';

package/src/types/index.ts

@@ -0,0 +1,10 @@
+export type { BrowserData, GoPayEnvironment } from '@gopay-internal/core';
+
+export interface ClientCredentialsRequest {
+    grant_type: 'client_credentials';
+    client_id: string;
+    client_secret: string;
+    scope: string;
+}
+
+export type AuthenticateRequest = ClientCredentialsRequest;

package/src/version.ts

@@ -0,0 +1 @@
+export const SDK_VERSION: string = __GOPAY_SDK_VERSION__;