insomnia-plugin-mastercard

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Installation
  • Configuration
    • OAuth 2.0
    • OAuth 1.0a
    • Disable Authentication
  • Authenticated Requests
  • Encryption
  • Signature
• Further Reading

Overview

An Insomnia REST Client plugin for consuming Mastercard APIs. It automatically computes and injects an Authorization header on outgoing requests, and can be configured to encrypt request payloads, decrypt response payloads, and generate or verify JWS signatures.

Compatibility

Insomnia v5.15.0+

References

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

Usage

Prerequisites

You will need a project in the Mastercard Developers Portal (See Quick Start Guide).

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:

   • OAuth 1.0a:

   • OAuth 2.0:

   • 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 workspace depending on your use case:
   • OAuth 1.0a
   • OAuth 2.0
   • Mastercard encryption
   • JWE encryption
5. Click "Fetch and Import"

Manual Configuration

Update your environment:

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

The authentication mode is determined by which key is present in your mastercard config:

Key present	Auth mode
oAuth2	OAuth 2.0 (FAPI 2.0 — private_key_jwt + DPoP)
oAuth1	OAuth 1.0a
neither (legacy)	OAuth 1.0a — root-level fields (deprecated)

Only one of oAuth1 or oAuth2 may be configured at a time.

---

OAuth 2.0

Requires a Client ID, Key ID (kid), scopes, and an Authentication Key (.p12 keystore file with its alias and password) from the Mastercard Developers Portal.

Linux/macOS

{
  "mastercard": {
    "oAuth2": {
      "clientId": "yourclientid",
      "kid": "yourkeyid",
      "keystoreP12Path": "/path/to/sandbox-signing-key.p12",
      "keyAlias": "keyalias",
      "keystorePassword": "keystorepassword",
      "tokenEndpoint": "https://auth.mastercard.com/oauth2/token",
      "issuer": "https://auth.mastercard.com",
      "scopes": ["service:scope1", "service:scope2"]
    },
    "appliesTo": [
      "mastercard.com",
      "api.ethocaweb.com"
    ]
  }
}

Windows

{
  "mastercard": {
    "oAuth2": {
      "clientId": "yourclientid",
      "kid": "yourkeyid",
      "keystoreP12Path": "C:\\path\\to\\sandbox-signing-key.p12",
      "keyAlias": "keyalias",
      "keystorePassword": "keystorepassword",
      "tokenEndpoint": "https://auth.mastercard.com/oauth2/token",
      "issuer": "https://auth.mastercard.com",
      "scopes": ["service:scope1", "service:scope2"]
    },
    "appliesTo": [
      "mastercard.com",
      "api.ethocaweb.com"
    ]
  }
}

Property	Description
clientId	OAuth 2.0 client identifier
kid	Key ID for the client authentication key
keystoreP12Path	Absolute path to the P12 keystore file
keyAlias	Key alias within the P12 keystore
keystorePassword	Password for the P12 keystore
tokenEndpoint	OAuth 2.0 token endpoint URL. - Sandbox: https://sandbox.api.mastercard.com/oauth/token - Production: https://api.mastercard.com/oauth/token
issuer	Authorization server issuer URL. - Sandbox: https://sandbox.api.mastercard.com - Production: https://api.mastercard.com
scopes	Array of OAuth scopes to request

---

OAuth 1.0a

Requires a Consumer Key and a Signing Key (.p12 keystore file with its alias and password) from the Mastercard Developers Portal.

Linux/macOS

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

Windows

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

Property	Description
consumerKey	Consumer key from the Mastercard Developers Portal
keyAlias	Key alias within the P12 keystore
keystoreP12Path	Absolute path to the signing key P12 file
keystorePassword	Password for the P12 keystore

---

Legacy OAuth 1.0a (deprecated)

Deprecated. Root-level OAuth 1.0a fields are still accepted for backwards compatibility but will be removed in a future release. Migrate to the oAuth1 nested format shown above.

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

---

Disable Authentication

The oAuthDisabled property is optional and can be placed at the mastercard level regardless of auth mode. By default it is false. Set it to true to skip adding an Authorization header entirely.

See more configuration examples here.

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

Signature

This plugin can take care of generating jws signature creation and/or jws signature verification. To enable jws signing support, you need to configure in the environment the signatureConfig property.

Here's a quick example for SignatureConfig which is part of extensions:

{
  "mastercard": {
    
    // ... // 
    "extensions":{
    "signatureConfig": {
      "paths": [
        {
          "path": "/tokenize",
          "signatureGenerationEnabled": true,
          "signatureVerificationEnabled": true
        }
      ],
     "signPrivateKey": "/path/to/private/key",
     "signKeyId": "signatureKID",
     "signVerificationCertificate": "/path/to/the/signing/certificate",
     "signAlgorithm": "RS256",
     "signExpirationSeconds": 300,
     "signAlgorithmConstraints": ["PS256","RS256"]
    }
   }
  }
}

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