Your First Payload: XUMM SDK

Once we establish connection to the XUMM platform using XUMM SDK, its time to actually learn about sending payload. Payload is nothing buy “transaction template”.

What is a Payload or “Transaction Template”?

Think of Payload or “Transaction Template” as invoice. The minimum things which an invoice should include are:
1. What kind of an invoice it is.
2. The destination address for payment.

We could even leave the amounts section empty assuming that the client will fill it.

Simple Transaction Template

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT"
}

This is the bare minimal Payload or Transaction template we can write. It has transaction type and destination address(XRP address). The keywords “TransactionType”: “Payment” and “Destination” should be formatted as per XRP ledger transaction specifications.

If we don’t mention amount in our payload, end user can edit and enter the amount himself or herself after opening the payload request using their XUMM App. If we mention the amount in payload or transaction template, then he or she will not be able to edit it while signing.

Signing simply means authorizing the payment request. Or authorizing the sign request.

Sample Transaction Template With More Information

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
  "Amount": "1000000",
  "Memos": [
    {
      "Memo": {
        "MemoData": "F09F94A520546563686E6F7469702E636F6D"
      }
    }
  ]
}

Here we’ve explicitly mentioned the “Amount” which is 1 Million, which means 1 XRP. i.e., one XRP is one million Drops. And a Memo (HEX encoded string). TransactionType and Destination are mandatory fields, all other fields are optional.

Generating Memo(HEX encoded string)

const hex = Buffer.from('🔥 Technotip.com').toString('hex').toUpperCase()
console.log(hex)

Buffer is a nodejs packages built-in property, so you need not install any other packages once again.

Video Tutorial: Your First Payload: XUMM SDK

Things To Keep In Mind While Sending Payload

1. A payload (sign request) sent to the XUMM platform should be formatted as per XRP ledger transaction specifications, but some fields may be omitted as XUMM will automatically fill them in if able to do so.

2. Usually, a payload sent to the XUMM platform will be signed by the end user (e.g., for a sign in, subscription, payment, escrow creation etc). For this tutorial, you will be the initiator and the end user, either signing or rejecting your own payload.

3. The first sign request from a specific XUMM app will always have to be scanned using a QR code on the desktop. Once an end user trusts your application, by signing your sign request, your application can obtain a user specific user token to deliver future sign requests using push notification.

Source Code: Complete Code To Send Payload

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000",
    "Memos": [
      {
        "Memo": {
          "MemoData": "F09F94A520546563686E6F7469702E636F6D"
        }
      }
    ]
  }

  const payload = await Sdk.payload.create(request, true)
  console.log(payload)
}
main()

Here we are making use of Sdk.payload.create() method to generate sign request URL and QR code and other outputs. We pass 2 arguments to Sdk.payload.create(). First argument is the payload or the transaction template(in above code the constant by name request), and the second argument will be a flag (boolean, true) telling the code to return an error, if one occurs.

Running The Application

We issue the command node index.js to run our application and we get the following output:
payload

{
  uuid: '127287c3-bf55-40ee-b0ab-345f9edc8840',
  next: {
    always: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'
  },
  refs: {
    qr_png: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.png',    
    qr_matrix: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.json',
    qr_uri_quality_opts: [ 'm', 'q', 'h' ],
    websocket_status: 
'wss://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'   
  },
  pushed: false
}

Your output will be different, and most part of this output will be unique. The output at payload.next.always is the sign request URL. payload.refs.qr_png is the QR code which has sign request information encoded. payload.pushed is false as this is the first time we are sending payload to the end user and we do not yet have the user token. We get the user token if the user successfully signs the sign request. We store this user token, which is specific to XUMM platform and from next time we can send sign request as push notification to the end users mobile device.

Action Steps

Now you can open YOUR payload output and navigate to payload.next.always or payload.refs.qr_png, open the XUMM app present on your mobile phone, scan the QR code and sign or reject the sign request and check for the status changes at payload.next.always URL.

Benefits of using XUMM Platform for our Application

1. DEX or any site can make use of XUMM “sign” transaction type for authorization – for example, for signing up for a DEX account or for creating an account on an app etc.

2. We can use XUMM platform to create and accept payments and/or subscription services.

3. Once the user signs/authorizes our first sign request, we can start sending payments/sign requests as push notification directly to their XUMM app in their mobile devices. That’s so convenient and seamless payments experience.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL