modem-pay
Version:
A TypeScript SDK for integrating with the Modem Pay payment gateway, enabling seamless payment processing and financial services in your applications.
542 lines (541 loc) • 13.8 kB
TypeScript
import { Customer } from "./customers";
/**
* 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;
};
/**
* Representation of your balance.
*/
export type Balance = {
/**
* The amount that has been processed and is waiting to be settled or moved to payout balance.
*/
available_balance: number;
/**
* The amount of funds available for payout or withdrawal.
*/
payout_balance: number;
};
/**
* Options for listing resources, such as customers or transactions.
*/
export type ListOption = {
/**
* Maximum number of items to retrieve in a single request.
*/
limit?: number;
/**
* Search term for filtering records.
*/
search?: string;
/**
* Where to start the data load
*/
offset?: 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;
};
/**
* 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";
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.
*/
export 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;
};
export {};