SDK reference

Payments

new Payments(http: HttpClient)

cancel (id: string, options?: RequestOptions): Promise<Payment>

Cancels a PENDING payment. Only a 429 is retried automatically (a cancel is not idempotency-keyed).

create (params: PaymentCreateParams, options?: RequestOptions): Promise<Payment>

Creates a hosted Payment and returns it with its `checkoutUrl`. A secure Idempotency-Key is generated automatically (and reused on every automatic retry), so a retried call can never create a second payment. Pass `{ idempotencyKey }` to use your own, e.g. your order id.

list (params?: PaymentListParams, options?: RequestOptions): Promise<PaymentList>

One page. Use `listAutoPaging` to iterate every payment.

listAutoPaging (params?: Omit<PaymentListParams, "startingAfter">, options?: RequestOptions): AsyncGenerator<Payment, void, undefined>

Iterates every matching payment, fetching pages lazily. Optional — `list` is always available.

retrieve (id: string, options?: RequestOptions): Promise<Payment>

Retrieves one payment by id.

PayTaka

The PayTaka server client. SERVER-SIDE ONLY: it holds your secret key, so never bundle it into browser JavaScript, an Android/iOS app, React Native or Flutter. Mobile and browser apps get a `checkoutUrl` from YOUR backend.

new PayTaka(options: PayTakaOptions)

environment : "live" | "test"

Inferred from the key prefix; the server remains authoritative.

payments : Payments

testHelpers : TestHelpers

Sandbox helpers (`pt_test_sk_` keys only).

webhooks : { readonly verify: (rawBody: RawBody, signatureHeader: string | null | undefined, secret: string, options?: VerifyOptions) => WebhookEvent; readonly computeSignature: (secret: string, timestamp: number, rawBody: RawBody) => string; readonly DEFAULT_TOLERANCE_SECONDS: 300; }

PayTakaAPIError

The API answered with an error. Quote `requestId` to PayTaka support. Narrow with the subclasses below, or switch on `code` (an open string — new codes can be added without a major SDK release).

new PayTakaAPIError(fields: APIErrorFields)

cause ?: unknown

code : string

httpStatus : number

message : string

name : string

param : string | undefined

requestId : string | undefined

stack ?: string | undefined

PayTakaAuthenticationError

401 / 403: the key is invalid, revoked, or lacks the needed scope.

new PayTakaAuthenticationError(fields: APIErrorFields)

cause ?: unknown

code : string

httpStatus : number

message : string

name : string

param : string | undefined

requestId : string | undefined

stack ?: string | undefined

PayTakaConfigError

The SDK was configured incorrectly (bad/missing key, unsafe environment). Never sent to the API.

new PayTakaConfigError(message: string, options?: { cause?: unknown; })

cause ?: unknown

message : string

name : string

stack ?: string | undefined

PayTakaError

Base class for every error this SDK throws.

new PayTakaError(message: string, options?: { cause?: unknown; })

cause ?: unknown

message : string

name : string

stack ?: string | undefined

PayTakaIdempotencyError

409 idempotency_conflict / idempotency_in_progress.

new PayTakaIdempotencyError(fields: APIErrorFields)

cause ?: unknown

code : string

httpStatus : number

message : string

name : string

param : string | undefined

requestId : string | undefined

stack ?: string | undefined

PayTakaInputError

Invalid input rejected locally, before any request is made (for example an unusable `amount`).

new PayTakaInputError(message: string, param: string)

cause ?: unknown

message : string

name : string

param : string

stack ?: string | undefined

PayTakaNetworkError

No response was received: DNS/connection failure, timeout, or the request was aborted.

new PayTakaNetworkError(message: string, options?: { cause?: unknown; timedOut?: boolean; })

cause ?: unknown

message : string

name : string

stack ?: string | undefined

timedOut : boolean

PayTakaRateLimitError

429: too many requests. `retryAfterSeconds` mirrors the Retry-After header when present.

new PayTakaRateLimitError(fields: APIErrorFields & { retryAfterSeconds?: number; })

cause ?: unknown

code : string

httpStatus : number

message : string

name : string

param : string | undefined

requestId : string | undefined

retryAfterSeconds : number | undefined

stack ?: string | undefined

PayTakaSignatureVerificationError

A webhook could not be verified. Never trust or process the payload.

new PayTakaSignatureVerificationError(message: string, reason: PayTakaSignatureVerificationError["reason"])

cause ?: unknown

message : string

name : string

reason : "malformed_header" | "timestamp_outside_tolerance" | "no_matching_signature"

stack ?: string | undefined

PayTakaValidationError

400: a parameter was rejected. `param` names it when known.

new PayTakaValidationError(fields: APIErrorFields)

cause ?: unknown

code : string

httpStatus : number

message : string

name : string

param : string | undefined

requestId : string | undefined

stack ?: string | undefined

TestHelpers

Sandbox-only helpers. They work with a `pt_test_sk_` key; a live key gets the API's normal 404. They exist to complete a Test payment without any real money, SMS or bKash/Nagad account.

new TestHelpers(http: HttpClient)

payments : { succeed: (id: string, options?: RequestOptions) => Promise<Payment>; cancel: (id: string, options?: RequestOptions) => Promise<Payment>; }

normalizeAmount

Normalizes a developer-friendly amount to the API's canonical decimal string ("500" -> "500.00"). No float arithmetic and no rounding: anything that can't be represented exactly with two decimals is REJECTED rather than silently changed — 0.001 throws, it never becomes "0.00".

(amount: number | string): string

verifyWebhook

Verifies a webhook and returns the typed event. Pass the RAW request body — the exact bytes received, before any JSON parsing — and the value of the `PayTaka-Signature` header. Throws PayTakaSignatureVerificationError if it cannot be trusted; never process a payload that failed verification.

(rawBody: RawBody, signatureHeader: string | null | undefined, secret: string, options?: VerifyOptions): WebhookEvent

DEFAULT_TOLERANCE_SECONDS

Reject signatures older (or further in the future) than this.

300

SDK_VERSION

"0.1.0"

webhooks

`paytaka.webhooks` — also importable standalone, since a webhook receiver needs only the signing secret, not an API key.

verify (rawBody: RawBody, signatureHeader: string | null | undefined, secret: string, options?: VerifyOptions): WebhookEvent

computeSignature (secret: string, timestamp: number, rawBody: RawBody): string

DEFAULT_TOLERANCE_SECONDS : 300

EndpointTestEvent

The synthetic, non-financial event sent from the dashboard's "Send test event". It contains NO Payment.

type : "endpoint.test"

data : { object: { message: string; endpointId: string | null; }; }

id : string

livemode : boolean

createdAt : Date

apiVersion : string

Payment

A hosted Payment. `amount` is the canonical decimal string, e.g. "500.00".

id : string

livemode : boolean

status : PaymentStatus

amount : string

currency : "BDT"

description : string | null

merchantReference : string | null

externalId : string | null

metadata : Record<string, string>

allowedMethods : PaymentMethod[]

allowedChannels : CollectionChannel[]

returnUrl : string | null

checkoutUrl : string | null

Send your customer here (or open it from a native app).

createdAt : Date

paidAt : Date | null

cancelledAt : Date | null

PaymentCreateParams

amount : string | number

500, 500.5 or "500.50". Sent as a canonical two-decimal string.

description ?: string | undefined

merchantReference ?: string | undefined

externalId ?: string | undefined

returnUrl ?: string | undefined

metadata ?: Record<string, string> | undefined

allowedMethods ?: ("BKASH" | "NAGAD")[] | undefined

allowedChannels ?: ("SEND_MONEY" | "PAYMENT" | "CASH_IN" | "BANK_TRANSFER")[] | undefined

customerId ?: string | undefined

orderId ?: string | undefined

PaymentEvent

A `payment.*` event. `data.object` is the same Payment `payments.retrieve` returns.

type : T

data : { object: Payment; }

id : string

livemode : boolean

createdAt : Date

apiVersion : string

PaymentList

data : Payment[]

hasMore : boolean

nextCursor : string | null

PaymentListParams

status ?: "PENDING" | "PAID" | "CANCELLED" | "REVERSED" | undefined

externalId ?: string | undefined

createdFrom ?: string | Date | undefined

createdTo ?: string | Date | undefined

limit ?: number | undefined

1–100, default 20.

startingAfter ?: string | undefined

A payment id: return payments after it (the previous page's `nextCursor`).

PayTakaOptions

secretKey : string

Your secret key: `pt_test_sk_…` (sandbox) or `pt_live_sk_…`. Server-side only.

baseUrl ?: string | undefined

The PayTaka API base URL, for example `process.env.PAYTAKA_API_URL`. Required until a release ships with the production URL built in; then it is optional.

timeoutMs ?: number | undefined

Default 30000.

maxRetries ?: number | undefined

Automatic retries for safe failures. Default 2.

fetch ?: { (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | URL | Request, init?: RequestInit): Promise<Response>; } | undefined

A fetch implementation; defaults to the runtime's global `fetch`.

retryBaseDelayMs ?: number | undefined

Advanced/testing: first backoff delay in ms (default 500).

RequestOptions

idempotencyKey ?: string | undefined

Override the automatically generated Idempotency-Key (payments.create only).

timeoutMs ?: number | undefined

Per-request timeout in milliseconds.

maxRetries ?: number | undefined

Per-request retry budget.

signal ?: AbortSignal | undefined

UnknownWebhookEvent

An event type newer than this SDK. Its signature IS verified and it is safe to log or ignore: `rawType` is the type the API sent, `data.object` the raw payload. (`type` is the literal "unknown" so narrowing on the known event types stays exact.)

type : "unknown"

rawType : string

data : { object: Record<string, unknown>; }

id : string

livemode : boolean

createdAt : Date

apiVersion : string

CollectionChannel

KnownCollectionChannel | (string & {})

KnownCollectionChannel

How the customer pays: SEND_MONEY ("Send Money"), PAYMENT ("Payment"), CASH_IN ("Cash In"), BANK_TRANSFER ("Bank / Card Add Money").

Wire["CollectionChannel"]

KnownPaymentMethod

Wire["PaymentMethod"]

KnownPaymentStatus

Statuses this SDK version knows. Requests (for example the `list` filter) accept only these.

Wire["PaymentStatus"]

PaymentEventType

"payment.created" | "payment.paid" | "payment.cancelled" | "payment.reversed"

PaymentMethod

KnownPaymentMethod | (string & {})

PaymentStatus

What a response may contain. The API only ever adds values, so a value newer than this SDK is passed through as a string instead of failing — `(string & {})` keeps autocompletion and narrowing for the known ones. Always keep a default branch when switching on these.

KnownPaymentStatus | (string & {})

WebhookEvent

Narrow on `event.type`; always handle (or ignore) `"unknown"`.

| PaymentEvent<"payment.created"> | PaymentEvent<"payment.paid"> | PaymentEvent<"payment.cancelled"> | PaymentEvent<"payment.reversed"> | EndpointTestEvent | UnknownWebhookEvent