fixup! DOC-454 add enrichment to card transactions

swan-io · Jun 24, 2024 · cf6657b · cf6657b
1 parent 62853f2
commit cf6657b
Show file tree

Hide file tree

Showing 2 changed files with 56 additions and 39 deletions.
diff --git a/docs/topics/payments/cards/guide-get-enriched-info.mdx b/docs/topics/payments/cards/guide-get-enriched-info.mdx
@@ -5,6 +5,7 @@ title: Get enriched information about card transactions
 # Get enriched information about card transactions
 
 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
@@ -15,47 +16,39 @@ You need a **project access token** to call the query.
 
 1. Call the `transaction` query.
 1. Add the transaction ID.
-1. Add `CardTransaction`, then `enrichedTransactionInfo`.
+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}
 
-🔎 [Open the query in API Explorer]
-
-<mark>GET QUERY FROM PREPROD WHEN AVAILABLE</mark>
+🔎 [Open the query in API Explorer](https://explorer.preprod.swan.io?query=cXVlcnkgRW5yaWNoZWRUcmFuc2FjdGlvbkluZm8gewogIHRyYW5zYWN0aW9uKGlkOiAiJFRSQU5TQUNUSU9OX0lEIikgewogICAgLi4uIG9uIENhcmRUcmFuc2FjdGlvbiB7CiAgICAgIGlkCiAgICAgIGVucmljaGVkVHJhbnNhY3Rpb25JbmZvIHsKICAgICAgICBhZGRyZXNzCiAgICAgICAgY2FyYm9uRm9vdHByaW50CiAgICAgICAgY2F0ZWdvcnkKICAgICAgICBjaXR5CiAgICAgICAgY29udGFjdEVtYWlsCiAgICAgICAgY29udGFjdFBob25lCiAgICAgICAgY29udGFjdFdlYnNpdGUKICAgICAgICBjb3VudHJ5CiAgICAgICAgZW5yaWNoZWRNZXJjaGFudE5hbWUKICAgICAgICBpc1N1YnNjcmlwdGlvbgogICAgICAgIGxhdGl0dWRlCiAgICAgICAgbG9nb1VybAogICAgICAgIGxvbmdpdHVkZQogICAgICAgIHBvc3RhbENvZGUKICAgICAgICBzdWJjYXRlZ29yeQogICAgICB9CiAgICB9CiAgfQp9Cg%3D%3D&tab=api)
 
-```graphql {2,3,12} showLineNumbers
-query MyQuery {
+```graphql {2,3,5} showLineNumbers
+query EnrichedTransactionInfo {
   transaction(id: "$TRANSACTION_ID") {
     ... on CardTransaction {
       id
-      merchantCategoryCode
-      merchantCategoryDescription
-      merchantCity
-      merchantCountry
-      merchantId
-      merchantPostalCode
-      merchantName
       enrichedTransactionInfo {
-        enrichedMerchantName
-        logoUrl
-        category
-        subcategory
-        country
-        city
         address
-        longitude
-        latitude
-        postalcode
-        isSubscription
         carbonFootprint
+        category
+        city
         contactEmail
         contactPhone
         contactWebsite
+        country
+        enrichedMerchantName
+        isSubscription
+        latitude
+        logoUrl
+        longitude
+        postalCode
+        subcategory
       }
     }
   }
 }
+
 ```
 
 ## Payload {#payload}
@@ -64,6 +57,29 @@ query MyQuery {
 When new values aren't mapped yet, they're marked `Other`.
 :::
 
-```json {2} showLineNumbers
-
+```json showLineNumbers
+{
+  "data": {
+    "transaction": {
+      "id": "$TRANSACTION_ID",
+      "enrichedTransactionInfo": {
+        "address": null,
+        "carbonFootprint": null,
+        "category": null,
+        "city": null,
+        "contactEmail": null,
+        "contactPhone": null,
+        "contactWebsite": null,
+        "country": null,
+        "enrichedMerchantName": null,
+        "isSubscription": null,
+        "latitude": null,
+        "logoUrl": null,
+        "longitude": null,
+        "postalCode": null,
+        "subcategory": null
+      }
+    }
+  }
+}
 ```
diff --git a/docs/topics/payments/cards/index.mdx b/docs/topics/payments/cards/index.mdx
@@ -354,28 +354,27 @@ participant CM as Card holder's mobile device
 ## Enriched transaction information {#enriched}
 
 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 by reducing chargebacks and decreasing the need for customer support.
+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**.
+
+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 |
 | --- | --- | --- |
-| `brand_name` | Merchant brand name | Carrefour |
-| `brand_logo` | Merchant logo | Small image of the merchant's logo, or, if no logo is available, the category icon |
+| `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 |
-| `is subscription` | Subscription indicator boolean | `Yes` or `No` |
-| `contact_email`<br />`contact_phone`<br />`contact_website` | Merchant contact details | example[@]carrefour.fr<br />05.00.55.00.55<br />carrefour.fr |
-| `emission_in_ug` | Carbon footprint, measured in micrograms | 546 grams |
-
-:::caution Back-filling transaction info
-Swan plans to backfill enriched transaction information so you can display it to your users.
-If you integrate enriched transaction information, fields will be empty for transactions that aren't backfilled yet.
-:::
+| `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}
 
@@ -390,8 +389,10 @@ The following image is sample enriched information as displayed on the Dashboard
 
 Swan obtains enriched transaction information **asynchronously** to avoid processing delays and technical timeouts.
 
-- If enriched information is received when a transaction's status changes, only the `Transaction.Pending` webhook is triggered.
-- If enriched information is received outside of a transaction status update, Swan triggers the `Transaction.Enriched` webhook. In the `Transaction.Enriched` webhook notification, the resource ID is the transaction ID.
+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.