# API Basics source: https://developer.mastercard.com/mdes-customer-service/documentation/api-basics/index.md Alert: **Please note that the encryption functionality for the Search API is currently not available in the Sandbox environment. We recommend that customers perform their encryption testing in the MTF environment. This will help in identifying any potential issues and ensure that the encryption works as expected before deploying in Production environment.** ## Authentication {#authentication} Mastercard uses OAuth 1.0a for authenticating your application. You can manage your authentication keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard) after you created a project using the MDES Customer Service API. Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) guide. ## Encryption {#encryption} All communication between an issuer and MDES Customer Service is encrypted using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is encrypted by default when transmitted across networks. In addition to that, the MDES Customer Service API uses field-level encryption to provide end-to-end payload encryption to secure sensitive data like Personally Identifying Information (PII). The API request requires a field level encrypted object which contains the sensitive information required for the request. For example, an account number is sensitive information and must be encrypted. You can manage your encryption keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard). Tip: Do you want to learn more about the encryption schemes Mastercard uses? For that, read our [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) guide. * The encryption configuration below (to be used at the "*Enable Encryption*" step): * Java * C# ```java FieldLevelEncryptionConfig encryptionConfig = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig() .withEncryptionPath("$.EncryptedAccountInformation.EncryptedData", "$.EncryptedAccountInformation") .withEncryptionCertificate(EncryptionUtils.loadEncryptionCertificate("path/to/mdes-customer-service-sandbox.crt")) .withOaepPaddingDigestAlgorithm("SHA-512") .withEncryptedValueFieldName("EncryptedData") .withEncryptedKeyFieldName("EncryptedKey") .withIvFieldName("Iv") .withOaepPaddingDigestAlgorithmFieldName("OaepHashingAlgorithm") .withEncryptionKeyFingerprintFieldName("PublicKeyFingerprint") .withFieldValueEncoding(FieldValueEncoding.HEX) .build(); ``` ```csharp var fieldLevelEncryptionConfig = FieldLevelEncryptionConfigBuilder.AFieldLevelEncryptionConfig() .WithEncryptionPath("$.EncryptedAccountInformation.EncryptedData", "$.EncryptedAccountInformation") .WithEncryptionCertificate(EncryptionUtils.LoadEncryptionCertificate("path/to/mdes-customer-service-sandbox.crt")) .WithOaepPaddingDigestAlgorithm("SHA-512") .WithEncryptedValueFieldName("EncryptedData") .WithEncryptedKeyFieldName("EncryptedKey") .WithIvFieldName("Iv") .WithOaepPaddingDigestAlgorithmFieldName("OaepHashingAlgorithm") .WithEncryptionKeyFingerprintFieldName("PublicKeyFingerprint") .WithValueEncoding(FieldValueEncoding.Hex) .Build(); ``` ## How to consume the MDES Customer Service API? {#how-to-consume-the-mdes-customer-service-api} The MDES Customer Service APIs are designed as RPC style stateless web services where each API endpoint represents an operation to be performed. All request and response payloads are sent in the JSON (JavaScript Object Notation) data-interchange format. Each endpoint in the API specifies the HTTP Method used to access it. All strings in request and response objects are to be UTF-8 encoded. Please refer to the [integration tutorials](https://developer.mastercard.com/mdes-customer-service/documentation/tutorials/index.md). ## Environments {#environments} The table below describes the two different environments that are available. | **Environment** | **Description** | |--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox | This is the test environment. | | Mastercard Test Facility (MTF) | This is the environment to test your integration before going live. Use the production keys for your project to test in this environment. | | Production | This is the production environment. | ## Retry Policy {#retry-policy} Mastercard MDES Services are served from data centers in multiple locations. Mastercard uses a process of replication to ensure data integrity for each location and to avoid potential degradation of service. Issuers are advised to implement a retry policy including an exponential backoff with the first retry being sent after at least 3 seconds. New token information may not be available for a short period of time after the first request, and failure to implement a retry policy with suffient gap between initial request and retry may result in the following error: '**INVALID_REQUEST, ApiException MDES CSAPI: The request was invalid**'. ## Request http Headers {#request-http-headers} Two parameters must be set in the http header of each request: * Content-Type: it must include "application/json" if the customer wants to send their CS API requests in JSON format, or "application/xml" if the CS API requests are raised in XML format. * Accept: in the same way than for "Content-Type", "application/json" must be applied if the customer wants their CS API responses in JSON format, while "application/xml" must be specified if the CS API responses are required in XML format. Note: Most of the time, the headers 'Content-Type' and 'Accept' include the same values (i.e. "application/json" or "application/xml"), assuming that requests and responses are both either in JSON or XML format. ## Requests by Token State {#requests-by-token-state} The table below shows which valid API operations can be performed based on the current token state. | API | In Progress Status | Active Status | Suspended Status | Deleted | |------------------------------------------------|--------------------|---------------|------------------|---------| | Search | Yes | Yes | Yes | Yes | | Token Suspend | No | Yes | Yes^\[1\]^ | No | | Token Unsuspend | No | No | Yes^\[2\]^ | No | | Token Delete | Yes | Yes | Yes | No | | Token Update(FPAN/Product Configuration) | No | Yes | Yes | No | | Token Reset Mobile PIN | No | Yes | Yes | No | | Token Comments | Yes | Yes | Yes | Yes | | Token Status History | Yes | Yes | Yes | Yes | | Transactions | No | Yes | Yes | Yes | | Token Activation Methods | Yes^\[3\]^ | No | No | No | | Token Resend Activation Code | Yes^\[3\]^ | No | No | No | | Token Activate | Yes^\[3\]^ | No | No | No | | Token Update Assurance (Token Assurance Level) | No | Yes | Yes | No | | Disable Payment Channels | No | Yes | Yes | No | ^\[1\]^ Multiple suspender capability means that it is possible to suspend an already suspended token. A token can be suspended by any one or a combination of the following: Issuer, Token Requestor, Cardholder through a service offered by the Token Requestor, System. ^\[2\]^ Multiple suspender capability means that it is possible to Unsuspend a token and it still be suspended. ^\[3\]^ Activation related APIs are only applicable when a token has been provisioned but is not yet activated (yellow path)