---
title: "Add Processor / Value-Added Service"
method: POST
path: "/v4/processors"
tags: ["Processors and Services"]
---

# Add Processor / Value-Added Service

`POST /v4/processors`

## Request

- Base URL: `https://sandbox.nmi.com/api`
- URL: `https://sandbox.nmi.com/api/v4/processors`
- Auth: none required

<details>
<summary>Adding the Processor</summary>
This request submits the processor details for a specific merchant.
</details>
<details>
<summary>Add Value-Added Services</summary>
Value-added services (like Customer Vault) are added the same way as card/check processors, but they are far simpler requests.

Each VAS should be added in its own request, so if you wanted to make Customer Vault active, Invoicing active, and Mobile Payments offered, that would be 3 API requests to the `/api/v4/processors` endpoint.

### Service ID Table

`serviceId` will vary based on which service you’re trying to add. These are based on which services are available in your estate. 

| Service                                  | serviceId Value  | Additional Details Required? |
|:-----------------------------------------|:----------------:|-----------------------------:|
| Airline Industry                         | airline          | No                          |
| Automatic Card Updater                   | acu              | Yes                         |
| CardinalCommerce Centinel 3-D Secure 2.0 | centinl2         | Yes                         |
| Customer Vault                           | vault            | No                          |
| Encrypted Devices                        | magensa          | No                          |
| Enhanced Data (Level III)                | level3           | No                          |
| Fraud Prevention                         | isf              | No                          |
| Invoicing                                | invoice          | No                          |
| Kount Fraud Manager                      | kount            | No                          |
| Mobile Payments                          | mobile           | No                          |
| Payer Authentication 2.0                 | threeds2         | Yes                         |
| QuickBooks SyncPay                       | qb               | No                          |

### Additional Processor Details
A few services allow additional information to configure correctly. These are passed in the `processorFields` object.


<br>**Automatic Card Updater**<br>
This is optional, but passing the `processorFields` object will let you configure ACU to run the first day after the service is activated. You can skip the whole `processorFields` object if you don’t want it to run immediately.

```javascript
{
    "condition": "offered",
    "status": "active",
    "serviceId": "acu",
    "processorFields": {
        "14": "run_immediately"
    },
    "merchantId": "{{gateway_id}}"
}
```

<br>**CardinalCommerce Centinel 3-D Secure 2.0**<br>
Query the service using `/api/v4/services/centinl2/config` for the service for the details of the required fields. 

<br>**Payer Authentication 2.0**<br>
Query the service using `/api/v4/services/threeds2/config` for the service for the details of the required fields.

### Request to Make Service Active
All fields are required, and it’s the `status` variable that’s telling this to be active right away. The `serviceId` value can be acquired using the `/api/v4/services/search` [documented here](checkservices).

As seen in the response, value-added services are technically “processors” so they return many values that you also see when adding a credit card processor, but most of this is not useful info for VAS. Important values here include:
* `id` is the unique identifier for this instance of the service
* `serviceId` is the code name for the service
* `status` will show “pending” until the merchant agrees to the fees/TOS, then it will be “active”
* `condition` will always be “offered” even after the merchant signs up

### Request to Make Service Offered
The only real difference is that in the response the `status` is now “inactive”.
</details>
<details>
<summary>Cash Processor Overview</summary>
The “cash processor” provides the same basic functionality as a credit card or check processor, but simply documents transactions instead of “authorizing” them though a payment processor. This means that requests directed to the “cash processor” don’t require any bank account or credit card information.

Cash processors have several simplifications compared to credit card and electronic check processors when they are configured. Cash processors:
* Do not support duplicate checking.
* Do not support monthly or per-transaction limits.
* Do not support any “processor information” fields or merchant category codes.

For the merchant, the cash processor has certain interface differences from other processors:
* Only sale, refund and credit transactions are available on cash processors.
* Cash transactions can not be saved to the Customer Vault since there is no sensitive information in the transaction information.
* Recurring does not support cash as a payment method for subscriptions.
* Invoicing only supports cash payments when manually charging an invoice in the merchant control panel. Customers will not be able to select cash when paying through the payment link they are emailed.
</details>

## Headers

- `Content-Type` string, required
- `Authorization` string, required

## Request body

- union
  - AddProcessorRequest
    - `processorFields` object, required: The processor-specific fields.
    - `descriptor` object: The descriptor fields.
      - `descriptor` string: The descriptor.
      - `phone` string: The descriptor phone number.
      - `city` string: The descriptor city.
      - `state` string: The descriptor state.
      - `url` string: The descriptor URL.
    - `currencies` string[], required: The allowed currencies for the processor.
    - `accountClassification` string, required: The processor account classification.
    - `billingType` string: The processor billing type.
    - `paymentTypes` string[], required: The allowed payment types for the processor.
    - `maxTicketAmount` string: The maximum amount for a single transaction run through this processor.
    - `maxMonthlyVolume` string, required: The maximum total amount that can be run through this processor in a single month.
    - `applyToAllCardType` boolean: Whether the maxMonthlyVolume and maxTicketAmount should apply to all payment methods through this processor or not.
    - `avsCvvPreCheck` string: The AVS/CVV precheck method for the processor.
    - `skipAvsCvv` boolean: Whether to enable skipping AVS/CVV or not.
    - `enableDuplicateChecking` boolean: Whether to enable duplicate checking or not.
    - `allowMerchantOverride` boolean: Whether to allow the merchant to ignore the duplicate check on a per-transaction basis or not.
    - `duplicateTime` string, required: The amount of time in seconds to look back to check if a transaction is a duplicate.
    - `requiredFields` object: The fields that are required to be populated for each transaction.
      - `name` boolean: Whether the name should be a required field or not.
      - `company` boolean: Whether the company should be a required field or not.
      - `address` boolean: Whether the address should be a required field or not.
      - `city` boolean: Whether the city should be a required field or not.
      - `state` boolean: Whether the state should be a required field or not.
      - `zip` boolean: Whether the ZIP code should be a required field or not.
      - `country` boolean: Whether the country should be a required field or not.
      - `phone` boolean: Whether the phone should be a required field or not.
      - `email` boolean: Whether the email should be a required field or not.
      - `driversLicense` boolean: Whether the driver's license should be a required field or not.
      - `driversLicenseState` boolean: Whether the driver's license state should be a required field or not.
      - `driversLicenseDob` boolean: Whether the driver's license date of birth should be a required field or not.
      - `ssn` boolean: Whether the SSN should be a required field or not.
      - `cvv` string: The CVV requirement setting.
      - `fax` boolean: Whether the fax should be a required field or not.
      - `url` boolean: Whether the URL should be a required field or not.
      - `orderId` boolean: Whether the order ID should be a required field or not.
      - `orderDescription` boolean: Whether the order description should be a required field or not.
      - `poNumber` boolean: Whether the PO number should be a required field or not.
      - `shipping` boolean: Whether shipping should be a required field or not.
      - `tax` boolean: Whether tax should be a required field or not.
      - `shippingName` boolean: Whether the shipping name should be a required field or not.
      - `shippingAddress` boolean: Whether the shipping address should be a required field or not.
      - `shippingCity` boolean: Whether the shipping city should be a required field or not.
      - `shippingState` boolean: Whether the shipping state should be a required field or not.
      - `shippingZip` boolean: Whether the shipping ZIP code should be a required field or not.
      - `shippingCountry` boolean: Whether the shipping country should be a required field or not.
      - `mdf1` boolean: Whether Merchant Defined Field 1 should be a required field or not.
      - `mdf2` boolean: Whether Merchant Defined Field 2 should be a required field or not.
      - `mdf3` boolean: Whether Merchant Defined Field 3 should be a required field or not.
      - `mdf4` boolean: Whether Merchant Defined Field 4 should be a required field or not.
      - `mdf5` boolean: Whether Merchant Defined Field 5 should be a required field or not.
      - `mdf6` boolean: Whether Merchant Defined Field 6 should be a required field or not.
      - `mdf7` boolean: Whether Merchant Defined Field 7 should be a required field or not.
      - `mdf8` boolean: Whether Merchant Defined Field 8 should be a required field or not.
      - `mdf9` boolean: Whether Merchant Defined Field 9 should be a required field or not.
      - `mdf10` boolean: Whether Merchant Defined Field 10 should be a required field or not.
      - `mdf11` boolean: Whether Merchant Defined Field 11 should be a required field or not.
      - `mdf12` boolean: Whether Merchant Defined Field 12 should be a required field or not.
      - `mdf13` boolean: Whether Merchant Defined Field 13 should be a required field or not.
      - `mdf14` boolean: Whether Merchant Defined Field 14 should be a required field or not.
      - `mdf15` boolean: Whether Merchant Defined Field 15 should be a required field or not.
      - `mdf16` boolean: Whether Merchant Defined Field 16 should be a required field or not.
      - `mdf17` boolean: Whether Merchant Defined Field 17 should be a required field or not.
      - `mdf18` boolean: Whether Merchant Defined Field 18 should be a required field or not.
      - `mdf19` boolean: Whether Merchant Defined Field 19 should be a required field or not.
      - `mdf20` boolean: Whether Merchant Defined Field 20 should be a required field or not.
    - `processorName` string, required: The name for the processor.
    - `mcc` string, required: The Merchant Category Code.
    - `serviceId` string, required: The ID of the processor platform you want to board.
    - `merchantId` string, required: The merchant's Gateway ID.
    - `faceConfiguration` object: The FACe configuration for the processor.
  - MakeServiceActiveRequest
    - `merchantId` string, required: The merchant's Gateway ID.
    - `serviceId` string, required: The ID of the service you are trying to make active.
    - `condition` 'offered', required: The condition of the service.
    - `status` 'active', required: The status of the service.
  - MakeServiceOfferedRequest
    - `merchantId` string, required: The merchant's Gateway ID.
    - `serviceId` string, required: The ID of the service you are trying to make offered.
    - `condition` 'offered', required: The condition of the service.

## Response `200`

Success

- AddProcessorServiceResponse
  - `objectType` 'processor': The type of object that was returned as a result of the request.
  - `id` integer: The unique identifier of the processor or service instance added.
  - `processorType` string: The type of the processor added.
  - `processorId` string: The ID of the processor added.
  - `processorName` string: The name of the processor added.
  - `serviceId` string: The code name of the processor platform or service added.
  - `merchantId` string: The merchant's Gateway ID.
  - `mcc` string: The Merchant Category Code.
  - `accountClassification` string: The account classification of the processor added.
  - `maxTicketAmount` string: The maximum amount for a single transaction run through the added processor.
  - `maxMonthlyVolume` string: The maximum total amount that can be run through the processor in a single month.
  - `applyToAllCardType` boolean: Whether the maxMonthlyVolume and maxTicketAmount apply to all payment methods through the added processor or not.
  - `enableDuplicateChecking` boolean: Whether duplicate checking is enabled or not.
  - `allowMerchantOverride` boolean: Whether the merchant is allowed to ignore the duplicate check on a per-transaction basis or not.
  - `duplicateTime` string: The amount of time in seconds to look back to check if a transaction is a duplicate.
  - `status` 'active' | 'pending': The status of the added processor or service, depending on the processor/billing authorization status.
  - `condition` 'offered' | 'notOffered' | 'mandatory': The condition of the added processor or service.
  - `extraDetails` object: Any extra details about the added processor.
  - `created` string: The date and time of when the processor or service was added.
  - `updated` string: The date and time of when the processor or service was last updated.
  - `supportsReroutedRefunds` boolean: Whether the added processor supports rerouted refunds or not.
  - `shouldDisableFields` boolean: Whether the added processor should disable fields or not.
  - `disabled` boolean: Whether the processor is disabled or not.
  - `refundProcessor` string: The specified processor to reroute future refunds to, if this processor is disabled.
  - `billingType` string: The billing type of the added processor or service.
  - `avsCvvPreCheck` string: The AVS/CVV precheck method for the added processor.
  - `skipAvsCvv` boolean: Whether skipping AVS/CVV is enabled for the added processor or not.
  - `processorFields` object: The processor-dependent fields for the added processor.
  - `paymentTypes` string[]: The allowed payment types for the added processor.
  - `descriptor` object: The descriptor fields for the added processor.
    - `descriptor` string: The descriptor for the added processor.
    - `phone` string: The descriptor phone number for the added processor.
    - `city` string: The descriptor city for the added processor.
    - `state` string: The descriptor state for the added processor.
    - `url` string: The descriptor URL for the added processor.
  - `currencies` string[]: The allowed currencies for the added processor.
  - `requiredFields` object: The fields that are required to be populated for each transaction.
    - `name` boolean: Whether the name is a required field or not.
    - `company` boolean: Whether the company is a required field or not.
    - `address` boolean: Whether the address is a required field or not.
    - `city` boolean: Whether the city is required field or not.
    - `state` boolean: Whether the state is a required field or not.
    - `zip` boolean: Whether the ZIP code is a required field or not.
    - `country` boolean: Whether the country is a required field or not.
    - `phone` boolean: Whether the phone is a required field or not.
    - `email` boolean: Whether the email is a required field or not.
    - `driversLicense` boolean: Whether the driver's license is a required field or not.
    - `driversLicenseState` boolean: Whether the driver's license state is a required field or not.
    - `driversLicenseDob` boolean: Whether the driver's license date of birth is a required field or not.
    - `ssn` boolean: Whether the SSN is a required field or not.
    - `cvv` string: The CVV requirement setting.
    - `fax` boolean: Whether the fax is a required field or not.
    - `url` boolean: Whether the URL is a required field or not.
    - `orderId` boolean: Whether the order ID is a required field or not.
    - `orderDescription` boolean: Whether the order description is a required field or not.
    - `poNumber` boolean: Whether the PO number is a required field or not.
    - `shipping` boolean: Whether shipping is a required field or not.
    - `tax` boolean: Whether tax is a required field or not.
    - `shippingName` boolean: Whether the shipping name is a required field or not.
    - `shippingAddress` boolean: Whether the shipping address is a required field or not.
    - `shippingCity` boolean: Whether the shipping city is a required field or not.
    - `shippingState` boolean: Whether the shipping state is a required field or not.
    - `shippingZip` boolean: Whether the shipping ZIP code is a required field or not.
    - `shippingCountry` boolean: Whether the shipping country is a required field or not.
    - `mdf1` boolean: Whether Merchant Defined Field 1 is a required field or not.
    - `mdf2` boolean: Whether Merchant Defined Field 2 is a required field or not.
    - `mdf3` boolean: Whether Merchant Defined Field 3 is a required field or not.
    - `mdf4` boolean: Whether Merchant Defined Field 4 is a required field or not.
    - `mdf5` boolean: Whether Merchant Defined Field 5 is a required field or not.
    - `mdf6` boolean: Whether Merchant Defined Field 6 is a required field or not.
    - `mdf7` boolean: Whether Merchant Defined Field 7 is a required field or not.
    - `mdf8` boolean: Whether Merchant Defined Field 8 is a required field or not.
    - `mdf9` boolean: Whether Merchant Defined Field 9 is a required field or not.
    - `mdf10` boolean: Whether Merchant Defined Field 10 is a required field or not.
    - `mdf11` boolean: Whether Merchant Defined Field 11 is a required field or not.
    - `mdf12` boolean: Whether Merchant Defined Field 12 is a required field or not.
    - `mdf13` boolean: Whether Merchant Defined Field 13 is a required field or not.
    - `mdf14` boolean: Whether Merchant Defined Field 14 is a required field or not.
    - `mdf15` boolean: Whether Merchant Defined Field 15 is a required field or not.
    - `mdf16` boolean: Whether Merchant Defined Field 16 is a required field or not.
    - `mdf17` boolean: Whether Merchant Defined Field 17 is a required field or not.
    - `mdf18` boolean: Whether Merchant Defined Field 18 is a required field or not.
    - `mdf19` boolean: Whether Merchant Defined Field 19 is a required field or not.
    - `mdf20` boolean: Whether Merchant Defined Field 20 is a required field or not.
  - `faceConfiguration` object: The FACe configuration for the added processor.
  - `disabledFields` object: The disabled fields for the added processor.
    - `processorFields` object: The processor-dependent fields and whether they are disabled or not.

---

[API](https://skmtc.dev/nmi/apis/payments-api.md) - [All operations](https://skmtc.dev/nmi/apis/payments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nmi/apis/payments-api/revisions/c03727f27e27?raw)