@gray-adeyi/korapay-sdk
Version:
A korapay client SDK for the javascript runtime.
317 lines (312 loc) ā¢ 13.3 kB
JavaScript
import * as dntShim from "../_dnt.shims.js";
import { HTTPMethod } from "./enums.js";
import RestClient from "./restClient.js";
const SECRET_KEY_PREFIX = "sk_test_";
const PACKAGE_DEV_MODE_MESSAGE = `
šŖš½ "Korapay Integration powered by @gray-adeyi/korapay-sdk 0.2.1"š„
Need more guide on how to use this package?
See api reference at https://jsr.io/@gray-adeyi/korapay-sdk/doc/~/KorapayClient
Found a bug?
Create an issue for it at https://github.com/gray-adeyi/korapay-sdk/issues
If this project is useful to you or your company, please consider sponsoring the project by
- š§š»āš¤āš§ Sharing it with your developer friends
- āØ Starring it on github at https://github.com/gray-adeyi/korapay-sdk
- š» Contribute to it at https://github.com/gray-adeyi/korapay-sdk
- ā Buy me a coffee at https://buymeacoffee.com/jigani
Note: This message only appears in dev mode.
Set "disablePackageDevModeMessage" flag to true on instantiation
of KorapayClient to stop seeing this message.
`;
/**
* A class for interfacing with Korapay API in your JS/TS project.
*/
export default class KorapayClient {
/**
* @constructor Instantiate a KorapayClient.
*
* @remarks When no params are passed in, the client will attempt to load the
* publicKey, secretKey, and encryptionKey via their respective default
* environmental variable name. 'KORAPAY_PUBLIC_KEY','KORAPAY_SECRET_KEY'
* and 'KORAPAY_ENCRYPTION_KEY', If a client is passed in, the publicKey,
* and secretKey are ignored
*
* @param publicKey - Your korapay integration public key. Omit if
* 'KORAPAY_PUBLIC_KEY' is set in your environmental variables.
* @param secretKey - Your korapay integration secret key. Omit if
* 'KORAPAY_SECRET_KEY' is set in your environmental variables.
* @param encryptionKey - Your korapay integration key. Omit if
* 'KORAPAY_ENCRYPTION_KEY' is set in your environmental variables.
* @param client - A custom {@link RestClient} to use for making request to korapay.
*/
constructor(publicKey, secretKey, encryptionKey, client, disablePackageDevModeMessage = false) {
Object.defineProperty(this, "client", {
enumerable: true,
configurable: true,
writable: true,
value: void 0
});
if (client) {
this.client = client;
}
else {
this.client = new RestClient(publicKey, secretKey, encryptionKey);
}
this.showPackageMessage(disablePackageDevModeMessage, secretKey);
}
/**
* Accept debit card payments.
*
* @remarks No validation is done on the payload in the client, it is sent
* as it is.
*
* @param payload - {@link ChargeViaCardPayload} is the data that is sent to korapay.
*
* @returns A promise containing a {@link KorapayResponse}
*/
async chargeViaCard(payload) {
const chargeData = await this.client.encryptData(payload);
return await this.client.call("/merchant/api/v1/charges/card", HTTPMethod.POST, { chargeData });
}
/**
* Authorize a pending charge on a debit card.
*
* @param payload {@link AuthorizeCardChargePayload} is the data sent to korapay
* to authorize a charge
* @returns A promise containing a {@link KorapayResponse}
*/
authorizeCardCharge(payload) {
return this.client.call("/merchant/api/v1/charges/card/authorize", HTTPMethod.POST, payload);
}
/**
* Resend one time password/pin for pending transaction.
*
* @param transactionReference The reference to the pending charge
* returned as a response by korapay when the charge was initiated.
* @returns A promise containing a {@link KorapayResponse}
*/
resendCardOtp(transactionReference) {
return this.client.call("/merchant/api/v1/charges/card/resend-otp", HTTPMethod.POST, { transactionReference });
}
/**
* Accept payments via bank transfers.
*
* @param payload {@link ChargeViaBankTransferPayload} is the data sent to korapay
* to initiate a charge via bank transfer
* @returns A promise containing a {@link KorapayResponse}
*/
chargeViaBankTransfer(payload) {
return this.client.call("/merchant/api/v1/charges/bank-transfer", HTTPMethod.POST, payload);
}
/**
* Create a virtual bank account.
*
* @param payload {@link CreateVirtualBankAccountPayload} is the data sent to korapay to
* create a virtual bank account.
* @returns A promise containing a {@link KorapayResponse}
*/
createVirtualBankAccount(payload) {
return this.client.call("/merchant/api/v1/virtual-bank-account", HTTPMethod.POST, payload);
}
/**
* Retrieve a virtual bank account.
*
* @param accountReference Your unique reference for the virtual bank account.
* @returns A promise containing a {@link KorapayResponse}
*/
getVirtualBankAccount(accountReference) {
return this.client.call(`/merchant/api/v1/virtual-bank-account/${accountReference}`, HTTPMethod.GET);
}
/**
* Retrieve transactions associated with a virtual bank account.
*
* @param accountNumber The account number of the virtual account.
* @returns A promise containing a {@link KorapayResponse}
*/
getVirtualBankAccountTransactions(accountNumber) {
return this.client.call(`/merchant/api/v1/virtual-bank-account/transactions?account_number=${accountNumber}`, HTTPMethod.GET);
}
/**
* Create a virtual bank account for testing/development.
*
* @param accountNumber This is the account number of the Fixed Virtual Bank Account.
* @param amount This is the amount you want to credit to the account. The minimum
* amount is NGN 100, and the maximum amount is NGN 10,000,000.
* @param currency An enum representing the currency for the account. Only `Currency.NGN` is accepted
* for now.
* @returns A promise containing a {@link KorapayResponse}
*/
creditSandboxVirtualBankAccount(accountNumber, amount, currency) {
return this.client.call("/merchant/api/v1/virtual-bank-account/sandbox/credit", HTTPMethod.POST, { accountNumber, amount, currency });
}
/**
* Accept payments via mobile money.
*
* @param payload {@link ChargeViaMobileMoneyPayload} is the data sent to korapay to
* initiate a charge via mobile money
* @returns A promise containing a {@link KorapayResponse}
*/
chargeViaMobileMoney(payload) {
return this.client.call("/merchant/api/v1/charges/mobile-money", HTTPMethod.POST, payload);
}
/**
* Authorize a payment via mobile money
*
* @param reference The reference to the transaction.
* @param token the otp or token from the customer.
* @returns A promise containing a {@link KorapayResponse}
*/
authorizeMobileMoneyCharge(reference, token) {
return this.client.call("/merchant/api/v1/charges/mobile-money/authorize", HTTPMethod.POST, { reference, token });
}
/**
* Resend one time password/pin for a pending mobile money transaction.
*
* @param transactionReference The reference of the pending transaction.
* @returns A promise containing a {@link KorapayResponse}
*/
resendMobileMoneyOtp(transactionReference) {
return this.client.call("/merchant/api/v1/charges/mobile-money/resend-otp", HTTPMethod.POST, { transactionReference });
}
/**
* Resend SKT prompt.
*
* @param transactionReference The reference of the pending transaction.
* @returns A promise containing a {@link KorapayResponse}
*/
resendSkt(transactionReference) {
return this.client.call("/merchant/api/v1/charges/mobile-money/resend-stk", HTTPMethod.POST, { transactionReference });
}
/**
* Authorize SKT prompts in testing/development
*
* @param reference The reference of the pending transaction.
* @param pin The simulated customer's pin
* @returns A promise containing a {@link KorapayResponse}
*/
authorizeSkt(reference, pin) {
return this.client.call("/merchant/api/v1/charges/mobile-money/sandbox/authorize-stk", HTTPMethod.POST, { reference, pin });
}
/**
* Initiate a charge on your customer supporting multiple payment channels
*
* @param payload {@link InitiateChargePayload} is the data sent to korapay to
* initiate a charge.
* @returns A promise containing a {@link KorapayResponse}
*/
initiateCharge(payload) {
return this.client.call("/merchant/api/v1/charges/initialize", HTTPMethod.POST, payload);
}
/**
* Retrieve a charge.
*
* @param reference The reference of the charge.
* @returns A promise containing a {@link KorapayResponse}
*/
getCharge(reference) {
return this.client.call(`/merchant/api/v1/charges/${reference}`, HTTPMethod.GET);
}
/**
* Resolves a bank account.
*
* @param bankCode The code for the bank the account number belongs to.
* @param accountNumber The account number to be resolved.
* @returns A promise containing a {@link KorapayResponse}
*/
resolveBankAccount(bankCode, accountNumber) {
return this.client.call("/merchant/api/v1/misc/banks/resolve", HTTPMethod.POST, { bank: bankCode, account: accountNumber });
}
/**
* Retrieve all your pending and available balances
*
* @returns A promise containing a {@link KorapayResponse}
*/
getBalances() {
return this.client.call("/merchant/api/v1/balances", HTTPMethod.GET);
}
/**
* Retrieve a list of all banks supported by Korapay and their properties.
*
* @param country An enum representing the country to retrieve the banks from.
* E.g., `Country.NIGERIA`.
* @returns A promise containing a {@link KorapayResponse}
*/
getBanks(country) {
return this.client.call(`/merchant/api/v1/misc/banks?countryCode=${country}`, HTTPMethod.GET, undefined, true);
}
/**
* Retrieve a list of all mobile money operators supported by Korapay and their properties.
*
* @param country An enum representing the country to retrieve the MMOs from. E.g., `Country.GHANA`.
* @returns A promise containing a {@link KorapayResponse}
*/
getMmo(country) {
return this.client.call(`/merchant/api/v1/misc/mobile-money?countryCode=${country}`, HTTPMethod.GET);
}
/**
* Initiate a single disbursement to a bank account.
*
* @param payload {@link PayoutToBankAccountPayload} is the data sent to korapay to
* initiate a payout to bank account
* @returns A promise containing a {@link KorapayResponse}
*/
payoutToBankAccount(payload) {
return this.client.call("/merchant/api/v1/transactions/disburse", HTTPMethod.POST, payload);
}
/**
* Initiate a single disbursement to a mobile money account.
*
* @param payload {@link PayoutToMobileMoneyPayload} is the data sent to korapay
* to initiate a payout to mobile money
* @returns A promise containing a {@link KorapayResponse}
*/
payoutToMobileMoney(payload) {
return this.client.call("/merchant/api/v1/transactions/disburse", HTTPMethod.POST, payload);
}
/**
* Initiate a bulk payout to bank accounts.
*
* @param payload {@link BulkPayoutToBankAccountPayload} is the data sent to korapay
* to initiate a bulk payout to bank accounts
* @returns A promise containing a {@link KorapayResponse}
*/
bulkPayoutToBankAccount(payload) {
return this.client.call("/api/v1/transactions/disburse/bulk", HTTPMethod.POST, payload);
}
/**
* Retrieve a bulk payout
*
* @param bulkReference - The reference of the bulk payout to retrieve.
* @returns A promise containing a {@link KorapayResponse}
*/
getPayouts(bulkReference) {
return this.client.call(`/api/v1/transactions/bulk/${bulkReference}/payout`, HTTPMethod.GET);
}
/**
* Retrieve the transactions in a bulk payout.
*
* @param bulkReference - The reference of the bulk payout whose transactions you to retrieve.
* @returns A promise containing a {@link KorapayResponse}
*/
getBulkTransaction(bulkReference) {
return this.client.call(`/api/v1/transactions/bulk/${bulkReference}`, HTTPMethod.GET);
}
/**
* Retrieve the status and details of a disbursement through the reference.
*
* @param transactionReference - The transaction reference of the payout.
* @returns
*/
getPayoutTransaction(transactionReference) {
return this.client.call(`/merchant/api/v1/transactions/${transactionReference}`, HTTPMethod.GET);
}
showPackageMessage(disablePackageMessage, secretKey) {
if (!this.isUsingTestSecretKey(secretKey) || disablePackageMessage)
return;
console.log(PACKAGE_DEV_MODE_MESSAGE);
}
isUsingTestSecretKey(secretKey) {
if (secretKey)
return secretKey.startsWith(SECRET_KEY_PREFIX);
return dntShim.Deno.env.get(RestClient.ENV_SECRET_KEY_NAME)?.startsWith(SECRET_KEY_PREFIX) || false;
}
}