Payload life cycle

🚧

Please read the Payload workflow document first (if you haven't already done so).

1. Pre-payload: compose transaction template

👍

Compose the transaction you would like to sign in JSON format, as per the XRPL transaction format specification at xrpl.org. All common fields can also be part of your transaction template.

Therefore, any JSON value you'd use to sign and send to rippled(the xrp ledger) can be sent to the xumm API, with the (signing) account fields being added/filled being the only major difference.

All fields and values in the JSON transaction template sent to the xumm API are passed on as-is, except for:

1. Account: If this field is part of the transaction template, it will be completely ignored, as the Account will be automatically filled based on the account the end user uses to sign the transaction with in the xumm app.
2. Sequence: Based on the account used to sign by the end user in the xumm app, the Sequence will be automatically filled by xumm.
3. LastLedgerSequence: If a valid ledger index is entered in the LastLedgerSequence field, it will be passed on unchanged to the xumm app. However, if a value < 32570 is entered, the xumm app will automatically calculate the {current ledger index} + the given amount of ledgers, where {current ledger index} is based on the most recent closed ledger index at the moment the end user taps the button to accept & sign the sign request.

2. Compose payload options

If not omitted (defaults apply) the options section in the payload can contain the following keys:

Submit
If submit is false, the xumm app will not submit the signed transaction to the XRP ledger. As the signed transaction blob in HEX format will be stored for retrieval using the xumm API , your application will be responsible for fetching and processing/submitting the signed blob.

Multisign
If the user should sign a transaction that will be combined later on, as part of a multi sign transaction, multisign should be set to true. This will result in a signed transaction blob (HEX) with the Signers section, and a signature per signer. It would make sense to specify the submit option to be false, so that the signed transaction blob (HEX) can be retrieved from the xumm API for later combining.

Expire
A payload will be valid for the expire amount of minutes. If the end user does not resolve the payload in time, the user will no longer be able to review/sign the payload. If you deliver the payload to the end user in an asynchronous workflow (e.g. push notification), make sure to enter a higher amount than the default (240 minutes (4 hours)), as the user may open the push notification at a later moment.

Return URL(s)
If no return url is entered, the end user will be taken to the xumm app home screen after signing and closing the sign/submit result screen. If the user is originating from a device web environment, or another native iOS/Android app, the return_url.app value can be set to a URL or deep link URL.

When a valid URL is entered in the app value, instead of a Close button, the sign/submit confirmation screen in the xumm app will display a Next label. When pressed, the user will be redirected to the given URL (system browser, or in case of a deep link: back to your application).

If the xumm payload URL is opened on a desktop browser environment, and the end user scans the QR code displayed on the desktop page, the desktop xumm payload page will be updated in real time when the end user scans the QR code and opens the payload on their smart device. After resolving the payload (rejecting or signing), the desktop browser will automatically redirect to the given return_url.web URL.

🚧

Return URL origin logic

If both the app and web return URL values are present, and if they are identical, the XUMM platform will execute logic to see if the user is coming from a browser tab (local device or remote, e.g. desktop browser). If so, and if the origin browser window is still active, only the origin browser window will redirect, and the app won't. Else (if the browser window is not active anymore) XUMM will redirect to the return URL.

This behaviour prevents a double redirect (both on mobile and on desktop / browser window).

📘

Return URL

The following strings will be replaced:

• {id} will be replaced with the xumm payload UUID.
• {cid} will be replaced with the optional custom payload identifier
• {txid} will be replaced with the signed transaction hash
• {txblob} will be replaced with the signed transaction HEX blob

A sample options object could look like this:

{ 
  "options": {
    "submit": true,
    "multisign": false,
    "expire": 240,
    "return_url": {
      "app": "https://wietse.com/xrpl/?payload={id}&blob={txblob}",
      "web": "https://wietse.com/xrpl/?identifier={cid}&tx={txid}"
    }
  }
}

3. Optionally: specify user token for push delivery

See: Pushing sign requests

4. Submit payload

With your transaction template (JSON) assigned to the txjson key and optionally the user_token string and the options object, you can submit your payload to the xumm API HTTP POST /payload endpoint.

5. Client instruction & redirection

The xumm API will respond with a payload uuid and some other information. A sample payload POST response will look like this:

{
  "uuid": "<some-uuid>",
  "next": {
    "always": "https://xumm.app/sign/<some-uuid>",
    "no_push_msg_received": "https://xumm.app/sign/<some-uuid>/qr"
  },
  "refs": {
    "qr_png": "...",
    "qr_matrix": "...",
    ...
    "websocket_status": "wss://xumm.app/sign/<some-uuid>"
  },
  "pushed": true
}

You can subscribe to the refs.websocket_status WebSocket to receive live updates (if the user opened/resolved the payload). If the payload wasn't pushed (or if the user didn't receive the push notification, see Pushing sign requests), you can redirect the user to the next.always or next.no_push_msg_received location. Alternatively, you can display the payload QR code by rendering a QR in your application containing the next.always URL, or use the pre-rendered QR from refs.qr_png or refs.qr_matrix.

6. Payload resolvement

The user opens & reviews the payload, and either rejects or signs your transaction template in the xumm app.

7. Payload results & callback

While the user opens & resolves the payload, your application can receive status updates using a live status websocket, webhooks and API calls to the xumm API. See: Payload status updates.

8. On ledger verification

📘

If the transaction has been submitted by the xumm app on the end user device, your application should always verify the transaction outcome on ledger. As the signed transaction hash can be retrieved from the xumm API, you can use this value to fetch the transaction from a trusted XRPL node.

You can use the xrpl-txdata NPM package, the XUMM API xrpl-tx method or use a WebSocket or HTTP RPC method to a trusted XRPL node:

curl --request POST \
  --url https://xrpl.ws/ \
  --header 'content-type: application/json' \
  --data '{
    "method": "tx",
    "params": [
        {
            "transaction": "88BA5E...C5366",
            "binary": false
        }
    ]
}'

const s = new WebSocket('wss://xrpl.ws')
s.addEventListener('open', function () {
  s.send(JSON.stringify({
    command: 'tx',
    transaction: '88BA5E...C5366'}))
})
s.addEventListener('message', function (m) {
  console.log(JSON.parse(m.data))
})

9. Alternative payload result processing

If you instructed xumm to only sign (eg. options.submit: false), your application can use the signed transaction blob (HEX), retrieved from the xumm API, for further processing (e.g. in case of a multi sign use case: store, keep, wait for more signatures, combine and submit).