Your first payload

The most basic payload you can POST to the https://xumm.app/api/v1/platform/payload endpoint only requires a valid TransactionType + the mandatory fields and values for the given transaction type. You can however leave out the fields that are client (signer) specific, like in this example (Payment) the "Account"-field, as the xumm app running on the device of the end user will fill that field based on the selected account used to sign.

{ 
  "txjson": {
    "TransactionType": "Payment",
    "Destination": "rPdvC6ccq8hCdPKSPJkPmyZ4Mi1oG2FFkT",
    "Fee": "12"
  }
}

📘

Changes to the default XRP ledger transaction JSON

Please note that certain transaction fields normally required, may be omitted when using the xumm platform. See Payload transaction data.

Optionally, you can add more properties like options and user_token to the payload data, see the payload endpoint. Note that for Typescript developers, definitions of the payload object are available in the XUMM SDK.

Read more about adding options and/or the user token in the API Docs

Using 𝘅𝘂𝗺𝗺 to sign in users

If you want to identify a user based on a signed transaction (without asking the user for a payment) you can send a payload with a false TransactionType.

See: User Sign In

By sending SignIn as the transaction type, xumm will show an alternative "sign in" screen. When the user signs, the transaction:

• Will be signed
• Will not be submitted to the XRPL
• The signed transaction HEX will be delivered to your application (webhook / API call)

You can then use the signed HEX to verify the signature and identify the user. A sample payload for a sign in action could look something like this:

{ 
  "options": {
    "submit": false,
    "expire": 240,
    "return_url": {
      "app": "https://xrptipbot.com/signin?payload={id}",
      "web": "https://xrptipbot.com/signin?payload={id}"
    }
  },
  "user_token": "c5bc4ccc-28fa-4080-b702-0d3aac97b993",
  "txjson": {
    "TransactionType" : "SignIn"
  }
}

In this example, the user_token (if valid) will result in a direct push notification, with the sign request, to the end user. The sign in request will expire after 240 minutes, and the transaction will not be submitted ("submit": false) to the XRPL (as a SignIn transaction type does not exist on the XRPL).

See: Obtaining a user token

📘

A note on the return_url parameter

In the previous SignIn example, the given return_url for both app and web will redirect both the desktop browser flow (web) and the mobile (app) flow. In a real transaction scenario, only one of the two return URL's will most likely be entered.

If the user originates from a webapplication (desktop), the app return URL can be left out, so the user will return back home to the xumm app after signing, while the browser will redirect them back to your webapplication.

If the user originates from your own application, the web return URL can be left out, as the end user will be taken directly to the xumm app on their device, using the payload deep link, then returned to your application deep link.