The difference between XRP Ledger Transaction JSON and a Xumm Payload is that the XRP Ledger JSON needs to be complete and signed locally, while a Xumm Payload can contain an incomplete transaction.

The incomplete transaction, referred to as a Transaction Template, can be delivered to Xumm users allowing end users to view the Payload in the form of a "Sign Request": a transaction to sign and submit, or reject.

Xumm will then add the missing fields like the signer account, network Fee, Account Sequence, based on the context the user provides.

Xumm Payloads use the exact same syntax as the XRP Ledger JSON transaction format.

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 / SDK. Your application will receive a unique Payload ID that contains your Sign Request.

Typical fields Xumm provides:

• Fee will be automatically filled with the appropriate network fee, but when set in the Payload, Xumm will respect your provided fee.

• Sequence will be automatically filled with the Account sequence of the account interacting with your payload.

• Account will be automatically filled with the account interacting with your payload.

Payload Completion and Verification

After a payload completes its lifecycle, which includes creation, user interaction, transaction signing, and transaction submission to the XRP Ledger by Xumm, your application will receive (if configured) a Webhook callback.

This callback should trigger your application to fetch the payload results. It is highly advisable to fetch the payload results again on your "thank you" or "return" page in case you did not persist the payload results after receiving a Webhook.

Verifying Payment Transactions

Here are the steps to verify that you have indeed received a payment:

1. Check Payload Output: Verify if the Payload output contains meta.resolved. This value should be true. Otherwise, the payload is still pending or has been abandoned by the user. Also, check if the Payload output contains meta.signed. This value should be true, indicating that the user signed the transaction.

2. Check Response Dispatched Node Type: Verify the response.dispatched_nodetype value. If you are expecting a real payment, this value should contain MAINNET

Fetching Transaction Details

You can fetch transaction details using the XRPL Transaction Data fetcher or the JSON RPC (HTTP POST) method at .

Utilizing (flow+code) the xrpl-txdata Package (JS/TS) for Transaction Verification

After sending a Sign Request () to Xumm, you receive a response with the signed transaction hash (: payloadResponse.txid, : txid).

You're in luck if you immediately check this transaction hash on the XRP Ledger, and it's already in a validated ledger. However, if the transaction hasn't been included in a closed ledger, you might encounter a "Not Found" error, while if you had checked a few seconds later, you'd have found the transaction.

To streamline this process, use the xrpl-txdata NPM package (JS/TS). This package simplifies:

1. Establishing a redundant (multi-node, failover) and reliable (auto-timeout, auto-retry) connection to the XRP Ledger

2. Fetching a transaction by hash

3. Optionally, monitoring the XRP Ledger (all closed ledgers, all the transactions in those ledgers) and waiting for a specified time (seconds).

Once your transaction is found, the package returns the transaction outcome and validated balance changes.

Here's how to use it in JavaScript:

Good Practice: Cross-verify with the XRPL

It is always a good practice to cross-verify with the XRPL for absolute certainty. Using the tx method, you can fetch transaction details directly from the XRPL ledger.

More information on how to do this can be found in the .

Here's a step-by-step guide to understanding and implementing Xumm's workflow in your application:

1. Create a Payload: Start by using Xumm's API to create a payload. A payload is essentially a transaction template containing all the details for the transaction you want the User to sign.

2. Deliver the Payload to the User: Once the payload is created, you need to deliver it to the User for signing. Xumm offers multiple delivery options, including push notifications, QR codes, and deep links. Choose the method that best suits your application.

3. User Interaction: The User will interact with the payload through the Xumm app. They have the option to either sign or reject the transaction.

4. Retrieve the Result: After the User has interacted with the payload, your application needs to retrieve the result . This can be done by fetching the result from Xumm's API. The result will indicate whether the User signed or rejected the transaction.

5. Interact with the XRP Ledger: If the User signed the transaction, your application can now interact with the XRP Ledger to finalize the transaction. This involves submitting the signed transaction to the XRP Ledger and handling any responses or confirmations.

6. Provide Feedback to the User: Finally, provide appropriate Feedback based on the transaction's outcome. This could be a confirmation message for a successful transaction or an error message if something went wrong.

By following these steps, you can effectively integrate Xumm's workflow into your application and leverage its features for secure and streamlined transactions on the XRP Ledger.

Benefits of QR Scanning:

• Use Cases: QR scanning is common in retail scenarios or multi-device interactions. It is perfect for physical interaction, Point-of-sale terminals, or when users interact across devices (desktop to mobile).

• Multi-Device Scenarios: In cases like desktop to mobile, users can scan the QR code on the desktop screen with their mobile device. Typically, there's no need for a return URL as the desktop browser can pick up the results.

• How It Works: Generate a QR code for the payload using Xumm. Users scan this QR code with the Xumm app to access and interact with the payload.

User Perspective:

For end users, QR scanning is intuitive and engaging. They scan the QR code with their mobile device and are immediately taken to the payload in the Xumm app. This method is particularly effective in retail environments or when users operate across multiple devices.

Payload delivery from your native iOS / Android app happens through "Deep Links".

Deep Linking allows your mobile app to communicate directly with the Xumm app, enabling users to interact with payloads effortlessly.

For a detailed guide on implementing mobile payload delivery through Deep Linking, please refer to the Deep Linking page.

This includes options like QR code scanning and deep linking, adapted for larger screens.

• If you can't already identify the user, refer to the QR Scanning

• If you have already identified the user and obtained a user_token, refer to the Push

If you want to make sure a WebHook received by your platform has been sent by the Xumm platform, verify the signature the platform sends in an HTTP header.

Every WebHook call contains a signature to verify the authenticity. It sends an HMAC using your application secret as a key. Sample verification in NodeJS:

import crypto from 'crypto'

// Xumm App secret (Xumm developer console)
const secret = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

const timestamp = req.headers?.['x-xumm-request-timestamp'] || ''
const json = req.body

const hmac = crypto.createHmac('sha1', secret.replace('-', ''))
  .update(timestamp + JSON.stringify(json))
  .digest('hex')

console.log(hmac, hmac === req.headers?.['x-xumm-request-signature'])

Instead of polling, consider these efficient alternatives:

• Webhooks: Once a payload is resolved, Xumm can send a WebHook to your platform, eliminating the need for constant polling. Learn more: Webhooks.

• Websocket Subscription: Use Websocket to receive live status updates. Learn more: Websocket.

Excessive polling can lead to your application being temporarily rate limited, disrupting your service. If your application has been rate limited, you will receive a notification email later the same day on the e-mail address entered in the application details in the .

What is a Payload?

In Xumm, a payload is a sign request sent by applications or developers to users for interaction. Users review the payload and decide to reject or accept by signing.

Delivering Payloads within xApps

Delivering payloads within xApps is about efficiency and user experience. Since the user is already engaged with your xApp inside Xumm, delivering the payload directly within the xApp streamlines the process. This minimizes context switching for the user and keeps them focused on the task at hand.

Deep Links are a well known flow to allow users to automatically launch and open another app in a specific state. Xumm allows for a Deep Link workflow, where your application (browser based or native) can trigger Xumm to open and immediately show your sign request.

Benefits of Deep Linking:

• When to Use: Opt for deep linking when you want to minimize user steps and create a fluid transition between your app and Xumm.

Don't keep a list of explorer links youself: you can easily rely on our explorer launchpad URL.

When using TX Hash

The network param can be mainnet, xahau and any other key from the rails endpoint

Overview

When users interact with payloads, Xumm provides real-time status updates and results (e.g., rejected, signed with signature). These updates allow you to make your application user interface reflect the status of the interaction with the user, and return sign request results to your application.

If you are building a backend integration, the flow is slightly different.

Backend

If your application features user sign-in (to identify your user) and you obtained a user_token from a previously signed payload from this specific user, you can add the user_token to the next payload to deliver the payload through a push notification.

The first interaction (to obtain the user_token) will always involve either: showing a QR code for the user to scan with the Xumm app or a deep link to the Xumm app to sign a payload.

A payload containing a user token looks like this:

After posting the payload the Xumm SDK/API, the response will confirm push notification delivery:

Obtaining the `user_token`

From a webhook

After the end user resolves the sign request by signing, the configured application Webhook URL will receive a JSON body per POST request containing the accessToken section:

From a resolved Payload

When you get the payload results, the application.issued_user_token contains the user token.

Webhooks are essential for asynchronous communication and can trigger specific actions in your application based on events in Xumm.

If you entered a valid Webhook URL in your Application Settings at the Xumm Xumm Developer Console, your application would receive an HTTP POST containing a JSON body with limited details for the given payload.

Please note a Webhook will not contain the entire payload: to get the entire payload, you should GET the payload using an SDK/API call.

A sample webhook looks like this:

If a user token (userToken.user_token) is issued and you plan on payload delivery using push notifications in the future, your application could/should store the token. See

Use the payloadResponse.payload_uuidv4 to confirm and get payload outcome using an SDK/API call.

Safety

If you want to make sure the Webhook your application received came from the Xumm platform, there are two things you can do:

1. Send a GET for the payload to get the full payload using the SDK/API to the Xumm platform:

2. Verify the signature we send in a HTTP Header when we deliver the Webhook: \

However, a payload can include a forced network identifier to specify a particular network. When a user signs a payload, the result includes information about the network the user was on when signing, allowing developers to track and manage transactions across different networks.

Key Points:

1. Network Independence: The Xumm API/SDK operates independently of the network, giving the end user the freedom to choose their preferred network in the Xumm app.

2. Network Information in Results: The results of a signed payload include information about the network the user was on at the time of signing.

3. Forced Network Identifier: A user can be on any network while signing. You must check for the expected result in the Payload results. Alternatively, you can include a forced network identifier in a payload to specify a particular network.

Here's a comprehensive guide to understanding and implementing Xumm's transaction lifecycle:

1. Transaction Template

Start by composing the transaction you want to be signed in JSON format, as per the . You can include all except "Account" and "Sequence", which will be automatically filled by Xumm.

Therefore, any JSON value you'd use to sign and send to an XRPL node can be sent to the Xumm SDK/API, with the (signing) account fields being added/filled being the only major difference.

The Return URL (return_url) determines where the user is sent when the payload is signed. If none is given, the user will simply be displayed Close button in Xumm. Otherwise, the user will be presented a button which launches the Return URL.

Replacement variables

You can add the following replacement tags in your Return URL. They will be replaced with the appropriate values by Xumm.

• {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.

Routing / 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).

Sample payload body

All payloads get assigned a payload-specific Websocket URL. You can connect to this socket from the client side of your application to receive live status updates (if the user opens the payload on their device and the user resolves the payload).

The pushed information contains minimal information; it is meant to trigger your application to fetch more information from your application's backend.

If a payload doesn't exist, the Websocket connection will receive an {"message":"..."} update, and the socket will be closed. If the payload has expired, the connection will receive a {"expired":true"} message.

If the payload exists and did not expire, the connection will start with a message containing the remaining seconds until expiration: {"expires_in_seconds":51}. This message will be sent every 15 seconds for keepalive reasons. If the connection is still active when the payload expires, a {"expired":true"} message will be sent. The connection will be kept alive, leaving it up to the client to disconnect.

Expiration

The expiration should be handled as an OPEN/SCAN BEFORE, not a RESOLVE BEFORE. If the end user opens the payload (from the push notification, deep link, or QR scanning) but it didn't resolve before expiration, they will not receive a notification and will still be able to resolve it as if the payload hadn't expired.

When the user resolves after the expiration moment, the webhook and callback will handle the response as they would when the payload wasn't expired.

Websocket Events

Websocket events to expect

Sample

The Websocket payload resolve message looks like: