# API Reference
source: https://developer.mastercard.com/mdes-digital-enablement/documentation/api-reference/index.md

API Specification: `https://static.developer.mastercard.com/content/mdes-digital-enablement/swagger/mdes-digital-enablement-api.yaml`

## Test and Validate API using Insomnia {#test-and-validate-api-using-insomnia}

You can import this yaml file into Insomnia and use the Mastercard plugin to test this API with the OAuth Authentication [Insomnia Plugin](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#insomnia-plugin).

## Encrypting the Request Payload {#encrypting-the-request-payload}

The API request requires a field level encrypted object *encryptedPayload.encryptedData* which contains the Primary Account Number. For example:
* JSON

```JSON
{
  "requestId": "123456",
  "encryptedPayload": {"encryptedData" : {"accountNumber": "5412345678901234"}}
}
```

The account number is sensitive information and must be encrypted according to the [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) process.

## Encrypt/ Decrypt Configuration {#encrypt-decrypt-configuration}

Mastercard provides [Client Encryption libraries](https://github.com/Mastercard?q=client-encryption) in several languages which you can integrate into your project. For these you will need a configuration object as follows:
* Java
* NodeJS
* C#
* Python
* PHP
* Ruby

```Java
{
  FieldLevelEncryptionConfig config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
    .withEncryptionPath("$.encryptedPayload.encryptedData", "$.encryptedPayload")
    .withDecryptionPath("$.encryptedPayload", "$.encryptedPayload.encryptedData")
    .withEncryptionCertificate(encryptionCertificate)
    .withDecryptionKey(decryptionKey)
    .withOaepPaddingDigestAlgorithm("SHA-512")
    .withEncryptedValueFieldName("encryptedData")
    .withEncryptedKeyFieldName("encryptedKey")
    .withIvFieldName("iv")
    .withOaepPaddingDigestAlgorithmFieldName("oaepHashingAlgorithm")
    .withEncryptionCertificateFingerprintFieldName("publicKeyFingerprint")
    .withFieldValueEncoding(FieldValueEncoding.HEX)
    .withEncryptionCertificateFingerprint()
    .build();
}
```

```NodeJS
{
  paths: [
    {
      path: "/getPaymentAccountReference",
      toEncrypt: [
        {
          element: "encryptedPayload.encryptedData",
          obj: "encryptedPayload"
        }],
      toDecrypt: [
        {
          element: "encryptedPayload",
          obj: "encryptedPayload.encryptedData"
        }
      ]
    }
  ],
  oaepPaddingDigestAlgorithm: 'SHA-512',
  ivFieldName: 'iv',
  encryptedKeyFieldName: 'encryptedKey',
  encryptedValueFieldName: 'encryptedData',
  oaepHashingAlgorithmFieldName: 'oaepHashingAlgorithm',
  publicKeyFingerprintFieldName: 'publicKeyFingerprint',
  publicKeyFingerprintType: "certificate",
  dataEncoding: 'hex',
  encryptionCertificate: "./path/to/your/encryption.crt",
  privateKey: "./path/to/private.key",
  publicKeyFingerprintHeaderName: ""
}
```

```C#
var config = FieldLevelEncryptionConfigBuilder.AFieldLevelEncryptionConfig()
        .WithEncryptionPath("$.encryptedPayload.encryptedData", "$.encryptedPayload")
        .WithDecryptionPath("$.encryptedPayload", "$.encryptedPayload.encryptedData")
        .WithEncryptionCertificate(encryptionCertificate)
        .WithDecryptionKey(decryptionKey)
        .WithOaepPaddingDigestAlgorithm("SHA-512")
        .WithEncryptedValueFieldName("encryptedData")
        .WithEncryptedKeyFieldName("encryptedKey")
        .WithIvFieldName("iv")
        .WithOaepPaddingDigestAlgorithmFieldName("oaepHashingAlgorithm")
        .WithEncryptionCertificateFingerprintFieldName("publicKeyFingerprint")
        .WithValueEncoding(FieldValueEncoding.Hex)
        .WithEncryptionCertificateFingerprint("80810fc13a8319fcf0e2ec322c82a4c304b782cc3ce671176343cfe8160c2279")
        .Build();
```

```Python
{
  "paths": {
    "$": {
      "toEncrypt": {
          "encryptedPayload.encryptedData": "encryptedPayload"
      },
      "toDecrypt": {
          "encryptedPayload": "encryptedPayload.encryptedData"
      }
    }
  },
  "ivFieldName": "iv",
  "encryptedKeyFieldName": "encryptedKey",
  "encryptedValueFieldName": "encryptedData",
  "dataEncoding": "hex",
  "encryptionCertificate": "./path/to/your/encryption.crtt",
  "decryptionKey": "./path/to/private.key",
  "oaepPaddingDigestAlgorithm": "SHA-512",
  "encryptionKeyFingerprintFieldName": "publicKeyFingerprint",
  "encryptionCertificateFingerprint": "80810fc13a8319fcf0e2ec322c82a4c304b782cc3ce671176343cfe8160c2279",
  "oaepPaddingDigestAlgorithmFieldName": "oaepHashingAlgorithm",

}
```

```PHP
$config = FieldLevelEncryptionConfigBuilder::aFieldLevelEncryptionConfig()
    ->withEncryptionPath('$.encryptedPayload.encryptedData', '$.encryptedPayload')
    ->withDecryptionPath('$.encryptedPayload', '$.encryptedPayload.encryptedData')
    ->withEncryptionCertificate($encryptionCertificate)
    ->withDecryptionKey($decryptionKey)
    ->withOaepPaddingDigestAlgorithm('SHA-512')
    ->withEncryptedValueFieldName('encryptedData')
    ->withEncryptedKeyFieldName('encryptedKey')
    ->withIvFieldName('iv')
    ->withOaepPaddingDigestAlgorithmFieldName('oaepHashingAlgorithm')
    ->withEncryptionCertificateFingerprintFieldName('publicKeyFingerprint')
    ->withFieldValueEncoding(FieldValueEncoding::HEX)
    ->withEncryptionCertificateFingerprint("80810fc13a8319fcf0e2ec322c82a4c304b782cc3ce671176343cfe8160c2279")
    ->build();
```

```Ruby
{
  paths: [
    {
      path: "/getPaymentAccountReference",
      toEncrypt: [
        {
          element: "encryptedPayload.encryptedData",
          obj: "encryptedPayload"
        }],
      toDecrypt: [
        {
          element: "encryptedPayload",
          obj: "encryptedPayload.encryptedData"
        }
      ]
    }
  ],
  oaepPaddingDigestAlgorithm: 'SHA-512',
  ivFieldName: 'iv',
  encryptedKeyFieldName: 'encryptedKey',
  encryptedValueFieldName: 'encryptedData',
  oaepHashingAlgorithmFieldName: 'oaepHashingAlgorithm',
  publicKeyFingerprintFieldName: 'publicKeyFingerprint',
  publicKeyFingerprintType: "certificate",
  dataEncoding: 'hex',
  encryptionCertificate: "./path/to/your/encryption.crt",
  encryptionCertificateFingerprint: "80810fc13a8319fcf0e2ec322c82a4c304b782cc3ce671176343cfe8160c2279",
  privateKey: "./path/to/private.key"
}
```

## Decrypting the Response payload {#decrypting-the-response-payload}

Use the same library and configuration settings to decrypt. For example, a response payload of:
* JSON

```JSON
{
   "encryptedPayload":{
      "encryptedData":"add2771860b024dcb68f597360bf7b47245ebc02ce326686a861d56c1234fc489847c2a236ae028f5c23d2dbb50dcd9da4c20b5215ddfca894d2c9cf815793d2",
      "encryptedKey":"18fb2abac59b21d401b0cf7623088df23ace63c63dd20f8a073ffe157229ecda3d23f1b7759121efec9a8f0ee6c2153c2b0b8fb3577137530500e33931f6d02a4c90d82202384604f04eb83f22e45feb4cafebe14b09389f6e9a98aeb20c4f65fa5ecb15fbb157f9612067ce9eed6fbda70c188a446ee2663c65b9d61f9c1a8113b13eb7c65575d130b4dd94b6414275c772bb059e4819df7984793a4d5a64c1e4f13732ce791ddff4725cf1b0d4fed5a961b252bed2558c06153a090386006afabf171358d2253dbdb412dd8d020ec4ab33d4c53e2a2c407b0f0d090a9f95be7eb4b7cc670699ac3835056c03cf97a83b2d4970864823a2209b852305b67a8b",
      "iv":"42f17b342d06dcd06080ef18f488b408",
      "oaepHashingAlgorithm":"SHA512",
      "publicKeyFingerprint":"8fc11150a7508f14baca07285703392a399cc57c"
   },
   "responseId":"123456"
}
```

Will be decrypted by the above configurations to show an *encryptedPayload.encryptedData* object containing the paymentAccountReference in plain text. For example:
* JSON

```JSON
{
    "encryptedPayload": {
        "encryptedData": {
            "paymentAccountReference": "500103DMKZ9VHG9ILSR8I6SL2IZ5R"
        }
    },
    "responseId": "123456"
}
```