09.md

LUD-09: successAction field for payRequest.

author: rossdyson author: akumaigorodski discussion: https://t.me/lnurl/256

---

Standardization of the successAction field

This defines a field successAction returned by the SERVICE along with the payment request in the second callback.

It must be stored by the WALLET and shown to the user as soon as a payment succeeds.

To implement this, a SERVICE must alter its JSON response to the second callback to include it like the following:

 {
     "pr": string,
     "routes": [],
+   "successAction": Object
 }

In which Object has the format:

{
   tag: string, // action type
   ...rest of fields depends on tag value
}

This document defines the message and the url types. See examples:

{
  "tag": "message",
  "message": "Thank you for using bike-over-ln co! Your rental bike is unlocked now" // Up to 144 characters
}

{
   "tag": "url",
   "description": "Thank you for your purchase. Here is your order details", // Up to 144 characters
   "url": "https://www.ln-service.com/order/<orderId>" // url domain must be the same as `callback` domain at step 3
}

LNURL-pay flow change

A WALLET that decides to implement this scheme must, after a payment is complete and a successAction is present, show a popup or screen to the user with the contents of that successAction.

For message, a toaster or popup is sufficient. For url, the wallet should give the user a popup which displays description, url, and a 'open' button to open the url in a new browser tab.

WALLET should also store successAction data on the transaction record.

Support for successAction types

Since other successAction types can be added in the future, if a successAction is present in the response from SERVICE, a WALLET must make sure that its tag value is of a kind it supports, otherwise it must not proceed with the payment -- or the user might end up paying and not seeing its expected successAction.