Interacting with Store

Congrats on initializing the SDK! Now you can work with stores and invoices, so let's dive into the stores first.

Getting a store

To start interacting with the store, you need to get the Store instance. To do that, get the store id (obtainable on your store page in the merchant portal) by pressing the "COPY ID" button:

Let's suppose that our store id is EQD4CTLrsCUn2CFQlIhJtRZl7qJnIc76VW3TbDzVAh3ish-j. We need to use this id to get access to our Store object like so:

const store = tonpay.getStore('EQD4CTLrsCUn2CFQlIhJtRZl7qJnIc76VW3TbDzVAh3ish-j');

Viola! Now you have a store to work with!

Edit a store

To edit a store, all you need to do is to call edit() method on your store object:

await store.edit(
    "new name",
    "new description",
    "new image url",
    "new webhook url",
    1337 // new MCC code
);

As soon as the transaction is confirmed, consider your store updated. (5 seconds is all it takes for changes to appear in the TON Blockchain)

Manage active status

To activate or deactivate your store, just call the respective methods:

await store.activate();
// or
await store.deactivate();

Confirm the transaction and that's it.

When the store is deactivated, it won't accept any purchases and you won't be able to issue invoices in it.

Issue an invoice

To issue an invoice, you need several things first:

• customer's wallet address (not necessary if you don't know the address but can direct customer to the invoice itself)

• invoice id - arbitrary string up to 120 characters in length that you can use to track the invoice in your system

• metadata - arbitrary string up to 500 characters in length that you can use to store additional info about the invoice for your own use (won't be visible to customer)

• amount - amount for the user to pay, e.g. 4.2

• currency - currency of the invoice, defaults to TON

Example values:

customer address - EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N invoice id - in_abcdef123456 metadata - empty amount - 4.2 currency - TON

With all this data in place, you can issue the invoice:

const invoice = await store.issueInvoice({
    hasCustomer: true, // can be false, in which case anyone will be able to pay the invoice
    customer: "EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N", // can be ZERO_ADDRESS if hasCustomer is false
    invoiceId: "in_abcdef123456",
    metadata: "",
    amount: 4.2,
    currency: Currencies.TON
});

After confirming the transaction, you'll successfully create the invoice and get the Invoice object.

Only the merchant can issue the invoice.

Get payment link

Issuing an invoice is cool, but what if you want to accept payments 24/7 automatically on your website/bot? For that to happen, you have 2 options:

• get a payment link for the user

• send a purchase request to the store from the user's behalf

How do you get a payment link? Here's an example:

const link = store.getRequestPurchaseLink({
  invoiceId: "in_abcdef123456",
  metadata: "",
  amount: 4.2
});

After getting the link, you can give it to the user in any way you want - button, QR code, text, etc. User that navigates the link and makes a transaction will initiate a set of actions that will issue the invoice for that specific user and automatically pay for it. All of that in just a tap.

How about the purchase request? Well, you can make one like so:

const invoice = await store.requestPurchase({
   invoiceId: "in_abcdef123456",
   metadata: "",
   amount: 4.2,
   currency: Currencies.jUSDT // can be any other currency, defaults to TON
});

After user confirms the transaction, you'll get the invoice object that you can use to track the payment status easily.

This method of initiating a payment requires user to connect the wallet to your application. It's strongly recommended to use TON Connect 2.0 for that as it provides the best user experience and supports a wide variety of wallets. Additionally, your app will be added to the user's wallet, if they're using Tonkeeper, which can increase retention.

Get store info

If you want to get any info about your store using the SDK, then you'll get a variety of methods for that. Here's the full list:

getOwner(); // returns store's owner address (merchant)
getName(); // returns store name
getDescription(); // returns store description
getImage(); // returns store image URL
getWebhook(); // returns store webhook URL
getMccCode(); // returns store MCC code
isActive(); // returns active status of the store
getVersion(); // returns store contract version

getData(); // returns full store info, which includes all data above

It's recommended to just use the getData() to save up on requests.