Add user info request webhook, make bank account info optional during user creation

Author: shreyav

docusaurus-docs/docs/receiving-payments.md

@@ -43,7 +43,7 @@ The process consists of five main steps:
 1. **Platform configuration** (one-time setup) to set your UMA domain and required counterparty fields
 2. **Register users** with their bank account information so they can receive payments
 3. **Set up webhook endpoints** to receive notifications about incoming payments
-4. **Receive and approve/reject incoming payments** via webhooks
+4. **Provide user information and approve/reject incoming payments** via webhooks
 5. **Receive completion notification** when the payment completes
 
 ## Step 1: Platform configuration (one-time setup)
@@ -122,12 +122,13 @@ When someone initiates a payment to one of your users' UMA addresses, you'll rec
     },
     "reconciliationInstructions": {
       "reference": "REF-123456789"
-    },
-    "requestedReceiverUserInfoFields": [
-      { "name": "NATIONALITY", "mandatory": true },
-      { "name": "FULL_NAME", "mandatory": true }
-    ]
+    }
   },
+  "requestedReceiverUserInfoFields": [
+    { "name": "NATIONALITY", "mandatory": true },
+    { "name": "FULL_NAME", "mandatory": true }
+  ],
+  "requiresBankAccountInfo": true,
   "timestamp": "2023-08-15T14:32:00Z",
   "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
   "type": "INCOMING_PAYMENT"
@@ -142,8 +143,8 @@ You have two options for approving or rejecting the payment:
 
 To approve the payment synchronously, respond with a `200 OK` status:
 
-- If the `requestedReceiverUserInfoFields` array was present in the webhook request and contained mandatory fields, your `200 OK` response **must** include a JSON body containing a `receiverUserInfo` object. This object should contain the key-value pairs for the information fields that were requested.
-- If `requestedReceiverUserInfoFields` was not present, was empty, or contained only non-mandatory fields for which you have no information, your `200 OK` response can have an empty body.
+- If the `requestedReceiverUserInfoFields` array was present in the webhook request and contained mandatory fields, your `200 OK` response **must** include a JSON body containing a `receiverUserInfo` object. This object should contain the key-value pairs for the information fields that were requested. If `requiresBankAccountInfo` was `true` in the webhook request, your response must also include your user's `bankAccountInfo`.
+- If `requestedReceiverUserInfoFields` was not present, was empty, or contained only non-mandatory fields for which you have no information and `requiresBankAccountInfo` was false, your `200 OK` response can have an empty body.
 
 Example `200 OK` response body when information was requested and provided:
 
@@ -152,6 +153,10 @@ Example `200 OK` response body when information was requested and provided:
   "receiverUserInfo": {
     "NATIONALITY": "US",
     "FULL_NAME": "John Receiver"
+  },
+  "bankAccountInfo": {
+    "vpa": "receiver@psp",
+    "accountType": "UPI"
   }
 }
 ```
@@ -190,6 +195,10 @@ Request body (if information was requested):
   "receiverUserInfo": {
     "NATIONALITY": "US",
     "FULL_NAME": "John Receiver"
+  },
+  "bankAccountInfo": {
+    "vpa": "receiver@psp",
+    "accountType": "UPI"
   }
 }
 ```

openapi.yaml

@@ -2359,6 +2359,7 @@ webhooks:
             Webhook received successfully. 
             For PENDING transactions, this indicates approval to proceed with the payment.
             If `requestedReceiverUserInfoFields` were present in the webhook request, the corresponding fields for the recipient must be included in this response in the `receiverUserInfo` object.
+            If `requiresBankAccountInfo` is true, the platform must include the bank account information in the webhook response in the `bankAccountInfo` object.
           content:
             application/json:
               schema:
@@ -2787,8 +2788,6 @@ components:
       allOf:
         - $ref: '#/components/schemas/User'
         - type: object
-          required:
-            - bankAccountInfo
           properties:
             fullName:
               type: string
@@ -3527,6 +3526,10 @@ components:
           type: string
           description: UMA domain for this platform
           example: platform.uma.domain
+        proxyUmaaasSubdomain:
+          type: string
+          description: The subdomain that incoming requests will be proxied to
+          example: platform
         webhookEndpoint:
           type: string
           description: URL where webhook notifications will be sent
@@ -4335,7 +4338,11 @@ components:
               type: array
               items:
                 $ref: '#/components/schemas/CounterpartyFieldDefinition'
-              description: Information required by the sender's VASP about the recipient. Platform must provide these in the 200 OK response if approving. Note that this only includes fields which UMAaaS does not already have from initial user registration.
+              description: Information required by the sender's VASP or the banking provider about the recipient. Platform must provide these in the 200 OK response if approving. Note that this only includes fields which UMAaaS does not already have from initial user registration.
+            requiresBankAccountInfo:
+              type: boolean
+              description: Whether the platform needs to provide the bank account information in the webhook response. Note that this is only applicable if bank account information was not provided during initial user registration.
+              example: true
     BaseWebhook:
       type: object
       required:
@@ -4429,6 +4436,9 @@ components:
           type: object
           additionalProperties: true
           description: Information about the recipient, provided by the platform if requested in the webhook via `requestedReceiverUserInfoFields` and the payment is approved.
+        bankAccountInfo:
+          $ref: '#/components/schemas/UserBankAccountInfo'
+          description: Bank account information, provided by the platform if `requiresBankAccountInfo` is true.
     IncomingPaymentWebhookForbiddenResponse:
       allOf:
         - $ref: '#/components/schemas/Error'

openapi/components/schemas/transactions/IncomingTransaction.yaml

@@ -9,7 +9,7 @@ allOf:
         description: Amount received in the recipient's currency
       reconciliationInstructions:
         $ref: ../common/ReconciliationInstructions.yaml
-        description: Included for all transactions except those with "CREATED" status
+        description: Present when available; this varies by region and banking provider and may not be included until "COMPLETED" status
       rateDetails:
         $ref: ./IncomingRateDetails.yaml
         description: Details about the rate and fees for the transaction.

openapi/components/schemas/users/IndividualUser.yaml

@@ -1,8 +1,6 @@
 allOf:
   - $ref: ./User.yaml
   - type: object
-    required:
-      - bankAccountInfo
     properties:
       fullName:
         type: string

openapi/components/schemas/webhooks/IncomingPaymentWebhook.yaml

@@ -15,7 +15,14 @@ allOf:
         items:
           $ref: ../common/CounterpartyFieldDefinition.yaml
         description: >-
-          Information required by the sender's VASP about the recipient.
-          Platform must provide these in the 200 OK response if approving.
-          Note that this only includes fields which UMAaaS does not
-          already have from initial user registration.
+          Information required by the sender's VASP or the banking provider
+          about the recipient. Platform must provide these in the 200 OK
+          response if approving. Note that this only includes fields which
+          UMAaaS does not already have from initial user registration.
+      requiresBankAccountInfo:
+        type: boolean
+        description: >-
+          Whether the platform needs to provide the bank account information
+          in the webhook response. Note that this is only applicable if bank
+          account information was not provided during initial user registration.
+        example: true

openapi/components/schemas/webhooks/IncomingPaymentWebhookResponse.yaml

@@ -7,3 +7,8 @@ properties:
       Information about the recipient, provided by the platform if
       requested in the webhook via `requestedReceiverUserInfoFields`
       and the payment is approved.
+  bankAccountInfo:
+    $ref: '../users/UserBankAccountInfo.yaml'
+    description: >-
+      Bank account information, provided by the platform if
+      `requiresBankAccountInfo` is true.

openapi/webhooks/incoming-payment.yaml

@@ -136,6 +136,9 @@ post:
         If `requestedReceiverUserInfoFields` were present in the webhook
         request, the corresponding fields for the recipient must be included in
         this response in the `receiverUserInfo` object.
+
+        If `requiresBankAccountInfo` is true, the platform must include the bank
+        account information in the webhook response in the `bankAccountInfo` object.
       content:
         application/json:
           schema: