modem-pay
Version:
A TypeScript SDK for integrating with the Modem Pay payment gateway, enabling seamless payment processing and financial services in your applications.
1,143 lines (1,142 loc) • 29.1 kB
TypeScript
/**
* Configuration options for Pointer API interaction.
*/
export type ModemPayConfig = {
/**
* Maximum number of retry attempts for API requests in case of failure.
* If not specified, a default value may be used.
*/
maxRetries?: number;
/**
* Request timeout in seconds. Defaults to 60 seconds (1 minute).
*/
timeout?: number;
};
/**
* Parameters used to define or update a customer.
*/
export type CustomerParams = {
/**
* Customer's name.
*/
name?: string;
/**
* Customer's email address.
*/
email?: string;
/**
* Customer's phone number.
*/
phone?: string;
/**
* Initial balance assigned to the customer.
*/
balance?: number;
};
/**
* Options for creating a customer.
*/
export type CustomerCreateOption = {
/**
* Determines whether the customer should be created uniquely.
* If true, ensures no duplicate customers are created based on unique constraints.
*/
distinct: boolean;
};
/**
* Options for listing resources, such as customers or transactions.
*/
export type ListOption = {
/**
* Maximum number of items to retrieve in a single request.
*/
limit?: number;
};
/**
* Options for listing transactions.
*/
export type TransactionListOption = {
/**
* Maximum number of transactions to retrieve in a single request.
*/
limit?: number;
/**
* Search term for filtering transactions.
* Can be used to filter by currency, reference, payment method, or customer.
*/
search?: string;
/**
* Duration in minutes to filter transactions within a specific timeframe.
*/
timeframe?: number;
};
/**
* Options for listing customers.
*/
export type CustomerListOption = {
/**
* Maximum number of customers to retrieve in a single request.
*/
limit?: number;
/**
* Search term for filtering customers.
* Can be used to filter by name, email, or other customer attributes.
*/
search?: string;
};
/**
* Representation of a customer.
*/
export type Customer = {
/**
* Unique identifier for the customer.
*/
id: string;
/**
* Customer's name.
*/
name: string;
/**
* Customer's email address.
*/
email: string;
/**
* Customer's phone number. Optional field.
*/
phone?: string;
/**
* Current balance associated with the customer. Optional field.
*/
balance?: number;
};
/**
* Parameters for creating a payment session.
*/
export type SessionParams = {
/**
* Title of the session, typically used to describe the payment purpose.
*/
title?: string;
/**
* Detailed description of the session.
*/
description?: string;
/**
* Amount to be charged during the session.
*/
amount?: number;
/**
* Minimum amount to be charged through the payment link.
*/
min_amount?: number;
/**
* Currency in which the payment will be made, e.g., "XOF", "GMD".
*/
currency?: string;
/**
* URL to redirect the customer to after a successful payment.
*/
redirect_url?: string;
/**
* URL to redirect the customer to if they cancel the payment.
*/
cancel_url?: string;
/**
* Custom fields for capturing additional information during the session.
*/
custom_fields?: string[];
/**
* Duration in seconds for which the session will remain active before expiring.
*/
expires_in?: number;
/**
* Unique identifier of the customer associated with the session.
*/
customer?: string;
/**
* Metadata to attach additional information to the session, represented as key-value pairs.
*/
metadata?: object;
/**
* Email address of the customer.
*/
customer_email?: string;
/**
* Phone number of the customer.
*/
customer_phone?: string;
/**
* Name of the customer.
*/
customer_name?: string;
};
/**
* Representation of a payment session.
*/
export interface Session extends SessionParams {
/**
* Indicates whether the session has expired.
*/
expired: boolean;
/**
* Unique identifier for the session.
*/
id: string;
/**
* Link to the payment page for the session.
*/
payment_link: string;
/**
* Unique code associated with the session for identification or verification.
*/
unique_code: string;
/**
* Type of session, either for a single charge or subscriptions.
*/
type: "single-charge" | "subscriptions";
}
/**
* Parameters for creating a payment link.
*/
export type PaymentLinkParams = {
/**
* Title of the payment link, typically used to describe the purpose of the payment.
*/
title: string;
/**
* Description of the payment link, providing further details about the payment.
*/
description: string;
/**
* Amount to be charged through the payment link.
*/
amount?: number;
/**
* Minimum amount to be charged through the payment link.
*/
min_amount?: number;
/**
* Currency in which the payment will be processed (e.g., "GMD", "XOF").
*/
currency?: string;
/**
* URL to redirect the customer to after a successful payment.
*/
redirect_url?: string;
/**
* URL to redirect the customer to if they cancel the payment.
*/
cancel_url?: string;
/**
* Custom fields for collecting additional information during the payment process.
*/
custom_fields?: string[];
/**
* Custom metadata associated with the payment link.
*/
metadata?: object;
};
/**
* Parameters for updating an existing payment link.
*/
export type PaymentLinkUpdateParams = {
/**
* Status of the payment link, either "active" or "inactive".
*/
status?: "active" | "inactive";
/**
* Title of the payment link, typically used to describe the purpose of the payment.
*/
title?: string;
/**
* Description of the payment link, providing further details about the payment.
*/
description?: string;
/**
* Amount to be charged through the payment link.
*/
amount?: number;
/**
* Minimum amount to be charged through the payment link.
*/
min_amount?: number;
/**
* Currency in which the payment will be processed (e.g., "XOF", "GMD").
*/
currency?: string;
/**
* URL to redirect the customer to after a successful payment.
*/
redirect_url?: string;
/**
* URL to redirect the customer to if they cancel the payment.
*/
cancel_url?: string;
/**
* Custom fields for collecting additional information during the payment process.
*/
custom_fields?: string[];
/**
* Custom metadata associated with the payment link.
*/
metadata?: object;
};
/**
* Representation of a payment link.
*/
export interface PaymentLink extends PaymentLinkParams {
/**
* Unique identifier for the payment link.
*/
id: string;
/**
* URL for the payment link.
*/
payment_link: string;
/**
* Unique code associated with the payment link for identification or tracking.
*/
unique_code: string;
/**
* Current status of the payment link, either "active" or "inactive".
*/
status: "active" | "inactive";
/**
* Type of payment link, can be "single-charge", "subscriptions", or "donations".
*/
type: "single-charge" | "subscriptions" | "donations";
}
export type PaymentMethodType = "card" | "bank" | "wallet";
/**
* Parameters for creating a payment intent.
*/
export type PaymentIntentParams = {
/**
* The amount to be charged for the payment intent.
*/
amount: number;
/**
* The currency in which the payment will be processed (e.g., "XOF", "GMD").
*/
currency?: string;
/**
* An array of payment method types to be used for processing the payment (e.g., "card", "bank", "wallet").
*/
payment_methods?: PaymentMethodType[];
/**
* Title or name of the payment intent. It provides a label or description for the payment.
*/
title?: string;
/**
* Detailed description of the payment intent.
*/
description?: string;
/**
* The customer associated with the payment intent. Can be a customer ID.
*/
customer?: string;
/**
* The name of the customer associated with the payment intent.
*/
customer_name?: string;
/**
* The email address of the customer associated with the payment intent.
*/
customer_email?: string;
/**
* The phone number of the customer associated with the payment intent.
*/
customer_phone?: string;
/**
* Custom metadata associated with the payment intent.
*/
metadata?: object;
/**
* URL to redirect the customer after successful payment.
*/
return_url?: string;
/**
* URL to redirect the customer if the payment is cancelled.
*/
cancel_url?: string;
/**
* The payment method ID selected for processing the payment.
*/
payment_method?: string;
/**
* The ID of the coupon code to be applied to the payment intent for discounts or special offers.
*/
coupon?: string;
/**
* The URL to which Modem Pay will send a callback or webhook notification after payment processing.
*/
callback_url?: string;
};
/**
* Representation of a payment intent.
*/
export interface PaymentIntent extends PaymentIntentParams {
/**
* Unique identifier for the payment intent.
*/
id: string;
/**
* The available payment gateway options for the payment method.
*/
payment_method_options: PaymentGateway[];
/**
* Customer associated with the payment intent.
*/
Customer?: Customer;
/**
* Secret key used to authenticate the payment intent.
*/
intent_secret: string;
/**
* The current status of the payment intent. Possible values include:
* "initialized", "processing", "requires_payment_method", "successful", "failed", and "cancelled".
*/
status: "initialized" | "processing" | "requires_payment_method" | "successful" | "failed" | "cancelled";
/**
* URL link to the payment intent, typically used for redirecting the customer.
*/
link: string;
/**
* Custom values associated with the fields of the payment intent.
*/
custom_fields_values: object;
/**
* Indicates if the payment intent is part of a session.
*/
is_session: boolean;
}
/**
* Represents the structure of the response returned after creating a payment intent.
*/
export type PaymentIntentResponse = {
/**
* Indicates whether the payment intent creation was successful.
* `true` means success, `false` would indicate an error or failure.
*/
status: boolean;
/**
* A message providing additional details about the result of the payment intent creation.
*/
message: string;
/**
* The data associated with the created payment intent.
*/
data: {
/**
* Unique identifier for the payment intent.
*/
id: string;
/**
* The secret key for the payment intent used to complete the payment. (Not your API secret key)
*/
intent_secret: string;
/**
* The payment link that allows the customer to complete the payment.
*/
payment_link: string;
/**
* The amount involved in the payment intent (in the smallest unit of the currency).
*/
amount: number;
/**
* The currency used for the payment intent (e.g., "GMD", "XOF").
*/
currency: string;
/**
* The expiration time for the payment intent. The user must complete the payment before this time.
*/
expires_at: string;
/**
* The current status of the payment intent (e.g., "initialized", "processing", etc.).
*/
status: string;
};
};
export type ChargeParams = {
gateway?: string;
payment_account?: string;
customer?: IntentCustomerParams;
amount?: number;
};
export type Salt = {
/** Returns an encrypted hash */
salt: string;
};
/**
* Parameters for customer-related information used in payment intents.
*/
type IntentCustomerParams = {
/**
* The phone number of the customer associated with the payment intent.
*/
customer_phone?: string;
/**
* The email address of the customer associated with the payment intent.
*/
customer_email?: string;
/**
* The name of the customer associated with the payment intent.
*/
customer_name?: string;
};
/**
* Represents a payment gateway that can be used in a payment transaction.
*/
type PaymentGateway = {
/**
* A unique tag identifying the payment gateway.
*/
tag: string;
/**
* The group to which this payment gateway belongs (e.g., "bank", "wallet", etc.).
*/
group: string;
/**
* The logo of the payment gateway, typically in URL form.
*/
logo: string;
/**
* Unique identifier for the payment gateway.
*/
id: string;
};
/**
* A generic interface for a paginated list of items of type T.
*/
export interface List<T> {
/**
* The list of data items.
*/
data: T[];
/**
* Metadata about the list, including the total number of items.
*/
meta: {
/**
* Total number of items in the list.
*/
total: number;
};
}
/**
* Parameters for creating a payment method, including mobile payment details.
*/
export type PaymentMethodParams = {
/**
* Details for a mobile payment method.
*/
mobilepay: {
/**
* The details of the mobile wallet used for mobile payments.
*/
details: MobileWallet;
/**
* The type of payment method (defaults to "mobilepay").
*/
type?: "mobilepay";
};
/**
* The customer associated with the payment method.
*/
customer?: string;
};
/**
* Represents the details of a mobile wallet used for mobile payments.
*/
export type MobileWallet = {
/**
* The payment account associated with the mobile wallet.
*/
payment_account: string;
/**
* The payment gateway for the mobile wallet (e.g., "afrimoney", "orange").
*/
gateway: string;
/**
* The group that the mobile wallet belongs to (e.g., "bank", "wallet", "card").
*/
group: string;
};
/**
* Represents a payment method, which could include mobile wallet details.
*/
export type PaymentMethod = {
/**
* Unique identifier for the payment method.
*/
id: string;
/**
* Mobile payment details if the payment method is a mobile wallet.
*/
mobilepay?: {
/**
* Type of the mobile payment (always "mobilepay").
*/
type: "mobilepay";
/**
* The group for the mobile wallet.
*/
group: string;
/**
* The last 4 digits of the payment method.
*/
last4: string;
/**
* The gateway provider for the mobile payment.
*/
gateway: string;
/**
* The fingerprint identifier for the mobile payment method.
*/
fingerprint: string;
};
/**
* The customer associated with the payment method.
*/
customer?: string;
/**
* Type of the payment method (e.g., "card", "mobilepay").
*/
type: string;
/**
* Indicates whether the payment method has been detached.
*/
has_been_detached: boolean;
};
/**
* Represents a transaction in the payment system.
*/
export interface Transaction {
/**
* Unique identifier for the transaction.
*/
id: string;
/**
* The ID of the payment intent associated with the transaction.
*/
payment_intent_id: string;
/**
* The amount of money involved in the transaction.
*/
amount: number;
/**
* The currency used for the transaction (e.g., "GMD").
*/
currency: string;
/**
* The current status of the transaction.
* Possible values include: "pending", "completed", "failed", "refunded", or "cancelled".
*/
status: "pending" | "completed" | "failed" | "refunded" | "cancelled";
/**
* The type of transaction (e.g., "payment", "subscription", "invoice").
*/
type: "payment" | "subscription" | "invoice";
/**
* The transaction reference, typically unique to the transaction.
*/
transaction_reference: string;
/**
* The payment account used in the transaction.
*/
payment_account: string;
/**
* The payment method used for the transaction.
*/
payment_method: string;
/**
* The name of the customer associated with the transaction.
*/
customer_name: string;
/**
* The phone number of the customer associated with the transaction.
*/
customer_phone: string;
/**
* The email address of the customer associated with the transaction.
*/
customer_email: string;
/**
* The account ID related to the transaction.
*/
account_id: string;
/**
* The business ID related to the transaction.
*/
business_id: string;
/**
* The creation date of the transaction.
*/
createdAt: string;
/**
* The last update date of the transaction.
*/
updatedAt: string;
/**
* Custom values associated with the transaction fields.
*/
custom_fields_values: Object;
/**
* Metadata associated with the transaction.
*/
metadata: Object;
/**
* The payment gateway used for processing the transaction.
*/
PaymentGateway: PaymentGateway;
/**
* The customer associated with the transaction.
*/
Customer?: Customer;
}
/**
* Represents a mandate for a payment method, typically used for recurring payments.
*/
export type Mandate = {
/**
* Unique identifier for the mandate.
*/
id: string;
/**
* The customer acceptance details of the mandate.
*/
customer_acceptance: object;
/**
* The payment method used for the mandate.
*/
payment_method: string;
/**
* The details of the payment method used for the mandate.
*/
payment_method_details: object;
/**
* The current status of the mandate.
* Possible values: "active", "inactive", "pending".
*/
status: "active" | "inactive" | "pending";
/**
* The type of mandate (e.g., "one-time", "recurring").
*/
type: "one-time" | "recurring";
/**
* The business ID associated with the mandate.
*/
business_id: string;
/**
* The account ID associated with the mandate.
*/
account_id: string;
/**
* Indicates if the mandate is in test mode.
*/
test_mode: boolean;
};
/**
* Represents an event in the payment system, triggered by specific actions or state changes.
*/
export type Event = {
/**
* The type of event (e.g., "customer.created", "payment_intent.created").
*/
event: EventType;
/**
* The payload data associated with the event.
*/
payload: Object;
};
/**
* Enumeration of the possible event types in the system.
*/
type EventType = "customer.created" | "customer.updated" | "customer.deleted" | "payment_intent.created" | "payment_intent.cancelled" | "charge.cancelled" | "charge.succeeded" | "charge.created" | "charge.updated" | "charge.failed" | "transfer.failed" | "transfer.succeeded" | "transfer.reversed";
/**
* Parameters for creating a coupon.
*/
export type CouponParams = {
/**
* Amount to be discounted from the total.
*/
amount_off?: number;
/**
* Currency in which the discount is applied.
*/
currency?: string;
/**
* Duration of the coupon's validity.
*/
duration: "forever" | "once" | "repeating";
/**
* Number of months the coupon is valid for if the duration is "repeating".
*/
duration_in_months?: number;
/**
* Metadata associated with the coupon.
*/
metadata?: object;
/**
* Name of the coupon.
*/
name: string;
/**
* Percentage discount to be applied.
*/
percent_off?: number;
/**
* Maximum number of times the coupon can be redeemed.
*/
max_redemptions?: number;
/**
* The ID of the product associated with the coupon.
*/
product_id?: string;
/**
* The ID of the storefront where the coupon can be redeemed.
*/
store_id?: string;
/**
* Date by which the coupon must be redeemed.
*/
redeem_by?: Date;
/**
* Restrictions associated with the promotion code.
*/
restrictions?: {
/**
* Indicates if the coupon is restricted to first-time transactions.
*/
first_time_transaction: boolean;
/**
* Minimum amount required to use the coupon.
*/
minimum_amount: number | null;
/**
* Currency of the minimum amount required to use the coupon.
*/
minimum_amount_currency: string | null;
};
};
/**
* Parameters for creating a coupon.
*/
export type UpdateParams = {
duration_in_months?: number;
/**
* Metadata associated with the coupon.
*/
metadata?: object;
/**
* Name of the coupon.
*/
name?: string;
/**
* Percentage discount to be applied.
*/
percent_off?: number;
/**
* Maximum number of times the coupon can be redeemed.
*/
max_redemptions?: number;
/**
* Date by which the coupon must be redeemed.
*/
redeem_by?: Date;
/**
* Restrictions associated with the promotion code.
*/
restrictions?: {
/**
* Indicates if the coupon is restricted to first-time transactions.
*/
first_time_transaction: boolean;
/**
* Minimum amount required to use the coupon.
*/
minimum_amount: number | null;
/**
* Currency of the minimum amount required to use the coupon.
*/
minimum_amount_currency: string | null;
};
};
/**
* Representation of a coupon.
*/
export type Coupon = CouponParams & {
/**
* Unique identifier for the coupon.
*/
id: string;
/**
* Number of times the coupon has been redeemed.
*/
times_redeemed: number;
/**
* Indicates if the coupon is currently valid.
*/
valid: boolean;
};
/**
* Options for listing coupons.
*/
export type CouponListOption = {
/**
* Maximum number of coupons to retrieve in a single request.
*/
limit?: number;
/**
* Search term for filtering coupons.
*/
search?: string;
};
/**
* Parameters for creating or updating a promotion code.
*/
export type PromotionCodeParams = {
/**
* The code for the promotion.
*/
code?: string;
/**
* The ID of the associated coupon.
*/
coupon_id: string;
/**
* Metadata associated with the promotion code.
*/
metadata?: object;
/**
* Indicates if the promotion code is active.
*/
active?: boolean;
/**
* The ID of the customer associated with the promotion code.
*/
customer_id?: string;
/**
* Maximum number of times the promotion code can be redeemed.
*/
max_redemptions?: number;
/**
* Expiration date of the promotion code.
*/
expires_at?: Date;
/**
* Restrictions associated with the promotion code.
*/
restrictions?: {
/**
* Indicates if the promotion code is restricted to first-time transactions.
*/
first_time_transaction: boolean;
/**
* Minimum amount required to use the promotion code.
*/
minimum_amount: number | null;
/**
* Currency of the minimum amount required to use the promotion code.
*/
minimum_amount_currency: string | null;
};
};
/**
* Representation of a promotion code.
*/
export type PromotionCode = PromotionCodeParams & {
/**
* Unique identifier for the promotion code.
*/
id: string;
/**
* The ID of the account associated with the promotion code.
*/
account_id: string;
/**
* The ID of the business associated with the promotion code.
*/
business_id: string;
};
/**
* Options for listing promotion codes.
*/
export type PromotionCodeListOption = {
/**
* Maximum number of promotion codes to retrieve in a single request.
*/
limit?: number;
/**
* Search term for filtering promotion codes.
*/
search?: string;
};
export type TransferParams = {
/**
* The amount to be transferred.
*/
amount: number;
/**
* The currency code for the transfer (e.g., "GMD", "USD").
*/
currency: string;
/**
* Optional description or note for the transfer.
*/
narration?: string;
/**
* The payment network to use for the transfer (e.g., "afrimoney", "wave").
*/
network: string;
/**
* Name of the beneficiary receiving the transfer.
*/
beneficiary_name: string;
/**
* Optional additional metadata associated with the transfer.
*/
metadata?: object;
/**
* The account number of the beneficiary.
*/
account_number: string;
/**
* The URL to which Modem Pay will send a callback or webhook notification after payout processing.
*/
callback_url?: string;
};
/**
* Representation of a transfer transaction.
*/
export type Transfer = {
/**
* Unique identifier for the transfer.
*/
id: string;
/**
* ID of the business initiating the transfer.
*/
business_id: string;
/**
* ID of the account from which the transfer is made.
*/
account_id: string;
/**
* ID of the merchant associated with the transfer.
*/
merchant_id?: string;
/**
* ID of the recipient business, if applicable.
*/
recipient_business_id?: string;
/**
* Amount to be transferred.
*/
amount: number;
/**
* Fee charged for the transfer.
*/
fee: number;
/**
* Currency code for the transfer (e.g., "GMD", "USD").
*/
currency: string;
/**
* Type of transfer (self, modem-pay, mobile-money, or bank).
*/
type: "self" | "modem-pay" | "mobile-money" | "bank";
/**
* Current status of the transfer.
*/
status: "pending" | "completed" | "failed" | "cancelled";
/**
* Account balance before the transfer.
*/
balance_before: number;
/**
* Account balance after the transfer.
*/
balance_after: number;
/**
* Name of the account holder.
*/
account_name?: string;
/**
* Payment network used for the transfer.
*/
network?: string;
/**
* Bank name for bank transfers.
*/
bank?: string;
/**
* Amount received by the beneficiary.
*/
amount_received?: number;
/**
* Mobile number for mobile money transfers.
*/
mobile_number?: string;
/**
* Account number for bank transfers.
*/
account_number?: string;
/**
* Unique reference number for the transfer.
*/
transfer_reference: string;
/**
* Indicates if the transfer is in test mode.
*/
test_mode: boolean;
/**
* Record of events related to the transfer.
*/
events: object;
/**
* Additional notes about the transfer.
*/
note?: string;
/**
* One-time password for transfer verification.
*/
otp?: string;
/**
* Additional metadata associated with the transfer.
*/
metadata: object;
};
export type TransferFeeCheckParams = {
/**
* The amount to be transferred.
*/
amount: number;
/**
* The currency code for the transfer amount (e.g., "GMD", "USD").
*/
currency: string;
/**
* The payment network to be used for the transfer (e.g., "afrimoney", "wave").
*/
network: string;
};
export type TransferFeeCheckResponse = {
/**
* The fee amount charged for the transfer.
*/
fee: number;
/**
* The currency code for the fee amount (e.g., "GMD", "USD").
*/
currency: string;
/**
* The payment network used for the transfer (e.g., "afrimoney", "wave").
*/
network: string;
/**
* The total amount to be transferred including fees.
*/
amount: number;
};
export {};