Skip to content

juanroman-zz/emvqr

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

EMV Complaint QR Codes

NuGet

Build status

EMV(R) Compliant Library built in .NET Standard for generating and parsing QR Codes. The library is based on the EMV(R) QR Code Specification for Payment Systems: Merchant-Presented Mode Version 1.

Creating a Merchant-Presented QR

To create a static (used for many transactions) you can use the static constructor

var globalUniqueIdentifier = Guid.NewGuid().ToString().Replace("-", string.Empty);
var merchantPayload = MerchantPayload.CreateStatic(
    merchantGlobalUniqueIdentifier: globalUniqueIdentifier,
    merchantCategoryCode: 4111,
    transactionCurrencyNumericCode: Iso4217Currency.MexicoPeso.Value.NumericCode,
    countryCode: Iso3166Countries.Mexico,
    merchantName: "My Super Shop",
    merchantCity: "Mexico City");

var payload = merchantPayload.GeneratePayload();

The above would produce some of the following fields.

Value String Field Reference Spec ID Value Length Spec Value Explanation
000201 Payload Format Indicator "00" 2 1 The Payload Format Indicator shall contain a value of "01"
000211 Point of Initiation Method "01" 2 11 The value of "11" should be used when the same QR Code is shown for more than one transaction
52044111 Merchant Category Code "52" 4 4111 The Merchant Category Code (MCC) shall contain an MCC as defined by ISO 18245.
6011Mexico City Merchant City "60" 11 Mexico City The Merchant City should indicate the city of the merchant's physical location.

To see the full spec reference please read the specification provided by EMV(R) or read it from the file included

You can also go full fluent. The following example shows most of the fields used with the easier fluent approach:

var globalUniqueIdentifier = Guid.NewGuid().ToString().Replace("-", string.Empty);

var merchantPayload = MerchantPayload
    .CreateDynamic(globalUniqueIdentifier, 4111, Iso4217Currency.MexicoPeso.Value.NumericCode, Iso3166Countries.Mexico, "Chocolate Powder", "Mexico City")
    .WithAlternateLanguage(Iso639Languages.SpanishCastilian, "Chocolate en Polvo", "CDMX")
    .WithTransactionAmount(34.95m)
    .WithTipByUser()
    .WithAdditionalData(
        billNumber: "1234",
        mobileNumber: "5512341234",
        storeLabel: "The large store",
        loyaltyNumber: "A12341234",
        referenceLabel: "***",
        terminalLabel: "T12341",
        purposeOfTransaction: "We do commerce",
        additionalConsumerDataRequest: "AME")
    .WithUnreservedTemplate(globalUniqueIdentifier, new Dictionary<int, string>
    {
        {1, "Some value" },
        {2, "Another value" }
    });

var payload = merchantPayload.GeneratePayload();

Decoding a Merchant-Presented QR

You can easily decode a QR code by using the FromQR static constructor. Please note that the data will be validated against the spec automatically.

var merchantPayload = MerchantPayload.FromQR(qr);

Sample

The following sample which is included in the Unit Tests shows how to generate the QR data and then decode it back to an object.

var globalUniqueIdentifier = Guid.NewGuid().ToString().Replace("-", string.Empty);
var merchantPayload = MerchantPayload
    .CreateDynamic(globalUniqueIdentifier, 4111, Iso4217Currency.MexicoPeso.Value.NumericCode, Iso3166Countries.Mexico, "Chocolate Powder", "Mexico City")
    .WithAlternateLanguage(Iso639Languages.SpanishCastilian, "Chocolate en Polvo", "CDMX")
    .WithTransactionAmount(34.95m)
    .WithTipByUser()
    .WithAdditionalData(
        billNumber: "1234",
        mobileNumber: "5512341234",
        storeLabel: "The large store",
        loyaltyNumber: "A12341234",
        referenceLabel: "***",
        terminalLabel: "T12341",
        purposeOfTransaction: "We do commerce",
        additionalConsumerDataRequest: "AME")
    .WithUnreservedTemplate(globalUniqueIdentifier, new Dictionary<int, string>
    {
        {1, "Some value" },
        {2, "Another value" }
    });
merchantPayload.PostalCode = "12345";

var qr = merchantPayload.GeneratePayload();

merchantPayload = MerchantPayload.FromQR(qr);
Assert.Equal(globalUniqueIdentifier, merchantPayload.MerchantAccountInformation.First().Value.GlobalUniqueIdentifier);
Assert.Equal(4111, merchantPayload.MerchantCategoryCode);
Assert.Equal(Iso4217Currency.MexicoPeso.Value.NumericCode, merchantPayload.TransactionCurrency);
Assert.Equal(Iso3166Countries.Mexico, merchantPayload.CountyCode);
Assert.Equal("Chocolate Powder", merchantPayload.MerchantName);
Assert.Equal("Mexico City", merchantPayload.MerchantCity);
Assert.Equal(Iso639Languages.SpanishCastilian, merchantPayload.MerchantInformation.LanguagePreference);
Assert.Equal("Chocolate en Polvo", merchantPayload.MerchantInformation.MerchantNameAlternateLanguage);
Assert.Equal("CDMX", merchantPayload.MerchantInformation.MerchantCityAlternateLanguage);
Assert.Equal(34.95m, merchantPayload.TransactionAmount);
Assert.Equal(1, merchantPayload.TipOrConvenienceIndicator);
Assert.Equal("1234", merchantPayload.AdditionalData.BillNumber);
Assert.Equal("5512341234", merchantPayload.AdditionalData.MobileNumber);
Assert.Equal("The large store", merchantPayload.AdditionalData.StoreLabel);
Assert.Equal("A12341234", merchantPayload.AdditionalData.LoyaltyNumber);
Assert.Equal("***", merchantPayload.AdditionalData.ReferenceLabel);
Assert.Equal("T12341", merchantPayload.AdditionalData.TerminalLabel);
Assert.Equal("We do commerce", merchantPayload.AdditionalData.PurposeOfTransaction);
Assert.Equal("AME", merchantPayload.AdditionalData.AdditionalConsumerDataRequest);
Assert.Equal(globalUniqueIdentifier, merchantPayload.UnreservedTemplate.First().Value.GlobalUniqueIdentifier);
Assert.Equal("Some value", merchantPayload.UnreservedTemplate.First().Value.ContextSpecificData[1]);
Assert.Equal("Another value", merchantPayload.UnreservedTemplate.First().Value.ContextSpecificData[2]);
Assert.Equal("12345", merchantPayload.PostalCode);
Assert.NotNull(merchantPayload.CRC);