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:

store = tonpay_sdk.get_store('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.issue_invoice(InvoiceInfo(
    True, # can be False, in which case anyone will be able to pay the invoice
    "EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N", // can be ZERO_ADDRESS if hasCustomer is false
    "in_abcdef123456",
    "",
    4.2,
    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:

link = await store.get_request_purchase_link(PurchaseRequestInvoice(
  "in_abcdef123456",
  "",
  4.2,
  Currencies.TON
))

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:

invoice = await store.request_purchase(PurchaseRequestInvoice(
   "in_abcdef123456",
   "",
   4.2,
   Currencies.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:

get_owner() # returns store's owner address (merchant)
get_name() # returns store name
get_description() # returns store description
get_image() # returns store image URL
get_webhook() # returns store webhook URL
get_mcc_code() # returns store MCC code
is_active() # returns active status of the store
get_version() # returns store contract version

get_data() # returns full store info, which includes all data above

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