January 2023 doc updates

Author: aurelienshz

SDK_reference.md

@@ -79,7 +79,7 @@ to be present:
 
 Signature: `(payment: PaymentDTO) => void`
 
-Every time the user is authenticated, and when they try to start a new payment flow, the SDK checks that there is no
+Every time when the user is authenticated, and when they try to start a new payment flow, the SDK checks that there is no
 incomplete payment for this user. An incomplete payment, in this context, is a payment which has been submitted to
 the Pi blockchain, but where `status.developer_completed` is still `false` (i.e. the developer has not called the
 `/complete` endpoint on this payment).
@@ -157,7 +157,8 @@ Example: `{ orderId: 1234, itemIds: [11, 42, 314] }`
 
 Signature: `(paymentId: string) => void`
 
-This is called when the payment identifier (paymentId) is obtained from Pi Servers.
+This is called when the payment identifier (paymentId) is obtained from Pi Servers. During the approval time period, this callback will be invoked multiple times in case of failure.
+If the initial trial fails, the Pi SDK will continue to invoke the function roughly every 10 seconds until the approval timer ends.
 
 Use this callback to send the paymentId to your backend for **Server-Side Approval**.
 Read more about Server-Side Approval and the full payment flow in the dedicated
@@ -167,7 +168,8 @@ Read more about Server-Side Approval and the full payment flow in the dedicated
 
 Signature: `(paymentId: string, txid: string) => void`
 
-This is called when the user has submitted the transaction to the Pi blockchain.
+This is called when the user has submitted the transaction to the Pi blockchain. During the completion time period, this callback will be invoked multiple times in case of failure.
+If the initial trial fails, the Pi SDK will continue to invoke the function roughly every 10 seconds until the completion timer ends.
 
 Use this callback to send the blockchain transaction identifier (txid), along with the paymentId
 to your backend for **Server-Side Completion**.

developer_portal.md

@@ -24,12 +24,12 @@ With the help of Pi SDK and Pi API, you can create applications that run within
 
 > When the app is connecting to the Pi Mainnet, you can pair one of your testnet apps to the mainnet app. More specific usage is coming soon in the future.
 
-> When you're hosting the app on your server, you will also need to provide the url. Notice that you'll be asked to verify the ownership of the url after you register the app. After you filled in the required fields, you can submit to register your app by clicking on `Submit` button at the bottom of the page.
-
 <div style="text-align:center;">
     <img src="./img/dev_portal_new_3.png" alt="drawing" width="200"/>
 </div>
 
+> When you're hosting the app on your server, you will also need to provide the url. Notice that you'll be asked to verify the ownership of the url after you register the app. After you filled in the required fields, you can submit to register your app by clicking on `Submit` button at the bottom of the page.
+
 3. After you register your app, you can see your apps in the main page. If you selected the paired app for your mainnet app, it will show like the following.
 
 <div style="text-align:center;">

img/payment_flow_simplified.png

@@ -64,3 +64,17 @@ This implementation is your responsibility.
 > have made a payment. If the API call for Server-Side completion
 > returns a non-200 error code, **do not** mark the payment as complete on your
 > side, and **do not** deliver whatever the user was trying to buy.
+
+
+## Simplified flow
+
+This diagram shows the same payment flow from your app's point of view in a simplified manner.
+
+![Payment flow](./img/payment_flow_simplified.png)
+
+1. Use the Pi SDK function to initiate the payment
+2. A callback function that gets called automatically by the Pi SDK (letting your App Server know that it needs to make an approve API request)
+3. An API request from your App Server to the Pi Server to approve the payment (letting the Pi Server know that you are aware of this payment)
+4. The Pi browser shows the payment detail page to a user, and we are waiting until the user signs the transaction
+5. A callback function that gets called automatically by the Pi SDK (letting your App Server know that it needs to make an complete API request)
+6. An API request from your App Server to the Pi Server to complete the payment (letting the Pi Server know that you completed this payment)