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.

$3

Insomnia v5.15.0+

$3

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

Usage

$3

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)

$3

#### 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"


$3

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

- 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 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:
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",
"oAuthDisabled": false,
"appliesTo": [
"mastercard.com",
"api.ethocaweb.com"
]
}
}
`
Windows
`json
{
"mastercard": {
"consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000",
"keyAlias": "keyalias",
"keystoreP12Path": "C:\\path\\to\\sandbox-signing-key.p12",
"keystorePassword": "keystorepassword",
"oAuthDisabled": false,
"appliesTo": [
"mastercard.com",
"api.ethocaweb.com"
]
}
}
`

The oAuthDisabled parameter is optional within the configuration settings. By default, its value is implicitly set to false, indicating that OAuth-based authorization is enabled unless explicitly specified otherwise.
If the application do not require the use of an authorization header for secure access, this parameter must be explicitly set to true to disable OAuth functionality. In the absence of this parameter, the system assumes OAuth is enabled and proceeds accordingly.


$3


From now on, an Authorization header will be automatically added to every request sent to Mastercard:


$3

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


$3


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"]
}
}
}
}
``

See more examples here.

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