Pushing sign requests

If your application features user sign in (to identify your user) and you obtained an app+user specific token from a previously signed payload from this specific user, you can add the user_token to the payload. The user will then be informed with a live push notification on their smart device(s).

The first interaction sign request will always involve either:

• Showing a QR code for the user to scan with the xumm app or
• If in a native app mobile flow: a deep link to the xumm app

Once a user signs a payload created by your application, a user token will be generated (bound to your API key and valid only for your application). See: Obtaining a user token.

If you can identify, and know the previously obtained user token for, the end user, you can deliver a sign request to the user using a push notification to their smart device(s).

A payload containing a user token looks like this:

{
  "user_token": "c5bc4ccc-28fa-4080-b702-0d3aac97b993",
  "txjson": {
    ...
  }
}

After posting the payload the the xumm API, the response will confirm push notification delivery:

{
  "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
}

🚧

The pushed attribute is a Boolean containing either true or false. The value will not confirm actual notification delivery to the device; e.g. when the end user device is offline, the value may still be true. The pushed value will only indicate if the given user_token was still valid (not expired or not revoked by the end user).

If a push notification was sent, the next.always URL will show a message the payload was pushed, and a button to view the QR code anyway. If you want to offer the user the option to click a 'Didn't receive' button in your own application user interface, and the user clicks it as they didn't receive the push notification (eg. because they use a different / new device), you can send the user to the next.no_push_msg_received URL. If the user is on a device with xumm installed, the xumm app will automatically open and render the sign request. Otherwise, the browser will open and render either the payload page with a QR code for the user to scan, or (if a smart device) display a link to the App/Play Store for the user to get the xumm app.

If your application is opened on the desktop, it can also render the QR code for the user to scan directly from the pre generated QR (png) from the refs.qr_png value or the refs.qr_matrix value. Optionally, you can have your application subscribe to the refs.websocket_status URL, to receive live notifications if the user opens / resolves the payload. See: Payload response resources.