Kore Payment SDK - API Reference

Kore Class

Constructor

typescript

new Kore(config: KoreConfig)

Creates a new instance of the Kore SDK.

Parameters:

Parameter	Type	Required	Description
`config.apiKey`	`string`	Yes	Your public API key
`config.baseUrl`	`string`	No	Custom API base URL
`config.environment`	`'sandbox' \| 'live'`	No	Environment (default: `'live'`)
`config.timeout`	`number`	No	Request timeout in ms (default: `30000`)
`config.retryAttempts`	`number`	No	Number of retry attempts (default: `3`)
`config.retryDelay`	`number`	No	Delay between retries in ms (default: `1000`)
`config.onError`	`(error: KoreError) => void`	No	Global error handler
`config.onRequest`	`(config: RequestConfig) => void`	No	Request interceptor
`config.onResponse`	`(response: Response) => void`	No	Response interceptor
`config.debug`	`boolean`	No	Enable debug logging (default: `false`). Use only for development; do not enable in production.
`config.logger`	`(message: string) => void`	No	Custom logger function

Example:

javascript

const kore = new Kore({
  apiKey: 'pk_test_xxxxxxxxxxxxx',
  environment: 'sandbox',
  debug: true
});

Payment Methods

createSession

typescript

createSession(sessionData: SessionData, options?: SessionOptions): Promise<SessionResponse>

Creates a new payment session.

Parameters:

sessionData

Field	Type	Required	Description
`order_id`	`string`	Yes	Unique order identifier
`amount`	`number`	Yes	Amount in minor units (e.g., 10000 = $100.00)
`currency`	`string`	Yes	ISO-4217 currency code (e.g., 'USD')
`capture_mode`	`'auto' \| 'manual'`	No	Capture mode (default: 'auto')
`payer`	`PayerInfo`	Yes	Payer information
`billing`	`AddressInfo`	Yes	Billing address
`shipping`	`AddressInfo`	No	Shipping address
`return_url`	`string`	Yes	URL to redirect after payment
`cancel_url`	`string`	Yes	URL to redirect on cancellation
`metadata`	`object`	No	Additional metadata

PayerInfo

Field	Type	Required	Description
`email`	`string`	Yes	Payer email address
`name`	`string`	Yes	Payer full name
`phone`	`string`	No	Payer phone number

AddressInfo

Field	Type	Required	Description
`address_line_1`	`string`	Yes	Street address line 1
`address_line_2`	`string`	No	Street address line 2
`city`	`string`	Yes	City
`state`	`string`	No	State or province
`postal_code`	`string`	Yes	Postal or ZIP code
`country`	`string`	Yes	ISO-3166-1 alpha-2 country code
`name`	`string`	No	Address name (for shipping)
`phone`	`string`	No	Address phone (for shipping)

options

Field	Type	Required	Description
`idempotencyKey`	`string`	No	Custom idempotency key
`timeout`	`number`	No	Request timeout in ms

Returns:

typescript

{
  session_id: string;
  payment_id: string;
  redirect_url: string;
  expires_at: string;  // ISO 8601 timestamp
}

Throws:

KoreValidationError - If required fields are missing or invalid
KoreAuthenticationError - If API key is invalid
KoreNetworkError - If network request fails
KorePaymentError - If payment creation fails

Example:

javascript

const session = await kore.createSession({
  order_id: 'order_12345',
  amount: 10000,
  currency: 'USD',
  payer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  billing: {
    address_line_1: '123 Main St',
    city: 'New York',
    postal_code: '10001',
    country: 'US'
  },
  return_url: 'https://yourstore.com/success',
  cancel_url: 'https://yourstore.com/cancel'
});

createEmbeddedSession

typescript

createEmbeddedSession(sessionData: EmbeddedSessionData, options?: SessionOptions): Promise<EmbeddedSessionResponse>

Creates a new embedded payment session. Used for embedded payment flows where payment forms are rendered directly in your page.

Parameters:

sessionData

Field	Type	Required	Description
`order_id`	`string`	Yes	Unique order identifier
`amount`	`number`	Yes	Amount in minor units (e.g., 10000 = $100.00)
`currency`	`string`	Yes	ISO-4217 currency code (e.g., 'USD')
`capture_mode`	`'auto' \| 'manual'`	No	Capture mode (default: 'auto')
`payer`	`PayerInfo`	Yes	Payer information
`billing`	`AddressInfo`	Yes	Billing address
`shipping`	`AddressInfo`	No	Shipping address
`return_url`	`string`	Yes	URL to redirect after payment
`cancel_url`	`string`	Yes	URL to redirect on cancellation
`metadata`	`object`	No	Additional metadata
`processing_channel_id`	`string`	No	Processing channel ID (Checkout.com only)

Returns:

typescript

{
  session_id: string;
  payment_id: string;
  gateway: {
    id: number;
    code: string;
    name: string;
  };
  gateway_config: {
    // Checkout.com Flow SDK
    publicKey?: string;
    paymentSession?: string;
    environment?: string;
    
    // Adyen Drop-in SDK
    clientKey?: string;
    
    // QiCard
    redirectUrl?: string;
    embedMode?: string;
    paymentId?: string;
  };
  expires_at: string;  // ISO 8601 timestamp
}

Example:

javascript

const session = await kore.createEmbeddedSession({
  order_id: 'order_12345',
  amount: 10000,
  currency: 'USD',
  capture_mode: 'auto',
  payer: {
    email: '[email protected]',
    name: 'John Doe',
    phone: '+1234567890'
  },
  billing: {
    address_line_1: '123 Main St',
    city: 'New York',
    postal_code: '10001',
    country: 'US'
  },
  return_url: 'https://yourstore.com/success',
  cancel_url: 'https://yourstore.com/cancel',
  processing_channel_id: 'pc_xxxxx'  // Optional: Checkout.com only
});

initializePayment

typescript

initializePayment(config: InitializePaymentConfig): Promise<void>

Initializes the payment form for embedded payment flow. The SDK automatically detects the gateway (Checkout.com, Adyen, or QiCard) and loads the appropriate payment SDK.

Parameters:

Parameter	Type	Required	Description
`config.session`	`EmbeddedSessionResponse`	Yes	Session object from `createEmbeddedSession()`
`config.container`	`string`	Yes	CSS selector for the container element
`config.onSuccess`	`(result: PaymentResult) => void`	No	Success callback
`config.onError`	`(error: Error) => void`	No	Error callback
`config.onSubmit`	`(result: AdyenResult) => Promise<void>`	No	Adyen-specific submit handler (for 3DS)
`config.onAdditionalDetails`	`(result: AdyenResult) => Promise<void>`	No	Adyen-specific 3DS completion handler

Example:

javascript

await kore.initializePayment({
  session: session,
  container: '#payment-form-container',
  onSuccess: (result) => {
    console.log('Payment successful!', result);
    // result.payment_id - Payment ID
    // result.session - Final session status
  },
  onError: (error) => {
    console.error('Payment failed:', error);
  }
});

HTML:

html

<div id="payment-form-container"></div>

updatePaymentGatewayId

typescript

updatePaymentGatewayId(sessionId: string, gatewayPaymentId: string): Promise<PaymentUpdateResponse>

Updates payment with gateway payment ID. This is automatically called by the SDK when Checkout.com Flow SDK completes, but can be called manually if needed.

Parameters:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes	Session ID
`gatewayPaymentId`	`string`	Yes	Gateway payment ID (e.g., Checkout.com payment ID)

Returns:

typescript

{
  payment_id: string;
  gateway_payment_id: string;
  status: string;
}

Example:

javascript

await kore.updatePaymentGatewayId('session_12345', 'pay_xxxxx');

getSessionStatus

typescript

getSessionStatus(sessionId: string): Promise<SessionStatus>

Gets the current status of a payment session.

Parameters:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes	Session ID from createSession

Returns:

typescript

{
  session_id: string;
  status: 'pending' | 'requires_action' | 'redirected' | 'completed' | 'failed';
  payment_id: string | null;
  order_id: string;
  amount: number;
  currency: string;
  created_at: string;  // ISO 8601 timestamp
  expires_at: string;  // ISO 8601 timestamp
}

Throws:

KoreValidationError - If sessionId is missing
KoreNotFoundError - If session not found
KoreNetworkError - If network request fails

Example:

javascript

const status = await kore.getSessionStatus('session_12345');
console.log(`Status: ${status.status}`);

getTransaction

typescript

getTransaction(paymentId: string | number): Promise<Transaction>

Gets detailed transaction information.

Parameters:

Parameter	Type	Required	Description
`paymentId`	`string \| number`	Yes	Payment ID

Returns:

typescript

{
  payment_id: string;
  order_id: string;
  amount: number;
  currency: string;
  status: 'pending' | 'authorized' | 'captured' | 'failed' | 'refunded' | 'partial_refunded' | 'canceled';
  gateway: {
    id: number;
    code: string;
    name: string;
  } | null;
  gateway_payment_id: string | null;
  authorized_at: string | null;  // ISO 8601 timestamp
  captured_at: string | null;    // ISO 8601 timestamp
  failed_at: string | null;      // ISO 8601 timestamp
  failure_reason: string | null;
  created_at: string;             // ISO 8601 timestamp
  updated_at: string;             // ISO 8601 timestamp
}

Throws:

KoreValidationError - If paymentId is missing
KoreNotFoundError - If payment not found
KoreNetworkError - If network request fails

Example:

javascript

const transaction = await kore.getTransaction('payment_12345');
console.log(`Transaction status: ${transaction.status}`);

handleRedirectReturn

typescript

handleRedirectReturn(
  urlParams: URLSearchParams | Record<string, string>,
  apiSecret: string
): Promise<RedirectResult>

Handles redirect return from payment gateway with signature verification.

Parameters:

Parameter	Type	Required	Description
`urlParams`	`URLSearchParams \| Record<string, string>`	Yes	URL search parameters from returnUrl
`apiSecret`	`string`	Yes	Merchant API secret (server-side recommended)

Returns:

typescript

{
  success: boolean;
  data?: {
    payment_id: string;
    order_id: string;
    status: 'captured' | 'authorized' | 'failed' | 'canceled' | 'pending';
    gateway?: string;
  };
  error?: {
    code: string;
    message: string;
    payment_id?: string;
    order_id?: string;
    gateway?: string;
  };
}

Example:

javascript

const urlParams = new URLSearchParams(window.location.search);
const result = await kore.handleRedirectReturn(urlParams, apiSecret);

if (result.success) {
  console.log('Payment successful:', result.data);
} else {
  console.error('Payment failed:', result.error);
}

redirectToPayment

typescript

redirectToPayment(redirectUrl: string, options?: RedirectOptions): void

Redirects the browser to the payment gateway.

Parameters:

Parameter	Type	Required	Description
`redirectUrl`	`string`	Yes	URL from createSession response
`options.target`	`'_self' \| '_blank'`	No	Window target (default: `'_self'`)

Example:

javascript

kore.redirectToPayment(session.redirect_url);
// Or open in new window
kore.redirectToPayment(session.redirect_url, { target: '_blank' });

pollPaymentStatus

typescript

pollPaymentStatus(sessionId: string, options?: PollOptions): Promise<SessionStatus>

Polls payment status until completion or failure.

Parameters:

Parameter	Type	Required	Description
`sessionId`	`string`	Yes	Session ID
`options.interval`	`number`	No	Polling interval in ms (default: `2000`)
`options.maxAttempts`	`number`	No	Maximum polling attempts (default: `30`)
`options.onStatusChange`	`(status: SessionStatus) => void`	No	Callback on status change

Returns:

typescript

Promise<SessionStatus>  // Final session status

Example:

javascript

const finalStatus = await kore.pollPaymentStatus('session_12345', {
  interval: 2000,
  maxAttempts: 30,
  onStatusChange: (status) => {
    console.log(`Status changed to: ${status.status}`);
  }
});

verifyRedirectSignature

typescript

verifyRedirectSignature(params: RedirectParams, apiSecret: string): boolean

Verifies redirect signature synchronously (limited functionality in browser).

Note: For full verification, use verifyRedirectSignatureAsync or verify server-side.

Parameters:

Parameter	Type	Required	Description
`params`	`RedirectParams`	Yes	Redirect parameters
`apiSecret`	`string`	Yes	Merchant API secret

Returns:

typescript

boolean  // true if signature is valid

verifyRedirectSignatureAsync

typescript

verifyRedirectSignatureAsync(params: RedirectParams, apiSecret: string): Promise<boolean>

Verifies redirect signature asynchronously using Web Crypto API.

Parameters:

Parameter	Type	Required	Description
`params`	`RedirectParams`	Yes	Redirect parameters
`apiSecret`	`string`	Yes	Merchant API secret

Returns:

typescript

Promise<boolean>  // true if signature is valid

Utility Methods

Static Methods

generateIdempotencyKey

typescript

static generateIdempotencyKey(): string

Generates a UUID v4 string for use as an idempotency key.

Returns:

typescript

string  // UUID v4 string

Example:

javascript

const idempotencyKey = Kore.generateIdempotencyKey();

formatAmount

typescript

static formatAmount(amount: number, currency: string): string

Formats amount in minor units to display format.

Parameters:

Parameter	Type	Required	Description
`amount`	`number`	Yes	Amount in minor units
`currency`	`string`	Yes	ISO-4217 currency code

Returns:

typescript

string  // Formatted amount string (e.g., '$100.00')

Example:

javascript

const formatted = Kore.formatAmount(10000, 'USD');  // Returns: '$100.00'

validateCurrency

typescript

static validateCurrency(currency: string): boolean

Validates ISO-4217 currency code.

Parameters:

Parameter	Type	Required	Description
`currency`	`string`	Yes	Currency code to validate

Returns:

typescript

boolean  // true if valid

Example:

javascript

Kore.validateCurrency('USD');  // Returns: true
Kore.validateCurrency('INVALID');  // Returns: false

validateEmail

typescript

static validateEmail(email: string): boolean

Validates email format.

Parameters:

Parameter	Type	Required	Description
`email`	`string`	Yes	Email address to validate

Returns:

typescript

boolean  // true if valid

Example:

javascript

Kore.validateEmail('[email protected]');  // Returns: true
Kore.validateEmail('invalid');  // Returns: false

Error Codes

Access error code constants via Kore.ErrorCodes:

SDK Error Codes

typescript

Kore.ErrorCodes.AUTHENTICATION_ERROR  // Invalid or missing API key
Kore.ErrorCodes.VALIDATION_ERROR      // Invalid request parameters
Kore.ErrorCodes.PAYMENT_ERROR         // Payment processing error
Kore.ErrorCodes.NETWORK_ERROR         // Network/connection error
Kore.ErrorCodes.RATE_LIMIT_ERROR      // Rate limit exceeded
Kore.ErrorCodes.NOT_FOUND_ERROR       // Resource not found
Kore.ErrorCodes.SERVER_ERROR          // Server error

Redirect Error Codes

typescript

Kore.ErrorCodes.SESSION_NOT_FOUND              // Payment session not found or expired
Kore.ErrorCodes.PAYMENT_NOT_FOUND              // Payment record not found
Kore.ErrorCodes.GATEWAY_NOT_AVAILABLE          // Gateway is not active
Kore.ErrorCodes.GATEWAY_CREDENTIALS_ERROR      // Gateway credentials invalid
Kore.ErrorCodes.GATEWAY_ADAPTER_ERROR          // Gateway adapter failed
Kore.ErrorCodes.GATEWAY_SESSION_CREATION_FAILED // Failed to create gateway session
Kore.ErrorCodes.GATEWAY_VERIFICATION_FAILED    // Failed to verify payment
Kore.ErrorCodes.GATEWAY_TIMEOUT                // Gateway request timed out
Kore.ErrorCodes.NO_ACTIVE_API_KEY              // No active API key
Kore.ErrorCodes.RESOURCE_NOT_FOUND             // Resource not found
Kore.ErrorCodes.BAD_REQUEST                    // Invalid request
Kore.ErrorCodes.FORBIDDEN                      // Access denied
Kore.ErrorCodes.INTERNAL_ERROR                 // Server error
Kore.ErrorCodes.UNKNOWN_ERROR                  // Unknown error

Type Definitions

KoreConfig

typescript

interface KoreConfig {
  apiKey: string;
  baseUrl?: string;
  environment?: 'sandbox' | 'live';
  timeout?: number;
  retryAttempts?: number;
  retryDelay?: number;
  onError?: (error: KoreError) => void;
  onRequest?: (config: RequestConfig) => void;
  onResponse?: (response: Response) => void;
  debug?: boolean;
  logger?: (message: string) => void;
}

SessionData

typescript

interface SessionData {
  order_id: string;
  amount: number;
  currency: string;
  capture_mode?: 'auto' | 'manual';
  payer: {
    email: string;
    name: string;
    phone?: string;
  };
  billing: {
    address_line_1: string;
    address_line_2?: string;
    city: string;
    state?: string;
    postal_code: string;
    country: string;
  };
  shipping?: {
    address_line_1: string;
    address_line_2?: string;
    city: string;
    state?: string;
    postal_code: string;
    country: string;
    name?: string;
    phone?: string;
  };
  return_url: string;
  cancel_url: string;
  metadata?: Record<string, any>;
}

RedirectParams

typescript

interface RedirectParams {
  payment_id?: string;           // Optional, may be null for errors
  order_id: string;
  status: 'captured' | 'authorized' | 'failed' | 'canceled' | 'pending';
  gateway?: string;              // Optional gateway code
  error_code?: string;           // Present if status is 'failed'
  error_message?: string;        // Present if status is 'failed'
  signature: string;
}

RedirectResult

typescript

interface RedirectResult {
  success: boolean;
  data?: {
    payment_id: string;
    order_id: string;
    status: 'captured' | 'authorized' | 'failed' | 'canceled' | 'pending';
    gateway?: string;
  };
  error?: {
    code: string;
    message: string;
    payment_id?: string;
    order_id?: string;
    gateway?: string;
  };
}

Last Updated: SDK Version: 1.0.0

Kore Payment SDK - API Reference ​

Kore Class ​

Constructor ​

Payment Methods ​

createSession ​

sessionData ​

PayerInfo ​

AddressInfo ​

options ​

createEmbeddedSession ​

sessionData ​

initializePayment ​

updatePaymentGatewayId ​

getSessionStatus ​

getTransaction ​

handleRedirectReturn ​

redirectToPayment ​

pollPaymentStatus ​

verifyRedirectSignature ​

verifyRedirectSignatureAsync ​

Utility Methods ​

Static Methods ​

generateIdempotencyKey ​

formatAmount ​

validateCurrency ​

validateEmail ​

Error Codes ​

SDK Error Codes ​

Redirect Error Codes ​

Type Definitions ​

KoreConfig ​

SessionData ​

RedirectParams ​

RedirectResult ​

Kore Payment SDK - API Reference

Kore Class

Constructor

Payment Methods

createSession

sessionData

PayerInfo

AddressInfo

options

createEmbeddedSession

sessionData

initializePayment

updatePaymentGatewayId

getSessionStatus

getTransaction

handleRedirectReturn

redirectToPayment

pollPaymentStatus

verifyRedirectSignature

verifyRedirectSignatureAsync

Utility Methods

Static Methods

generateIdempotencyKey

formatAmount

validateCurrency

validateEmail

Error Codes

SDK Error Codes

Redirect Error Codes

Type Definitions

KoreConfig

SessionData

RedirectParams

RedirectResult