Add partner validation documentation

docs/flows/crypto-offramp.mdx

@@ -23,6 +23,14 @@ The crypto off-ramp flow allows a user to sell cryptocurrency and convert it int
   - `displayName` (_optional_): Partner name to be displayed to the user.
   - `fee` (_optional_): An object configuring the partner fee to be charged.
     - `percentage`: Percentage of the total source amount (the maximum allowed value is "5").
+  - `validation` (_optional_): Custom request validation parameters.
+    - `device`: (_optional_): Device parameters to validate.
+      - `alg` (_optional_): Algorithm used to hash the fields. In case no algorithm is set, we'll be assumed that `sha256` was used.
+      - `fields` (_optional_): Fields that have been hashed.
+      - `hash` (_optional_): Result of hashing the fields appended in the given order, without any extra characters or whitespaces, using the given algorithm.
+      - `ip` (_optional_): User IP on partner's side that we should validate remains the same.
+      - `ipVersion` (_optional_): Version of IP value used on the hash.
+      - `user-agent` (_optional_): User agent used on partner's side that we should validate remains the same.
 - `refund` (_optional_): An object configuring the refund details. The asset and network of the refund will be the same as the source asset and network.
   - `address`: Address to which the refund will be sent.
   - `tag` (_optional_): Tag of the crypto transaction, used to complement the `address`.
@@ -83,6 +91,12 @@ We recommend that you use `XRP` for testing purposes when integrating Topper sin
     "displayName": "ACME",
     "fee": {
       "percentage": "1"
+    },
+    validation: {
+      device:{
+        ip:'1.2.3.4',
+        'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)'
+      }
     }
   },
   "refund": {
@@ -118,6 +132,23 @@ We recommend that you use `XRP` for testing purposes when integrating Topper sin
   </TabItem>
 </Tabs>
 
+### Custom partner validation
+
+To increase customer security we support an extra layer of validations that can be customizable by our partners. This layer includes validations from customer's device, like IP and user agent, that we ensure is the same as the one provided by you. In case of any mismatch, the user request to initiate a widget session will fail.
+We accept this validation parameters as plain strings or as an hashed string. If you send us hashed parameters, we'll fetch the same parameters we receive from the user request, hash them and compare if both hashes are equal.
+If you plan on using hashed validation, please check the example below to see how you should hash your data.
+
+```js
+import { createHash } from 'node:crypto';
+
+await createHash('sha256')
+  .update('1.2.3.4')
+  .digest('hex');
+```
+
+  :::note
+  When validating user IP, if the IP versions mismatch, validation will be partially (plain string validation) or entirely (hashed validation) skipped.
+
 ## Events
 
 Full information about the available events and their associated payloads can be found on the [events page](../events/crypto-offramp.mdx).

docs/flows/crypto-onramp.mdx

@@ -15,14 +15,22 @@ The crypto on-ramp flow allows a user to add funds from a credit or debit card t
   <TabItem label="Schema" value="schema" default>
 
 - `partner` (_optional_): Partner object.
+  - `continueUrl` (_optional_): URL to redirect the user to after the order is placed.
+  - `continueUrlTarget` (_optional_): In which tab should the `continueUrl` be opened.
   - `displayName` (_optional_): Partner name to be displayed to the user.
   - `fee` (_optional_): An object configuring the partner fee to be charged.
     - `percentage`: Percentage of the total source amount (the maximum allowed value is "5").
-  - `continueUrl` (_optional_): URL to redirect the user to after the order is placed.
-  - `continueUrlTarget` (_optional_): In which tab should the `continueUrl` be opened.
     - `new-tab`: Open in a new tab.
     - `same-tab`: Open in the same tab or iframe (default).
     - `parent-tab`: Useful only in an iframe: open in the tab that contains the iframe.
+  - `validation` (_optional_): Custom request validation parameters.
+    - `device`: (_optional_): Device parameters to validate.
+      - `alg` (_optional_): Algorithm used to hash the fields. In case no algorithm is set, we'll be assumed that `sha256` was used.
+      - `fields` (_optional_): Fields that have been hashed.
+      - `hash` (_optional_): Result of hashing the fields appended in the given order, without any extra characters or whitespaces, using the given algorithm.
+      - `ip` (_optional_): User IP on partner's side that we should validate remains the same.
+      - `ipVersion` (_optional_): Version of IP value used on the hash.
+      - `user-agent` (_optional_): User agent used on partner's side that we should validate remains the same.
 - `partnerFee` (_deprecated_): Use `partner.fee` instead.
 - `simulation` (_optional_): Simulation object.
   - `country` (_optional_): Country to use during simulations, in alpha-2 code format; It will be ignored after the user is authenticated and the user's country will be used.
@@ -71,12 +79,18 @@ We recommend that you use `XRP` for testing purposes when integrating Topper sin
   "sub": "b9fe022b-f436-49e1-bb89-6f2e8eabf336",
   // highlight-start
   "partner": {
+    "continueUrl": "https://example.com",
+    "continueUrlTarget": "new-tab",
     "displayName": "ACME",
     "fee": {
       "percentage": "1"
     },
-    "continueUrl": "https://example.com",
-    "continueUrlTarget": "new-tab"
+    validation: {
+      device:{
+        ip:'1.2.3.4',
+        'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)'
+      }
+    }
   },
   "simulation": {
     "country": "US"
@@ -109,6 +123,23 @@ We recommend that you use `XRP` for testing purposes when integrating Topper sin
   </TabItem>
 </Tabs>
 
+### Custom partner validation
+
+To increase customer security we support an extra layer of validations that can be customizable by our partners. This layer includes validations from customer's device, like IP and user agent, that we ensure is the same as the one provided by you. In case of any mismatch, the user request to initiate a widget session will fail.
+We accept this validation parameters as plain strings or as an hashed string. If you send us hashed parameters, we'll fetch the same parameters we receive from the user request, hash them and compare if both hashes are equal.
+If you plan on using hashed validation, please check the example below to see how you should hash your data.
+
+```js
+import { createHash } from 'node:crypto';
+
+await createHash('sha256')
+  .update('1.2.3.4')
+  .digest('hex');
+```
+
+:::note
+When validating user IP, if the IP versions mismatch, validation will be partially (plain string validation) or entirely (hashed validation) skipped.
+
 ### Recipient edit mode
 
 <Tabs>