https://github.com/mastercard/insomnia-plugin-mastercard
An Insomnia plugin for handling authentication and encryption for consuming Mastercard APIs.
https://github.com/mastercard/insomnia-plugin-mastercard
encryption insomnia insomnia-plugins jwe mastercard oauth1 oauth1a openapi
Last synced: 8 months ago
JSON representation
An Insomnia plugin for handling authentication and encryption for consuming Mastercard APIs.
- Host: GitHub
- URL: https://github.com/mastercard/insomnia-plugin-mastercard
- Owner: Mastercard
- License: apache-2.0
- Created: 2018-03-27T15:06:05.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2025-03-19T13:13:53.000Z (about 1 year ago)
- Last Synced: 2025-05-15T04:48:33.540Z (10 months ago)
- Topics: encryption, insomnia, insomnia-plugins, jwe, mastercard, oauth1, oauth1a, openapi
- Language: JavaScript
- Homepage: https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/
- Size: 435 KB
- Stars: 43
- Watchers: 23
- Forks: 26
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# insomnia-plugin-mastercard
[](https://developer.mastercard.com/)
[](https://sonarcloud.io/dashboard?id=Mastercard_insomnia-plugin-mastercard)
[](https://github.com/Mastercard/insomnia-plugin-mastercard/actions?query=workflow%3A%22broken+links%3F%22)
[](https://www.npmjs.com/package/insomnia-plugin-mastercard)
[](https://github.com/Mastercard/insomnia-plugin-mastercard/blob/master/LICENSE)
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-insomnia-workspace.json)
## Table of Contents
- [Overview](#overview)
* [Compatibility](#compatibility)
* [References](#references)
- [Usage](#usage)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Configuration](#configuration)
* [Authenticated Requests](#authenticated-requests)
* [Encryption](#encryption)
- [Further Reading](#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](https://insomnia.rest/)
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](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/)
* [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/)
* [A Mastercard Plugin for Insomnia REST Client](https://developer.mastercard.com/blog/a-mastercard-plugin-for-insomnia-rest-client)
### Prerequisites
Before using this library, you will need to set up a project in the [Mastercard Developers Portal](https://developer.mastercard.com).
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)
#### 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](https://github.com/Mastercard/insomnia-plugin-mastercard/releases)
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"
#### 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:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-insomnia-workspace.json)
- Mastercard Encryption:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-with-mastercard-encryption-insomnia-workspace.json)
- JWE Encryption:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/master/workspace/mastercard-apis-with-jwe-encryption-insomnia-workspace.json)
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](https://support.insomnia.rest/article/18-environment-variables):
1. Click "Manage Environments"
2. Create a "mastercard" environment variable with your credentials:
Linux/macOS
```json
{
"mastercard": {
"consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
"keyAlias": "keyalias",
"keystoreP12Path": "/path/to/sandbox-signing-key.p12",
"keystorePassword": "keystorepassword",
"appliesTo": [
"mastercard.com",
"api.ethocaweb.com"
]
}
}
```
Windows
```json
{
"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:
```jsonc
{
"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:
```jsonc
{
"mastercard": {
"encryptionConfig": {
// ... //
"encryptionCertificate": "/path/to/the/encryption/certificate",
"keyStore": "/path/to/the/keystore",
"keyStoreAlias": "keystorealias",
"keyStorePassword": "keystorepassword",
}
}
}
```
[See more examples here](docs/configuration-examples.md).
Both Mastercard encryption and JWE encryption are supported.
For more details on the encryption configurations, checkout these links:
- [Mastercard Encryption](https://github.com/Mastercard/client-encryption-nodejs/blob/main/README.md#configuring-the-field-level-encryption)
- [JWE Encryption](https://github.com/Mastercard/client-encryption-nodejs/blob/main/README.md#configuring-the-jwe-encryption)
* [oauth1-signer-nodejs](https://github.com/Mastercard/oauth1-signer-nodejs) — A zero dependency library for generating a Mastercard API compliant OAuth signature
* [client-encryption-nodejs](https://github.com/Mastercard/client-encryption-nodejs) — Library for Mastercard API compliant payload encryption/decryption.
* [Insomnia Plugins](https://support.insomnia.rest/article/26-plugins)
* [The Insomnia Plugin Hub](https://insomnia.rest/plugins)