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 learn more about the XRP Ledger first (concepts, transaction types, etc.) we have a great resource for you at https://learn.xumm.dev:

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.

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.

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:

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 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:

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.

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

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: .

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

Information

• ott

This method is only available when using the SDK in a JWT context!

The getNftokenDetail method allows you to get basic XLS20 token information as fetched/parsed/cached for you by the XUMM backend.

Note: it's best to retrieve these results yourself instead of relying on the XUMM platform to get live XRPL transaction information!

Returns:

PaymentChannelAuthorize is normally a 'Command' or locally signed object. Implemented in Xumm as a TransactionType (which it actually isn't, also: the resulting signed blob can never be submitted to an XRPL node as is). For more information, see:

Sample PayChan transactions (gist):

The getRails method allows you to get the network information for all networks known to Xumm.

Returns:

• Standard Transaction Types: Xumm accepts all mainnet XRPL transaction types.

  • Exception: Transaction types for non-voted in amendments may be unavailable

Sdk.getHookHash(hookHash: string)

The getHookHash method allows you to get meta information for a specific Hook hash (64 hex chars)

Returns:

The ping method allows you to verify API access (valid credentials) and returns some info on your XUMM APP:

Returns :

See

Can be used to check connectivity / JWT (credential) validity & to obtain basic information about the calling credentials.

Sample response

Sdk.getHookHashes()

The getHookHashes allows you to get all meta information for all Hooks known to Xumm.

Returns:

The getRates method allows you to get the exchange rates for an XRP <> requested pair. The source information is aggregated from several data providers.

Example response

Two types of Push:

1. Payload (Sign Request Push). Any application can send Sign Requests with a push notification after the user interacted with the app at least once.

   1. Backend integration: the Webhook & Payload get will contain a user token after the user decided to interact by signing a payload.

   2. xApp & Browser (Web3) integrations obtain a user token after xApp open / Sign In.\

   - A user token is valid for 30 days (default, can be extended on a per app basis if good reasons are provided). Every time the user interacts with the app again, the 30 day cycle will reset. - When creating a new payload (sign request), the user token can be specified in the payload, after which the user will receive a push notification, and the sign request will present itself in the Event List of the user. - Users can revoke the user token validity in Xumm (Settings - 3rd party apps - Revoke) - A user token is user & app bound, meaning the same user token can only be used by the API credentials it was originally extended to.

2. Custom xApp push events. Custom xApp push events are permissioned.

   1. Notification with link to xApp

   2. Notification with link to xApp & Event in Event list with link to xApp

The verifyUserTokens (or single token: verifyUserToken) method allows you to verify one or more User Tokens obtained from previous sign requests. This allows you to detect if you will be able to push your next Sign Request to specific users.

const someToken = '691d5ae8-968b-44c8-8835-f25da1214f35')

const tokenValidity = Sdk.verifyUserTokens([
  someToken,
  'b12b59a8-83c8-4bc0-8acb-1d1d743871f1',
  '51313be2-5887-4ae8-9fda-765775a59e51'
])

if ((await Sdk.verifyUserToken(someToken).active) {
  // Push, use `user_token` in payload
} else {
  // QR or Redirect (deeplink) flow
}

Returns: Promise<UserTokenValidity[]> or Promise

The getCuratedAssets method allows you to get the list of trusted issuers and IOU's. This is the same list used to populate the "Add Asset" button at the XUMM home screan.

const curatedAssets = await Sdk.getCuratedAssets();

Returns <CuratedAssetsResponse>:

{
  curatedAssets: {
    issuers: [ 'Bitstamp', 'GateHub' ],
    currencies: [ 'USD', 'BTC', 'EUR', 'ETH' ],
    details: {
      Bitstamp: [Object],
      GateHub: [Object]
    }
  }
}

Parameters

{ text: 'Some text to share' }

Syntax

xumm.xapp.share({ text: 'Some text to share' })

Parameters

{
  account: '...',
  tx: 'HASH...',
  network?: 'MAINNET|TESTNET|XAHAU|...',
}

Syntax

xumm.xapp.tx({
  account: 'rwietsevLFg8XSmG3bEZzFein1g8RBqWDZ',
  tx: '250DC3E83946EFE965DE36B3F9AE8608CD7ED793657BDEC5B794B665B2DCBC0E',
  network: 'MAINNET',
})

Requirement(s)

• The given account must be imported in Xumm

• Xumm must be on the network the transaction is present on

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 XRPL transaction format specification at xrpl.org. You can include all common fields 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.

All fields and values in the JSON transaction template sent to the Xumm SDK/API are passed on as-is, except for the following:

1. Account: If this field is part of the transaction template, it will be completely ignored, as the Account will be automatically filled based on the account the end user uses to sign the transaction with in the Xumm app.

2. Sequence: Based on the account used to sign by the end user in the Xumm app, the Sequence will be automatically filled by Xumm.

2. Payload Options

Configure Payload Options: Configure the payload options to customize the transaction request. Refer to the for detailed information on the available options.

3. User Token (Optional)

If you are using a backend flow, you can optionally include a user token. This token is specific to the user and can be used for personalized transactions.

4. Submit the Payload

Submit the payload to Xumm through the Xumm SDK or API. You can also use alternative language SDKs for this step. This initiates the transaction signing process.

5. Handle Client Interaction

The client, a mobile app, xApp, or desktop application, will interact with the payload. Implement logic to handle this interaction and guide the user through the signing process.

6. Resolve the Transaction

The user will either sign or reject the transaction. Your application should be ready to handle both outcomes and take appropriate action.

7. Retrieve Payload Results

After resolution, retrieve the payload results to understand the outcome of the transaction. You can use WebHooks, and WebSockets or verify through the SDK/API.

8. On-Ledger Verification

Finally, verify the transaction on the XRP Ledger. You can use libraries like or for on-ledger verification. Ensure to check for delivered_amount and other relevant fields.

Understanding and implementing Xumm's transaction lifecycle is crucial for creating secure and efficient transactions on the XRP Ledger through the Xumm platform.

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: \

On average, the Xumm platform allows API consumers to make between 60~200 calls per minute. These numbers depend on the load on the platform and the use of the API consumer.

Some endpoints have lower limits, e.g.:

• POST a Payload (sign request) on average allows for sending 30 payloads per minute

• Fetching TXs (no need to use our platform, best use a native XRPL WebSocket connection): 60 requests per minute

• KYC status: 600 calls per minute

• Account metadata: 120 calls per minute

These numbers are not guarantees: they are averages and can be adjusted by our platform on the fly, based on your overall API call behaviour & end user interaction(s).

Raising API limits

If there are good reasons to assign elevated API limits, we're happy to have a discussion to hear about the reasons how your application consumes the Xumm API, and why your application needs higher limits. Please .

API limits will only be raised if:

• Your app does not use polling techniques: to retrieve the status of a payload, use the websocket we provide for status updates (or the createAndSubscribe / subscribe method provided by the SDK: / ). Backend applications can also use a webhook: .

• (If your app is an xApp) - Your app respects the xApp \

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.

Delivery Methods

Xumm offers various payload delivery methods:

• Deep Linking: Open the Xumm app with the payload already loaded.

• QR Code Scanning: Users scan a QR code to access the payload.

• Push Notifications: Send payloads as push notifications.

Status Updates

After delivering a payload, tracking its status is vital to know whether the user has interacted with it. Xumm provides mechanisms for obtaining notifications and results of payload interactions. You can learn more about this in the section.

Moving Forward

Now that you have an overview of what payload delivery entails in Xumm, you can delve into the specifics of each delivery method.

• Partial Payments: if you are processing received payments: make sure to check the delivered_amount (meta) field for the transaction outcome, and not the Amount field. Amount is the instruction, Delivered Amount is the actual delivered amount, which may be lower. See: https://xrpl.org/partial-payments.html

• When determining if users are able to send funds, make sure to take the Account and Owner reserve into account. See: You can obtain them with a server_info and account_info call on the chain (tip: use to interact with the network). Then calculate like this:\

• Use WebSockets over HTTP RPC (JSON POST) if you want realtime status updates from the ledger using the subscribe method. You can subsribe to ledger closes, transaction stream and account activity:

The SignIn transaction type is Xaman specific, signature only, can never be submitted. When sending a JSON transaction payload, you can use all XRPL transaction types, including a Xumm-specific "pseudo transaction type": SignIn.

The payload for a SignIn transaction can look like this:

After the user signs your SignIn request, the server-to-server call (to your configured Webhook location) will receive the signed transaction containing the signed transaction HEX blob.

You can verify the signature using the verify-xrpl-signature package:

Note: The SignIn transaction type is particularly useful when you want to authenticate a user without performing any transaction on the XRPL.

To offer users a direct payment link, you can send them straight to a URL (deeplink) or QR containing that same URL. The URL already contains destination, network, currency & other parameters.

Example URLs

A simple payment on Xahau for 2 XAH (native asset) to the rwietse... account:

A payment on the XRP Ledger for 2 $RLUSD to the rwietse... account:

Variants (universal)

If the user does not have Xaman installed, the above links will automatically fall back to a regular webpage showing the payment request information & download links to Xaman. If you however want to craft a link / QR that is not Xaman specific, you can use a protocol prefix which can be claimed by any XRPL supporting app in the ecosystem. The downside is that if one does not have a supporting app installed, there is no graceful fallback webpage.

Instead of prefixing with https://xaman.app/detect/request you can prefix with the xrpl:// protocol handler:

Parameters

• amount - The amount in native asset or issued currency to request - can be omitted, the user can then enter the amount

• network - The network the transaction should be sent on, can be XRPL or XAHAU, can be omitted, defaults to XRPL

App Developers

For App/Platform developers, there's an easy JS lib. to decode strings & parse them into normalised objects to support payment requests (and other ecosystem data formats):

Backend integration intro here...

Sample code

import { Xumm } from "xumm"

const { Xumm } = require('xumm

Step 1: Create Your xApp

Begin by opening your preferred code editor (in this case, we are using VS Code). Establish a project folder, and within this, create an index.html file. Type some text between the body tag.

Next, install the Live Server extension for VS Code.

Then, initiate the Live Server by clicking the 'Go Live' button/link located in the bottom right corner of VS Code. Take note of the port number that is displayed.

Step 2: Make Your Website or Web Service Globally Accessible

In your terminal, execute the command npm install -g localtunnel. If you encounter a permission error, use sudo npm install -g localtunnel.

Following this, run lt --port 5500, making sure to replace '5500' with the port number noted in Step 1.

The terminal will output a unique URL. Copy this, and open it in your browser. Here, submit your IP address (if you are unsure of your IP, a quick Google search of 'whatsmyip' will provide it).

For further information about this package, you can refer to the official .

Step 3: Set Up Your Xumm Developer Console Account

Navigate to the and create an xApp account.

Paste the URL acquired in Step 2 into the 'WebApp URL' section. In the 'Debug Device ID' section, enter your device ID (which can be found by navigating through Xumm -> settings -> advanced -> Device ID).

Step 4: Access Your xApp on xAppBuilder

Open xAppBuilder and scan the provided QR code using Xumm. Afterward, click on the xApp within xAppBuilder.

Now, when you make and save changes to your code in the VS code editor, these changes will be reflected in xAppBuilder, allowing for real-time modifications and testing.

A sign SignIn sign request can be as simple as this:

{
  "txjson": {
    "TransactionType": "SignIn"
  }
}

All Xumm payload options are valid for a SignIn transaction.

After the user signs your SignIn request, the server to server call (to your configured Webhook location) will receive the signed transaction containing the signed transaction HEX blob.

Response

When the user signs the Sign Request, you will get a signed transaction (that has never been submitted to the XRP Ledger).

You can now get the account address and some basic public account information from the payload details, and assign this information to your own local dataset, like a session.

Verify the signature

If you want to you can run your own signature verification on the signed SignIn pseudo transaction our platform returns to you. Of course the Xumm platform also verified the signature for you. Would you like to check yourself as well, we have created this package

xumm.payload?.get('some-payload-uuid').then(payloadResult => { /**/ })

If you want the actual blob and signature for the user signed in with the Xumm OAuth2 flow:

1. Get the JWT contents

2. Get the payload from the JWT (that's the Sign In payload)

3. Get that payload with the SDK

4. Check the payload data, the response.hex property holds the signed TX Blob

Now you can verify the signature using the xrpl-verify-signature package, or using any native method capable of verifying XRP Ledger signatures:

When creating Sign Requests from a backend environment, the Xumm SDK is called with your API Key & Secret. A payload can be opened by any user. A user will not get notified about a payload, unless if they interacted with the payload through a deeplink or scanning the Payload QR code.

If you want to deliver backend created Sign Requests to a user & the user is identified by your application, you have to provide a user_token to the payload. The user_token can be obtained after the user interacted with your application & signed a payload. See: Push

JavaScript/TypeScript

NPM

The Xaman Javascript/TypeScript SDK can be found on npm:

CDN

The latest version of the Xumm SDK is always available at:

Code samples

See

Warning (legacy packages)

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.

Seamless xApp Emulation

This is where xAppBuilder shines - it seamlessly emulates your xApp directly on your local development environment.

What does this mean for you? Instant, real-time feedback on your code modifications. Every tweak you save in your IDE, you can immediately see its effect on the emulated xApp.

xAppBuilder transforms these challenges into a smooth, manageable process.

Simplified OTT Replay

One Time Tokens (OTTs) and replay tokens can often present challenges, particularly for those new to xApp development.

xAppBuilder assists in addressing this issue by offering an automatic fetching feature for OTT and Replay OTT, reducing development time and allowing developers to concentrate more on enhancing the functionality of their xApp.

Real-Time Debugging

Debugging becomes a breeze with xAppBuilder. How? With live console logs of your xApp, spotting and fixing bugs is a more efficient process.

These real-time logs help you to monitor and understand your xApp's performance and behavior better.

Get Started with xAppBuilder

Ready to level up your xApp development process? xAppBuilder is now live for Linux on the , , and . Check out the demo video and download the tool today!

For more about xApps and Xumm, visit our . Here's to smoother, faster, and more efficient xApp development. Happy building, developers! 🏗️ 🛠️

Some things that may help debugging your xApp:

Remote JS Console

Using you can drop one line (script) in your page's <head> and get realtime access to the remote console (bi-directional).

Replay OTT's

If you open your own xApp using the device you added in the Xumm Developer Console as debug device (using the Device Identifier), the OTT (one time token) can be replayed when visiting from the same IP address.

• Make sure your device (Xumm - Settings - Advanced) is whitelisted as Debug Identifier in the Xumm Developer Console

• Make sure your phone and computer are visiting from the same public IP address (e.g. by having them both on the same WiFi and internet connection

• Obtain your OTT in the xApp: it's the value of the xAppToken query parameter. Your xApp is being called with https://your-url/?xAppToken=...

You will now see your xApp in your browser.

Use your local dev URL as xApp URL

Use a tool like ngrok () or localtunnel.me () to temporarily publish your local development URL to a publicly available URL you can use to access your xApp during live debug/development.

Troubleshooting

If an xApp integration doesn't allow for running commands, and the console shows messages like "Couldn't connect to host", problems are a result of the same cause: CORS issues.

• The SDK can't reach Xumm (the app), so:

• "Could not contact Xumm host" error appears, and:

• For example: the openSignRequest trigger doesn't fire, the Sign Request doesn't open, and:

• Xumm keeps on trying, and is stalling the init. to see if the host can be reached - yielding "Attempt n » Retry" console messages (just to make sure it isn't a timing issue).

Find the cause

Check the following things:

1. Are you getting this messages from your frontend console, or backend (node?)

2. Do you have CORS setup correctly? (Allow iframe loading, allow CORS (origin: *)

3. Does your app run over http (instead of https with a valid certificate?)

While #3 and #4 should be valid, we've seen some Android phones where this prevented the integration from working. We use ngrok to work around the local http and non standard port development issues.

\

CORS (Cross-Origin Resource Sharing) is a mechanism that allows a web page from one origin (domain) to access resources from another origin. In other words, it is a security feature implemented by web browsers that restricts a web page from making requests to a different domain than the one that served the web page.

The Xumm API endpoints allow cross origin requests: we want your web application to be able to make calls to the Xumm platform using the credential (JWT) you have received when a user logged in.

If you are building a Backend (SDK / API)integration, CORS is irrelevant.

If you are building something in the browser (a web application), the most convenient way to interact with the Xumm platform is through the Javascript/TypeScript SDK: https://github.com/XRPL-Labs/Developer-Help-Center/blob/main/environments/browser-web3/broken-reference/README.md.

If you are building your own, custom implementation, you will have to make sure you are calling the : only our JWT (JSON Web Token) routes allow for cross origin calls, and serve the right headers to allow your browser to do so.

While developing your xApp, you may want to easily test & debug your web application. You may even benefit from live reaload during development. You can expose your local development environment with a tool like https://ngrok.io or https://localtunnel.me and configure your public URL as your xApp URL.

You can get access to the remote browser console using the techniques explained in the Development & Debugging article.

If you want to share your xApp with a small group of testers or team members, you can ask them for their Xumm Device Identifier (Xumm - Settings - Advanced). You can add up to 10 Device Identifiers as xApp testers, so they can open your sandboxed xApp.

When you want to develop in your local browser instead of in Xumm, please see the "OTT Replay" section in the article.

The following properties are part of the user object. Every property is a Promise that is resolved when the user is signed in.

• account - r-address

• picture - Profile picture or Hashicon URL

• name - Account name (if present) - e.g. Xumm Pro account name

• domain - Domain name (if present) for account

• source - Information source (e.g. a specific explorer)

• networkType - Enum, e.g. MAINNET, TESTNET, ... the user is connected to

• networkEndpoint - WebSocket endpoint to connect to the network

• blocked - If the account is on a blacklist (e.g. because of scams)

• kycApproved - If the account owner went through opt in KYC with Xumm

• proSubscription - If the account has a Xumm Pro subscription

• profile - Xumm Pro Profile slug (URL)

• token - User Token for future sign request Push delivery

The token field contains a user_token; this token is specific to both the application (SDK) credentials and the end user. It grants you access to asynchronously send notifications to the end user (for 30 days, unless granted long living tokens).

When your application creates a payload for the end user to sign using the SDK session (or JWT), a user will always receive a push notification.

If you want to asynchronously create a payload on your backend using the flow, you can include this token in the user_token field of the payload.

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.

How to Deliver Payloads within xApps

1. Create a Payload: First, you need to create a payload with the transaction details. This payload is essentially a sign request you want the user to interact with. See:

2. Use Xumm SDK: To deliver the payload within your xApp, use the Xumm SDK. The SDK provides functions allowing you to seamlessly integrate the payload within your xApp. See:

3. Once integrated, the payload will be displayed to the user within your xApp. The user can then review and interact with the payload without leaving the xApp.

The Payload

To request delivery of 5 RLUSD:

{
  options: {
    force_network: 'MAINNET',
    pathfinding: true
  },
  custom_meta: {
    instruction: 'Pay for this and that...'
  },
  txjson: {
    TransactionType: 'Payment',
    Destination: 'r...YourAddress...',
    Amount: {
      currency: '524C555344000000000000000000000000000000',
      issuer: 'rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De',
      value: '15'
    }
  }
}

It's as simple as that. Xaman sees Amount, Xaman sees pathfinding in the option and done!

You will always get what you asked for, user can pay with anything. delivered_amount is always your preferred currency from Amount.

The Sign Request (user facing)

When a payload like above is opened by the user, they will have to wait a few seconds for the XRP Ledger to finish a Pathfinding request, to see which assets the user posesses that can satisfy delivering the requested amount (with in-line, in-transaction, atomic conversion of the asset the user sends to the asset you want to receive).

Syntax

xumm.xapp.scanQr()
xumm.xapp.on('qr', data => {
    console.log('QR', data)
})

Response

Returns an event: qr. Use to subscribe to the return data.

Parameters

The refreshEvents param. is optional. If passed (and true) the Event list will be forcefully refreshed (updated) when the xApp closes. This can be useful if the xApp closes programatically after e.g. resolving (cancelling) or signing a Sign Request.

{ refreshEvents: true }

Syntax

Parameters

{ uuid: '...' }

Syntax

xumm.payload.create({
  TransactionType: 'Payment',
  Destination: 'rfHn6cB5mmqZ6fHZ4fdemCDSxqLTijgMwo',
  Amount: String(1)
}).then(payload => {
  xumm.xapp.openSignRequest(payload)
})

Response

Returns an event: payload. Use to subscribe to the return data.

The getTransaction method allows you to get the transaction outcome (mainnet) live from the XRP ledger, as fetched for you by the XUMM backend.

Note: it's best to retrieve these results yourself instead of relying on the XUMM platform to get live XRPL transaction information! You can use the xrpl-txdata package to do this:

const txInfo = await Sdk.getTransaction(txHash);

Returns: <XrplTransaction>

Parameters

The provided value of the xApp property should be a valid xApp identifier.

Syntax

This makes it really convenient to obtain three things at once, making calls to your own backend with an Autorization: Bearer {The Xumm JWT} header:

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

xApps are WebApps. They are opened in Xumm for a great user experience. They add value (tooling, wizards) for end users, using Sign Requests to help users perform tasks on the XRPL.

To add value for end users, your xApp will most likely implement some of the features Xumm offers natively in your xApp. E.g. open the QR scanner, Account Destination Picker, or start a Sign Request flow. Then to receive the response from these native Xumm flows in your xApp (WebApp).

Your xApp can trigger specific actions in Xumm:

These actions can be sent form your xApp (frontend Javascript) context, and will trigger functionality native to the Xumm app:

Font family

The main application uses the font-family: proxima-nova, sans-serif. Only when using this font for your (web) xApp to be embedded in XUMM, use this stylesheet:

When offering your application anywhere else than as embedded (web) xApp, check your licensing needs and requirements for the use of Proxima Nova.

Q: I do not see my xApp in the xAppBuilder. What should I do?

A: Ensure your Device ID has been entered in the Debug Device ID section.

• Step 1: Retrieve your Device ID from Xumm by going to Xumm -> Settings -> Advanced -> Device ID (double tap to copy it).

• 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

The object is basically a object with the created payload results in the created property:

All information that applies on Sdk.payload.create() and Sdk.payload.subscribe() applies. / . For the contents of a Payload, see the . Differences are:

1. The input for a

The process to integrate Sign In with Xumm and transaction signing by Xumm with your own native app is actually quite similar to either the flow: it uses OAuth2 (PKCE or Implicit flow) or the flow.

Combined with "Deep Links", your application sending off the user to Xumm will happen with a simple app-redirect. After the user interacted with your sign request, Xumm will return the user to the Return URL: the URL you added to your sign request payload to be opened post-signing.

If your application registers a Deep Link URL as well, and you pass that URL to Xumm as the payload Return URL, the user will be redirected back to your app. To match state, you can add information to the Deep Link URL Xumm sends the user to.

The getKycStatus return the KYC status of a user based on a user_token, issued after the user signed a Sign Request (from your app) before (see Payloads - Intro).

If a user token specified is invalid, revoked, expired, etc. the method will always return NONE, just like when a user didn't go through KYC. You cannot distinct a non-KYC'd user from an invalid token.

Alternatively, KYC status can be retrieved for an XPRL account address: the address selected in XUMM when the session KYC was initiated by.

... or using an account address:

Parameters

If you want to request the destination address only, skipping the "Destination Tag" required check & input, you can provide the ignoreDestinationTag param. If not provided (or false) Xumm will chech if the destination account requires a Destination Tag and ask the user to input one.

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 ) or use a subscription to receive live payload updates (for non-SDK users: ).

You can get() a payload by:

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:

As you can see the payload looks like a regular XRPL transaction, wrapped in an txjson object, omitting the mandatory Account

To prevent showing a double loader (first the Xumm xApp loader, then your xApp's loader while hydrating / booting) you have to . The xApp will then show the Xumm native loader, until your application calls the ready() method on the Xumm SDK.

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 ) looks like:

Welcome to the Xaman Developer Docs! Xaman is a powerful platform designed to make your interaction with the XRP Ledger (XRPL) seamless. Whether you are an experienced developer or just getting started, Xaman offers a range of features, including xApps, payloads, transaction signing, and much more. This documentation will guide you through the essentials to get you up and running in no time.

While app users can simply use the Xaman app to manage their XRP ledger accounts, balances and transactions, the true power of Xaman can be experienced through the Xaman SDK, using our platform made available for developers.

Ways to interact

The Xaman SDK can be used to interact with Xaman users. An example can be a "sign request", where the user is asked to sign a transaction, identification (sign in) or a user interface presented in Xaman (xApp).

Packages

The Xaman SDK offers a ready to use Javascript & Typescript SDK for all frontend and backend projects. With only minor differences depending on the environment you are using the SDK in, the SDK is the most convenient way to interact with Xaman users & the Xaman ecosystem.

If you are not working in a environment and prefer to build your own backend implementation, you can use our or use one of our SDKs for , or

While app users can simply use the Xaman application interact with the XRP Ledger with their accounts, balances and transactions, the true power of Xaman is unleashed through the platform available for developers.

This way users can interact with third party tools & platforms in the most secure and convenient way, while developers don't have to worry about wallet & key management.

Concept

XRP Ledger transactions are traditionally user initiated: users open their wallet, enter the destination, amount, etc. and then you submit a transaction. This is referred to as a Push Transaction.

In retail / e-commerce & third party interaction scenarios, the ideal flow is inverted: a Pull Transaction. The third party environment wants the user to sign a specific transaction, and a transaction to sign is offered to the user.

This is where the Xaman platform comes in. An XRP Ledger transaction template can be delivered to the end user through the Xaman platform. This is called a Sign Request.

Interaction

The most convenient way to interact with the Xaman platform is through the JavaScript/TypeScript SDK: . There are also some other SDKs available for Backend use in other languages:

The Xaman platform allows for easy integration in your application & workflow. Make sure to check the documentation for your environment:

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:

The Xumm SDK can run fully client side: either as part of your compiled web app or using plain HTML and Javascript using our ready to use browserified version.

Using the Xumm SDK, you can easily add "Sign in with Xumm" capabilities to your web app. You don't even need a backend. You get the full "Web3" experience (sign in with a blockchain account) with our "Web2" compatible stack (see: Identity (OAuth2, OpenID) / Native Apps).

Capabilities

Using the Xumm SDK in your web project, you get:

• Sign in with a QR code for when loaded on a desktop

• Deeplink (redirect to Xumm, back to your web app) on mobile

• Basic user information: XRP Ledger account address, icon (hashicon or even avatar), connected chain (mainnet, testnet, ..) & some basic information about the end user's environment (currency, language, ...)

Sample code

More links

For the SDK documentation (objects, methods), see the SDK section: . For a simple demo of the Xumm SDK in a React Native environment, check this sample repository:

xApps are web apps. They are offered to users as integrated apps, opened in Xumm for a great user experience. They add value (tools, apps, wizards, ...) for end users. They receive context information when opened, and can interact with some of the native Xumm features & users through Sign Requests.

Permissions

xApps have extra special permissions, allowing the xApp (web app) to interact with some of the native Xumm features:

• They receive context (user account selected in Xumm when opened, Xumm theme, input params, account type (eg. Tangem / ...)

• They can trigger overlay Sign Requests and receive callback info

• They can trigger the QR scanner and receive scanned QR data

Opening xApps

xApps can be opened (triggered) in lots of ways:

• In the Xumm shortlist (we feature some apps, they get replaced by frequently used apps by the user)

• From the xApp directory

• By opening a deeplink (browser / from within another app)

Advanced ways to open xApps

• By attaching an xApp memo to an XRPL TX (so the Event list will show there's an xApp attached to the TX)

• Using push notifications

• From the Event list, as an xApp session pushed to a Xumm user

xApp example use cases

• Trading interface (offloads signing to Xumm)

• Admission ticket checking

• NFT marketplaces / viewers

Sample code

• Verify transactions on ledger: Secure Payment Verification

1. Fetch Payload Results: Trigger your application to fetch payload results after receiving a Webhook callback.

2. Inspect Payload Output: Confirm meta.resolved and meta.signed are both true in the payload output.

3. Identify Dispatched Node Type: Ensure response.dispatched_nodetype is "MAINNET" for real payments.

4. Validate Transaction ID: Validate the response.txid value on the ledger.

5. Examine Delivered Amount: Confirm the meta.delivered_amount equals the expected payment amount.

6. Use xrpl-txdata Package: Establish a connection to the XRP Ledger, fetch the transaction by hash, and cross-verify transaction details with the XRPL ledger.

• Consider the end user network:

1. Network Independence: Use the Xumm API/SDK, which operates independently of the network, to allow users the freedom of network choice.

2. Network Information: Ensure the results of a signed payload include the network the user was on during the signing.

3. Forced Network Identifier: Check for the expected result in the Payload results or specify a particular network using a forced network identifier in a payload.

• Verify Webhook signatures:

1. Secure Your Webhooks: Implement appropriate security measures.

2. Verify Payloads: Authenticate received payloads.

3. Error Handling: Develop robust error management mechanisms.

• Protecting your application from the "partial payments exploit" is crucial when implementing payment functionalities. Instead of relying on the Amount field, which merely indicates the transaction instruction, you should base your logic on the delivered_amount field in the transaction metadata. The Amount field is the instruction, and the delivered_amount metadata field is the result. For more detailed information, please refer to the .\

• xApps:

1. xApp Creation & Audit: Anyone can create sandbox xApps, but public release requires an audit by XRPL Labs for user safety, compliance, and value addition.

2. User Experience: xApps must be self-explanatory, prevent dangerous mistakes, and provide a unique experience tailored to Xumm users.

3. Technical & Styling Standards: xApps must meet Xumm's technical guidelines and respect or have unique styling.

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

Offering a direct link / QR code to a payload does not come with the advantages of creating a Payloads (sign requests) of getting live feedback & webhooks based on the user's engagement.

The advantage of a simple Sign Link / QR is that you can craft the link / QR once, and it will be available for all users without further code implementations.

Simple Sign Link/QR is available for the following transaction type(s)

• TrustSet (adding a Trust Line, a.k.a. adding a Token)

Crafting the link / QR contents

Example QR:

xApps are natively aware of the end user context, so a Sign Request payload can easily be served with the xumm.xapp.openSignRequest method: