Back to plugins
Logo

Mastercard API

Version 2.7.0
Install Plugin

Overview

mastercard developers logo

Table of Contents

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

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:
  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:

Further Reading