Payloads are the primary reason for the XUMM API (thus this SDK) to exist.

An XRPL transaction "template" can be posted to the XUMM API. Your transaction tample to sign (so: your "sign request") will be persisted at the XUMM API backend. We now call it a a Payload. XUMM app user(s) can open the Payload (sign request) by scanning a QR code, opening deeplink or receiving push notification and resolve (reject or sign) on their own device.

A payload can contain an XRPL transaction template. Some properties may be omitted, as they will be added by the XUMM app when a user signs a transaction. A simple payload may look like this:

{
  txjson: {
    TransactionType : 'Payment',
    Destination : 'rwiETSee2wMz3SBnAG8hkMsCgvGy9LWbZ1',
    Amount: '1337'
  }
}

As you can see the payload looks like a regular XRPL transaction, wrapped in an txjson object, omitting the mandatory Account, Fee and Sequence properties. They will be added containing the correct values when the payload is signed by an app user.

Optionally (besides txjson) a payload can contain these properties ():

• options to define payload options like a return URL, expiration, etc.

• custom_meta to add metadata, user insruction, your own unique ID, ...

• user_token

A more complex payload . A can be found in:

Instead of providing a txjson transaction, a transaction formatted as HEX blob (string) can be provided in a txblob property.

To create a payload, a txjson XRPL transaction can be provided. Alternatively, a transaction formatted as HEX blob (string) can be provided in a txblob property.

Example contents of a payload

The response of a Sdk.payload.create() operation, looks like this:

The next.always URL is the URL to send the end user to, to scan a QR code or automatically open the XUMM app (if on mobile). If a user_token has been provided as part of the payload data provided to Sdk.payload.create(), you can see if the payload has been pushed to the end user. A button "didn't receive a push notification" could then take the user to the next.no_push_msg_received URL. The

Alternatively user routing / instruction flows can be custom built using the QR information provided in the refs object, and a subscription for live status updates (opened, signed, etc.) using a WebSocket client can be setup by connecting to the refs.websocket_status URL. Please note: this SDK already offers subscriptions. There's no need to setup your own WebSocket client:

Object

To get payload details, status and if resolved & signed: results (transaction, transaction hash, etc.) you can get() a payload.

Note! Please don't use polling! The XUMM API offers Webhooks (configure your Webhook endpoint in the Developer Console) or use a subscription to receive live payload updates (for non-SDK users: Webhooks).

You can get() a payload by:

• Payload UUID

• Passing a created Payload object (see: Sdk.payload.create)

If a payload can't be fetched (eg. doesn't exist), null will be returned, unless a second param (boolean) is provided to get the SDK to throw an Error in case a payload can't be retrieved:

Object

The <PayloadAndSubscription> object is basically a <PayloadSubscription> object with the created payload results in the created property:

All information that applies on Sdk.payload.create() and Sdk.payload.subscribe() applies. create( … ) / subscribe( … ). For the contents of a Payload, see the API Docs for more information about payloads object contents. Differences are:

1. The input for a Sdk.payload.createAndSubscribe() call isn't a payload UUID / existing payload, but a payload to create.

2. The response object also contains (<PayloadAndSubscription>.created) the response obtained when creating the payload.

Example code

Object

To cancel a payload, provide a payload UUID (string), a <XummPayload> (by performing a Sdk.payload.get() first) or a <CreatedPayload> (by using the response of a Sdk.payload.create() call). By cancelling an existing payload, the payload will be marked as expired and can no longer be opened by users.

Please note: if a user already opened the payload in XUMM APP, the payload cannot be cancelled: the user may still be resolving the payload in the XUMM App, and should have a chance to complete that process.

A response (generic API types here) looks like:

{
  result: {
    cancelled: boolean;
    reason: XummCancelReason;
  }
  meta: XummPayloadMeta;
  custom_meta: XummCustomMeta;
}

Object

• Returning non-void in the callback function passed to the Sdk.payload.subscribe() method

• Manually calling <PayloadSubscription>.resolve() on the object returned by the Sdk.payload.subscribe() method