# insomnia-plugin-mastercard
[](https://github.com/Mastercard/insomnia-plugin-mastercard/actions?query=workflow%3ASonar)
[](https://github.com/Mastercard/insomnia-plugin-mastercard/actions?query=workflow%3A%22broken+links%3F%22)
[](http://www.npmjs.com/package/insomnia-plugin-mastercard)
[](https://github.com/Mastercard/insomnia-plugin-mastercard/blob/main/LICENSE)
## Table of Contents
- [Overview](#overview)
* [Compatibility](#compatibility)
* [References](#references)
- [Usage](#usage)
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Configuration](#configuration)
+ [OAuth 2.0](#oauth-20)
+ [OAuth 1.0a](#oauth-10a)
+ [Disable Authentication](#disable-authentication)
* [Authenticated Requests](#authenticated-requests)
* [Encryption](#encryption)
* [Signature](#signature)
- [Further Reading](#further-reading)
## Overview
An [Insomnia REST Client](https://insomnia.rest/) plugin for consuming [Mastercard APIs](https://developer.mastercard.com/products). 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](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/)
* [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-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)
## Usage
### Prerequisites
You will need a project in the [Mastercard Developers Portal](https://developer.mastercard.com) (See [Quick Start Guide](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/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](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"
### 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:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/workspace/mastercard-apis-insomnia-workspace.json)
- OAuth 2.0:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/workspace/mastercard-apis-insomnia-workspace-oauth2.json)
- Mastercard Encryption:
[](https://insomnia.rest/run/?label=Import%20Mastercard%20Workspace&uri=https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/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/main/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 workspace depending on your use case:
- [OAuth 1.0a](https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/workspace/mastercard-apis-insomnia-workspace.json)
- [OAuth 2.0](https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/workspace/mastercard-apis-insomnia-workspace-oauth2.json)
- [Mastercard encryption](https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/workspace/mastercard-apis-with-mastercard-encryption-insomnia-workspace.json)
- [JWE encryption](https://raw.githubusercontent.com/Mastercard/insomnia-plugin-mastercard/main/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.
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](https://developer.mastercard.com).
Linux/macOS
```json
{
"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
```json
{
"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](https://developer.mastercard.com).
Linux/macOS
```json
{
"mastercard": {
"oAuth1": {
"consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
"keyAlias": "keyalias",
"keystoreP12Path": "/path/to/sandbox-signing-key.p12",
"keystorePassword": "keystorepassword"
},
"appliesTo": [
"mastercard.com",
"api.ethocaweb.com"
]
}
}
```
Windows
```json
{
"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.
```json
{
"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](https://github.com/Mastercard/insomnia-plugin-mastercard/blob/main/docs/configuration-examples.md).
### 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",
}
}
}
```
### 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:
```jsonc
{
"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](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)
## Further Reading
* [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)
