addpay-js/dist/index.d.mts

TypeScript SDK for AddPay Cloud API - CNP payment processing

type TransactionStatus = 0 | 1 | 2 | 3;
type TransactionType = 1 | 2 | 3 | 4 | 11;
type PaymentScenario = 'WEB_PAY' | 'WAP_PAY' | 'CNP_PAY';
type PlatformType = 'WEB' | 'WAP' | 'ANDROID' | 'IOS';
type Currency = 'ZAR' | 'USD' | 'EUR' | 'GBP';
interface ApiConfig {
    appId: string;
    merchantNo: string;
    storeNo: string;
    privateKey: string;
    publicKey: string;
    gatewayPublicKey: string;
    baseUrl?: string;
    timeout?: number;
    sandbox?: boolean;
}
interface ApiResponse<T = any> {
    code: string;
    msg: string;
    data?: T;
    sign?: string;
    timestamp?: number;
}
interface ApiError {
    code: string;
    message: string;
    details?: any;
    timestamp?: number;
}
declare class AddPayError extends Error {
    code: string;
    details?: any;
    timestamp?: number;
    constructor(code: string, message: string, details?: any);
}
interface RequestOptions {
    timeout?: number;
    retries?: number;
    headers?: Record<string, string>;
}

interface CheckoutRequest {
    merchant_order_no: string;
    order_amount: string | number;
    price_currency: Currency;
    notify_url: string;
    return_url: string;
    description?: string;
    attach?: string;
    expire_time?: number;
    goods_info?: GoodsInfo[];
    terminal?: PlatformType;
    scene_info?: SceneInfo;
    customer_info?: CustomerInfo;
}
interface GoodsInfo {
    goods_name: string;
    goods_id?: string;
    goods_category?: string;
    goods_desc?: string;
    goods_quantity?: number;
    goods_price?: string | number;
}
interface SceneInfo {
    device_id?: string;
    device_ip?: string;
    latitude?: string;
    longitude?: string;
}
interface CustomerInfo {
    customer_id?: string;
    customer_email?: string;
    customer_phone?: string;
    customer_name?: string;
}
interface CheckoutResponse {
    merchant_order_no: string;
    order_no: string;
    pay_url: string;
    qr_code?: string;
    expire_time?: number;
    trans_status: TransactionStatus;
}
interface CheckoutStatusRequest {
    merchant_order_no?: string;
    order_no?: string;
}
interface CheckoutStatusResponse {
    merchant_order_no: string;
    order_no: string;
    trans_status: TransactionStatus;
    trans_type: TransactionType;
    order_amount: string;
    price_currency: Currency;
    paid_amount?: string;
    paid_currency?: Currency;
    pay_time?: string;
    complete_time?: string;
    cancel_time?: string;
    refund_amount?: string;
    attach?: string;
}

interface DebiCheckMandateRequest {
    merchant_order_no: string;
    customer_info: DebiCheckCustomerInfo;
    mandate_info: MandateInfo;
    notify_url: string;
    return_url?: string;
}
interface DebiCheckCustomerInfo {
    customer_id: string;
    customer_name: string;
    customer_email?: string;
    customer_phone?: string;
    id_number: string;
    account_number: string;
    account_type: 'CURRENT' | 'SAVINGS' | 'TRANSMISSION';
    bank_name: string;
    branch_code: string;
}
interface MandateInfo {
    mandate_type: 'ONCE_OFF' | 'RECURRING';
    max_amount: string | number;
    currency: Currency;
    start_date: string;
    end_date?: string;
    frequency?: 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY';
    installments?: number;
    tracking_days?: number;
    description?: string;
}
interface DebiCheckMandateResponse {
    merchant_order_no: string;
    mandate_reference: string;
    mandate_status: 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED';
    auth_url?: string;
    expire_time?: number;
}
interface DebiCheckCollectionRequest {
    mandate_reference: string;
    merchant_order_no: string;
    collection_amount: string | number;
    currency: Currency;
    collection_date?: string;
    notify_url: string;
}
interface DebiCheckCollectionResponse {
    merchant_order_no: string;
    collection_reference: string;
    trans_status: TransactionStatus;
    collection_amount: string;
    currency: Currency;
    collection_date: string;
}
interface DebiCheckStatusRequest {
    mandate_reference?: string;
    merchant_order_no?: string;
}
interface DebiCheckStatusResponse {
    mandate_reference: string;
    mandate_status: 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED';
    merchant_order_no: string;
    collections?: DebiCheckCollection[];
}
interface DebiCheckCollection {
    collection_reference: string;
    merchant_order_no: string;
    trans_status: TransactionStatus;
    collection_amount: string;
    currency: Currency;
    collection_date: string;
    response_code?: string;
    response_message?: string;
}

interface TokenizationRequest {
    merchant_order_no: string;
    card_info?: CardInfo;
    customer_info?: TokenCustomerInfo;
    notify_url: string;
    return_url?: string;
    verification_amount?: string | number;
    currency?: Currency;
}
interface CardInfo {
    card_number?: string;
    card_holder_name?: string;
    expiry_month?: string;
    expiry_year?: string;
    cvv?: string;
}
interface TokenCustomerInfo {
    customer_id: string;
    customer_email?: string;
    customer_phone?: string;
    customer_name?: string;
    billing_address?: BillingAddress;
}
interface BillingAddress {
    address_line1?: string;
    address_line2?: string;
    city?: string;
    state?: string;
    postal_code?: string;
    country?: string;
}
interface TokenizationResponse {
    merchant_order_no: string;
    token: string;
    token_status: 'ACTIVE' | 'INACTIVE' | 'EXPIRED';
    card_info: TokenizedCardInfo;
    expire_time?: string;
}
interface TokenizedCardInfo {
    masked_card_number: string;
    card_brand: 'VISA' | 'MASTERCARD' | 'AMEX' | 'DISCOVER' | 'OTHER';
    card_type: 'CREDIT' | 'DEBIT';
    expiry_month: string;
    expiry_year: string;
    card_holder_name?: string;
}
interface TokenPaymentRequest {
    token: string;
    merchant_order_no: string;
    order_amount: string | number;
    currency: Currency;
    cvv?: string;
    description?: string;
    notify_url: string;
    return_url?: string;
    customer_info?: TokenCustomerInfo;
}
interface TokenPaymentResponse {
    merchant_order_no: string;
    order_no: string;
    trans_status: TransactionStatus;
    order_amount: string;
    currency: Currency;
    auth_code?: string;
    response_code?: string;
    response_message?: string;
    trans_time?: string;
}
interface TokenDeleteRequest {
    token: string;
    customer_id?: string;
}
interface TokenDeleteResponse {
    token: string;
    status: 'DELETED' | 'NOT_FOUND';
    delete_time?: string;
}
interface TokenListRequest {
    customer_id: string;
    page?: number;
    limit?: number;
}
interface TokenListResponse {
    customer_id: string;
    tokens: TokenInfo[];
    total: number;
    page: number;
    limit: number;
}
interface TokenInfo {
    token: string;
    token_status: 'ACTIVE' | 'INACTIVE' | 'EXPIRED';
    card_info: TokenizedCardInfo;
    created_at: string;
    last_used_at?: string;
}

declare class HttpClient {
    private config;
    private baseUrl;
    constructor(config: ApiConfig);
    request<T = any>(endpoint: string, method?: 'GET' | 'POST' | 'PUT' | 'DELETE', data?: Record<string, any>, options?: RequestOptions): Promise<ApiResponse<T>>;
    private prepareRequestData;
    private generateSignature;
    private verifySignature;
    private delay;
}

declare class CheckoutResource {
    private client;
    constructor(client: HttpClient);
    /**
     * Create a checkout session for hosted payment page
     */
    create(request: CheckoutRequest): Promise<CheckoutResponse>;
    /**
     * Get the status of a checkout session
     */
    getStatus(request: CheckoutStatusRequest): Promise<CheckoutStatusResponse>;
    /**
     * Cancel a checkout session
     */
    cancel(merchantOrderNo: string): Promise<CheckoutStatusResponse>;
    /**
     * Refund a completed checkout transaction
     */
    refund(merchantOrderNo: string, refundAmount?: string | number, reason?: string): Promise<CheckoutStatusResponse>;
    /**
     * Create a checkout session with fluent API
     */
    createCheckout(): CheckoutBuilder;
}
/**
 * Fluent builder for checkout requests
 */
declare class CheckoutBuilder {
    private resource;
    private request;
    constructor(resource: CheckoutResource);
    merchantOrderNo(value: string): this;
    amount(value: string | number): this;
    currency(value: CheckoutRequest['price_currency']): this;
    notifyUrl(value: string): this;
    returnUrl(value: string): this;
    description(value: string): this;
    attach(value: string): this;
    expireTime(value: number): this;
    goods(value: CheckoutRequest['goods_info']): this;
    terminal(value: CheckoutRequest['terminal']): this;
    sceneInfo(value: CheckoutRequest['scene_info']): this;
    customerInfo(value: CheckoutRequest['customer_info']): this;
    execute(): Promise<CheckoutResponse>;
    private validate;
}

declare class DebiCheckResource {
    private client;
    constructor(client: HttpClient);
    /**
     * Create a DebiCheck mandate
     */
    createMandate(request: DebiCheckMandateRequest): Promise<DebiCheckMandateResponse>;
    /**
     * Initiate a collection against an approved mandate
     */
    collect(request: DebiCheckCollectionRequest): Promise<DebiCheckCollectionResponse>;
    /**
     * Get the status of a mandate and its collections
     */
    getStatus(request: DebiCheckStatusRequest): Promise<DebiCheckStatusResponse>;
    /**
     * Cancel a mandate
     */
    cancelMandate(mandateReference: string): Promise<DebiCheckStatusResponse>;
    /**
     * Create a mandate with fluent API
     */
    createMandateBuilder(): DebiCheckMandateBuilder;
    /**
     * Create a collection with fluent API
     */
    createCollectionBuilder(): DebiCheckCollectionBuilder;
}
/**
 * Fluent builder for DebiCheck mandate requests
 */
declare class DebiCheckMandateBuilder {
    private resource;
    private request;
    constructor(resource: DebiCheckResource);
    merchantOrderNo(value: string): this;
    customerInfo(value: DebiCheckCustomerInfo): this;
    customer(builder: (info: CustomerInfoBuilder) => void): this;
    mandateInfo(value: MandateInfo): this;
    mandate(builder: (info: MandateInfoBuilder) => void): this;
    notifyUrl(value: string): this;
    returnUrl(value: string): this;
    execute(): Promise<DebiCheckMandateResponse>;
    private validate;
}
/**
 * Builder for customer info
 */
declare class CustomerInfoBuilder {
    private info;
    id(value: string): this;
    name(value: string): this;
    email(value: string): this;
    phone(value: string): this;
    idNumber(value: string): this;
    accountNumber(value: string): this;
    accountType(value: DebiCheckCustomerInfo['account_type']): this;
    bankName(value: string): this;
    branchCode(value: string): this;
    build(): DebiCheckCustomerInfo;
}
/**
 * Builder for mandate info
 */
declare class MandateInfoBuilder {
    private info;
    type(value: MandateInfo['mandate_type']): this;
    maxAmount(value: string | number): this;
    currency(value: MandateInfo['currency']): this;
    startDate(value: string): this;
    endDate(value: string): this;
    frequency(value: MandateInfo['frequency']): this;
    installments(value: number): this;
    trackingDays(value: number): this;
    description(value: string): this;
    build(): MandateInfo;
}
/**
 * Fluent builder for DebiCheck collection requests
 */
declare class DebiCheckCollectionBuilder {
    private resource;
    private request;
    constructor(resource: DebiCheckResource);
    mandateReference(value: string): this;
    merchantOrderNo(value: string): this;
    amount(value: string | number): this;
    currency(value: DebiCheckCollectionRequest['currency']): this;
    collectionDate(value: string): this;
    notifyUrl(value: string): this;
    execute(): Promise<DebiCheckCollectionResponse>;
    private validate;
}

declare class TokenResource {
    private client;
    constructor(client: HttpClient);
    /**
     * Tokenize a card for future payments
     */
    tokenize(request: TokenizationRequest): Promise<TokenizationResponse>;
    /**
     * Process a payment using a stored token
     */
    pay(request: TokenPaymentRequest): Promise<TokenPaymentResponse>;
    /**
     * Delete a stored token
     */
    delete(request: TokenDeleteRequest): Promise<TokenDeleteResponse>;
    /**
     * List all tokens for a customer
     */
    list(request: TokenListRequest): Promise<TokenListResponse>;
    /**
     * Get token details
     */
    get(token: string): Promise<TokenizationResponse>;
    /**
     * Create a tokenization request with fluent API
     */
    createTokenization(): TokenizationBuilder;
    /**
     * Create a token payment with fluent API
     */
    createPayment(): TokenPaymentBuilder;
}
/**
 * Fluent builder for tokenization requests
 */
declare class TokenizationBuilder {
    private resource;
    private request;
    constructor(resource: TokenResource);
    merchantOrderNo(value: string): this;
    cardInfo(value: CardInfo): this;
    card(builder: (info: CardInfoBuilder) => void): this;
    customerInfo(value: TokenCustomerInfo): this;
    customer(builder: (info: TokenCustomerBuilder) => void): this;
    notifyUrl(value: string): this;
    returnUrl(value: string): this;
    verificationAmount(value: string | number): this;
    currency(value: TokenizationRequest['currency']): this;
    execute(): Promise<TokenizationResponse>;
    private validate;
}
/**
 * Builder for card info
 */
declare class CardInfoBuilder {
    private info;
    cardNumber(value: string): this;
    cardHolderName(value: string): this;
    expiryMonth(value: string): this;
    expiryYear(value: string): this;
    cvv(value: string): this;
    build(): CardInfo;
}
/**
 * Builder for token customer info
 */
declare class TokenCustomerBuilder {
    private info;
    id(value: string): this;
    email(value: string): this;
    phone(value: string): this;
    name(value: string): this;
    billingAddress(value: BillingAddress): this;
    address(builder: (addr: BillingAddressBuilder) => void): this;
    build(): TokenCustomerInfo;
}
/**
 * Builder for billing address
 */
declare class BillingAddressBuilder {
    private address;
    line1(value: string): this;
    line2(value: string): this;
    city(value: string): this;
    state(value: string): this;
    postalCode(value: string): this;
    country(value: string): this;
    build(): BillingAddress;
}
/**
 * Fluent builder for token payment requests
 */
declare class TokenPaymentBuilder {
    private resource;
    private request;
    constructor(resource: TokenResource);
    token(value: string): this;
    merchantOrderNo(value: string): this;
    amount(value: string | number): this;
    currency(value: TokenPaymentRequest['currency']): this;
    cvv(value: string): this;
    description(value: string): this;
    notifyUrl(value: string): this;
    returnUrl(value: string): this;
    customerInfo(value: TokenCustomerInfo): this;
    execute(): Promise<TokenPaymentResponse>;
    private validate;
}

/**
 * AddPay SDK Client
 *
 * Main entry point for interacting with the AddPay Cloud API
 */
declare class AddPayClient {
    private httpClient;
    readonly checkout: CheckoutResource;
    readonly debicheck: DebiCheckResource;
    readonly token: TokenResource;
    constructor(config: ApiConfig);
    private validateConfig;
    /**
     * Create a new AddPay client instance
     */
    static create(config: ApiConfig): AddPayClient;
}

export { AddPayClient, AddPayError, type ApiConfig, type ApiError, type ApiResponse, type BillingAddress, type CardInfo, CheckoutBuilder, type CheckoutRequest, CheckoutResource, type CheckoutResponse, type CheckoutStatusRequest, type CheckoutStatusResponse, type Currency, type CustomerInfo, type DebiCheckCollection, DebiCheckCollectionBuilder, type DebiCheckCollectionRequest, type DebiCheckCollectionResponse, type DebiCheckCustomerInfo, DebiCheckMandateBuilder, type DebiCheckMandateRequest, type DebiCheckMandateResponse, DebiCheckResource, type DebiCheckStatusRequest, type DebiCheckStatusResponse, type GoodsInfo, type MandateInfo, type PaymentScenario, type PlatformType, type RequestOptions, type SceneInfo, type TokenCustomerInfo, type TokenDeleteRequest, type TokenDeleteResponse, type TokenInfo, type TokenListRequest, type TokenListResponse, TokenPaymentBuilder, type TokenPaymentRequest, type TokenPaymentResponse, TokenResource, TokenizationBuilder, type TokenizationRequest, type TokenizationResponse, type TokenizedCardInfo, type TransactionStatus, type TransactionType };