@herberthtk/yo-payments-api 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,391 @@
+type NonBlocking = "TRUE" | "FALSE";
+type DepositTransactionType = "PULL" | "PUSH";
+type YoMode = "production" | "sandbox";
+interface PaymentNotificationBody {
+    date_time: string;
+    amount: string;
+    narrative: string;
+    network_ref: string;
+    external_ref: string;
+    msisdn: string;
+    signature: string;
+}
+interface PaymentFailureNotificationBody {
+    failed_transaction_reference: string;
+    transaction_init_date: string;
+    verification: string;
+}
+interface PaymentNotificationResult {
+    is_verified: boolean;
+    date_time: string;
+    amount: string;
+    narrative: string;
+    network_ref: string;
+    external_ref: string;
+    msisdn: string;
+}
+interface PaymentFailureNotificationResult {
+    is_verified: boolean;
+    failed_transaction_reference: string;
+    transaction_init_date: string;
+}
+interface DepositFundsResponse {
+    Status: string;
+    StatusCode: string;
+    StatusMessage: string;
+    TransactionStatus: string;
+    ErrorMessageCode?: string;
+    ErrorMessage?: string;
+    TransactionReference?: string;
+    MNOTransactionReferenceId?: string;
+    IssuedReceiptNumber?: string;
+}
+interface TransactionCheckStatusResponse extends DepositFundsResponse {
+    Amount?: string;
+    AmountFormatted?: string;
+    CurrencyCode?: string;
+    TransactionInitiationDate?: string;
+    TransactionCompletionDate?: string;
+}
+type InternalTransferResponse = DepositFundsResponse;
+interface BalanceEntry {
+    code: string;
+    balance: string;
+}
+interface AcctBalanceResponse {
+    Status: string;
+    StatusCode: string;
+    balance: BalanceEntry[];
+    StatusMessage?: string;
+    ErrorMessageCode?: string;
+    ErrorMessage?: string;
+}
+interface TransactionDetail {
+    TransactionSystemId: string;
+    TransactionReference: string;
+    TransactionStatus: string;
+    InitiationDate: string;
+    CompletionDate: string;
+    NarrativeBase64: string;
+    Currency: string;
+    Amount: string;
+    Balance: string;
+    GeneralType: string;
+    DetailedType: string;
+    BeneficiaryMsisdn?: string;
+    BeneficiaryBase64: string;
+    SenderMsisdn?: string;
+    SenderBase64: string;
+    Base64TransactionExternalReference?: string;
+    TransactionEntryDesignation: string;
+}
+interface MinistatementResponse {
+    Status: string;
+    StatusCode: string;
+    TotalTransactions: string;
+    ReturnedTransactions: string;
+    Transactions: TransactionDetail[];
+    ErrorMessageCode?: string;
+    ErrorMessage?: string;
+}
+type SendAirtimeResponse = DepositFundsResponse;
+interface PurchaseAirtimeStockResponse {
+    Status: string;
+    StatusCode: string;
+    StatusMessage?: string;
+    TransactionReference?: string;
+    TotalCurrencyDebited?: string;
+    CommissionAmount?: string;
+    ErrorMessageCode?: string;
+    ErrorMessage?: string;
+}
+interface MsisdnKycInfoResponse {
+    Status: string;
+    StatusCode: string;
+    StatusMessage?: string;
+    FirstName?: string;
+    MiddleName?: string;
+    Surname?: string;
+}
+
+/**
+ * Error thrown for transport-level and protocol-level failures:
+ * connection errors, timeouts, non-2xx HTTP statuses, oversized bodies,
+ * malformed XML and responses missing the <Response> node.
+ * Gateway-level business failures (e.g. Status FAILED) are still returned
+ * as normal response objects, exactly like the PHP library.
+ */
+declare class YoAPIError extends Error {
+    /** HTTP status code when the failure came with an HTTP response. */
+    readonly status?: number;
+    /** Truncated response body (up to 500 chars) when one was received. */
+    readonly body?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * Yo! Payments API client (TypeScript port of the official PHP library YoAPI.php).
+ *
+ * Values are inserted into the request XML verbatim (exactly like the PHP library),
+ * so any special XML characters in narratives, references or notification URLs must
+ * be escaped by the caller.
+ */
+declare class YoAPI {
+    /** The Yo! Payments API Username. Required. */
+    private username;
+    /** The Yo! Payments API Password. Required. */
+    private password;
+    /** Whether the gateway connection is held open until the request completes. Default "FALSE". */
+    private nonBlocking;
+    /** An externally agreed reference (e.g. an invoice number). */
+    private externalReference;
+    /** A reference code related to another Yo! Payments system transaction. */
+    private internalReference;
+    /** Text appended to the confirmation SMS sent by the mobile money provider. */
+    private providerReferenceText;
+    /** URL notified as soon as funds are successfully deposited into your account. */
+    private instantNotificationUrl;
+    /** URL notified as soon as a deposit request fails. */
+    private failureNotificationUrl;
+    /** May be required to authenticate certain deposit requests. */
+    private authenticationSignatureBase64;
+    /** "PULL" or "PUSH". Default "PULL". */
+    private depositTransactionType;
+    /** The URL API requests are submitted to. */
+    private yoUrl;
+    /** Certificate used to verify IPN signatures (sandbox or production). */
+    private publicKeyFile;
+    /** Whether publicKeyFile is still the bundled default (enables the embedded-cert fallback). */
+    private publicKeyFileIsDefault;
+    private transactionLimitAccountIdentifier;
+    /** Unique nonce per request, required when public key authentication is enabled. */
+    private publicKeyAuthenticationNonce;
+    /** Base64 RSA signature over SHA1(username+amount+account+narrative+external_ref+nonce). */
+    private publicKeyAuthenticationSignatureBase64;
+    /** Location of the private key used to sign the public key authentication signature. */
+    private privateKeyFileLocation;
+    /**
+     * Private key PEM content used to sign the public key authentication signature.
+     * Prefer this over a file location on serverless/bundled hosts where the
+     * filesystem is ephemeral (e.g. Vercel). Takes precedence when both are set.
+     */
+    private privateKeyContent;
+    private readonly mode;
+    /** Request timeout in milliseconds (PHP library uses curl timeout 120s). <= 0 means no timeout, like curl. */
+    private timeoutMs;
+    /**
+     * Whether to verify the gateway TLS certificate. Default true.
+     * The PHP library disables peer verification; this port verifies by default and
+     * only skips verification when explicitly opted out via setTlsVerificationEnabled(false).
+     */
+    private verifyTls;
+    /** Maximum accepted gateway response body in bytes (default 1 MiB). */
+    private maxResponseBytes;
+    constructor(username: string, password: string, mode?: YoMode);
+    /** Returns the mode ("production" or "sandbox") this instance was created with. */
+    getMode(): YoMode;
+    /** Set the API Username. */
+    setUsername(username: string): void;
+    /** Returns the API Username. */
+    getUsername(): string;
+    /** Set the API Password. */
+    setPassword(password: string): void;
+    /** Returns the API Password. */
+    getPassword(): string;
+    /** Set the URL to submit API requests to. */
+    setUrl(url: string): void;
+    /** Returns the URL API requests are submitted to. */
+    getUrl(): string;
+    /** Set the path of the certificate used to verify IPN signatures. */
+    setPublicKeyFileUrl(publicKeyFileUrl: string): void;
+    /** Returns the path of the certificate used to verify IPN signatures. */
+    getPublicKeyFileUrl(): string;
+    /** Set the NonBlocking variable: "TRUE" for non-blocking API requests. */
+    setNonblocking(nonblocking: NonBlocking): void;
+    /** Returns the NonBlocking variable. */
+    getNonblocking(): NonBlocking;
+    /** Set the External Reference used when submitting payment requests. */
+    setExternalReference(externalReference: string | null): void;
+    /** Returns the externalReference variable. */
+    getExternalReference(): string | null;
+    /** Set the Internal Reference used when submitting payment requests. */
+    setInternalReference(internalReference: string | null): void;
+    /** Returns the internalReference variable. */
+    getInternalReference(): string | null;
+    /** Set the Provider Reference Text used when submitting payment requests. */
+    setProviderReferenceText(providerReferenceText: string | null): void;
+    /** Returns the providerReferenceText variable. */
+    getProviderReferenceText(): string | null;
+    /** Set the Instant Notification URL (useful for non-blocking requests). */
+    setInstantNotificationUrl(instantNotificationUrl: string | null): void;
+    /** Returns the instantNotificationUrl variable. */
+    getInstantNotificationUrl(): string | null;
+    /** Set the Failure Notification URL (useful for non-blocking requests). */
+    setFailureNotificationUrl(failureNotificationUrl: string | null): void;
+    /** Returns the failureNotificationUrl variable. */
+    getFailureNotificationUrl(): string | null;
+    /** Set the Authentication Signature Base64. */
+    setAuthenticationSignatureBase64(authenticationSignatureBase64: string | null): void;
+    /** Returns the Authentication Signature Base64 variable. */
+    getAuthenticationSignatureBase64(): string | null;
+    /** Set the Deposit Transaction Type ("PULL" or "PUSH") used by acTransactionCheckStatus. */
+    setDepositTransactionType(depositTransactionType: DepositTransactionType): void;
+    /** Returns the Deposit Transaction Type variable. */
+    getDepositTransactionType(): DepositTransactionType;
+    /** Set the Transaction Limit Account Identifier (refer to your account administrator). */
+    setTransactionLimitAccountIdentifier(transactionLimitAccountIdentifier: string | null): void;
+    /** Returns the Transaction Limit Account Identifier variable. */
+    getTransactionLimitAccountIdentifier(): string | null;
+    /** Set the Public Key Authentication Nonce (refer to your account administrator). */
+    setPublicKeyAuthenticationNonce(publicKeyAuthenticationNonce: string | null): void;
+    /** Returns the Public Key Authentication Nonce variable. */
+    getPublicKeyAuthenticationNonce(): string | null;
+    /** Set the Public Key Authentication Base64-Encoded Signature (refer to your account administrator). */
+    setPublicKeyAuthenticationSignatureBase64(publicKeyAuthenticationSignatureBase64: string | null): void;
+    /** Returns the Public Key Authentication Base64-Encoded Signature variable. */
+    getPublicKeyAuthenticationSignatureBase64(): string | null;
+    /** Set the location of the private key used to sign the public key authentication signature. */
+    setPrivateKeyFileLocation(privateKeyFileLocation: string | null): void;
+    /** Returns the Private Key File variable. */
+    getPrivateKeyFileLocation(): string | null;
+    /**
+     * Set the private key PEM content directly (alternative to setPrivateKeyFileLocation).
+     * Useful where key files are unavailable, e.g. serverless deployments reading
+     * the key from an environment variable. Takes precedence when both are set.
+     */
+    setPrivateKeyContent(privateKeyContent: string | null): void;
+    /** Returns the Private Key PEM content variable. */
+    getPrivateKeyContent(): string | null;
+    /** Set the request timeout in milliseconds. Values <= 0 disable the timeout (like PHP curl timeout 0). */
+    setTimeout(timeoutMs: number): void;
+    /** Returns the request timeout in milliseconds. */
+    getTimeout(): number;
+    /**
+     * Enable or disable verification of the gateway TLS certificate (default enabled).
+     * Disable only for testing against endpoints with self-signed certificates —
+     * the PHP library always skips verification.
+     * Note: the underlying mechanism is a Bun fetch extension; on Node.js, disabling
+     * verification additionally requires NODE_TLS_REJECT_UNAUTHORIZED=0 in the environment.
+     */
+    setTlsVerificationEnabled(enabled: boolean): void;
+    /** Returns whether gateway TLS certificate verification is enabled. */
+    getTlsVerificationEnabled(): boolean;
+    /** Set the maximum accepted gateway response body in bytes (default 1048576). */
+    setMaxResponseBytes(maxResponseBytes: number): void;
+    /** Returns the maximum accepted gateway response body in bytes. */
+    getMaxResponseBytes(): number;
+    /**
+     * Request Mobile Money User to deposit funds into your account.
+     * Shortly after submitting, the mobile money user receives an on-screen prompt to
+     * authorize the transfer. Not supported by all mobile money operator networks.
+     * @param msisdn the mobile money phone number in the format 256772123456
+     * @param amount the amount to deposit into your account (fractions supported)
+     * @param narrative the reason for the mobile money user to deposit funds
+     */
+    acDepositFunds(msisdn: string, amount: number | string, narrative: string): Promise<DepositFundsResponse>;
+    /**
+     * Check the status of a transaction that was earlier submitted for processing.
+     * Particularly useful when NonBlocking is "TRUE".
+     * @param transactionReference the gateway reference uniquely identifying the transaction
+     * @param privateTransactionReference the External Reference used to carry out the transaction
+     */
+    acTransactionCheckStatus(transactionReference: string | null, privateTransactionReference?: string | null): Promise<TransactionCheckStatusResponse>;
+    /**
+     * Transfer funds from your Payment Account to another Yo! Payments Account.
+     * @param currencyCode e.g. "UGX-MTNMM", "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+     * @param amount the amount to be transferred
+     * @param beneficiaryAccount account number of the beneficiary Yo! Payments user
+     * @param beneficiaryEmail email address of the recipient of funds
+     * @param narrative textual narrative about the transaction
+     */
+    acInternalTransfer(currencyCode: string, amount: number | string, beneficiaryAccount: number | string, beneficiaryEmail: string, narrative: string): Promise<InternalTransferResponse>;
+    /**
+     * Get the current balance of your Yo! Payments Account.
+     * The returned object contains an array of balances (including airtime).
+     */
+    acAcctBalance(): Promise<AcctBalanceResponse>;
+    /**
+     * Return transactions carried out on your account for a certain period of time.
+     * @param startDate format YYYY-MM-DD HH:MM:SS
+     * @param endDate format YYYY-MM-DD HH:MM:SS
+     * @param transactionStatus e.g. "FAILED", "PENDING", "INDETERMINATE", "SUCCEEDED", "FAILED,SUCCEEDED"
+     * @param currencyCode e.g. "UGX-MTNMM", "UGX-WARIDMM", "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+     * @param resultSetLimit a value of 0 returns all; default gateway limit = 15
+     * @param transactionEntryDesignation "TRANSACTION", "CHARGES" or "ANY"
+     * @param externalReference filter using this external reference
+     */
+    acGetMinistatement(startDate?: string | null, endDate?: string | null, transactionStatus?: string | null, currencyCode?: string | null, resultSetLimit?: number | null, transactionEntryDesignation?: string, externalReference?: string | null): Promise<MinistatementResponse>;
+    /**
+     * Send airtime to a mobile phone user.
+     * @param msisdn the mobile phone number in the format 256772123456
+     * @param amount the amount of airtime to be sent to the mobile user
+     * @param narrative textual narrative about the transfer
+     */
+    acSendAirtimeMobile(msisdn: string, amount: number | string, narrative: string): Promise<SendAirtimeResponse>;
+    /**
+     * Send airtime from your Yo! Payments account to another Yo! Payments user account.
+     * @param currencyCode e.g. "UGX-MTNAT", "UGX-WTLAT", "UGX-OULAT", "UGX-AIRAT"
+     * @param amount the amount of airtime to be sent to the beneficiary Yo! Payments user
+     * @param beneficiaryAccount the beneficiary Yo! Payments account number
+     * @param beneficiaryEmail the beneficiary email address
+     * @param narrative textual narrative about the transfer
+     */
+    acSendAirtimeInternal(currencyCode: string, amount: number | string, beneficiaryAccount: number | string, beneficiaryEmail: string, narrative: string): Promise<SendAirtimeResponse>;
+    /**
+     * Withdraw funds from your Yo! Payments Account to a mobile money user.
+     * Handle with care: if compromised, it can lead to withdrawal of funds from your account.
+     * Requires permission granted by the issuance of an API Access Letter.
+     * @param msisdn the mobile money phone number in the format 256772123456
+     * @param amount the amount to withdraw from your account (fractions supported)
+     * @param narrative the reason for withdrawal of funds from your account
+     */
+    acWithdrawFunds(msisdn: string, amount: number | string, narrative: string): Promise<DepositFundsResponse>;
+    /**
+     * Purchase airtime using your Mobile Money Credit.
+     * @param airtimeCurrencyCode e.g. "UGX-MTNAT", "UGX-AIRAT", "UGX-OULAT", "UGX-UTLAT", "UGX-SMTAT"
+     * @param amount the amount to spend (fractions supported)
+     */
+    acUserPurchaseAirtimestock(airtimeCurrencyCode: string, amount: number | string): Promise<PurchaseAirtimeStockResponse>;
+    /**
+     * Obtain the name of a phone number before paying out funds.
+     * Only available for MTN Uganda and Airtel Uganda networks; requires permission
+     * from support@yo.co.ug.
+     * @param msisdn the phone number in the format 2567XXXXXXXXXX
+     */
+    acGetMsisdnKycInfo(msisdn: string): Promise<MsisdnKycInfoResponse>;
+    /**
+     * Decode and verify a successful payment notification (IPN) POSTed to your
+     * Instant Notification URL. Pass the parsed form body of the request.
+     */
+    receivePaymentNotification(body: PaymentNotificationBody): PaymentNotificationResult;
+    /**
+     * Decode and verify a failed payment notification POSTed to your
+     * Failure Notification URL. Pass the parsed form body of the request.
+     */
+    receivePaymentFailureNotification(body: PaymentFailureNotificationBody): PaymentFailureNotificationResult;
+    /**
+     * Calculate the Public Key Authentication Signature required by some payout requests.
+     * Sets publicKeyAuthenticationSignatureBase64 on success.
+     * @param msisdn the account the funds will be pushed to
+     * @param amount the transaction amount
+     * @param narrative the transaction narrative
+     */
+    generatePublicKeyAuthenticationSignature(msisdn: string, amount: number | string, narrative: string): void;
+    /** POST raw XML to the gateway and return the XML response body. */
+    protected getXmlResponse(xml: string): Promise<string>;
+    /** Verify the RSA-SHA256 signature on a payment notification against the Yo public certificate. */
+    protected verifyPaymentNotification(body: PaymentNotificationBody): boolean;
+    /** Verify the RSA-SHA256 signature on a payment failure notification against the Yo public certificate. */
+    protected verifyPaymentFailureNotification(body: PaymentFailureNotificationBody): boolean;
+    private verifySignature;
+    private authXml;
+    private requestXml;
+    /** POST the request XML to the gateway and return the parsed envelope that holds the <Response> node. */
+    private parseResponse;
+}
+
+export { type AcctBalanceResponse, type BalanceEntry, type DepositFundsResponse, type DepositTransactionType, type InternalTransferResponse, type MinistatementResponse, type MsisdnKycInfoResponse, type NonBlocking, type PaymentFailureNotificationBody, type PaymentFailureNotificationResult, type PaymentNotificationBody, type PaymentNotificationResult, type PurchaseAirtimeStockResponse, type SendAirtimeResponse, type TransactionCheckStatusResponse, type TransactionDetail, YoAPI, YoAPIError, type YoMode, YoAPI as default };