Feat/v2 auth module

cards/concepts.mdx

@@ -10,6 +10,7 @@ and what to expect of them.
 This is not an extensive guide and we encourage you to use this document as a way to start
 your journey. Both VISA and Mastercard have great resources and guides that you can also use.
 
+<<<<<<< HEAD
 <Note>
   For transaction-related concepts like payments, refunds, and reversals, see our dedicated
   [Card Transactions](/transactions) guide.
@@ -56,6 +57,53 @@ and undergo through different analysis to reach a conclusion.
 2. **Investigation**: Review transaction details and evidence
 3. **Provisional Credit**: Temporary refund while investigating
 4. **Resolution**: Final decision and permanent credit/debit
+=======
+## Authorizations
+
+When a card is used to make a purchase, an authorization request is created, which can be approved or declined.
+The process to authorize transactions takes into consideration a lot of factors, some are:
+
+- The card balance has enough funds to cover the transaction amount
+- The card is active, with enough spending limits
+- Risk/AML screening
+- Anti-fraud analysis, and so on.
+
+If the authorization is approved, we deduct the amount from your card wallet and hold it in reserve until
+the authorization is either captured, canceled, or expired without a capture.
+In case it's not captured, unused funds will return to your card wallet.
+
+There are a few other edge cases that you should be ready to handle:
+
+1. **Partial authorizations**: used to increase the amount authorized.
+2. **Incremental authorizations**: hotels can send more authorizations to cover for fees after checking out.
+3. **Partial reversals**: used to reduce the amount authorized.
+
+Once an authorization is approved, it will be captured and becomes a transaction.
+
+## Transactions
+
+An authorization is captured and becomes a transaction usually under 24h.
+But as with everything in the card universe, this has edge cases.
+Car rentals, hotels, and some other businesses (defined by MCC) can capture up to a month
+after the authorization event.
+
+Again, more edge cases to handle:
+
+1. **Refunds**: unlike what you'd expect, this is not directly related to an authorization.
+2. **Partial capture**: a capture happens with an amount lower than the authorized amount.
+3. **Over capture**: some MCCs can over capture, meaning they can capture a value higher than the authorized amount.
+4. **Multi capture**: basically multiple partial captures on a single authorization, limited to some MCCs as well.
+5. **Force capture**: sometimes you receive a capture on a rejected authorization (yes, really), for example, some POS terminals on planes are not connected to the internet and when the plane lands it sends the transactions that happened mid-flight.
+
+These edge cases are limited to some MCCs, but they can be used for fraudulent behaviour.
+That's why we have the dispute process to contest suspicious transactions.
+
+## Disputes
+
+Disputes are used to recover funds for captured transactions. Their main use-case is to revert fraudulent transactions
+or problems with the product or service paid for. Fraud and non-fraud disputes have different requirements and rules,
+and undergo through different analysis to reach a conclusion.
+>>>>>>> ce2d52e (Separate card order state transitions)
 
 ## Card PINs
 

cards/create-physical-cards.mdx

@@ -10,7 +10,11 @@ description: "Order physical cards for your Users."
 <Step title="Create a Card Order">
 
 
+<<<<<<< HEAD
 [This endpoint creates a new `CardOrder` with the status of `PENDINGTRANSACTION`](/api-reference/physical-card-order/create-physical-card-order):
+=======
+[This endpoint creates a new `CardOrder` with the status of `PENDINGTRANSACTION`](/api-reference/card-order/create-a-new-card-order):
+>>>>>>> ce2d52e (Separate card order state transitions)
 
 ```bash cURL
 curl -X POST /api/v1/order/create
@@ -76,7 +80,11 @@ The conditions for the payment are:
 If all the conditions above are met, the `CardOrder.status` is set to `READY`.
 </Step>
 <Step title="Create the Physical Card">
+<<<<<<< HEAD
 [Finally, you can create the Physical Card](/api-reference/physical-card-order/create-a-physical-card):
+=======
+[Finally, you can create the Physical Card](/api-reference/card-order/create-a-card-out-of-a-card-order):
+>>>>>>> ce2d52e (Separate card order state transitions)
 
 ```bash cURL
 curl -X POST /api/v1/order/:orderId/create-card

docs.json

@@ -1,97 +1,162 @@
 {
   "theme": "mint",
   "name": "Gnosis Pay Documentation",
+  "versions": ["v2", "v1"],
   "colors": {
     "primary": "#707A2D",
     "light": "#D8EB81",
     "dark": "#919E3A"
   },
   "favicon": "/static/img/favicon.ico",
   "navigation": {
-    "tabs": [
+    "versions": [
       {
-        "tab": "Guides",
-        "groups": [
+        "version": "v2",
+        "tabs": [
           {
-            "group": "Introduction to Gnosis Pay",
-            "icon": "play",
-            "pages": ["index", "integration-model", "auth", "onboarding-flow"]
-          },
-          {
-            "group": "Accounts",
-            "icon": "user",
-            "pages": [
-              "account",
-              "account/update-authenticated-account",
-              "account/adding-safe-owner"
-            ]
-          },
-          {
-            "group": "On/Off Ramps",
-            "icon": "landmark",
-            "pages": [
-              "on-off-ramps/index",
-              "on-off-ramps/iban-integration",
-              "on-off-ramps/kyc-sharing"
-            ]
-          },
-          {
-            "group": "Cards",
-            "icon": "credit-card",
-            "pages": [
-              "cards/concepts",
-              "cards/create-physical-cards",
-              "cards/create-virtual-cards",
-              "cards/card-order-state-transitions",
-              "cards/pse-integration"
-            ]
-          },
-          {
-            "group": "Card Transactions",
-            "icon": "receipt",
-            "pages": [
-              "transactions/index",
-              "transactions/lifecycle",
-              "transactions/integration-guide"
-            ]
-          },
-          {
-            "group": "On-chain",
-            "icon": "cubes",
-            "pages": [
-              "gp-onchain/overview",
-              "gp-onchain/about-GP-safe",
-              "gp-onchain/sign-message",
-              "gp-onchain/daily-limit",
-              "gp-onchain/withdraw-funds-from-safe",
-              "gp-onchain/third-party-bridges"
+            "tab": "Guides",
+            "groups": [
+              {
+                "group": "Getting Started",
+                "icon": "play",
+                "pages": [
+                  "v2/v2-overview",
+                  "v2/v1-v2-diff",
+                  "v2/v2-siwe-auth",
+                  "v2/v2-onboard"
+                ]
+              },
+              {
+                "group": "GP On-chain",
+                "icon": "cube",
+                "pages": [
+                  "v2/gp-onchain/v2-account",
+                  "v2/gp-onchain/v2-account-statement",
+                  "v2/gp-onchain/v2-withdraw"
+                ]
+              },
+              {
+                "group": "Card",
+                "icon": "credit-card",
+                "pages": [
+                  "v2/cards/v2-virtual-card",
+                  "v2/cards/v2-card-details",
+                  "v2/cards/v2-simulate-card",
+                  "v2/cards/v2-pse-integration"
+                ]
+              },
+              {
+                "group": "Webhooks",
+                "icon": "webhook",
+                "pages": ["v2/webhooks/webhook", "v2/webhooks/webhook-events"]
+              }
             ]
           },
           {
-            "group": "Webhooks",
-            "icon": "webhook",
-            "pages": [
-              "webhooks/introduction",
-              "webhooks/getting-started",
-              "webhooks/events"
+            "tab": "API Reference",
+            "groups": [
+              {
+                "group": "V2 Production API",
+                "openapi": "https://gp-auth-module.prod.gnosispay.com/openapi.json",
+                "collapsed": true
+              }
             ]
           }
         ]
       },
       {
-        "tab": "API reference",
-        "groups": [
+        "version": "v1",
+        "tabs": [
           {
-            "group": "Authentication",
-            "pages": ["api-reference/intro", "api-reference/auth-app"]
-          },
-          {
-            "group": "API reference",
-            "openapi": "https://api.gnosispay.com/api-docs/spec.json"
+            "tab": "Guides",
+            "groups": [
+              {
+                "group": "Introduction to Gnosis Pay",
+                "icon": "play",
+                "pages": [
+                  "v1/overview",
+                  "v1/integration-model",
+                  "v1/auth",
+                  "v1/quickstart"
+                ]
+              },
+              {
+                "group": "Accounts",
+                "icon": "user",
+                "pages": [
+                  "v1/account/index",
+                  "v1/account/update-authenticated-account",
+                  "v1/account/adding-safe-owner"
+                ]
+              },
+              {
+                "group": "On/Off Ramps",
+                "icon": "landmark",
+                "pages": [
+                  "v1/on-off-ramps/index",
+                  "v1/on-off-ramps/iban-integration",
+                  "v1/on-off-ramps/kyc-sharing"
+                ]
+              },
+              {
+                "group": "Cards",
+                "icon": "credit-card",
+                "pages": [
+                  "v1/cards/concepts",
+                  "v1/cards/create-physical-cards",
+                  "v1/cards/create-virtual-cards",
+                  "v1/cards/card-order-state-transitions",
+                  "v1/cards/pse-integration"
+                ]
+              },
+              {
+                "group": "Card Transactions",
+                "icon": "receipt",
+                "pages": [
+                  "v1/transactions/index",
+                  "v1/transactions/lifecycle",
+                  "v1/transactions/integration-guide"
+                ]
+              },
+              {
+                "group": "On-chain",
+                "icon": "cubes",
+                "pages": [
+                  "v1/gp-onchain/overview",
+                  "v1/gp-onchain/about-GP-safe",
+                  "v1/gp-onchain/sign-message",
+                  "v1/gp-onchain/daily-limit",
+                  "v1/gp-onchain/withdraw-funds-from-safe",
+                  "v1/gp-onchain/third-party-bridges"
+                ]
+              },
+              {
+                "group": "Webhooks",
+                "icon": "webhook",
+                "pages": [
+                  "v1/webhooks/introduction",
+                  "v1/webhooks/getting-started",
+                  "v1/webhooks/events"
+                ]
+              }
+            ]
           },
           {
-            "group": "PSE API",
-            "openapi": "https://api-pse-public.gnosispay.com/api-docs/spec.json"
+            "tab": "API reference",
+            "groups": [
+              {
+                "group": "Authentication",
+                "pages": ["v1/api-reference/intro", "v1/api-reference/auth-app"]
+              },
+              {
+                "group": "API reference",
+                "openapi": "https://api.gnosispay.com/api-docs/spec.json"
+              },
+              {
+                "group": "PSE API",
+                "openapi": "https://api-pse-public.gnosispay.com/api-docs/spec.json"
+              }
+            ]
           }
         ]
       }

v1/account/adding-safe-owner.mdx

@@ -0,0 +1,63 @@
+---
+title: "Managing Safe Ownership"
+description: "Add a new owner to a Gnosis Pay Safe Account"
+---
+
+Adding a new owner to a Gnosis Pay Safe registers that account as a **Delay Module owner**.  
+Only Delay Module owners can approve and execute on-chain transactions.
+
+<Warning>
+**Important distinction:**  
+- **Authenticated wallets** are linked to a Gnosis Pay user for API access (via SIWE and JWT).  
+- **Safe owners (Delay Module owners)** are accounts explicitly added on-chain to the Safe.  
+Authenticated wallets do **not** become Safe owners unless they are also as owners for the safe.
+</Warning>
+
+This guide walks through the process of adding an additional Safe owner. Once complete, the new owner will be able to approve and execute transactions through the Delay Module.
+
+<Steps>
+  <Step title="Get a JWT token for the session">
+    Follow the [authentication flow](https://docs.gnosispay.com/auth) to obtain a JWT token for the Gnosis Pay user.
+  </Step>
+
+  <Step title="Get typed data for adding a new Safe owner">
+    Call [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/get-typed-data-for-adding-a-new-safe-owner) to receive the typed data.  
+    Sign the typed data with the current Safe owner’s key to produce a signature.
+
+    ```bash
+    curl --request GET \
+      --url https://api.gnosispay.com/api/v1/owners/add/transaction-data \
+      --header "Authorization: Bearer <token>"
+    ```
+  </Step>
+
+  <Step title="Submit the signature">
+    Send the new owner’s address, the signature, and the signed message to [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/add-a-new-owner-to-the-safe).
+
+    ```bash
+    curl --request POST \
+      --url https://api.gnosispay.com/api/v1/owners \
+      --header "Authorization: Bearer <token>" \
+      --header "Content-Type: application/json" \
+      --data '{
+        "newOwner": "0x3270bf32AB647e90eF94A026c70Aa1daaaDA2382",
+        "signature": "0x1234567890abcdef...",
+        "message": {
+          "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+          "data": "0xa9059cbb0000000000000000000000003270bf32ab647e90ef94a026c70aa1daaaada2382"
+        }
+      }'
+    ```
+    The operation is processed through the Delay Relay and executes after a 3-minute delay.
+  </Step>
+
+  <Step title="Verify ownership">
+    Confirm that the new owner was added to the Delay Module by checking the [Safe’s owner list](https://docs.gnosispay.com/api-reference/safe-owners/get-the-list-of-safe-owners).
+
+    ```bash
+    curl --request GET \
+      --url https://api.gnosispay.com/api/v1/owners \
+      --header "Authorization: Bearer <token>"
+    ```
+  </Step>
+</Steps>