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.