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-sdk
import {BeansMerchantSdk, BeansMerchantSdkEnvironment} from '../node_modules/beans-merchant-sdk/dist/sdk.js';
// Create an instance of BeansMerchantSdk
const sdk = new BeansMerchantSdk(BeansMerchantSdkEnvironment.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.
BeansMerchantSdk(...)
: Initializes a new SDK instance.
Parameters:
-
environment
: API environment (STAGING or PRODUCTION). -
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);
});
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.