Doc 454/triple enrichment

docs/developers/using-api/authentication/guide-get-token-user.mdx

@@ -72,7 +72,7 @@ https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID&r
 | Parameter | Description |
 | --- | --- |
 | `phoneNumber`<br />`firstName`<br />`lastName`<br />`birthDate`<br />`birthCity`<br />`birthCountry`<br />`nationality`<br />`language` |  Avoids asking the customer to enter this information during user registration.<br /><br />Required formats: <ul><li>`birthDate`: YYYY-MM-DD *(year-month-day)*</li><li>`birthCountry` and `nationality`: ISO 3166-1 alpha-3 *(France = `FRA`)*</li><li>`language`: ISO 639-1 (alpha 2) *(Spanish = `es`)*</li></ul> |
-| `identificationLevel` |  Indicate your preferred [identification level](../../../topics/users/identifications/index.mdx#levels-processes): `PVID`, `QES`, `expert`, or `Auto`.<br /><br />If you include the `onboardingId`, or if you're trying to reengage your user to complete their identification, Swan recommends setting `Auto` as your preferred identification level. `Auto` allows Swan to direct your users to the best identification flow for their situation. |
+| `identificationLevel` |  Indicate your preferred [identification level](../../../topics/users/identifications/index.mdx#levels-processes): `PVID`, `QES`, `Expert`, or `Auto`.<br /><br />If you include the `onboardingId`, or if you're trying to reengage your user to complete their identification, Swan recommends setting `Auto` as your preferred identification level. `Auto` allows Swan to direct your users to the best identification flow for their situation. |
 | `onboardingId` |  Avoids asking the customer to enter their own residence address and email if they provide that information during onboarding. |
 
 ### 2.2 Receive approval from user {#code-approve}

docs/developers/using-api/webhooks.mdx

@@ -237,17 +237,23 @@ The first part of the `eventType` will tell you what resources to query in an AP
 | `MerchantProfile.Created` | Merchant profile was created |
 | `MerchantProfile.Updated` | Merchant profile was updated |
 
-### [Payments and transactions](../../topics/payments/index.mdx) {#events-payments-transactions}
+### [Payments](../../topics/payments/index.mdx) {#events-payments}
 
 | `eventType` | Explanation |
 | --- | --- |
 | `ReceivedDirectDebitMandate.Created` | Received direct debit mandate was created either through the API or automatically by Swan |
 | `ReceivedDirectDebitMandate.Updated` | Received direct debit mandate was updated |
 | `StandingOrder.Canceled` | Standing order was canceled |
 | `StandingOrder.Scheduled` | Standing order was scheduled |
+
+### [Transactions](../../topics/payments/index.mdx#transactions) {#events-transactions}
+
+| `eventType` | Explanation |
+| --- | --- |
 | `Transaction.Booked` | Transaction was completed and will appear on the account statement |
 | `Transaction.Canceled` | Upcoming direct debit was canceled |
 | `Transaction.Deleted` | Scheduled direct debit was deleted  |
+| `Transaction.Enriched` | [Enriched transaction information](../../topics/payments/cards/index.mdx#enriched) was received for a card transaction outside of a status update |
 | `Transaction.Pending` | Outgoing SEPA Credit Transfer was processed and is waiting for the next SEPA batch, a card authorization was accepted, and more |
 | `Transaction.Rejected` | Transaction was rejected for compliance reasons |
 | `Transaction.Released` | Transaction was released |

docs/topics/partials/_in-dev.mdx

@@ -0,0 +1,4 @@
+:::caution In development
+{props.feature} is **currently in development**.
+Feel free to review this section to understand how the feature will work when live.
+:::

docs/topics/payments/cards/guide-get-enriched-info.mdx

@@ -0,0 +1,86 @@
+---
+title: Get enriched information about card transactions
+---
+
+# Get enriched information about card transactions
+
+import InDevelopment from '../../partials/_in-dev.mdx';
+
+<InDevelopment feature="Providing enriched transaction information" />
+
+You can **call the API** to get [enriched information about card transactions](./index.mdx#enriched).
+
+Enriched information is also available on your Dashboard by going to **Data** > **Transactions** > **Details**.
+
+:::tip Prerequisites
+You need a **project access token** to call the query.
+:::
+
+## Guide {#guide}
+
+1. Call the `transaction` query.
+1. Add the transaction ID.
+1. Add `CardTransaction` (line 3), then `enrichedTransactionInfo` (line 5).
+1. Choose all the enriched information you'd like to review about the card transaction.
+
+## Query {#query}
+
+```graphql {2,3,5} showLineNumbers
+query EnrichedTransactionInfo {
+  transaction(id: "$TRANSACTION_ID") {
+    ... on CardTransaction {
+      id
+      enrichedTransactionInfo {
+        address
+        carbonFootprint
+        category
+        city
+        contactEmail
+        contactPhone
+        contactWebsite
+        country
+        enrichedMerchantName
+        isSubscription
+        latitude
+        logoUrl
+        longitude
+        postalCode
+        subcategory
+      }
+    }
+  }
+}
+```
+
+## Payload {#payload}
+
+:::note Other
+When new values aren't mapped yet, the API responds `Other`.
+:::
+
+```json showLineNumbers
+{
+  "data": {
+    "transaction": {
+      "id": "$TRANSACTION_ID",
+      "enrichedTransactionInfo": {
+        "address": "1 rue de Paris",
+        "carbonFootprint": "2.2",
+        "category": "Restaurants",
+        "city": "Paris",
+        "contactEmail": "hello@mybrand.com",
+        "contactPhone": "+35500550055",
+        "contactWebsite": "www.mybrand.com",
+        "country": "FRA",
+        "enrichedMerchantName": "MyBrand",
+        "isSubscription": "false",
+        "latitude": "48.870010",
+        "logoUrl": "https://data.swan.io/enriched-merchant-data/logos/$FILE_NAME",
+        "longitude": "2.373500",
+        "postalCode": "75000",
+        "subcategory": "Bars and Restaurants"
+      }
+    }
+  }
+}
+```

docs/topics/payments/cards/index.mdx

@@ -37,7 +37,7 @@ import SuspicionOfFraud from '../../partials/_card-fraud-suspicion.mdx';
 
 <SuspicionOfFraud />
 
-## Card transaction statuses {#statuses}
+### Card transaction statuses {#statuses}
 
 ```mermaid
 %%{ init: { 'flowchart': { 'curve': 'linear' } } }%%
@@ -316,7 +316,7 @@ If a payment *should* require 3DS and doesn't (which probably means the merchant
 In the case of recurring payments, such as subscriptions and automatic top-up, the merchant is only required to use 3DS during setup and **not for subsequent recurring payments**.
 :::
 
-### Consent flow {#3ds-consent}
+### 3DS consent flow {#3ds-consent}
 
 Swan designed a PSD2-compliant two-factor authentication (2FA) solution based on [Mastercard's 3DS Smart Interface](https://developer.mastercard.com/product/3ds-smart-interface/).
 Swan automatically detects card payments that require additional security and triggers the 3DS consent flow.
@@ -351,7 +351,58 @@ participant CM as Card holder's mobile device
     CH->> M: Redirected to merchant
 ```
 
+## Enriched transaction information {#enriched}
+
+import InDevelopment from '../../partials/_in-dev.mdx';
+
+<InDevelopment feature="Providing enriched transaction information" />
+
+When reviewing their transaction history, **card holders** can see **enriched information** (more detailed data) about the merchant and the transaction.
+Providing enriched transaction information **improves the user experience** for you and your users.
+For example, enriched information can reduce chargebacks and decrease the need for customer support.
+
+You can retrieve this information with the API and view it on your Dashboard by going to **Data** > **Transactions** > **Details**.
+If you use Swan's Web Banking interface, enriched transaction information is available for your users automatically in their History list.
+
+Enriched transaction information is **only available for card transactions** at this time.
+It's available for all card transactions dating back to the beginning of Swan. 
+
+Swan enriches card transactions with the following data (as availability allows):
+
+| API | Description | Example |
+| --- | --- | --- |
+| `enrichedMerchantName` | Merchant brand name | Carrefour |
+| `logoUrl` | Merchant logo | Small image of the merchant's logo, or, if no logo is available, the category icon |
+| `category` | Merchant category | Groceries |
+| `subcategory` | Merchant subcategory | Supermarket |
+| `isSubscription` | Subscription indicator boolean | `Yes` or `No` |
+| `contactEmail`<br />`contactPhone`<br />`contactWebsite` | Merchant contact details | example[@]carrefour.fr<br />05.00.55.00.55<br />carrefour.fr |
+| `city`<br />`country`<br />`postalCode`<br />`latitude`<br />`longitude` | Location details | Paris<br />France (FRA)<br />75000<br />48.864716<br />2.349014 |
+| `carbonFootprint` | Carbon footprint in micrograms of CO2 emitted | 546 micrograms |
+
+### Displaying enriched info {#enriched-display}
+
+In the API and on your Dashboard, `enrichedTransactionInfo` doesn't override the existing merchant information received during the classic transaction flow.
+If you use Swan's Web Banking interface, however, the enriched information overrides the merchant name.
+
+The following image is sample enriched information as displayed on the Dashboard:
+
+![Example of enriched card transaction information on the Dashboard](../../../images/topics/payments/cards/card-enriched-dashboard.png)
+
+### Webhooks & enriched info {#enriched-webhooks}
+
+Swan obtains enriched transaction information **asynchronously** to avoid processing delays and technical timeouts.
+The information is usually received within seconds after a card transaction is created.
+
+Anytime enriched information is received, Swan triggers the `Transaction.Enriched` webhook.
+In the `Transaction.Enriched` webhook notification, the resource ID is the transaction ID.
+
+If enriched information is received when a transaction's status changes, the `Transaction.Enriched` webhook is triggered *after* the `Transaction.Pending` webhook.
+
+Subscribe to both [webhooks](../../../developers/using-api/webhooks.mdx) to stay updated on your transactions.
+
 ## Guides {#guides}
 
 - [Get a list of card transactions](./guide-get-list.mdx)
+- [Get enriched information about card transactions](./guide-get-enriched-info.mdx)
 - [Sandbox](./sandbox.mdx)

docs/topics/payments/cards/sandbox.mdx

@@ -34,4 +34,15 @@ Simulating receiving authorization for a card payment by entering testing data..
 1. Click **Simulate**.
 1. After clicking **Simulate**, notice the status change to `Success`, meaning your authorization was executed successfully.
 
-![Screenshot of Swan Dashboard authorization release page in event simulator](../../../images/topics/payments/cards/sandbox-card-auth-release.png)
+![Screenshot of Swan Dashboard authorization release page in event simulator](../../../images/topics/payments/cards/sandbox-card-auth-release.png)
+
+## Simulate receiving enriched card transaction information {#simulate-enriched}
+
+<mark>UPDATE WHEN AVAILABLE</mark>
+
+1. Go to **Dashboard** > **Developers** > **Event Simulator**.
+1. Go to **$SIMULATION** (not shown).
+1. Go to the tab for `...` .
+1. Enter the transaction ID and `...` .
+1. Click **Simulate**.
+1. After clicking **Simulate**, notice `...` .

sidebars.js

@@ -335,6 +335,7 @@ module.exports = {
           collapsed: true,
           items: [
             "topics/payments/cards/guide-get-list",
+            "topics/payments/cards/guide-get-enriched-info",
             "topics/payments/cards/sandbox",
           ],
         },