Payload response resources

Read more about the payload body in the API Docs

The response from the xumm API will look something like this:

  "uuid": "<payload-uuid>",
  "next": {
    "always": "<payload-uuid>",
    "no_push_msg_received": "<payload-uuid>/qr"
  "refs": {
    "qr_png": "<payload-uuid>_q.png",
    "qr_matrix": "<payload-uuid>_q.json",
    "qr_uri_quality_opts": [
    "websocket_status": "wss://<payload-uuid>"
  "pushed": true

The uuid is the unique ID assigned to the payload. You can use the uuid to:

  • Fetch (or subscribe to) the payload status
  • Show the user a payment page (desktop browser)
  • Redirect the user directly to the sign request in the xumm app
  • Generate a QR code for the end user to scan
  • Get a QR code (so you don't have to render one locally)

The next.always URL contains the URL to send users to:

  • If the user is on a device with the xumm app installed, the next.always URL will automatically open the xumm application and take the user to the sign request flow.
  • If the user is on a device without the xumm app installed, the URL will open the browser and display the appropriate App Store / Play Store link to get the xumm app.
  • If the user is not on their device, the next.always URL will show a QR code for the user to scan with a device that has the xumm app installed.

The refs offer pre rendered QR codes in data matrix (JSON, true = black, false = white) and PNG format, with different quality (error recovery) levels (replace the q in the URL with the other available qr_uri_quality_opts values if you like).

Live payload status updates
A (publicly accessible) websocket_status URL that emits live status updates if the end user opened the payload and either rejected or signed it:

wscat -c wss://

# connected (press CTRL+C to quit)
< {"message": "Welcome 78b44f35-ce0f-43c2-9812-a965e1c67cbc"}
# A little later: user opened the payload
< {"opened": true}
# Some time after opening: user resolved the payload (rejected / signed)
< {"payload_uuidv4":"78b44f35-ce0f-43c2-9812-a965e1c67cbc", ... }