Merge pull request #278 from blockchyp/feature/CHYP-3573

Card Metadata and HSA/EBT

README.md

@@ -354,6 +354,53 @@ Console.WriteLine(response);
 
 ```
 
+#### Card Metadata
+
+
+
+* **API Credential Types:** Merchant
+* **Required Role:** Payment API Access
+
+This API allows you to retrieve card metadata.
+
+Card metadata requests can use a payment terminal to retrieve metadata or
+use a previously enrolled payment token.
+
+**Terminal Transactions**
+
+For terminal transactions, make sure you pass in the terminal name using the `terminalName` property.
+
+**Token Transactions**
+
+If you have a payment token, omit the `terminalName` property and pass in the token with the `token`
+property instead.
+
+**Card Numbers and Mag Stripes**
+
+You can also pass in PANs and Mag Stripes, but you probably shouldn't, as this will
+put you in PCI scope and the most common vector for POS breaches is keylogging.
+If you use terminals for manual card entry, you'll bypass any keyloggers that
+might be maliciously running on the point-of-sale system.
+
+
+
+
+```c#
+// Populate request parameters.
+CardMetadataRequest request = new CardMetadataRequest
+{
+    Test = true,
+    TerminalName = "Test Terminal",
+};
+
+// Run the transaction.
+CardMetadataResponse response = await blockchyp.CardMetadataAsync(request);
+
+// View the result.
+Console.WriteLine(response);
+
+```
+
 #### Time Out Reversal
 
 

src/BlockChyp/Client/BlockChypClient.cs

@@ -351,6 +351,49 @@ public EnrollResponse Enroll(EnrollRequest request)
                 .ConfigureAwait(false).GetAwaiter().GetResult();
         }
 
+        /// <summary>
+        /// Retrieves card metadata.
+        /// </summary>
+        /// <param name="request">The request details.</param>
+        public async Task<CardMetadataResponse> CardMetadataAsync(CardMetadataRequest request)
+        {
+            ISignatureRequest signatureRequest = request as ISignatureRequest;
+            if (signatureRequest != null)
+            {
+                PopulateSignatureOptions(signatureRequest);
+            }
+
+            CardMetadataResponse response;
+            if (await IsTerminalRouted(request.TerminalName).ConfigureAwait(false))
+            {
+                response = await TerminalRequestAsync<CardMetadataResponse>(HttpMethod.Post, "/api/card-metadata", request.TerminalName, request)
+                    .ConfigureAwait(false);
+            }
+            else
+            {
+                response = await GatewayRequestAsync<CardMetadataResponse>(HttpMethod.Post, "/api/card-metadata", request, null, request.Test, relay: true)
+                    .ConfigureAwait(false);
+            }
+
+            ISignatureResponse signatureResponse = response as ISignatureResponse;
+            if (signatureRequest != null && signatureResponse != null)
+            {
+                DumpSignatureFile(signatureRequest, signatureResponse);
+            }
+
+            return response;
+        }
+
+        /// <summary>
+        /// Synchronous form of <see cref="CardMetadataAsync"/>.
+        /// </summary>
+        /// <param name="request">The request details.</param>
+        public CardMetadataResponse CardMetadata(CardMetadataRequest request)
+        {
+            return CardMetadataAsync(request)
+                .ConfigureAwait(false).GetAwaiter().GetResult();
+        }
+
         /// <summary>
         /// Activates or recharges a gift card.
         /// </summary>

src/BlockChyp/Entities/AuthorizationRequest.cs

@@ -389,8 +389,8 @@ public class AuthorizationRequest : BaseEntity, ITimeoutRequest, ICoreRequest, I
         /// <summary>
         /// Details for HSA/FSA transactions.
         /// </summary>
-        [JsonProperty(PropertyName = "healthcare")]
-        public Healthcare Healthcare { get; set; }
+        [JsonProperty(PropertyName = "healthcareMetadata")]
+        public HealthcareMetadata HealthcareMetadata { get; set; }
 
         /// <summary>
         /// That the transaction should be a cryptocurrency transaction. Value should be a
@@ -455,5 +455,29 @@ public class AuthorizationRequest : BaseEntity, ITimeoutRequest, ICoreRequest, I
         /// </summary>
         [JsonProperty(PropertyName = "passthroughSurcharge")]
         public string PassthroughSurcharge { get; set; }
+
+        /// <summary>
+        /// Marks a transaction as HSA/FSA.
+        /// </summary>
+        [JsonProperty(PropertyName = "healthcare")]
+        public bool Healthcare { get; set; }
+
+        /// <summary>
+        /// The total amount to process as healthcare.
+        /// </summary>
+        [JsonProperty(PropertyName = "healthcareTotal")]
+        public string HealthcareTotal { get; set; }
+
+        /// <summary>
+        /// The total amount to process as ebt.
+        /// </summary>
+        [JsonProperty(PropertyName = "ebtTotal")]
+        public string EbtTotal { get; set; }
+
+        /// <summary>
+        /// That this transaction will include a card metadata lookup.
+        /// </summary>
+        [JsonProperty(PropertyName = "cardMetadataLookup")]
+        public bool CardMetadataLookup { get; set; }
     }
 }

src/BlockChyp/Entities/AuthorizationResponse.cs

@@ -360,5 +360,11 @@ public class AuthorizationResponse : BaseEntity, IAbstractAcknowledgement, IAppr
         /// </summary>
         [JsonProperty(PropertyName = "status")]
         public string Status { get; set; }
+
+        /// <summary>
+        /// Details about a payment card derived from its BIN/IIN.
+        /// </summary>
+        [JsonProperty(PropertyName = "cardMetadata")]
+        public CardMetadata CardMetadata { get; set; }
     }
 }

src/BlockChyp/Entities/CardMetaData.cs

@@ -0,0 +1,88 @@
+// Copyright 2019-2024 BlockChyp, Inc. All rights reserved. Use of this code is
+// governed by a license that can be found in the LICENSE file.
+//
+// This file was generated automatically by the BlockChyp SDK Generator. Changes
+// to this file will be lost every time the code is regenerated.
+
+using Newtonsoft.Json;
+
+namespace BlockChyp.Entities
+{
+    /// <summary>
+    /// Essential information about a payment card derived from its BIN/IIN.
+    /// </summary>
+    public class CardMetadata : BaseEntity
+    {
+        /// <summary>
+        /// The brand or network of the card (e.g., Visa, Mastercard, Amex).
+        /// </summary>
+        [JsonProperty(PropertyName = "cardBrand")]
+        public string CardBrand { get; set; }
+
+        /// <summary>
+        /// The name of the financial institution that issued the card.
+        /// </summary>
+        [JsonProperty(PropertyName = "issuerName")]
+        public string IssuerName { get; set; }
+
+        /// <summary>
+        /// Whether the card supports Level 3 processing for detailed transaction data.
+        /// </summary>
+        [JsonProperty(PropertyName = "l3")]
+        public bool L3 { get; set; }
+
+        /// <summary>
+        /// Whether the card supports Level 2 processing for additional transaction data.
+        /// </summary>
+        [JsonProperty(PropertyName = "l2")]
+        public bool L2 { get; set; }
+
+        /// <summary>
+        /// The general category or type of the card product.
+        /// </summary>
+        [JsonProperty(PropertyName = "productType")]
+        public string ProductType { get; set; }
+
+        /// <summary>
+        /// The specific name or designation of the card product.
+        /// </summary>
+        [JsonProperty(PropertyName = "productName")]
+        public string ProductName { get; set; }
+
+        /// <summary>
+        /// Whether the card is an Electronic Benefit Transfer (EBT) card.
+        /// </summary>
+        [JsonProperty(PropertyName = "ebt")]
+        public bool Ebt { get; set; }
+
+        /// <summary>
+        /// Whether the card is a debit card.
+        /// </summary>
+        [JsonProperty(PropertyName = "debit")]
+        public bool Debit { get; set; }
+
+        /// <summary>
+        /// Whether the card is a healthcare-specific payment card.
+        /// </summary>
+        [JsonProperty(PropertyName = "healthcare")]
+        public bool Healthcare { get; set; }
+
+        /// <summary>
+        /// Whether the card is a prepaid card.
+        /// </summary>
+        [JsonProperty(PropertyName = "prepaid")]
+        public bool Prepaid { get; set; }
+
+        /// <summary>
+        /// The geographical region associated with the card's issuer.
+        /// </summary>
+        [JsonProperty(PropertyName = "region")]
+        public string Region { get; set; }
+
+        /// <summary>
+        /// The country associated with the card's issuer.
+        /// </summary>
+        [JsonProperty(PropertyName = "country")]
+        public string Country { get; set; }
+    }
+}