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. Click
2. Click "Run Import Mastercard Workspace"

Alternatively, you can:

1. Go to Application > Preferences > Data
2. Click "Import Data"
3. Click "From URL"
4. Type: https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-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:

{
  "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",
    }
  }
}

For further details on the configuration object and predefined service configurations, please checkout this page.

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