Merchant API client
Merchant API client is a library to interact with Merchant API.
Usage
To make client work:
-
Create Provider that will handle all HTTP job.
const provider = new HttpProvider({ apiKey: 'EXAMPLE-API-KEY', url: 'https://merchant-app-api2.tonb.io/', merchantId: 11, });
The provider may accept one of the options:
- API key + Base URL + Merchant ID
- Axios Client with the data inside.
-
Pass the Provider to the InvoiceManager
const manager = new InvoiceManager(provider);
InvoiceManager manages all work with invoices and is a part of a Merchant API client.
-
Create client
const client = new MerchantAPIClient(manager);
The invoice management may be performed through client.invoiceManager.
const stats = await client.invoiceManager.stats();
InvoiceManager
InvoiceManager implements 4 methods to interact with BackEnd and 1 to handle webhooks:
// Creates new Invoice
create(data: CreateInvoiceData): Promise<DataContainer<Invoice>>
// Cancels existing Invoice
cancel(invoiceId: InvoiceID): Promise<DataContainer<Invoice>>
// Retrieves Invoice information
info(invoiceId: InvoiceID): Promise<DataContainer<Invoice>>
// Retrieves merchant statistics
stats(): Promise<DataContainer<InvoiceStats>>
// Process WebHook data
processUpdate(update: InvoiceUpdate): DataContainer<Omit<Invoice, 'id'>>
The InvoiceManager returns all entities inside the container DataContainer<R>.
type DataContainer<R> = {
data: R | null;
isValid: boolean;
error?: unknown;
};
Before accessing the data, you should check whether the data is valid:
if (stats.isValid) {...}
Thereby, library does not throw errors. In case of errors, ex.during HTTP interactions, the library handles all errors, sets the isValid flag to false. Additionally, it may include Error inside DataContainer in the error field.
The Invoice contains the following data:
type Invoice = {
domain?: string;
id: InvoiceID;
code?: string;
webhook?: string;
amount: bigint;
order_id?: bigint;
status?: InvoiceEnumStatus;
transaction?: unknown; // any json object
createdAt?: number; // UTC time
updatedAt?: number; // UTC time
user_from_id?: bigint;
user_to_id?: bigint;
wallet_from_id?: number;
wallet_to_id?: number;
user_from?: {
first_name: string;
last_name?: string;
photo_url?: string;
};
wallet_from?: {
address?: string;
};
};
Methods
-
Create Invoice
This method is used to create a new invoice.
async create(data: CreateInvoiceData): Promise<DataContainer<Invoice>>
Example:
const invoiceData = { order_id: 12345, amount: 500, }; const invoiceContainer = await invoiceManager.create(invoiceData); if (invoiceContainer.isValid) { const invoice = invoiceContainer.data; // Do something with the created invoice console.log('New Invoice ID:', invoice.id); } else { console.error('Error creating invoice:', invoiceContainer.error); }
-
Cancel Invoice
This method is used to cancel an existing invoice.
async cancel(invoiceId: InvoiceID): Promise<DataContainer<Invoice>>
Example:
const invoiceIdToCancel = 12345; const canceledInvoiceContainer = await invoiceManager.cancel(invoiceIdToCancel); if (canceledInvoiceContainer.isValid) { const canceledInvoice = canceledInvoiceContainer.data; // Handle the canceled invoice data console.log('Canceled Invoice ID:', canceledInvoice.id); } else { console.error('Error canceling invoice:', canceledInvoiceContainer.error); }
-
Get Invoice Information
This method is used to retrieve information about a specific invoice.
async info(invoiceId: InvoiceID): Promise<DataContainer<Invoice>>
Example:
const invoiceIdToRetrieve = 12345; const invoiceInfoContainer = await invoiceManager.info(invoiceIdToRetrieve); if (invoiceInfoContainer.isValid) { const invoiceInfo = invoiceInfoContainer.data; // Use the retrieved invoice information console.log('Invoice Status:', invoiceInfo.status); } else { console.error('Error getting invoice information:', invoiceInfoContainer.error); }
-
Get Merchant Statistics
This method is used to get statistical data related to the merchant's invoices.
async stats(): Promise<DataContainer<InvoiceStats>>
Example:
const merchantInvoiceStatsContainer = await invoiceManager.stats(); if (merchantInvoiceStatsContainer.isValid) { const invoiceStats = merchantInvoiceStatsContainer.data; // Utilize the merchant's invoice statistics console.log('Total Invoice Count:', invoiceStats.count); } else { console.error('Error getting merchant invoice statistics:', merchantInvoiceStatsContainer.error); }
-
Process WebHook Data
This method is used to process WebHook data related to an invoice update.
processUpdate(update: InvoiceUpdate): DataContainer<Omit<Invoice, 'id'>>
Example:
const webhookData = { data: { status: 'created', code: '123456789', amount: 500, order_id: 12345, sign: 'signature', }, }; const processedData = invoiceManager.processUpdate(webhookData); if (processedData.isValid) { const processedInvoiceData = processedData.data; // Processed invoice data (without 'id' field) console.log('Processed Invoice Status:', processedInvoiceData.status); } else { console.error('Invalid data received in WebHook:', processedData.error); }
Extending MerchantAPIClient
The MerchantAPIClient may be extended via adding new services, like InvoiceManager, inside it.