Commerce SDK - Web

Our Commerce SDK works seamlessly on any website or inside any mobile or desktop app as a webview. It has also been built for Web3 and can be configured as a dApp that can connect to a mobile, web or desktop wallet.

Below is an example of it being used as a permissionless dApp, by navigating to bida.li/dapp using the embedded dApp browser inside the Phantom Wallet on the Solana network. Anyone can go to use this so long as they have a supported mobile wallet. No installation or developer work necessary!

To integrate our Commerce SDK as embedded functionality right in your application and have a bit more customization and control over the customer experience, follow the steps below. 👇

Step 1: Obtain your API Key

To get set up with an API Key please email us at support@bidali.com with your request.

Step 2: Include the Commerce script

Copy and paste this into the head of your website

Production / Mainnet

<script type="text/javascript" src="https://commerce.bidali.com/commerce.min.js"></script>

Staging / Testnet

<script type="text/javascript" src="https://commerce.staging.bidali.com/commerce.min.js"></script>

This will expose a global object, bidaliSdk, which you can use to render the Commerce widget.

The protocol's to use for paymentCurrencies are listed on the following pages:

Environment	URL
Staging / Testnet	https://docs.bidali.com/commerce/currencies?environment=testnet
Production / Mainnet	https://docs.bidali.com/commerce/currencies

Usage

Pay via External Wallet

User pays by scanning QR code / copying amount & address, or via MetaMask

Default options

bidaliSdk.Commerce.render({
  apiKey: 'YOUR API KEY'
});

Pay with Solana only

bidaliSdk.Commerce.render({
  apiKey: 'YOUR API KEY',
  paymentCurrencies: ['solana']
});

Pre-populate users email address

email is optional

bidaliSdk.Commerce.render({
  apiKey: 'YOUR API KEY',
  paymentCurrencies: ['solana', 'usdcsolana'],
  email: 'user@email.com'
});

Payment in-wallet (Web Wallets)

User pays in-app / wallet, after selecting a payment currency wallet receives a paymentRequest specifying the amount and address to send to.

bidaliSdk.Commerce.render({
  apiKey: 'YOUR API KEY',
  paymentType: 'prefill',
  onPaymentRequest: (paymentRequest) => {
    const { amount, currency, description, chargeId } = paymentRequest;
    console.log('received onPaymentRequest', paymentRequest);
  }
});

Prepopulate users email address

info

This will pre-populate the users email address and they will be prompted to confirm it in the checkout flow

bidaliSdk.Commerce.render({
  apiKey: 'YOUR API KEY',
  paymentType: 'prefill',
  email: 'user@email.com',
  onPaymentRequest: (paymentRequest) => {
    const { amount, currency, description, chargeId } = paymentRequest;
    console.log('received onPaymentRequest', paymentRequest);
  }
});

Here's what a paymentRequest looks like:

  {
    amount: '0.125',
    currency: 'ETH',
    address: '0x220b48eda85a0a067c769f0442dd2f4e03ba625a',
    protocol: 'ethereum',
    chargeId: 'vIQ807gvR',
    description: '$50 Amazon Gift Card'
  }

A paymentRequest has the following properties:

Property	Type	Description
address	String	The address to send to
amount	String	The amount to send, as a user readable string (ex. "25")
symbol	String	The symbol of the currency the user has chosen to pay with, ex: BTC, not unique to a currency (for instance USDC ERC20 and USDC on Stellar both have the symbol USDC)
protocol	String	The protocol of the currency the user has chosen to pay with, this is unique for each currency. ex: usdcstellar
description	String	A comma-delimited list of products being purchased. Can be used on your payment approval screen so the user sees what they are approving payment for. Ex: $50 USD Amazon US, 2x $25 USD Apple US
lineItems	Array	A list of products being purchased. Just like with description, you can use this on your payment approval screen. A line item looks like { name: 'Apple US', quantity: 1, amount: '$5 USD', image: 'https://assets.bidali.com/commerce/brands/apple.png' }
chargeId	String	The users order reference, helpful to reference the order in the future or if there are any issues. Ex: vIQ807gvR
extraId	String	The extraId that must be passed for the payment to be credited appropriately to the order. Currently only applicable to currencies on Stellar, Algorand, and Solana networks
extraIdName	String	The name of the extraId that must be sent with the transaction. Currently only applicable to currencies on Stellar, Algorand, and Solana networks

Note for currencies on Stellar, Algorand, and Solana networks

Below are the additional fields that will be populated on the BidaliPaymentRequest and MUST be passed with the transaction for it to be successful.

Network	extraIdName
Stellar	Memo text
Solana	Memo
Algorand	Note/Memo
Cosmos	Memo
Osmosis	Memo