README.md

insomnia-plugin-mastercard

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Installation
  • Configuration
  • Authenticated Requests
  • Encryption
• Further Reading

Overview

A plugin for consuming Mastercard APIs with support for authentication and encryption. This plugin computes and adds an Authorization header to requests sent from Insomnia REST Client and it can be configured to automatically encrypt request and/or decrypt response payloads.

Compatibility

Insomnia v5.15.0+

References

• Using OAuth 1.0a to Access Mastercard APIs
• Securing Sensitive Data Using Payload Encryption
• A Mastercard Plugin for Insomnia REST Client

Usage

Prerequisites

Before using this library, you will need to set up a project in the Mastercard Developers Portal.

As part of this set up, you'll receive credentials for your app:

• A consumer key (displayed on the Mastercard Developer Portal)
• A private request signing key (matching the public certificate displayed on the Mastercard Developer Portal)

Installation

1. One-Click Installation

1. Go to https://insomnia.rest/plugins/insomnia-plugin-mastercard
2. Click the "Install Plugin" button
3. Click "Open Insomnia" and "Install"

2. Manual Installation

1. Download "insomnia-plugin-mastercard-{version}.zip" from Releases > Assets
2. Go to Application > Preferences > Plugins
3. Click "Reveal Plugins Folder"
4. Extract the ZIP file from step 1 to the "plugins" folder
5. Click "Reload Plugins"

Configuration

One-Click Import

To import two ready to be used "sandbox" and "production" environments:

1. Depending on your use case, click either of these:

   • No encryption:

   • Mastercard Encryption:

   • JWE Encryption:

2. Click "Run Import Mastercard Workspace"

Alternatively, you can:

1. Go to Application > Preferences > Data
2. Click "Import Data"
3. Click "From URL"
4. Input either of these depending on your use case:
   • No encryption: https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-insomnia-workspace.json
   • Mastercard encryption: https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-with-mastercard-encryption-insomnia-workspace.json
   • JWE encryption: https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-with-jwe-encryption-insomnia-workspace.json
5. Click "Fetch and Import"

Manual Configuration

Update your environment:

1. Click "Manage Environments"
2. Create a "mastercard" environment variable with your credentials:

Linux/macOS

{
  "mastercard": {
    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
    "keyAlias": "keyalias",
    "keystoreP12Path": "/path/to/sandbox-signing-key.p12",
    "keystorePassword": "keystorepassword",
    "appliesTo": [
      "mastercard.com",
      "api.ethocaweb.com"
    ]
  }
}

Windows

{
  "mastercard": {
    "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
    "keyAlias": "keyalias",
    "keystoreP12Path": "C:\\path\\to\\sandbox-signing-key.p12",
    "keystorePassword": "keystorepassword",
    "appliesTo": [
      "mastercard.com",
      "api.ethocaweb.com"
    ]
  }
}

Authenticated Requests

From now on, an Authorization header will be automatically added to every request sent to Mastercard:

Encryption

This plugin can take care of encrypting requests and/or decrypting response payloads. To enable encryption support, you need to configure in the environment the encryptionConfig property.

Here's a quick example for Mastercard Encryption:

{
  "mastercard": {
    
    // ... // 
    
    "encryptionConfig": {
      "paths": [
        {
          "path": "/tokenize",
          "toEncrypt": [
            {
              "element": "cardInfo.encryptedData",
              "obj": "cardInfo"
            },
            {
              "element": "fundingAccountInfo.encryptedPayload.encryptedData",
              "obj": "fundingAccountInfo.encryptedPayload"
            }
          ],
          "toDecrypt": [
            {
              "element": "tokenDetail",
              "obj": "tokenDetail.encryptedData"
            }
          ]
        }
      ],
      "oaepPaddingDigestAlgorithm": "SHA-512",
      "ivFieldName": "iv",
      "encryptedKeyFieldName": "encryptedKey",
      "encryptedValueFieldName": "encryptedData",
      "oaepHashingAlgorithmFieldName": "oaepHashingAlgorithm",
      "publicKeyFingerprintFieldName": "publicKeyFingerprint",
      "publicKeyFingerprintType": "certificate",
      "dataEncoding": "hex",
      "encryptionCertificate": "/path/to/the/encryption/certificate",
      "privateKey": "/path/to/private/key"
    }
  }
}

As an alternative to providing the privateKey in the encryptionConfig, you can configure the keystore along with alias and password as shown below:

{
  "mastercard": {
    "encryptionConfig": {

      // ... //

      "encryptionCertificate": "/path/to/the/encryption/certificate",
      "keyStore": "/path/to/the/keystore",
      "keyStoreAlias": "keystorealias",
      "keyStorePassword": "keystorepassword",
    }
  }
}

See more examples here.

Both Mastercard encryption and JWE encryption are supported.
For more details on the encryption configurations, checkout these links:

• Mastercard Encryption
• JWE Encryption

Further Reading

• oauth1-signer-nodejs — A zero dependency library for generating a Mastercard API compliant OAuth signature
• client-encryption-nodejs — Library for Mastercard API compliant payload encryption/decryption.
• Insomnia Plugins
• The Insomnia Plugin Hub