- Introduction
- Getting Started
- API Reference
- Questions and Answers
- Examples
The Beans Merchant SDK offers a comprehensive toolkit for integrating the advanced payment capabilities of the Beans platform directly into your JavaScript applications. This SDK is designed to simplify the integration process, allowing you to leverage the Beans Merchant API's full potential without needing to manage the intricacies of direct API calls. By incorporating the Beans Merchant SDK, developers can unlock a wide range of use cases.
-
Build an In-Person Merchant POS: Facilitate in-person point of sale at stores or restaurants by generating payment requests through QR codes. This combines the convenience of online transactions with the traditional in-store shopping experience.
-
Shopify App for Currency Flexibility: Develop a Shopify application that empowers merchants to request payments in their preferred currency while offering customers the flexibility to pay in theirs. This functionality enhances the shopping experience, catering to a global customer base.
-
Integrate Beans as Your On/Off Ramp Partner: Streamline your application's payment infrastructure by using Beans as your central on/off ramp partner. This integration saves significant development time and resources by eliminating the need to individually integrate multiple on/off ramp solutions.
-
Monetize Your GPT Applications: For applications utilizing Generative Pre-trained Transformers (GPT), integrating Beans enables a monetization strategy where services can be accessed for free up to a certain limit, after which users are prompted to pay for additional usage or to purchase credits. This model is perfect for applications offering premium content or services on a per-use basis.
Welcome to Beans App! To start your journey as a merchant, please request an account by contacting us. Follow the steps below to ensure your application is processed smoothly.
Reach out to us via email at merchants@beansapp.com with the following required details:
- Company Name: Provide the official name of your company.
- Company Website: Include the URL to your business website.
- Company Email Address: This should be the official contact email for your business.
- Company Logo: Attach a high-resolution logo (minimum dimensions 500x500 pixels).
To handle payments, please provide your Stellar account details:
- Beans App Account (reccomended):
- Username: Provide your Beans App username.
- Recommendation: Using a Beans App account simplifies the withdrawal process.
- New Users: To create a Beans App account, download the app here.
- Custom Stellar Account:
- Public Key: Provide the public key if you prefer to receive payments in a custom Stellar account.
Thank you for choosing Beans App. We look forward to facilitating your business transactions!
You can install the package using npm:
npm install beans-merchant-sdkimport {BeansMerchantSdk, BeansMerchantSdkEnvironment} from '../node_modules/beans-merchant-sdk/dist/sdk.js';
// Create an instance of BeansMerchantSdk
const sdk = new BeansMerchantSdk.staging('YOUR_API_KEY');
// Fetch currencies
sdk.fetchCurrencies('stellarAccountId')
.then((response: FetchStellarCurrenciesResponse) => {
console.log('Available currencies:', response.stellarCurrencies);
});
// Generate deeplink
sdk.generateDeeplink('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook')
.then((response: DeeplinkResponse) => {
console.log('Generated deeplink:', response.deeplink);
});
// Generate SVG QR code
sdk.generateSvgQRCode('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook', 250)
.then((response: SvgQrCodeResponse) => {
console.log('Generated deeplink:', response.deeplink);
console.log('Generated SVG QR code:', response.svgQrCode);
});
// Generate PNG QR code
merchant.generatePngQRCode('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook', 250)
.then((response: PngQrCodeResponse) => {
console.log('Generated deeplink:', response.deeplink);
console.log('Generated PNG QR code:', response.pngQrCodeBase64String);
});The Beans Merchant SDK provides a simple and intuitive interface for interacting with the Beans Merchant API. This section outlines the available methods and response objects provided by the SDK.
The BeansMerchantSdk class provides methods for interacting with the Beans Merchant API.
The SDK provides three static factory methods to create instances:
BeansMerchantSdk.production(apiKey: string): Creates an SDK instance for the production environment.
Parameters:
apiKey: Your Beans Merchant API key.
BeansMerchantSdk.staging(apiKey: string): Creates an SDK instance for the staging environment.
Parameters:
apiKey: Your Beans Merchant API key.
Retrieves available Stellar currencies for the specified account.
Method Signature:
Promise<FetchStellarCurrenciesResponse> fetchStellarCurrencies(...)
Parameters:
stellarAccountId: Your Stellar account ID.
Returns:
Promise<FetchStellarCurrenciesResponse>: A promise that resolves with the response object containing the available Stellar currencies.
Return Object Properties:
stellarCurrencies: An array of Stellar currencies accessible for the specified Stellar Account.
Example:
sdk.fetchCurrencies('stellarAccountId')
.then((response: FetchStellarCurrenciesResponse) => {
console.log('Available currencies:', response.stellarCurrencies);
});Creates a payment request deeplink.
Method Signature:
Promise<DeeplinkResponse> generateDeeplink(...)
Parameters:
stellarAccountId: Your Stellar account ID.currencyId: Stellar currency ID.amount: Amount for the payment request.memo: Memo for the payment request.maxAllowedPayments: (Optional) Maximum number of payments allowed for the payment request.- Unlimited is -1
- Default is 1
webhookUrl: (Optional) Webhook URL for payment received notification.
Returns:
Promise<DeeplinkResponse>: A promise that resolves with the response object containing the payment request deeplink.
Return Object Properties:
id: The ID of the payment request.deeplink: The Beans App deeplink for the payment request.
Example:
sdk.generateDeeplink('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook')
.then((response: DeeplinkResponse) => {
console.log('Generated deeplink:', response.deeplink);
});Generates a PNG QR code for payment requests.
Method Signature:
Promise<PngQrCodeResponse> generatePngQrCode(...)
Parameters:
stellarAccountId: Your Stellar account ID.currencyId: Stellar currency ID.amount: Amount for the payment request.memo: Memo for the payment request.maxAllowedPayments: (Optional) Maximum number of payments allowed for the payment request.- Unlimited is -1
- Default is 1
webhookUrl: (Optional) Webhook URL for payment received notification.preferredSize: (Optional) Preferred size of the QR code. We will try to generate a QR code with a size as close as possible to the preferred size provided.
Returns:
Promise<PngQrCodeResponse>: A promise that resolves with the response object containing the payment request PNG QR code.
Return Object Properties:
id: The ID of the payment request.deeplink: The Beans App deeplink for the payment request.pngQrCodeBase64String: The base64 encoded PNG QR code containing the deeplink.
Example:
sdk.generatePngQRCode('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook', 250)
.then((response: PngQrCodeResponse) => {
console.log('Generated deeplink:', response.deeplink);
console.log('Generated PNG QR code:', response.pngQrCodeBase64String);
});Generates an SVG QR code for payment requests.
Method Signature:
Promise<SvgQrCodeResponse> generateSvgQrCode(...)
Parameters:
stellarAccountId: Your Stellar account ID.currencyId: Stellar currency ID.amount: Amount for the payment request.memo: Memo for the payment request.maxAllowedPayments: (Optional) Maximum number of payments allowed for the payment request.- Unlimited is -1
- Default is 1
webhookUrl: (Optional) Webhook URL for payment received notification.size: (Optional) Size of the QR code.
Returns:
Promise<SvgQrCodeResponse>: A promise that resolves with the response object containing the payment request SVG QR code.
Return Object Properties:
id: The ID of the payment request.deeplink: The Beans App deeplink for the payment request.svgQrCode: The SVG QR code containing the deeplink.
Example:
sdk.generateSvgQRCode('stellarAccountId', 'stellarCurrencyId', 100, 'memo', 1, 'https://your-domain.com/webhook', 250)
.then((response: SvgQrCodeResponse) => {
console.log('Generated deeplink:', response.deeplink);
console.log('Generated SVG QR code:', response.svgQrCode);
});Creates an account for the company or its clients to receive payments..
Method Signature:
Promise<CreateCompanyAccountResponse> createCompanyAccount(...)
Parameters:
stellarAccountId: The Stellar account ID for the account.name: The name of the account in different languages as a map where the key is the language code (e.g., 'en', 'vn') and the value is the name in that language.
Returns:
Promise<CreateCompanyAccountResponse>: A promise that resolves with the response object containing the created company account.
Return Object Properties:
account: The CompanyAccount object representing the created account.
Example:
const name = {
'en': 'Marketing Account',
'vn': 'Tài khoản Marketing'
};
sdk.createCompanyAccount('GBZX4364PEPQTDICMIQDZ56K4T75QZCR4NBEYKO6PDRJAHZKGUOJPCXB', name)
.then((response) => {
console.log('Created company account:', response.account.id);
});Uploads an avatar for a company account.
Method Signature:
Promise<CompanyAccount> uploadCompanyAccountAvatar(...)
Parameters:
companyId: The ID of the company, or the string "me" to automatically resolve the ID from the provided API token.stellarAccountId: The Stellar account ID of the account.imageData: The image data as a File, Blob, or ArrayBuffer.
Returns:
Promise<CompanyAccount>: A promise that resolves with the updated CompanyAccount object.
Example:
// Using a File from file input
const imageFile = document.getElementById('avatarFile').files[0];
sdk.uploadCompanyAccountAvatar('me', 'GBZX4364PEPQTDICMIQDZ56K4T75QZCR4NBEYKO6PDRJAHZKGUOJPCXB', imageFile)
.then((updatedAccount) => {
console.log('Account updated with avatar URL:', updatedAccount.avatarUrl);
});Deletes an account from the company.
Method Signature:
Promise<DeleteCompanyAccountResponse> deleteCompanyAccount(...)
Parameters:
stellarAccountId: The Stellar account ID of the account to delete.
Returns:
Promise<DeleteCompanyAccountResponse>: A promise that resolves with the response object containing information about the deleted an account.
Return Object Properties:
account: The CompanyAccount object representing the deleted an account.status: The status of the deletion operation, typically "deleted".
Example:
sdk.deleteCompanyAccount('GCQYCNYU3T73JCQ2J36A3JJ5CUQO4DY4EOKMPUL5723ZH7N6XMMNPAA3')
.then((response) => {
console.log('Deleted account:', response.account.id);
console.log('Status:', response.status);
});Gets the avatar bytes from a URL.
Method Signature:
Promise<ArrayBuffer> getAvatarUrlBytes(...)
Parameters:
avatarUrl: The full URL of the avatar.
Returns:
Promise<ArrayBuffer>: A promise that resolves with the image data as an ArrayBuffer.
Example:
// After uploading or fetching an account, use the avatarUrl from the account object
const account = await sdk.getCompanyAccount('stellarAccountId');
if (account.account.avatarUrl) {
sdk.getAvatarUrlBytes(account.account.avatarUrl)
.then((avatarArrayBuffer) => {
// Convert ArrayBuffer to Blob and create URL
const blob = new Blob([avatarArrayBuffer]);
const imageUrl = URL.createObjectURL(blob);
// Display the image
const imgElement = document.getElementById('avatarImage');
imgElement.src = imageUrl;
});
}Fetches all company accounts.
Method Signature:
Promise<GetCompanyAccountsResponseDto> getCompanyAccounts()
Returns:
Promise<GetCompanyAccountsResponseDto>: A promise that resolves with the response DTO containing an array of company accounts.
Example:
sdk.getCompanyAccounts()
.then((response) => {
console.log('Company accounts:', response.accounts);
});Fetches a specific company account by Stellar account ID.
Method Signature:
Promise<GetCompanyAccountResponseDto> getCompanyAccount(...)
Parameters:
stellarAccountId: The Stellar account ID to fetch.
Returns:
Promise<GetCompanyAccountResponseDto>: A promise that resolves with the response DTO containing the company account.
Example:
sdk.getCompanyAccount('stellarAccountId')
.then((response) => {
console.log('Company account:', response.account);
});Beans Merchant API sends a webhook notification to the provided URL when a payment is received.
Example Webhook Payload:
{
"PaymentRequestId": "e3cfa903-548f-475c-a9f2-ebf3f4e2fa17",
"Memo": "example",
"TransactionHash": "b7f4e42935eb120e3a6f43cdae3c6a511a346da77b7e17299aff0f8c72dcf3c0"
}Our platform utilizes Stellar blockchain technology to simplify digital transactions, making it accessible even to those unfamiliar with cryptocurrencies. We've streamlined the payment process using Stellar Lumen (XLM) and other cryptocurrencies, allowing you to transact in main currency units instead of dealing with complex conversions like stroops. For example, to request a payment of 1 XLM, you just set the amoun to "1" and our system automatically handles the conversion to 10,000,000 stroops, ensuring a user-friendly payment experience.
We've provided examples to help you understand what you as a business can do with the Beans Merchant SDK.
This example showcases a checkout page that allows users to pay for items using Beans. You can see how easy it is to integrate Beans payments into your e-commerce platform.
Find the full example code here.
We've added an example that demonstrates how to create and manage company accounts. This example shows how to:
- Create a new account with multi-language support
- Upload an avatar for an account
- Retrieve and display the avatar
- Delete an account when it's no longer needed
This functionality is particularly useful for businesses that need to manage multiple Stellar accounts under a single company account.
Find the full example code here.
This example is more technical and aimed at developers who want to understand the full capabilities of the Beans Merchant SDK.
Find the full example code here.