Payload workflow

The typical payload workflow starts in your application: you would like your user to sign something. This can be a payment from the user to your application, or another type of XRPL transaction, like setting up an escrow, setting up multi signing, creating a trust line, etc.

📘

Terminology: payload vs. sign request vs. transaction template

When you want your end user to sign a transaction (sign request) you need to compose a transaction template (in JSON formatted as per XRPL transactions specifications) and POST the transaction template to the xumm platform (API) to create a payload, to be resolved (rejected or signed) by the xumm app user.

Your application crafts the XRPL transaction template. The difference between a regular XRPL JSON transaction and a xumm transaction template is that you can leave out some fields (or leave them blank) as the xumm app on the device of the end user will fill them automatically.

Your application backend will send the transaction template to the xumm API. Your application will receive a unique payload ID.

🚧

A note on Testnet/Devnet/Mainnet

To interact with Testnet / Devnet, simply sign your request with the xumm app connected to Testnet / Devnet. As the XUMM platform is simply an "interaction channel" between the end user and an external application, the net used is irrelevant for the API. The net the user is connected to when signing is leading.

The developer can see the used net (TESTNET/DEVNET/MAINNET) in the payload results post signing.

DESKTOP CLIENTS
Your application can then generate a QR code or use one of the pre-generated QR codes. The xumm app end user is able to scan the QR code, review the transaction template, and sign the transaction. Alternatively, you can redirect the end user to the payload URL.

DEVICE CLIENTS
When this process happens on a device with the xumm app installed, the xumm app will automatically open when you redirect the user to the payload URL.

Based on the payload options your application posted when you created the payload, the xumm app will either submit the signed transaction directly to the XRPL, or post the signed transaction HEX back to your application (so your application can submit or retain the signed transaction, eg. in case of a multi sign platform).

Your application backend will receive a HTTP POST webhook when the payload has been resolved by the end user, by either rejecting or signing it. You can also subscribe to a payload specific websocket to receive live status updates, or get the payload status (and if resolved: results) by calling the xumm API.

When a user decides to sign and trust your application, you will receive a User Token. You can now deliver sign requests directly to the end user using a push notification. Client side interaction with your application is now optional.

For a more detailed, step by step payload life cycle overview, check out the step by step Payload life cycle page.