# API Reference
source: https://developer.mastercard.com/payment-account-management/documentation/api-reference/index.md

The Payment Account Management API is the unified Mastercard interface for allowing Mastercard Customers to perform account related operations. Some API calls contain encrypted data. For a full listing of the encrypted data structure please refer to the [Encrypting the Request Payload](https://developer.mastercard.com/payment-account-management/documentation/api-reference/index.md#encrypting-the-request-payload) section or download the latest PAM API Swagger definition.

API Specification: `https://static.developer.mastercard.com/content/payment-account-management/swagger/pam.yaml`

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

Refer to [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/securing-sensitive-data-using-payload-encryption/) for details on how to encrypt the sensitive fields in the POST request payloads.

### GetPaymentAccountReference {#getpaymentaccountreference}

#### Request {#request}

Contents of encryptedData in encryptedPayload prior to encryption:

* *accountNumber* - The Primary Account Number of the account or the affiliated MDES token.

For example:
* JSON

```JSON
{
  "accountNumber": "5123456789012345"
}
```

#### Response {#response}

Contents of encryptedData in encryptedPayload after decryption:

* *paymentAccountReference* - The PAR assigned to the PAN.

For example:
* JSON

```JSON
{
  "paymentAccountReference": "512381d9f8e0629211e3949a08002"
}
```

### Update Account {#update-account}

#### Request {#request-1}

Contents of encryptedData in encryptedPayload prior to encryption:

* *oldCardInfo* - Card object for the old card, containing PAN(Required), Expiry Month(Required), Expiry Year(Required), and PAN Sequence Number(Optional except for a PAN Sequence Number Update).
* *newCardInfo* - Card object for the new card, containing PAN(Required), Expiry Month(Required), Expiry Year(Required), and PAN Sequence Number(Optional except for a PAN Sequence Number Update).

For example:
* JSON

```JSON
{
  "oldCardInfo": {
    "accountNumber": "5123456789012345",
    "expiryMonth": "12",
    "expiryYear": "20",
    "panSequenceNumber": "01"
  },
  "newCardInfo": {
    "accountNumber": "5123456789054321",
    "expiryMonth": "12",
    "expiryYear": "21",
    "panSequenceNumber": "01"
  }
}
```

#### Response {#response-1}

Response does not contain encrypted fields.

### Close Account {#close-account}

#### Request {#request-2}

Contents of encryptedData in encryptedPayload prior to encryption:

* *accountNumber* - The Primary Account Number of the account.

For example:
* JSON

```JSON
{
  "accountNumber": "5123456789012345"
}
```

#### Response {#response-2}

Response does not contain encrypted fields.

### Add Account {#add-account}

#### Request {#request-3}

Contents of encryptedData in encryptedPayload prior to encryption:

* cardInfo - Card object containing PAN, Expiry Month, Expiry Year and PAN Sequence Number.

For example:
* JSON

```JSON
{
  "cardInfo": {
    "accountNumber": "5123456789012345",
    "expiryMonth": "12",
    "expiryYear": "18",
    "panSequenceNumber": "01"
  }
}
```

### OverrideForDeleteAccount {#overridefordeleteaccount}

#### Request {#request-4}

Contents of encryptedData in encryptedPayload prior to encryption:

* *accountNumber* - The Primary Account Number of the account.

For example:
* JSON

```JSON
{
  "accountNumber": "5123456789012345"
}
```

#### Response {#response-3}

Response does not contain encrypted fields.

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

Mastercard provides [Client Encryption libraries](https://github.com/search?q=topic%3Afield-level-encryption+org%3AMastercard&type=Repositories) 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
class Example {
  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")
    .withEncryptionKeyFingerprintFieldName("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"
}
```

```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)
        .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",
  "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)
    ->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",
  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. For example:
* JSON

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